3tears-enforcement

Shared static-analysis enforcement scanners for the 3tears ecosystem.

What this package does

Each module under threetears.enforcement.<domain> ships an AST-based scanner that enforces a single architectural invariant across a Python source tree. Consumer repos import the scanner, inject their per-repo configuration (allowlists, exemption files, src roots), and run it from a thin pytest test class.

This replaces a previous pattern in which the same enforcement test files were vendored verbatim across multiple repos with manual sync requirements. The shared package eliminates duplication and drift while keeping per-repo configuration where it belongs.

Domains

Module Invariant enforced
cache Every stateful data surface routes through BaseCollection; no bespoke SQLiteBackend wrappers; no direct pool access to Collection-backed tables; every migration-defined table has a Collection class.
underscore_access Underscore prefix is a stability contract: no cross-module private import, no cross-class protected access, modules with public names have __all__, no subclass shadowing of base private attributes, no __all__ listing private names.
codebase_conventions No bare print(), no stdlib logging.getLogger (use threetears.observe), from __future__ import annotations required, return type annotations required.
coercion_coverage Tool subclasses override execute, never run, preserving the normalize_kwargs → execute input-coercion path.
dependency_alignment Declared dependencies match actual imports (no undeclared module-top sibling import, no declaration nothing imports); designated contracts packages import only stdlib, their own namespace, and configured extras; a package with a pinned DependencyFloor declares exactly the ruled hard-dependency list, no more and no fewer.
dict_state_detection No raw dict/OrderedDict persistent state in __init__; use SQLiteBackend (L1) or NATS KV for shared state.
logger_coverage Every production module declares a module-level log = get_logger(__name__) unless explicitly exempt.
migration_yugabyte_safety Migration shapes are yugabyte-safe per threetears.core.data.migrations.enforcement.
nats_wrapper_usage All nats-py imports route through threetears.nats.NatsClient; no direct import nats.
no_silent_swallow Exception handlers must log, re-raise, or carry # NOSILENT: <reason>.
no_stdlib_logging No production module imports stdlib logging directly; use threetears.observe.

How to use it

Each domain exposes a configuration dataclass and a high-level runner:

# tests/enforcement/test_cache_primitive_usage.py
from pathlib import Path
from threetears.enforcement.cache import CacheEnforcementConfig, run_cache_enforcement

_CONFIG = CacheEnforcementConfig(
    repo_root=Path(__file__).parents[2],
    allowed_sqlite_construction_sites=frozenset({
        "packages/registry/src/threetears/registry/l1_cache.py",
    }),
    collection_table_allowlist={
        "memories": "MemoriesCollection",
        # ... per-repo
    },
    migration_table_allowlist=frozenset({"_schema_migrations"}),
    exemptions_path=Path(__file__).parent / "_cache_exemptions.txt",
    enforcement_mode_env_var="CACHE_ENFORCEMENT_MODE",
)

class TestCachePrimitiveUsage:
    def test_no_bespoke_sqlite_backend_construction(self) -> None:
        run_cache_enforcement(_CONFIG, walker="sqlite_construction")

    def test_no_bespoke_cache_wrapper_classes(self) -> None:
        run_cache_enforcement(_CONFIG, walker="wrapper_class")

    def test_no_direct_pool_access_to_collection_tables(self) -> None:
        run_cache_enforcement(_CONFIG, walker="pool_access")

    def test_all_tables_have_collections(self) -> None:
        run_cache_enforcement(_CONFIG, walker="missing_collection")

Per-repo exemption files (e.g., _cache_exemptions.txt) stay in the consumer repo's tests/enforcement/ directory. The package's parse_exemptions_with_rationale reads them at test time.

How to onboard a new repo

  1. Add 3tears-enforcement as a dev dependency.
  2. For each domain you want to enforce: create a thin shell test file at tests/enforcement/test_<domain>.py following the pattern above. Inject your repo's allowlists/exemptions.
  3. Create per-domain exemption files at tests/enforcement/_<domain>_exemptions.txt if needed. Every exemption requires a preceding # rationale: <specific reason> line.
  4. Run pytest tests/enforcement/ to verify the scanners work against your tree.

