markitect-main

Guidance

Abstractor: MarkiTect python library

We will provide MarkiTect functionality as python library well suited for reuse in a commandline cli, as the basis of a service offering and as a foundation for reuse in third party projects.

Here are the key best practices for a reusable Python library we want to respect:

Project Structure

Use a clear package hierarchy with __init__.py files
Separate concerns: core logic, utilities, interfaces, and tests in distinct modules
Keep modules focused on single responsibilities

API Design

Design for simplicity: expose only what users need
Use clear, consistent naming conventions
Provide sensible defaults but allow configuration
Make functions pure and idempotent where possible

Testing

Write tests first (TDD approach)
Aim for high coverage of public APIs
Use fixtures and mocks to isolate unit tests
Include integration tests for key workflows

Dependencies

Minimize external dependencies
Pin dependency versions in setup.py/pyproject.toml
Use optional dependencies for non-core features

Documentation

Write clear docstrings (Google or NumPy style)
Include type hints for all public functions
Provide a comprehensive README with usage examples
Document edge cases and error conditions

Code Quality

Use consistent formatting (Black, Ruff)
Run linters (pylint, flake8, mypy)
Keep functions small and composable
Avoid side effects; make dependencies explicit

Distribution

Use pyproject.toml for modern packaging
Semantic versioning for releases
Include a CHANGELOG
Set up CI/CD for automated testing and publishing