tesseraline-invariants
Know when a change breaks a business rule.
$ pip install tesseraline-invariants
Documentation · Changelog · Security
A function makes promises about its output: it never returns a credential, it keeps every number of its input, its
result adds up. Write the promise next to the function; invariants check runs the function on many inputs and
says, with a minimal failing input, when a later change breaks it.
from dataclasses import dataclass
from tesseraline_invariants import Secret, invariant, never_contains, preserves, holds
@dataclass(frozen=True, slots=True)
class WriteHandle:
table: str
credentials: Secret[str]
@invariant(never_contains(Secret), dry_run=True)
def to_query_json(handle: WriteHandle) -> str: ...
@invariant(preserves("numbers", "dates"), dry_run=True)
def restyle(text: str) -> str: ...
@invariant(holds(lambda inp, out: out.total == sum(inp.items)), dry_run=True)
def summarize(order: Order) -> Summary: ...
$ invariants check # 0 all promises hold, 1 a promise broke, 2 a promise was removed, 3 configuration error
$ invariants list # every promise, where it lives, whether it can be checked
$ invariants lock --update # record the current promises in invariants.lock (review the diff)
$ invariants impact --since main # which promises a change may affect (from imports; never "safe")
$ invariants check --since main # check only those; the lock is still compared with every promise
$ pytest --invariants # the same check as test items (opt-in)
$ semgrep --metrics=off --disable-version-check --config "$(invariants rules)" src/ # point at exits that bypass promises
Install
$ pip install tesseraline-invariants # production: Secret and @invariant, standard library only
$ pip install "tesseraline-invariants[check]" # CI and developers: invariants check, pytest plugin
$ uv tool install semgrep # for invariants scan (kept apart from your project)
Block a commit and a push while a promise is broken or an exit is unguarded, in .pre-commit-config.yaml:
- repo: https://github.com/tesseraline/invariants
rev: v0.0.3
hooks:
- id: invariants-check # promises hold (strict)
- id: invariants-scan # the Semgrep rules for unguarded exits
Install the hooks for both moments: pre-commit install --hook-type pre-commit --hook-type pre-push.
Why not a property test?
- The promise sits next to the code it protects, so nobody has to remember to write the test.
never_containsplants canary values in every secret field and searches the output for them, also JSON-escaped, URL-encoded and base64-encoded.invariants.lockrecords the promises themselves: deleting a decorator to get a green build fails the check.- Every check leaves an audit record: which promise, which code version, which result.
What it does not do (read this first)
- It calls only functions whose author wrote
dry_run=True, meaning "safe to run when every dependency is a fake". Every other promise is reported as not checked; it never counts as a pass. - The network is blocked during a check. Writes to files outside the temporary working directory are not prevented in v0.1.
- A secret that is hashed or truncated before it leaves cannot be found by a canary search.
- No runtime checking in production in v0.1; no model-based judging, ever: checks are code.
lock --updatecan be run by anyone; the protection is that the change shows in review.
Inputs: give your types factories
A check calls each dry_run=True function with saved regressions first, then values from your factories,
then values Hypothesis builds from the types. Random values rarely look like real data: a preserves
promise on text needs real sentences to mean anything. Name a factory per type in settings (below); the
examples/ folder shows the difference.
Settings
pyproject.toml:
[tool.invariants]
modules = ["myapp.exporters", "myapp.reports"] # imported to collect promises
strict = true # "not checked" fails the run
secret_types = ["myapp.auth:Token"] # your own secret types ("module:Class")
secret_fields = ["*password*", "api_key"] # by name: heuristic, opt-in
[tool.invariants.factories]
"myapp.models:WriteHandle" = "myapp.examples.data:example_handles"
"builtins:str" = "myapp.examples.data:example_sentences"
[tool.invariants.fakes]
"myapp.ports:Mailer" = "myapp.examples.fakes:FakeMailer" # Protocol-typed dependencies
Examples of code the check catches and of the same code done right: examples/README.md.
Licence
PolyForm Noncommercial 1.0.0 (LICENSE.md). Personal and other noncommercial use is free. Use by a company, or
any use with a commercial purpose, needs a separate commercial licence: contact Tesseraline through
https://github.com/tesseraline.
Required Notice: Copyright 2026 Tesseraline (https://github.com/tesseraline)
No permission is given to use this code or its documentation to train or evaluate machine learning or AI models,
for any purpose; text and data mining for that purpose is reserved (Article 4(3), Directive (EU) 2019/790). See
LICENSE.md.
Development
$ git clone https://github.com/tesseraline/invariants && cd invariants
$ uv sync --all-extras
$ uv run pytest -q -p no:invariants # the library's own tests; its pytest plugin stays off here
Metadata
Release files for tesseraline-invariants 0.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tesseraline_invariants-0.0.3.tar.gz | 455.7 kB | With provenance | Details for tesseraline_invariants-0.0.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tesseraline_invariants-0.0.3-py3-none-any.whl | Python 3 | none | any | Details for tesseraline_invariants-0.0.3-py3-none-any.whl |
Total release size: 518.7 kB
Release files / tesseraline_invariants-0.0.3.tar.gz
| Download URL | tesseraline_invariants-0.0.3.tar.gz |
|---|---|
| Size | 455.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f592558884248629f25c4feea094ee7252e95c17ab32504fd468b9f8267cecbc
|
|
BLAKE2b-256 checksum How to use checksums |
75bd8d45b6823deb21616863baca1a98efb62fac64dfea602654d5220f405659
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / tesseraline_invariants-0.0.3-py3-none-any.whl
| Download URL | tesseraline_invariants-0.0.3-py3-none-any.whl |
|---|---|
| Size | 63.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c14b5937b9b221642d5c709a9e02f01546508e36830b3ac76ab2ce781cd890ea
|
|
BLAKE2b-256 checksum How to use checksums |
02b6acdec38d21ae770fd2fca63652b445abaf91d98ea21135f97a117edbb07d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for tesseraline-invariants 0.0.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for tesseraline_invariants-0.0.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.