Contributing to tv-scraper

We welcome contributions from the community! This guide will help you get started with contributing to the tv-scraper project.

🚀 Ways to Contribute

Code Contributions

• Bug Fixes: Fix issues reported in the issue tracker
• New Features: Implement new scraping modules or enhance existing ones
• Performance Improvements: Optimize code for better performance
• Documentation: Improve documentation, add examples, or fix typos

Non-Code Contributions

• Bug Reports: Report bugs with detailed information
• Feature Requests: Suggest new features or improvements
• Documentation: Help improve or translate documentation
• Testing: Test the library and report issues

🛠️ Development Setup

Prerequisites

• Python 3.11 or higher
• Git
• uv (for dependency management)

Local Development

1. Fork and Clone the Repository

   git clone https://github.com/smitkunpara/tv-scraper.git
   cd tv-scraper
   

2. Set up Development Environment

   # Install all dependencies (main + dev tools)
   uv sync --extra dev
   
   # Install in development mode
   uv pip install -e .
   

3. Run Tests

   # Run all tests
   uv run pytest
   
   # Run specific test file
   uv run pytest tests/test_indicators.py
   

4. Build Documentation

   # Serve docs locally for development
   mkdocs serve
   
   # Build docs for production
   mkdocs build
   

📚 Versioned Docs

This project uses MkDocs Material with mike for versioned documentation publishing.

Local docs commands

# Install docs tooling
uv sync --extra dev

# Preview current docs
uv run mkdocs serve

# Preview versioned docs locally
uv run mike serve

Release-oriented docs publishing

# Publish a release docs version
uv run mike deploy --update-aliases <version> <alias>

# Set the default docs version
uv run mike set-default latest

Keep the docs flow aligned with release tags, and update AGENTS.md if it still describes older docs instructions or outdated project structure.

🧪 Testing

Writing Tests

• Edge Case Verification: For each new feature or scraper method, comprehensive test cases MUST be created to verify edge cases and failure modes.
• Write tests for all new features using descriptive test names
• Include both positive and negative (error handling) test cases
• Mock external API calls when possible

Test Structure

import pytest
from tv_scraper import CandleStreamer

class TestCandleStreamer:
    def test_get_candles_success(self):
        """Test fetching candles successfully."""
        streamer = CandleStreamer()
        result = streamer.get_candles(
            exchange="BINANCE",
            symbol="BTCUSDT",
            timeframe="1m",
            numb_candles=5
        )
        assert result["status"] == "success"
        assert "ohlcv" in result["data"]
        assert len(result["data"]["ohlcv"]) == 5

    def test_invalid_exchange(self):
        """Test error handling for invalid exchange."""
        streamer = CandleStreamer()
        result = streamer.get_candles(
            exchange="INVALID",
            symbol="BTCUSDT"
        )
        assert result["status"] == "failed"
        assert result["error"] is not None

📋 Pull Request Process

1. Create a Feature Branch

   git checkout -b feature/your-feature-name
   

2. Make Your Changes

3. Write clean, well-documented code
4. Add tests for new functionality

5. Update documentation if needed

6. Run Quality Checks

   # Run tests
   python -m pytest
   
   # Build documentation
   mkdocs build
   

7. Commit Your Changes

   git add .
   git commit -m "Add your descriptive commit message"
   

8. Push and Create Pull Request

   git push origin feature/your-feature-name
   

   Then create a pull request on GitHub.

Pull Request Guidelines

• Provide a clear description of the changes
• Reference any related issues
• Include screenshots for UI changes
• Ensure all tests pass
• Update documentation if needed

🐛 Reporting Bugs

Bug Report Template

When reporting bugs, please include:

1. Description: Clear description of the bug
2. Steps to Reproduce:

   # Provide a minimal code example that reproduces the issue
   

3. Expected Behavior: What should happen
4. Actual Behavior: What actually happens
5. Environment:
6. Python version: 3.11
7. OS: Windows 11
8. Library version: 1.5.0

Example Bug Report

**Bug: Technicals scraper fails with timeout**

**Steps to reproduce:**
```python
from tv_scraper import Technicals

scraper = Technicals()
result = scraper.get_technicals(
    exchange="BINANCE",
    symbol="BTCUSD",
    technical_indicators=["RSI", "MACD"]
)

Expected: Should return indicator data Actual: Times out with error Environment: Python 3.11, Windows 11 ```

💡 Feature Requests

Feature Request Template

• Title: Clear, descriptive title
• Description: Detailed description of the proposed feature
• Use Case: Explain why this feature would be useful
• Implementation Ideas: Optional suggestions for implementation

📞 Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Full Documentation

📜 Code of Conduct

This project follows a code of conduct to ensure a welcoming environment for all contributors. By participating, you agree to:

• Be respectful and inclusive
• Focus on constructive feedback
• Accept responsibility for mistakes
• Show empathy towards other contributors
• Help create a positive community

🙏 Acknowledgments

Thank you to all contributors who help make TradingView Scraper better! Your time and effort are greatly appreciated.

---

This contributing guide is adapted from open-source best practices and can be improved. Feel free to suggest changes!