Development Documentation¶

This section contains documentation for contributors and developers.

Development Setup¶

Clone and Install¶

# Clone repository
git clone --recursive https://github.com/shakfu/cymongoose.git
cd cymongoose

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e ".[dev]"

Running Tests¶

# Run all tests
make test

# Or with pytest directly
PYTHONPATH=src pytest tests/ -v

# Run specific test file
PYTHONPATH=src pytest tests/test_http_server.py -v

# Run with coverage
PYTHONPATH=src pytest tests/ --cov=cymongoose --cov-report=html

Build System¶

The project uses scikit-build-core with CMake as the build backend.

# Build/rebuild extension
make build

# Build with AddressSanitizer
make build-asan

# Clean build artifacts
make clean

Code Structure¶

cymongoose/
├── src/
│   └── cymongoose/
│       ├── __init__.py
│       ├── _mongoose.pyx      # Cython implementation
│       ├── _mongoose.pyi      # Type stubs
│       └── mongoose.pxd       # C declarations
├── tests/
│   ├── test_*.py              # Unit tests
│   └── examples/              # Example programs
├── thirdparty/
│   └── mongoose/              # Mongoose library
├── docs/                      # MkDocs documentation
├── CMakeLists.txt             # Build configuration
└── pyproject.toml             # Package metadata

Code Style¶

Python¶

# Format with ruff
ruff format .

# Lint
ruff check .

# Type check
mypy src/

Cython¶

4-space indentation
100-character line limit
Document all public functions
Use type hints in .pyi files

Documentation¶

# Build docs
make docs

# Serve locally with live reload
make docs-serve

# Deploy to GitHub Pages
make docs-deploy

Releases¶

Version Numbering¶

Follows semantic versioning: MAJOR.MINOR.PATCH

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes

Release Checklist¶

Update version in pyproject.toml
Update CHANGELOG.md
Run full test suite
Build and test distribution
Tag release
Push to PyPI

Contributing¶

See Contributing for contribution guidelines.

Useful Commands¶

# Run tests
make test

# Build extension
make build

# Clean build artifacts
make clean

# Format code
ruff format .

# Type check
mypy src/

# Build docs
make docs

# Run examples
python tests/examples/http/http_server.py

Vendored Mongoose Patches¶

The vendored copy of mongoose (thirdparty/mongoose/) includes the following local patches on top of the upstream release. These must be re-applied after upgrading the vendored source.

File	Description
`mongoose.c:12583`	Free PKCS8 key buffer before returning error in `mg_tls_init`. Upstream leaks the `mg_parse_pem` allocation when a PKCS8 key is rejected.