Building python-newtype¶
This guide covers how to build and package python-newtype for development and distribution.
Prerequisites¶
Before building python-newtype, ensure you have the following installed:
- Python 3.8 or later
- Poetry (for dependency management)
- pytest (for testing)
- build (for building packages)
Development Environment Setup¶
-
Clone the repository:
-
Create a new virtual environment using
venv
:
For Linux:
For Windows:- Install
poetry
:
- Get poetry to use the virtual environment in the project directory:
This will ensure that Poetry uses the current virtual environment located in the project directory. You can also set the virtual environment path explicitly if needed. For example:
Then, you can install all development dependencies using
Project Structure¶
python-newtype/
├── newtype/
│ ├── __init__.py
│ ├── core.py
│ └── utils.py
├── tests/
│ ├── __init__.py
│ ├── test_basic_examples.py
│ └── test_advanced_examples.py
├── docs/
│ └── ...
├── pyproject.toml
├── README.md
└── LICENSE
Building the Package¶
Using Poetry¶
- Build the package:
This will create both wheel and source distributions in the dist/
directory.
- Install the package locally for testing:
Using Build¶
Alternatively, you can use Python's build module:
Running Tests¶
-
Run all tests:
Or: -
Run tests with coverage:
-
Run specific test files: For example,
Code Quality¶
Type Checking¶
We use mypy for static type checking:
Code Style¶
Use ruff
and cppcheck
for style checking:
Formatting¶
We use ruff
and clang-format
for code formatting:
Documentation¶
Building Documentation¶
We use MkDocs for documentation:
-
Install Docs MkDocs:
-
Build the documentation:
-
Serve documentation locally:
Documentation Structure¶
/docs/index.md
: Main documentation page/docs/user-guide/
: User guides and tutorials/docs/api/
: API reference documentation/docs/examples/
: Code examples/docs/development/
: Development guides
Release Process¶
Poetry Dynamic Versioning¶
To use dynamic versioning, you need to install the poetry-dynamic-versioning plugin. You can do this by running:
To Release a New Version¶
-
Set the version to the next patch version:
-
Set the tag to the new version:
-
Commit your changes and push to the repository.
- Push the changes to the repository:
Development Guidelines¶
Code Style¶
- Follow PEP 8 guidelines
- Use type hints for all functions
- Write docstrings for all public APIs
- Keep functions focused and small
Testing¶
- Write tests for all new features
- Maintain high test coverage
- Include both unit and integration tests
- Test edge cases and error conditions
Documentation¶
- Update docs with new features
- Include code examples
- Keep API reference up to date
- Document breaking changes
Performance Optimization¶
Profiling¶
Use cProfile for performance profiling:
Benchmarking¶
Create benchmarks using pytest-benchmark:
def test_newtype_performance(benchmark):
def wrapped_operation():
# Your operation here
pass
benchmark(wrapped_operation)
Troubleshooting¶
Common Issues¶
- Import errors:
- Check PYTHONPATH
-
Verify virtual environment activation
-
Build failures:
- Update Poetry and dependencies
-
Clear Poetry cache
-
Test failures:
- Check Python version compatibility
- Verify test dependencies
Debug Mode¶
Enable debug logging:
Contributing¶
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and linting
- Submit a pull request
See CONTRIBUTING.md for detailed guidelines.