Skip to main content

tesseraline

PyPI version License: PolyForm Noncommercial 1.0.0 Python 3.12+ Typed

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.4
  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_contains plants canary values in every secret field and searches the output for them, also JSON-escaped, URL-encoded and base64-encoded.
  • invariants.lock records 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 --update can 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.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tesseraline-invariants 0.0.4
File Size Uploaded Provenance Actions
tesseraline_invariants-0.0.4.tar.gz 456.6 kB With provenance Details for tesseraline_invariants-0.0.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tesseraline-invariants 0.0.4
File Interpreter ABI Platform Actions
tesseraline_invariants-0.0.4-py3-none-any.whl Python 3 none any Details for tesseraline_invariants-0.0.4-py3-none-any.whl

Total release size: 519.8 kB

Release files / tesseraline_invariants-0.0.4.tar.gz

Download URL tesseraline_invariants-0.0.4.tar.gz
Size 456.6 kB
Tags Source
SHA-256 checksum
How to use checksums
c05edb3fde993e009523b4450f4ab6811515339ab6fadbf43d86a4abec68d1d3
BLAKE2b-256 checksum
How to use checksums
a76707e857bdfb2f02c53a15cfcbe554d4ffdf8db2b45d274c7dd308fb26eafd
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 log

Release files / tesseraline_invariants-0.0.4-py3-none-any.whl

Download URL tesseraline_invariants-0.0.4-py3-none-any.whl
Size 63.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d501f57643d003eeea4c8a4d0e0cebfef4f89a636c547f5d4fc93ca2e3ec3e79
BLAKE2b-256 checksum
How to use checksums
ddf4c41d2d78f8e4ddcf7149b553c869e72d3a1cd17f1635f75c7bef5bcba701
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 log

Security for tesseraline-invariants 0.0.4

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.

Select from 2 files

Attestation for tesseraline_invariants-0.0.4.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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page