fromscratch-pycrypt 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. fromscratch_pycrypt-0.2.0/.github/workflows/ci.yml +14 -0
  2. fromscratch_pycrypt-0.2.0/.github/workflows/docs.yml +16 -0
  3. fromscratch_pycrypt-0.2.0/.github/workflows/release.yml +58 -0
  4. fromscratch_pycrypt-0.2.0/.gitignore +14 -0
  5. fromscratch_pycrypt-0.2.0/.pre-commit-config.yaml +56 -0
  6. fromscratch_pycrypt-0.2.0/CLAUDE.md +53 -0
  7. fromscratch_pycrypt-0.2.0/CONTRIBUTING.md +199 -0
  8. fromscratch_pycrypt-0.2.0/LICENSE +21 -0
  9. fromscratch_pycrypt-0.2.0/PKG-INFO +225 -0
  10. fromscratch_pycrypt-0.2.0/README.md +193 -0
  11. fromscratch_pycrypt-0.2.0/conftest.py +21 -0
  12. fromscratch_pycrypt-0.2.0/docs/concepts/caesar.md +48 -0
  13. fromscratch_pycrypt-0.2.0/docs/concepts/hashing.md +46 -0
  14. fromscratch_pycrypt-0.2.0/docs/concepts/hmac.md +51 -0
  15. fromscratch_pycrypt-0.2.0/docs/concepts/key-derivation.md +57 -0
  16. fromscratch_pycrypt-0.2.0/docs/concepts/signatures.md +68 -0
  17. fromscratch_pycrypt-0.2.0/docs/concepts/xor.md +66 -0
  18. fromscratch_pycrypt-0.2.0/docs/index.md +67 -0
  19. fromscratch_pycrypt-0.2.0/docs/property-testing.md +235 -0
  20. fromscratch_pycrypt-0.2.0/mkdocs.yml +81 -0
  21. fromscratch_pycrypt-0.2.0/overrides/main.html +7 -0
  22. fromscratch_pycrypt-0.2.0/pyproject.toml +158 -0
  23. fromscratch_pycrypt-0.2.0/src/pycrypt/__init__.py +1 -0
  24. fromscratch_pycrypt-0.2.0/src/pycrypt/_version.py +24 -0
  25. fromscratch_pycrypt-0.2.0/src/pycrypt/caesar.py +76 -0
  26. fromscratch_pycrypt-0.2.0/src/pycrypt/cli.py +71 -0
  27. fromscratch_pycrypt-0.2.0/src/pycrypt/errors.py +13 -0
  28. fromscratch_pycrypt-0.2.0/src/pycrypt/hashing.py +56 -0
  29. fromscratch_pycrypt-0.2.0/src/pycrypt/hmac.py +67 -0
  30. fromscratch_pycrypt-0.2.0/src/pycrypt/kdf.py +49 -0
  31. fromscratch_pycrypt-0.2.0/src/pycrypt/py.typed +0 -0
  32. fromscratch_pycrypt-0.2.0/src/pycrypt/signatures.py +63 -0
  33. fromscratch_pycrypt-0.2.0/src/pycrypt/xor.py +80 -0
  34. fromscratch_pycrypt-0.2.0/tests/__init__.py +1 -0
  35. fromscratch_pycrypt-0.2.0/tests/test_caesar.py +87 -0
  36. fromscratch_pycrypt-0.2.0/tests/test_cli.py +13 -0
  37. fromscratch_pycrypt-0.2.0/tests/test_hashing.py +73 -0
  38. fromscratch_pycrypt-0.2.0/tests/test_hmac.py +75 -0
  39. fromscratch_pycrypt-0.2.0/tests/test_kdf.py +57 -0
  40. fromscratch_pycrypt-0.2.0/tests/test_properties.py +177 -0
  41. fromscratch_pycrypt-0.2.0/tests/test_signatures.py +61 -0
  42. fromscratch_pycrypt-0.2.0/tests/test_xor.py +92 -0
  43. fromscratch_pycrypt-0.2.0/uv.lock +920 -0
