Contributing
Welcome to the QType development guide! This document provides comprehensive instructions for setting up your development environment and contributing to the project.
Table of Contents
- Prerequisites
- Development Environment Setup
- Installing QType for Development
- Running Tests
- Code Quality and Standards
- Project Structure
- Making Changes
- CLI Usage
- Troubleshooting
Prerequisites
- Python 3.10 or higher (this project targets Python 3.10+)
- uv package manager (recommended) or pip
- Git for version control
Development Environment Setup
1. Clone the Repository
git clone https://github.com/yourusername/qtype.git
cd qtype
2. Set Up Python Environment
We recommend using uv
for dependency management as it's faster and more reliable:
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install all dependencies including development tools
uv sync --group dev --extra interpreter
Installing QType for Development
Install QType in editable mode so changes to the source code are immediately reflected:
# Install in development mode
uv pip install -e .[interpreter]
After installation, you should be able to run the qtype
command from anywhere:
qtype --help
Running Tests
The project uses pytest for testing with coverage measurement:
# Run all tests
uv run pytest
# Run tests with coverage
uv run pytest --cov=qtype
# Run tests with coverage and generate HTML report
uv run pytest --cov=qtype --cov-report=html
# Run tests with verbose output
uv run pytest -v
# Run specific test file
uv run pytest tests/test_loader_file_inclusion.py
# Run specific test class
uv run pytest tests/test_loader_file_inclusion.py::TestFileIncludeLoader
# Run specific test method
uv run pytest tests/test_loader_file_inclusion.py::TestFileIncludeLoader::test_include_yaml_file
# Run tests matching a pattern
uv run pytest -k "test_include"
# Run tests with specific markers
uv run pytest -m "not network" # Skip network tests
uv run pytest -m "not slow" # Skip slow tests
# Run tests in parallel (if pytest-xdist is installed)
uv run pytest -n auto
Coverage Reports
Coverage reports show:
- Which lines of code are executed during tests
- Which lines are missing test coverage
- Overall coverage percentage for each module
- HTML report with line-by-line coverage highlighting
The HTML coverage report (htmlcov/index.html
) provides the most detailed view, showing exactly which lines need more test coverage.
Test Markers
The project uses pytest markers to categorize tests:
- @pytest.mark.slow
: Tests that take longer to run
- @pytest.mark.network
: Tests requiring network access
Skip specific test categories:
# Skip slow tests
uv run pytest -m "not slow"
# Skip network tests
uv run pytest -m "not network"
# Run only network tests
uv run pytest -m "network"
Code Quality and Standards
This project follows strict Python coding standards:
Code Style Requirements
- PEP 8 compliance for all Python code
- Type hints for all function signatures and class attributes
- Docstrings for all public functions, classes, and modules
- Clear naming using snake_case for functions/variables, PascalCase for classes
- Line length limit of 79 characters (as per PEP 8)
- f-strings for string interpolation
- Explicit over implicit code style
Format code automatically:
# Format with ruff
ruff format qtype/ tests/
# Lint with ruff
ruff check qtype/ tests/
# Sort imports
isort qtype/ tests/
# Type checking with mypy
mypy qtype/ tests/
Pre-commit hooks (Optional but recommended):
uv pip install pre-commit
pre-commit install
Settings are in .pre-commit-config.yaml
:
Project Structure
qtype/
– Python package for parsing, validating, and interpreting QType specsexamples/
– Example.qtype.yaml
specsschema/
– JSON Schema auto-generated from the DSLdocs/
– Documentationtests/
– Unit and integration tests
Making Changes
Development Workflow
-
Create a feature branch:
bash git checkout -b feature/your-feature-name
-
Make your changes following the coding standards
-
Write or update tests for your changes
-
Run tests to ensure nothing is broken:
bash uv run pytest --cov=qtype
-
Check code quality:
bash ruff format qtype/ tests/ ruff check qtype/ tests/ isort qtype/ tests/ mypy qtype/
-
Test CLI functionality: ```bash # Generate schema ptython -m qtype.cli generate-schema -o schema/test.json
# Validate example spec ptython -m qtype.cli validate examples/hello_world.qtype.yaml ```
-
Update documentation if needed
-
Commit your changes:
bash git add . git commit -m "feat: add your feature description"
How To: Expand The DSL
The core of qtype is the DSL specified in qtype/dsl/model.py. All functionality is rooted in the pydantic classes in that file. To expand the dsl with new classes, types, etc., edit this file.
Once you have it to your liking, you can generate the new schema:
qtype generate schema -o schema/qtype.schema.json
Next, make a canonical example of your new type in the examples
folder (e.g., examples/new_type_example.qtype.yaml
).
You can make vscode validate it with your newly generated schema by adding it to your settings.json
:
"yaml.schemas" : {
"schema/qtype.schema.json": ["qtype.config.yaml", "*.qtype.yaml"],
},
The semantic model for your new class can be generated automatically as well:
qtype generate semantic-model
This command updates qtype/semantic/model.py
with any new types in the qtype/dsl/model.py
using the following rules:
* Class names that end in List
are ignored
* Any member that has an <DSLClass> | str
type are switched to <DSLClass>
(as it assumes the str
is a reference)
* All List | None
types are switched to List
as omitted lists are replaced with empty lists in the semantic representation.
Next, ensure your new types can be validated:
qtype validate examples/new_type_example.qtype.yaml
The docstrings in the types are used to update the documentation with:
qtype generate dsl-docs
Finally, if desired, you can update the interpreter to support your new type.
Adding New Dependencies
When adding new dependencies, use uv to add to pyproject.toml
:
uv add <dependency>
Then update the lock file:
uv lock
Next Steps
After setting up your development environment:
- Explore the
examples/
directory to understand QType specifications - Run the existing tests to ensure everything works
- Read the documentation in
docs/
- Look at open issues for contribution opportunities
- Start with small improvements or bug fixes
Happy coding! 🚀