From 32f20201acc12a51b4012c486ea8dc8eb1720c47 Mon Sep 17 00:00:00 2001 From: Bernd Worsch Date: Sun, 21 Sep 2025 21:12:23 +0000 Subject: [PATCH] Add MarkiTectLib --- MarkiTectLib.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 MarkiTectLib.md diff --git a/MarkiTectLib.md b/MarkiTectLib.md new file mode 100644 index 0000000..bd870f7 --- /dev/null +++ b/MarkiTectLib.md @@ -0,0 +1,47 @@ +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