Restructure ChaosCrypt from a single-file script into a complete, installable Python package with three interfaces: a typed Python API, an argument-driven CLI, and a bilingual interactive TUI. The algorithm itself is unchanged. Ciphertexts and key files remain fully interoperable with the original implementation in both directions, which is enforced by dedicated tests rather than merely documented. Added - Library API: ChaosCrypt facade plus ChaosCryptCore for the raw algorithm - Unified error hierarchy: 16 named types, all ChaosCryptError subclasses, rendering as ChaosCrypt_ERR_<Detail>_<Code> - CLI: keygen, encrypt, decrypt, file, info, chpwd, tui, with --json output, stdin/stdout piping, and three password sources per secret - Bilingual TUI: English default, runtime switch to Chinese, getpass password entry with a non-TTY fallback that keeps it scriptable - Binary and file support: encrypt_bytes/decrypt_bytes and encrypt_file/decrypt_file - Key management: change_key_password rewraps without altering key material; export_key_text/load_from_text move a key without touching disk - Documentation: SECURITY.md with the full design and threat analysis, plus docs/ covering the API, CLI, architecture and build process - Test suite: 92 tests across round-trips, binary safety, key management, error types, CLI, TUI, i18n and legacy interoperability - Packaging: pyproject.toml, setup.py compatibility shim, MANIFEST.in, py.typed, examples, MIT licence Fixed - Conflicting --pwd option between the -p and -P groups prevented the CLI from starting at all - Wrong key file password reported as file corruption (E002); structural validation now distinguishes it from a damaged file (E003) - export_key_text produced key material without loading it into the instance - Non-hexadecimal input was accepted as ciphertext and silently decrypted into garbage, making corruption indistinguishable from success; malformed input now raises E010 before any processing - TUI failed under piped input because getpass requires a TTY - TUI kept reading the default key file name after generating a new one Changed - Source tree reorganised: the package lives at chaoscrypt/, with tests, examples and legacy alongside it; documentation and build artefacts at the repository root - Code comments unified in English; public docstrings document parameters, return values and raised exceptions - English is now the default UI language - ChaosCryptChat removed from the repository - Attribution updated to Dvs (DvsXT); project URLs point to Gitea
8.7 KiB
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:
pip install -e ".[dev]"
Development setup
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
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:
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:
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
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
twine check dist/*
Both files should report PASSED.
Inspect the wheel contents:
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:
# 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:
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
rm -rf dist/ build/ *.egg-info chaoscrypt/*.egg-info
3. Run the full test suite
pytest
Do not release with a failing test.
4. Build
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:
twine upload --repository testpypi dist/*
Then to PyPI:
twine upload dist/*
Credentials come from ~/.pypirc, environment variables, or an API token
entered at the prompt. Never commit them.
7. Tag the release
git tag -a v2.1.6 -m "ChaosCrypt 2.1.6"
git push origin v2.1.6
Versioning policy
ChaosCrypt follows Semantic Versioning:
| 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:
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:
[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:
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.