extirpation 2.5.0

Auto-load Python modules from an online folder without manual updates

extirpation

A Python plugin-style library that auto-loads encryption modules from an online/ folder.

Highlights

• Drop-in modules: add a .py file to online/ and it loads automatically.
• Recursive discovery for nested module folders.
• Structured load reports with per-module errors.
• Built-in CLI for discovery, diagnostics, capability signatures, version checks, and direct function invocation.
• GitHub Actions CI + automated PyPI publishing on GitHub Release.

Install

pip install extirpation

For local development:

pip install -e .[dev]

Python API

from extirpation import (
    list_online_modules,
    load_online_modules,
    load_online_modules_with_report,
    setup,
)

print(list_online_modules("online"))
modules = load_online_modules("online")
print(modules["caesar"].caesar_encrypt("HELLO", shift=3))

report = load_online_modules_with_report("online", recursive=True)
print(report.modules.keys())
print(report.errors)

setup_result = setup("online")
print(len(setup_result.copied), len(setup_result.skipped))

CLI

List modules:

extirpation --online-dir online list

List modules as JSON:

extirpation --online-dir online list --json

Generate JSON load report:

extirpation --online-dir online --recursive --workers 4 report

Use cache for faster repeated inspection commands:

extirpation --online-dir online --cache catalog

Use cache for module listing too:

extirpation --online-dir online --cache list --json

Print installed version:

extirpation version

Invoke a function directly:

extirpation --online-dir online invoke --module caesar --function caesar_encrypt --kwargs "{\"plaintext\":\"HELLO\",\"shift\":3}"

Run a simple encrypt/decrypt flow without knowing exact function names:

extirpation --online-dir online transform --module caesar --mode encrypt --text "HELLO" --params "{\"shift\":3}"

Invoke multiple functions in one call:

extirpation --online-dir online invoke-batch --calls "[{\"module\":\"caesar\",\"function\":\"caesar_encrypt\",\"kwargs\":{\"plaintext\":\"ABC\",\"shift\":3}}]"

Continue batch execution even when one call fails (default), or stop immediately:

extirpation --online-dir online invoke-batch --stop-on-error --calls "[...]"

Show aggregate stats:

extirpation --online-dir online stats

Run a quick health check:

extirpation --online-dir online doctor

Fail CI when health issues are found:

extirpation --online-dir online doctor --fail-on-issues

Clear in-memory cache:

extirpation clear-cache

Benchmark load performance:

extirpation --online-dir online --cache --workers 4 benchmark --iterations 5

Search catalog for matching modules/functions:

extirpation --online-dir online find --query caesar

Inspect one module:

extirpation --online-dir online inspect --module caesar

Validate module contracts:

extirpation --online-dir online validate

Scaffold a new module template:

extirpation --online-dir online scaffold my_new_cipher

Provision bundled modules into your target folder:

extirpation --online-dir online setup

Export catalog to Markdown:

extirpation --online-dir online export-catalog --format markdown --output docs/catalog.md

Included modules

• online/quagmire_iv.py
• online/enigma.py (full Enigma simulation)
• online/vigenere.py
• online/autokey.py
• online/beaufort.py
• online/caesar.py
• online/baconian.py
• online/binary_cipher.py
• online/atbash.py
• online/affine.py
• online/columnar_transposition.py
• online/xor_cipher.py
• online/rail_fence.py
• online/rot47.py
• online/morse.py
• online/polybius.py
• online/bifid.py
• online/gronsfeld.py
• online/porta.py
• online/trithemius.py
• online/scytale.py
• online/keyword_substitution.py
• online/running_key.py
• online/route_cipher.py
• online/a1z26.py
• online/one_time_pad.py
• online/tap_code.py
• online/reverse_cipher.py
• online/caesar_box.py
• online/base64_cipher.py
• online/pig_latin.py
• online/playfair.py
• online/vernam.py
• online/spiral_route.py
• online/paired_caesar.py
• online/caesar_progressive.py
• online/mirror_chunks.py
• online/hex_cipher.py
• online/rot5.py
• online/rot13.py
• online/reverse_words.py
• online/leetspeak.py
• online/word_caesar.py
• online/rot18.py
• online/chunk_swap.py
• online/vowel_shift.py
• online/hill_cipher.py
• online/double_transposition.py
• online/substitution_monoalpha.py
• online/polyalpha_cycle.py
• online/permutation_blocks.py
• online/fibonacci_shift.py
• online/trinary_cipher.py
• online/zigzag_words.py
• online/caesar_prime.py
• online/base32_cipher.py
• online/keyword_caesar.py

Automated PyPI publishing from GitHub Releases

This repo includes .github/workflows/publish-pypi.yml that publishes automatically when a GitHub Release is published.

One-time setup in PyPI

1. Create the project (extirpation) on PyPI (or use an existing one).
2. In PyPI, configure Trusted Publishing and add this GitHub repo/workflow.
3. In GitHub, ensure the publish job can run with id-token: write (already configured).

Release flow

1. Merge to your default branch.
2. Create and publish a GitHub Release (for example tag v2.5.0).
3. GitHub Actions runs tests (ci.yml), builds distributions, validates them, and publishes to PyPI.

Local packaging checks

python -m build
python -m twine check dist/*