Files
dvs 2529edac1d v2.1.6: Restructure as a distributable library
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
2026-09-27 17:03:05 +08:00

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.