How to add a new enforcement domain

  1. Create src/threetears/enforcement/<domain>/ with walkers.py, config.py, runner.py, and __init__.py.
  2. Use common/ helpers (ast_helpers, repo_layout, pyproject_discovery, inheritance, exemptions, modes, violations, reports). Do not duplicate scaffolding.
  3. Walkers return list[Violation]. Configs are frozen dataclasses. Runners orchestrate walker → exemption-application → mode-resolution → report.
  4. Write unit tests in tests/<domain>/.
  5. Document the domain in this README.

Project links

Data verified by PyPI on Aug 18, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.41.4)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for pace from gravatar.com pace

Credits

Author: pace

GitHub Statistics

Data verified by PyPI on Aug 18, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.14

Provides Extra

test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

3tears_enforcement-0.26.1.tar.gz (176.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

3tears_enforcement-0.26.1-py3-none-any.whl (168.8 kB view details)

Uploaded Python 3

File details

Details for the file 3tears_enforcement-0.26.1.tar.gz.

File metadata

  • Download URL: 3tears_enforcement-0.26.1.tar.gz
  • Upload date:
  • Size: 176.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for 3tears_enforcement-0.26.1.tar.gz
Algorithm Hash digest
SHA256 9d705f1743efc72ba7bd2ada2754ba8bf4713d1579e111234eddf5e06b9ece3c
MD5 45c8f9aa22407d8b51844f5a9d617440
BLAKE2b-256 059f6739e2fb94a3ad252b2b519d03e454b297965f90b1fee20281000d105be9

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_enforcement-0.26.1.tar.gz:

Publisher: release.yml on pacepace/3tears

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file 3tears_enforcement-0.26.1-py3-none-any.whl.

File metadata

File hashes

Hashes for 3tears_enforcement-0.26.1-py3-none-any.whl
Algorithm Hash digest
SHA256 d33e7b1dab8bda4c726fd8591f6f066679588013515fb7a3d652f3a17414ef16
MD5 9e47bb1b5a6c3dbd26570cf5afa1d3b1
BLAKE2b-256 1d9c8dcb2d98dea0d6456c2df0110e94feae635b8a1efdea8956643872bb0e93

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_enforcement-0.26.1-py3-none-any.whl:

Publisher: release.yml on pacepace/3tears

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.41.4

2 files

0.41.3

2 files

0.41.2

2 files

0.41.1

2 files

0.41.0

2 files

0.40.0

2 files

0.39.0

2 files

0.38.0

2 files

0.37.0

2 files

0.36.0

2 files

0.35.1

2 files

0.35.0

2 files

0.34.0

2 files

0.33.0

2 files

0.32.1

2 files

0.32.0

2 files

0.31.0

2 files

0.30.1

2 files

0.30.0

2 files

0.29.0

2 files

0.28.0

2 files

0.27.0

2 files

This release

0.26.1 This release

2 files

0.26.0

2 files

0.25.0

2 files

0.24.7

2 files

0.24.6

2 files

0.24.5

2 files

0.24.4

2 files

0.24.3

2 files

0.24.2

2 files

0.24.1

2 files

0.24.0

2 files

0.23.11

2 files

0.23.10

2 files

0.23.9

2 files

0.23.8

2 files

0.23.7

2 files

0.23.6

2 files

0.23.5

2 files

0.23.3

2 files

0.23.2

2 files

0.23.1

2 files

0.23.0

2 files

0.22.5

2 files

0.22.4

2 files

0.22.3

2 files

0.22.2

2 files

0.22.1

2 files

0.22.0

2 files

0.21.0

2 files

0.20.0

2 files

0.19.4

2 files

0.19.3

2 files

0.19.2

2 files

0.19.1

2 files

0.19.0

2 files

0.18.0

2 files

0.17.9

2 files

0.17.8

2 files

0.17.7

2 files

0.17.6

2 files

0.17.5

2 files

0.17.4

2 files

0.17.3

2 files

0.17.2

2 files

0.17.1

2 files

0.17.0

2 files

0.16.1

2 files

0.16.0

2 files

0.15.0

2 files

0.14.1

2 files

0.14.0

2 files

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