Skip to content

Development and Testing

Jump to bottom
levi edited this page Nov 6, 2025 · 2 revisions

Development and Testing

Table of Contents

  1. Contribution Workflow
  2. Code Quality Standards
  3. Testing Strategy
  4. Build and Release Process
  5. Documentation and Changelog
  6. Debugging Techniques
  7. Versioning and Compatibility

Contribution Workflow

The contribution workflow for PyTradingView follows a structured process to ensure code quality and maintainability. Contributors should first fork the repository and create a feature or fix branch from the main branch. The development environment is set up using a virtual environment with dependencies installed via pip install -e ".[dev]" as specified in pyproject.toml. This installs both runtime and development dependencies including testing and code quality tools.

After implementing changes, contributors must verify their code by running the test suite and code quality checks. The process concludes with submitting a pull request that includes a description of changes, testing verification, and checklist confirmation of coding standards. The pull request template requires confirmation of passing tests, adherence to style guidelines, and appropriate documentation updates.

Code Quality Standards

PyTradingView enforces strict code quality standards through automated tools configured in pyproject.toml. The project uses black for code formatting with a line length of 100 characters, ruff for linting with selected error codes (E, F, I), and mypy for static type checking. These tools are specified in the dev dependencies in both pyproject.toml and requirements-dev.txt.

All Python code must include type hints for function signatures and proper docstrings following Google style conventions. Comments and logs must be in English. Imports are organized in three groups (standard library, third-party, local) and sorted using isort. The codebase follows PEP 8 guidelines with the specific configuration defined in the project's tool settings.

Testing Strategy

The testing strategy for PyTradingView is built around pytest, with support for asynchronous testing through pytest-asyncio. Tests are located in the tests/ directory and should achieve 80%+ code coverage. The project includes pytest-cov for coverage reporting, allowing developers to generate HTML coverage reports.

Unit tests should cover core functionality, indicators, and datafeed implementations. The false_breakout_indicator.py example demonstrates proper test structure with test functions for initialization and async methods. Integration tests should verify the Python-JavaScript bridge functionality and end-to-end indicator execution. Test files should follow the pattern test_[component].py and include both positive and negative test cases.

flowchart TD
A["Test Initialization"] --> B["Arrange: Set up test data"]
B --> C["Act: Execute method"]
C --> D["Assert: Verify results"]
D --> E["Cleanup: Reset state"]
Loading

Build and Release Process

The build and release process is automated through shell scripts in the scripts/ directory. The build.sh script executes python -m build to create distribution packages, generating both source and wheel distributions. The release.sh script uses twine to upload the built packages from the dist/ directory to PyPI.

The build configuration is defined in pyproject.toml, which specifies the build system requirements (setuptools and wheel), package metadata, dependencies, and packaging rules. The setuptools configuration excludes test, example, documentation, and script directories from the packaged distribution. The project uses semantic versioning, with version numbers managed in pyproject.toml.

Documentation and Changelog

Documentation updates are required for all significant changes to the codebase. Code-level documentation must include comprehensive docstrings for all public classes and methods, following the Google style guide with sections for Args, Returns, Raises, and Examples. The CONTRIBUTING.md file provides templates for proper docstring formatting.

External documentation updates should include modifications to README.md for major features and additions to the CHANGELOG.md file for all releases. The changelog follows a structured format with sections for new features, bug fixes, and breaking changes. When adding new indicators or core functionality, examples should be added to the examples/ directory to demonstrate proper usage.

Debugging Techniques

Debugging the Python-JavaScript bridge requires understanding the bidirectional communication through the TVBridge class. The bridge uses FastAPI to create an HTTP server that handles RPC calls from the JavaScript side. Key debugging techniques include monitoring the bridge logs, which are configured with INFO level logging, and verifying the connection status between Python and Node servers.

Common issues include port conflicts, which are handled by the _find_available_port method, and RPC call validation, which checks for valid class names, object IDs, and method names. The _handle_web_to_python_call method in TVBridge.py provides the main entry point for debugging RPC issues, with logging of all incoming calls. For indicator development, the false_breakout_indicator.py example provides a template for debugging calculation logic and signal generation.

sequenceDiagram
participant JS as JavaScript
participant Bridge as TVBridge
participant Indicator as TVIndicator
JS->>Bridge : RPC Call (JSON)
Bridge->>Bridge : Validate call parameters
Bridge->>Indicator : Route to appropriate handler
Indicator->>Indicator : Execute method
Indicator->>Bridge : Return response
Bridge->>JS : Send response (JSON)
Loading

Versioning and Compatibility

PyTradingView follows semantic versioning (MAJOR.MINOR.PATCH) as specified in pyproject.toml. The version number is updated for each release, with backward compatibility being a primary concern. Breaking changes to the API are avoided whenever possible, and when necessary, they are introduced in major version increments with appropriate deprecation warnings in prior releases.

The project maintains backward compatibility through careful management of the public API, particularly in core components like TVEngine and TVBridge. The TVEngine class uses a modular inheritance hierarchy that allows internal refactoring without affecting the external interface. The indicator system supports backward compatibility through the all export in indicator_engine.py and consistent configuration interfaces.

Clone this wiki locally