# Building and Releasing How to build, test, and publish ChaosCrypt. --- ## Requirements | Tool | Version | Purpose | |---|---|---| | Python | 3.8+ | Runtime and build | | `build` | 1.0+ | Building distributions | | `twine` | 4.0+ | Validating and uploading | | `pytest` | 7.0+ | Running the test suite | Install the development dependencies: ```bash pip install -e ".[dev]" ``` --- ## Development setup ```bash git clone https://git.dvscloud.net/dvs/ChaosCrypt cd ChaosCrypt pip install -e ".[dev]" ``` An editable install means changes to the source take effect immediately, without reinstalling. --- ## Running the tests ```bash pytest # everything pytest chaoscrypt/tests/test_chaoscrypt.py # one module pytest -k roundtrip # by name pytest -x # stop at first failure pytest -v # verbose ``` With coverage: ```bash pytest --cov=chaoscrypt --cov-report=term-missing ``` ### Test modules | Module | Covers | |---|---| | `test_chaoscrypt.py` | Round-trips, binary safety, key management, errors, CLI, i18n | | `test_tui.py` | Interactive interface, driven by piped key sequences | | `test_legacy_interop.py` | Bidirectional compatibility with the original implementation | The TUI tests work because the interface falls back from `getpass` to plain `input` when stdin is not a terminal. That fallback exists for automation, so it serves both purposes. ### Compatibility tests `test_legacy_interop.py` imports `chaoscrypt/legacy/chaoscrypt_legacy.py` directly and exchanges data in both directions: ```bash pytest chaoscrypt/tests/test_legacy_interop.py -v ``` These tests are the enforcement mechanism for the claim that the algorithm was ported without any behavioural change. If they fail, the compatibility promise is broken. --- ## Building distributions ```bash python -m build ``` This produces two artefacts in `dist/`: | Artefact | Contents | |---|---| | `chaoscrypt-2.1.6.tar.gz` | Source distribution — everything needed to rebuild | | `chaoscrypt-2.1.6-py3-none-any.whl` | Wheel — the installed package | ### What the wheel contains Only the importable package: ``` chaoscrypt/__init__.py chaoscrypt/_core.py chaoscrypt/cli.py chaoscrypt/tui.py chaoscrypt/errors.py chaoscrypt/i18n.py chaoscrypt/__main__.py chaoscrypt/py.typed ``` `tests/`, `examples/` and `legacy/` sit alongside the package in the source tree but are excluded from the wheel by the explicit `packages` declaration in `pyproject.toml`. They ship in the source distribution, because the tests are useful to anyone building from source. ### Verifying the artefacts ```bash twine check dist/* ``` Both files should report `PASSED`. Inspect the wheel contents: ```bash python -m zipfile -l dist/chaoscrypt-2.1.6-py3-none-any.whl ``` --- ## Testing the build in isolation Before publishing, verify the wheel installs and works in a clean environment with no development dependencies present: ```bash # Create a throwaway environment. python -m venv /tmp/verify /tmp/verify/bin/pip install dist/chaoscrypt-2.1.6-py3-none-any.whl # No third-party dependencies should appear. /tmp/verify/bin/pip list # Exercise the command line. cd /tmp /tmp/verify/bin/chaoscrypt --version /tmp/verify/bin/chaoscrypt keygen -k test.key -P keypass /tmp/verify/bin/chaoscrypt encrypt "hello" -p userpass -k test.key -P keypass # Exercise the API. /tmp/verify/bin/python -c " from chaoscrypt import ChaosCrypt cc = ChaosCrypt('test.key', 'keypass', auto_load=True) token = cc.encrypt('verify', 'userpass') assert cc.decrypt(token, 'userpass') == 'verify' print('clean install verified') " ``` On Windows, use `\tmp\verify\Scripts\` in place of `/tmp/verify/bin/`. --- ## Releasing ### 1. Update the version The version appears in two places and both must agree: - `pyproject.toml` — `version = "2.1.6"` - `chaoscrypt/__init__.py` — `__version__ = "2.1.6"` Update the changelog with a new dated section, then verify consistency: ```bash python -c " import chaoscrypt, tomllib with open('pyproject.toml', 'rb') as f: meta = tomllib.load(f) assert chaoscrypt.__version__ == meta['project']['version'], 'version mismatch' print('versions consistent:', chaoscrypt.__version__) " ``` ### 2. Clean previous artefacts ```bash rm -rf dist/ build/ *.egg-info chaoscrypt/*.egg-info ``` ### 3. Run the full test suite ```bash pytest ``` Do not release with a failing test. ### 4. Build ```bash python -m build twine check dist/* ``` ### 5. Test the built wheel Run the isolated install procedure from the previous section. ### 6. Upload To TestPyPI first, to confirm the metadata renders correctly: ```bash twine upload --repository testpypi dist/* ``` Then to PyPI: ```bash twine upload dist/* ``` Credentials come from `~/.pypirc`, environment variables, or an API token entered at the prompt. Never commit them. ### 7. Tag the release ```bash git tag -a v2.1.6 -m "ChaosCrypt 2.1.6" git push origin v2.1.6 ``` --- ## Versioning policy ChaosCrypt follows [Semantic Versioning](https://semver.org/): | Change | Version bump | |---|---| | Breaking API change | Major | | New functionality, backward compatible | Minor | | Bug fix or documentation | Patch | Additional guarantees for a given major version: - the public API will not change incompatibly; - error codes will not be renumbered; - the key file format will not change; - ciphertexts from any earlier release will continue to decrypt. The algorithm is frozen. The package layout, documentation and tooling may evolve freely within a major version. --- ## Continuous integration A minimal GitHub Actions workflow: ```yaml name: test on: [push, pull_request] jobs: test: runs-on: ${{ matrix.os }} strategy: matrix: os: [ubuntu-latest, windows-latest, macos-latest] python-version: ["3.8", "3.11", "3.13"] steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} - run: pip install -e ".[dev]" - run: pytest - run: python -m build - run: twine check dist/* ``` Testing across operating systems matters here because the TUI and CLI handle terminal behaviour, path separators and encoding differently on each. --- ## Project layout ``` ChaosCrypt/ ├── README.md project overview ├── SECURITY.md design and threat analysis ├── CHANGELOG.md release history ├── LICENSE MIT ├── MANIFEST.in sdist contents ├── pyproject.toml build configuration ├── .gitignore ├── docs/ this directory │ ├── README.md documentation index │ ├── API.md Python API reference │ ├── CLI.md command line reference │ ├── ARCHITECTURE.md internal design │ └── BUILDING.md this file ├── dist/ build artefacts (generated) └── chaoscrypt/ source tree ├── __init__.py public API and facade ├── _core.py the algorithm ├── cli.py command line interface ├── tui.py interactive interface ├── errors.py error hierarchy ├── i18n.py UI strings ├── __main__.py python -m entry point ├── py.typed PEP 561 marker ├── tests/ test suite ├── examples/ runnable examples └── legacy/ original implementation ``` --- ## Troubleshooting **`error: package directory 'chaoscrypt/chaoscrypt' does not exist`** The `package-dir` mapping in `pyproject.toml` is wrong for this layout. The package lives at `chaoscrypt/`, alongside `tests/` and `examples/`, so the mapping must be: ```toml [tool.setuptools] packages = ["chaoscrypt"] package-dir = { "chaoscrypt" = "chaoscrypt" } ``` **The wheel contains `tests/` or `examples/`** The `packages` list is too broad. It should name only `chaoscrypt`, not use automatic discovery, because discovery would find the sibling directories. **`ModuleNotFoundError: No module named 'chaoscrypt'` after an editable install** Check that the install registered the right directory: ```bash python -c "import chaoscrypt, os; print(os.path.dirname(chaoscrypt.__file__))" ``` The path should point at the repository's `chaoscrypt/` directory. **Tests pass locally but fail in CI** Most often an encoding issue. The library explicitly uses UTF-8 for text I/O, but locale settings can still affect terminal behaviour. The TUI tests set `PYTHONIOENCODING=utf-8` and `NO_COLOR=1` for exactly this reason.