@@ -0,0 +1,14 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ ci:
14
+ uses: robcox2910/robcox2910.github.io/.github/workflows/python-ci.yml@v1
@@ -0,0 +1,16 @@
1
+ name: Deploy Docs
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ workflow_dispatch: {}
7
+
8
+ jobs:
9
+ docs:
10
+ uses: robcox2910/robcox2910.github.io/.github/workflows/docs.yml@v1
11
+ permissions:
12
+ contents: read
13
+ pages: write
14
+ id-token: write
15
+ with:
16
+ coverage-report: false
@@ -0,0 +1,58 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*.*.*"
7
+
8
+ permissions:
9
+ contents: write
10
+ id-token: write
11
+
12
+ jobs:
13
+ build:
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - uses: actions/checkout@v7
17
+ with:
18
+ fetch-depth: 0
19
+
20
+ - name: Install uv
21
+ uses: astral-sh/setup-uv@v7
22
+ with:
23
+ version: "latest"
24
+
25
+ - name: Set up Python
26
+ run: uv python install 3.14
27
+
28
+ - name: Build distributions
29
+ run: uv build
30
+
31
+ - name: Upload build artifacts
32
+ uses: actions/upload-artifact@v7
33
+ with:
34
+ name: dist
35
+ path: dist/
36
+
37
+ - name: Upload to GitHub Release
38
+ uses: softprops/action-gh-release@v3
39
+ with:
40
+ files: dist/*
41
+
42
+ publish:
43
+ needs: build
44
+ runs-on: ubuntu-latest
45
+ environment:
46
+ name: pypi
47
+ url: https://pypi.org/project/fromscratch-pycrypt/
48
+ permissions:
49
+ id-token: write
50
+ steps:
51
+ - name: Download build artifacts
52
+ uses: actions/download-artifact@v8
53
+ with:
54
+ name: dist
55
+ path: dist/
56
+
57
+ - name: Publish to PyPI
58
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,14 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .venv/
7
+ .pytest_cache/
8
+ htmlcov/
9
+ .coverage
10
+ .pyright/
11
+ .DS_Store
12
+ src/pycrypt/_version.py
13
+ site/
14
+ .hypothesis/
@@ -0,0 +1,56 @@
1
+ default_language_version:
2
+ python: python3.14
3
+
4
+ repos:
5
+ - repo: https://github.com/pre-commit/pre-commit-hooks
6
+ rev: v5.0.0
7
+ hooks:
8
+ # Pages paste real pytest output, trailing spaces included.
9
+ - id: trailing-whitespace
10
+ exclude: ^docs/property-testing\.md$
11
+ - id: end-of-file-fixer
12
+ exclude: ^docs/property-testing\.md$
13
+ - id: check-yaml
14
+ args: ['--unsafe']
15
+ - id: check-added-large-files
16
+ - id: check-json
17
+ - id: check-toml
18
+ - id: check-merge-conflict
19
+ - id: debug-statements
20
+
21
+ - repo: https://github.com/astral-sh/ruff-pre-commit
22
+ rev: v0.15.4
23
+ hooks:
24
+ - id: ruff
25
+ args: [--fix, --exit-non-zero-on-fix]
26
+ - id: ruff-format
27
+
28
+ - repo: https://github.com/RobertCraigie/pyright-python
29
+ rev: v1.1.408
30
+ hooks:
31
+ - id: pyright
32
+
33
+ - repo: local
34
+ hooks:
35
+ - id: pip-audit
36
+ name: pip-audit
37
+ language: system
38
+ pass_filenames: false
39
+ files: ^(pyproject\.toml|uv\.lock)$
40
+ entry: >-
41
+ bash -c 'f=$(mktemp) &&
42
+ uv export --frozen --no-emit-project --all-extras --no-hashes -o "$f" >/dev/null &&
43
+ uvx pip-audit==2.10.0 -r "$f" --disable-pip --no-deps;
44
+ status=$?; rm -f "$f"; exit $status'
45
+
46
+ - repo: https://github.com/rhysd/actionlint
47
+ rev: v1.7.7
48
+ hooks:
49
+ - id: actionlint
50
+
51
+ - repo: https://github.com/commitizen-tools/commitizen
52
+ rev: v4.13.8
53
+ hooks:
54
+ - id: commitizen
55
+ stages: [commit-msg]
56
+ additional_dependencies: [typing_extensions]
@@ -0,0 +1,53 @@
1
+ # Claude Code Instructions
2
+
3
+ <!-- standard:start -->
4
+ ## Code Style
5
+
6
+ - All public functions, methods, classes, and modules **must** have a docstring
7
+ - Use imperative mood: "Return the result." not "Returns the result."
8
+ - One-line docstrings for simple functions; multi-line with summary + details for complex ones
9
+ - Follow the Google docstring convention (D211, D212 selected via ruff)
10
+
11
+ ## Linting
12
+
13
+ - Ruff enforces a comprehensive rule set -- run `uv run ruff check .` before committing
14
+ - Pyright runs in strict mode -- run `uv run pyright src tests` before committing
15
+ - All violations must be fixed, not ignored. Exceptions are the repo-owned `ignore` and `per-file-ignores` lists in `pyproject.toml`, which belong to this repo; the series sync never edits them
16
+
17
+ ## Testing
18
+
19
+ - TDD workflow: Red-Green-Refactor
20
+ - Coverage is enforced by pytest-cov; the floor in `pyproject.toml` is repo-owned
21
+ - Test classes and methods also require docstrings
22
+ - Use named constants instead of magic values (PLR2004)
23
+ - Run `uv run pytest` before committing
24
+ - Property-based tests (Hypothesis) live in `tests/test_properties.py` and `tests/test_model.py`; the shared profiles are in the root `conftest.py` (owned by `series sync`). Run `uv run pytest --hypothesis-profile=thorough` before a release.
25
+
26
+ ## Commits
27
+
28
+ - Use conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `ci:`, `chore:`
29
+ - All changes go via PR from a feature branch (main is protected); merge when CI is green
30
+
31
+ ## Dependencies
32
+
33
+ - Package manager: uv
34
+ - Run `uv sync --all-extras` after modifying dependencies
35
+ - `uv.lock` is committed; CI and pre-commit audit it with pip-audit through `uvx`, so pip-audit is not a project dependency
36
+ - Sibling projects, where used, are pinned release tags in `[tool.uv.sources]` (git + tag); never use `path` sources
37
+
38
+ ## Releasing
39
+
40
+ - A release is a `vX.Y.Z` tag on main after the PR is merged
41
+ - Docs-only and tooling-only changes do not get a release tag
42
+ - Docs are built with `mkdocs build --strict` and deployed to GitHub Pages by the docs workflow
43
+ <!-- standard:end -->
44
+
45
+ ## Project notes
46
+
47
+ - Use imperative mood: "Return the response." not "Returns the response."
48
+ - Pyright in strict mode -- run `uv run pyright src tests` before committing
49
+ - All violations must be fixed, not ignored (except D203/D213 incompatible pair)
50
+ - Minimum 80% coverage enforced by pytest-cov
51
+ - Use conventional commits (enforced by commitizen): `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `ci:`, `chore:`
52
+ - All changes go via PR from a feature branch (main is protected)
53
+ - Add production deps to `[project.dependencies]`
@@ -0,0 +1,199 @@
1
+ # Contributing to PyCrypt
2
+
3
+ Thanks for your interest in contributing! This guide covers everything you need
4
+ to get started.
5
+
6
+ ## Prerequisites
7
+
8
+ | Tool | Version | Install |
9
+ |------|---------|---------|
10
+ | Python | 3.14+ | [python.org](https://www.python.org/downloads/) |
11
+ | uv | latest | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
12
+ | git | 2.x+ | [git-scm.com](https://git-scm.com/) |
13
+
14
+ ## Setup
15
+
16
+ ```bash
17
+ # Clone the repo
18
+ git clone https://github.com/robcox2910/pycrypt.git
19
+ cd pycrypt
20
+
21
+ # Install all dependencies (including dev tools)
22
+ uv sync --all-extras
23
+
24
+ # Install pre-commit hooks (linting + commit message validation)
25
+ uv run pre-commit install
26
+ uv run pre-commit install --hook-type commit-msg
27
+ ```
28
+
29
+ Verify everything works:
30
+
31
+ ```bash
32
+ uv run pytest --cov # tests pass, >= 80% coverage
33
+ uv run ruff check src/ tests/ # no lint errors
34
+ uv run pyright src tests # no type errors
35
+ ```
36
+
37
+ ## TDD Workflow
38
+
39
+ We follow **Red-Green-Refactor** for every code change:
40
+
41
+ 1. **Red** -- Write a failing test that describes the behaviour you want.
42
+ 2. **Green** -- Write the simplest code that makes the test pass.
43
+ 3. **Refactor** -- Clean up while keeping all tests green.
44
+
45
+ Never skip the red step. If you can't write a failing test first, take a moment
46
+ to think about what the code should actually do.
47
+
48
+ ## Branch Naming
49
+
50
+ Create a branch from `main` using one of these prefixes:
51
+
52
+ | Prefix | When to use |
53
+ |--------|-------------|
54
+ | `feat/` | New cryptography feature or algorithm |
55
+ | `fix/` | Bug fix |
56
+ | `refactor/` | Restructuring without behaviour change |
57
+ | `test/` | Test-only changes |
58
+ | `docs/` | Documentation updates |
59
+ | `ci/` | CI/CD workflow changes |
60
+ | `chore/` | Dependency bumps, config tweaks |
61
+
62
+ Example: `feat/aes-encryption`, `fix/hmac-verification`
63
+
64
+ ## Conventional Commits
65
+
66
+ Every commit message must follow [Conventional Commits](https://www.conventionalcommits.org/):
67
+
68
+ ```
69
+ <type>: <short description in imperative mood>
70
+
71
+ Optional longer explanation.
72
+ ```
73
+
74
+ Types match the branch prefixes: `feat:`, `fix:`, `refactor:`, `test:`,
75
+ `docs:`, `ci:`, `chore:`.
76
+
77
+ Good examples:
78
+
79
+ ```
80
+ feat: add XOR cipher encryption
81
+ fix: resolve HMAC key encoding issue
82
+ docs: add Caesar cipher concept page
83
+ ```
84
+
85
+ Bad examples:
86
+
87
+ ```
88
+ updated stuff # no type, vague description
89
+ feat: adds hashing # not imperative mood ("adds" -> "add")
90
+ ```
91
+
92
+ ## Code Style
93
+
94
+ ### Modern Python
95
+
96
+ Use Python 3.14 idioms everywhere:
97
+
98
+ - `X | Y` for union types (not `Union[X, Y]` or `Optional[X]`)
99
+ - `StrEnum` for string enumerations
100
+ - `match/case` instead of if/elif chains where appropriate
101
+ - Direct imports: `from enum import StrEnum` not `import enum`
102
+
103
+ ### Docstrings
104
+
105
+ Every public function, method, class, and module needs a docstring:
106
+
107
+ - Use **imperative mood**: "Return the record." not "Returns the record."
108
+ - One-liner for simple functions, multi-line (Google style) for complex ones.
109
+
110
+ ```python
111
+ def sha256(data: str) -> str:
112
+ """Calculate the SHA-256 hash of a string."""
113
+
114
+ def derive_key(
115
+ password: str,
116
+ salt: bytes | None = None,
117
+ ) -> tuple[bytes, bytes]:
118
+ """Derive a cryptographic key from a password.
119
+
120
+ Args:
121
+ password: The password to derive from.
122
+ salt: Random salt bytes (generated if not provided).
123
+
124
+ Returns:
125
+ A tuple of (derived_key, salt).
126
+
127
+ Raises:
128
+ ValueError: If the password is empty.
129
+ """
130
+ ```
131
+
132
+ ### Named Constants
133
+
134
+ Use named constants instead of magic numbers in tests and source code. Ruff
135
+ rule PLR2004 enforces this.
136
+
137
+ ```python
138
+ # Good
139
+ SHA256_HEX_LENGTH = 64
140
+ assert len(result) == SHA256_HEX_LENGTH
141
+
142
+ # Bad
143
+ assert len(result) == 64
144
+ ```
145
+
146
+ ## Linting and Type Checking
147
+
148
+ Run these before every commit (pre-commit hooks enforce them automatically):
149
+
150
+ ```bash
151
+ uv run ruff check src/ tests/ # lint
152
+ uv run ruff format src/ tests/ # format (or --check to verify)
153
+ uv run pyright src tests # type check (strict mode)
154
+ ```
155
+
156
+ Fix all violations. Inline `# noqa:` is acceptable only when tools genuinely
157
+ conflict (e.g., ARG002 vs pyright protocol parameter names).
158
+
159
+ ## Testing
160
+
161
+ ```bash
162
+ uv run pytest # run all tests
163
+ uv run pytest --cov # with coverage report
164
+ uv run pytest tests/test_x.py # run a specific file
165
+ uv run pytest -k "test_name" # run tests matching a pattern
166
+ ```
167
+
168
+ - Minimum **80% coverage** is enforced.
169
+ - Test classes and methods need docstrings too.
170
+ - Use `pytest.raises` as a context manager for exception testing.
171
+
172
+ ## Documentation Style
173
+
174
+ Our docs target a **12-year-old with an interest in computing**. Keep language
175
+ simple, use analogies, and avoid jargon without explanation.
176
+
177
+ Good:
178
+
179
+ > A hash is like a meat grinder: put any data in, get a fixed-size fingerprint
180
+ > out. You can't reverse it, but the same input always gives the same result.
181
+
182
+ Bad:
183
+
184
+ > A cryptographic hash function is a deterministic one-way mapping from an
185
+ > arbitrary-length input domain to a fixed-length output codomain.
186
+
187
+ ## Pull Request Process
188
+
189
+ 1. Create a feature branch from `main`.
190
+ 2. Make your changes following TDD.
191
+ 3. Ensure all checks pass: `uv run ruff check .`, `uv run pyright src tests`,
192
+ `uv run pytest --cov`.
193
+ 4. Push your branch and open a PR against `main`.
194
+ 5. PRs are squash-merged to keep history clean.
195
+
196
+ ## Questions?
197
+
198
+ Open an issue on [GitHub](https://github.com/robcox2910/pycrypt/issues) --
199
+ we're happy to help!
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rob Cox
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,225 @@
1
+ Metadata-Version: 2.5
2
+ Name: fromscratch-pycrypt
3
+ Version: 0.2.0
4
+ Summary: An educational cryptography library built from scratch in Python
5
+ Project-URL: Homepage, https://github.com/robcox2910/pycrypt
6
+ Project-URL: Repository, https://github.com/robcox2910/pycrypt
7
+ Project-URL: Issues, https://github.com/robcox2910/pycrypt/issues
8
+ Project-URL: Documentation, https://robcox2910.github.io/pycrypt/
9
+ Author: Rob Cox
10
+ License: MIT
11
+ License-File: LICENSE
12
+ Keywords: cryptography,education,encryption,hashing
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Education
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Topic :: Education
19
+ Classifier: Topic :: Security :: Cryptography
20
+ Classifier: Typing :: Typed
21
+ Requires-Python: >=3.14
22
+ Provides-Extra: dev
23
+ Requires-Dist: commitizen>=4.4.0; extra == 'dev'
24
+ Requires-Dist: hypothesis>=6.170; extra == 'dev'
25
+ Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
26
+ Requires-Dist: pre-commit>=4.0.1; extra == 'dev'
27
+ Requires-Dist: pyright>=1.1.400; extra == 'dev'
28
+ Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
29
+ Requires-Dist: pytest>=8.3.4; extra == 'dev'
30
+ Requires-Dist: ruff>=0.9.3; extra == 'dev'
31
+ Description-Content-Type: text/markdown
32
+
33
+ # PyCrypt
34
+
35
+ **An educational cryptography library in plain Python.** The classic
36
+ ciphers (Caesar, XOR) are built from scratch; the modern primitives
37
+ (SHA-256, HMAC, PBKDF2) wrap Python's battle-tested `hashlib`/`hmac`
38
+ standard library so you can see how the pieces fit together.
39
+
40
+ > ⚠️ **For LEARNING, not real security.** The Caesar and XOR ciphers
41
+ > and the homemade-style signatures here are easy to break. Never use
42
+ > PyCrypt to protect real passwords, messages, or secrets -- use a
43
+ > vetted library like `cryptography` for that.
44
+
45
+ ## What Is Cryptography?
46
+
47
+ Imagine you want to pass a secret note to your friend in class, but you don't
48
+ want anyone else to read it. You could write it in a secret code that only you
49
+ and your friend understand. That's cryptography!
50
+
51
+ Cryptography is the science of keeping information secret and safe. It's used
52
+ every time you:
53
+
54
+ - Send a text message
55
+ - Log in to a website
56
+ - Pay for something online
57
+ - Download an app
58
+
59
+ PyCrypt teaches you how all of this works by building each piece from scratch.
60
+
61
+ ## Examples
62
+
63
+ ### Hashing -- One-Way Fingerprints
64
+
65
+ A hash turns any text into a fixed-size "fingerprint." You can't reverse it,
66
+ but the same input always gives the same fingerprint.
67
+
68
+ ```python
69
+ from pycrypt.hashing import sha256
70
+
71
+ # Same input always gives the same hash
72
+ print(sha256("hello")) # "2cf24dba5fb0a30e..."
73
+ print(sha256("hello")) # "2cf24dba5fb0a30e..." (identical!)
74
+
75
+ # Even a tiny change makes a completely different hash
76
+ print(sha256("Hello")) # "185f8db32271fe25..." (totally different!)
77
+ ```
78
+
79
+ ### Caesar Cipher -- The Secret Decoder Ring
80
+
81
+ Shift every letter by a number. A becomes D (shift 3), B becomes E, and so on.
82
+ It wraps around, so Z becomes C.
83
+
84
+ ```python
85
+ from pycrypt.caesar import encrypt, decrypt, brute_force
86
+
87
+ secret = encrypt("HELLO WORLD", shift=3)
88
+ print(secret) # "KHOOR ZRUOG"
89
+
90
+ original = decrypt(secret, shift=3)
91
+ print(original) # "HELLO WORLD"
92
+
93
+ # Try all 26 possible shifts to crack it!
94
+ for shift, text in brute_force(secret):
95
+ print(f"Shift {shift}: {text}")
96
+ ```
97
+
98
+ ### XOR Cipher -- Flipping Switches
99
+
100
+ XOR is its own inverse -- encrypt and decrypt use the exact same operation.
101
+ Real ciphers like AES use XOR inside, but a short repeating key like ours is
102
+ easy to break -- **for learning only**.
103
+
104
+ ```python
105
+ from pycrypt.xor import xor_encrypt, xor_encrypt_bytes
106
+
107
+ encrypted = xor_encrypt("secret message", key="mykey")
108
+ print(encrypted) # looks like random bytes
109
+
110
+ # Decrypt by XOR-ing again with the same key
111
+ decrypted = xor_encrypt_bytes(encrypted, b"mykey").decode("utf-8")
112
+ print(decrypted) # "secret message"
113
+ ```
114
+
115
+ ### HMAC -- Tamper-Evident Seals
116
+
117
+ HMAC is like a wax seal on an envelope. If someone changes the message, the
118
+ seal breaks.
119
+
120
+ ```python
121
+ from pycrypt.hmac import hmac_sign, hmac_verify
122
+
123
+ tag = hmac_sign("transfer $10", key="shared-secret")
124
+ print(hmac_verify("transfer $10", tag, key="shared-secret")) # True
125
+ print(hmac_verify("transfer $1000", tag, key="shared-secret")) # False!
126
+ ```
127
+
128
+ ### Digital Signatures -- A Shared Wax Seal
129
+
130
+ A digital signature proves who wrote a message and that it hasn't been
131
+ changed. Our version is like a wax seal that only you and your friend
132
+ know how to make: you both share one secret key, and that same key is
133
+ used to sign *and* to verify. (Real systems like RSA use a separate
134
+ private key to sign and a public key anyone can verify with.)
135
+
136
+ ```python
137
+ import os
138
+ from pycrypt.signatures import sign, verify
139
+
140
+ # You and your friend share this one secret key.
141
+ key = os.urandom(32)
142
+
143
+ signature = sign("I wrote this!", key)
144
+ print(verify("I wrote this!", signature, key)) # True
145
+ print(verify("I didn't write this", signature, key)) # False
146
+ ```
147
+
148
+ ## Features
149
+
150
+ - **Hashing** -- SHA-256 and MD5 fingerprints
151
+ - **Caesar Cipher** -- Shift-based encryption with brute-force cracking
152
+ - **XOR Cipher** -- Symmetric encryption using bitwise XOR
153
+ - **Key Derivation** -- Turn passwords into strong keys with PBKDF2
154
+ - **HMAC** -- Tamper-proof message authentication codes
155
+ - **Digital Signatures** -- Sign and verify messages with a shared secret key
156
+ - **CLI Tool** -- A demo that prints hashing, Caesar, XOR, and HMAC examples
157
+ - **100% Typed** -- Full type annotations with strict Pyright checking
158
+
159
+ ## Quick Start
160
+
161
+ ```bash
162
+ # Install with uv
163
+ uv add pycrypt
164
+
165
+ # Or install from source
166
+ git clone https://github.com/robcox2910/pycrypt.git
167
+ cd pycrypt
168
+ uv sync --all-extras
169
+
170
+ # Run the CLI demo
171
+ uv run pycrypt
172
+
173
+ # Run the tests
174
+ uv run pytest
175
+ ```
176
+
177
+ <!-- docs:start -->
178
+ ## Documentation
179
+
180
+ Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pycrypt/
181
+ <!-- docs:end -->
182
+
183
+ ## Releasing
184
+
185
+ Other projects in the series ([PyStack](https://github.com/robcox2910/pystack)) use a pinned release of this one,
186
+ not whatever is on `main`. To publish a change for them:
187
+
188
+ 1. Merge the change to `main`.
189
+ 2. Tag it: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
190
+ A change to the public API bumps the minor version (`v0.1.0` → `v0.2.0`);
191
+ anything else bumps the patch (`v0.1.0` → `v0.1.1`).
192
+ 3. In each project that uses it, edit the tag in `[tool.uv.sources]`, run
193
+ `uv lock --upgrade-package <name>`, and open a pull request so CI checks
194
+ the pair together.
195
+
196
+ <!-- series:start -->
197
+ ## Related Projects
198
+
199
+ This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the [series home](https://robcox2910.github.io/) for the full story.
200
+
201
+ | Project | What it teaches | Repository | Docs |
202
+ | --- | --- | --- | --- |
203
+ | PyOS | Operating systems | [py-os](https://github.com/robcox2910/py-os) | [Docs](https://robcox2910.github.io/py-os/) |
204
+ | Pebble | Compilers and programming languages | [pebble-lang](https://github.com/robcox2910/pebble-lang) | [Docs](https://robcox2910.github.io/pebble-lang/) |
205
+ | PyDB | Relational databases | [pydb](https://github.com/robcox2910/pydb) | [Docs](https://robcox2910.github.io/pydb/) |
206
+ | PyKV | Key-value stores | [pykv](https://github.com/robcox2910/pykv) | [Docs](https://robcox2910.github.io/pykv/) |
207
+ | PyDocDB | Document databases | [pydoc-db](https://github.com/robcox2910/pydoc-db) | [Docs](https://robcox2910.github.io/pydoc-db/) |
208
+ | PyGraphDB | Graph databases | [pygraphdb](https://github.com/robcox2910/pygraphdb) | [Docs](https://robcox2910.github.io/pygraphdb/) |
209
+ | PyTSDB | Time-series databases | [pytsdb](https://github.com/robcox2910/pytsdb) | [Docs](https://robcox2910.github.io/pytsdb/) |
210
+ | PyVecDB | Vector databases | [pyvecdb](https://github.com/robcox2910/pyvecdb) | [Docs](https://robcox2910.github.io/pyvecdb/) |
211
+ | PyColDB | Column-family databases | [pycoldb](https://github.com/robcox2910/pycoldb) | [Docs](https://robcox2910.github.io/pycoldb/) |
212
+ | **PyCrypt** | **Cryptography** | [pycrypt](https://github.com/robcox2910/pycrypt) | [Docs](https://robcox2910.github.io/pycrypt/) |
213
+ | PyNet | Computer networking | [pynet](https://github.com/robcox2910/pynet) | [Docs](https://robcox2910.github.io/pynet/) |
214
+ | PyWeb | HTTP web servers | [pyweb](https://github.com/robcox2910/pyweb) | [Docs](https://robcox2910.github.io/pyweb/) |
215
+ | PyGit | Version control | [pygit](https://github.com/robcox2910/pygit) | [Docs](https://robcox2910.github.io/pygit/) |
216
+ | PySearch | Search engines | [pysearch](https://github.com/robcox2910/pysearch) | [Docs](https://robcox2910.github.io/pysearch/) |
217
+ | PyMQ | Message queues | [pymq](https://github.com/robcox2910/pymq) | [Docs](https://robcox2910.github.io/pymq/) |
218
+ | PyLLM | Language models (the brain) | [pyllm](https://github.com/robcox2910/pyllm) | [Docs](https://robcox2910.github.io/pyllm/) |
219
+ | PyScheduler | Job scheduling | [pyscheduler](https://github.com/robcox2910/pyscheduler) | [Docs](https://robcox2910.github.io/pyscheduler/) |
220
+ | PyStack | Full-stack integration | [pystack](https://github.com/robcox2910/pystack) | [Docs](https://robcox2910.github.io/pystack/) |
221
+ <!-- series:end -->
222
+
223
+ ## License
224
+
225
+ MIT -- see [LICENSE](LICENSE) for details.