provably 0.1.0__tar.gz

provably-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+.eggs/
+*.egg
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+site/
+.venv/
+venv/
+.env
+.uv/
+uv.lock

provably-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.0 (2026-02-28)
+
+Initial release.
+
+- `@verified` decorator for Z3-backed formal verification of Python functions
+- Refinement types via `typing.Annotated` (`Ge`, `Le`, `Gt`, `Lt`, `Between`, `NotEq`)
+- Python AST → Z3 translator supporting arithmetic, comparisons, if/elif/else, early returns, min/max/abs
+- Bounded `for i in range(N)` loop unrolling (N must be a compile-time constant)
+- Proof certificates attached to functions as `func.__proof__`
+- `ProofCertificate.to_json()` / `from_json()` for serialization
+- Module-level constant resolution from function globals
+- Compositionality via `contracts=` parameter
+- `@runtime_checked` decorator for pre/post contract checking without Z3
+- `verify_module()` for batch verification of all `@verified` functions in a module
+- `configure()` for global settings (timeout, raise_on_failure, log_level)
+- Convenience type aliases: `Positive`, `NonNegative`, `UnitInterval`
+- Deprecated `strict=` parameter on `@verified`; replaced by `raise_on_failure=`
+- Graceful handling of async functions (attach SKIPPED cert, no crash)
+- Contract arity validation with actionable error messages
+- Line number information in `TranslationError` messages
+- `z3-solver` is a required dependency, installed automatically with `pip install provably`

provably-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tim Jacoby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

provably-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: provably
+Version: 0.1.0
+Summary: Proof-carrying Python functions via Z3 — annotate, verify, ship.
+Project-URL: Homepage, https://github.com/awkronos/provably
+Project-URL: Documentation, https://awkronos.github.io/provably
+Project-URL: Repository, https://github.com/awkronos/provably
+Project-URL: Bug Tracker, https://github.com/awkronos/provably/issues
+Project-URL: Changelog, https://github.com/awkronos/provably/blob/main/CHANGELOG.md
+Author: Tim Jacoby
+License-Expression: MIT
+License-File: LICENSE
+Keywords: contracts,formal-verification,refinement-types,static-analysis,z3
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: z3-solver>=4.12
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mkdocs-autorefs>=1.0; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'dev'
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.14.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-autorefs>=1.0; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# provably
+
+**Z3-backed formal verification for Python -- via decorators and refinement types**
+
+[![PyPI version](https://img.shields.io/pypi/v/provably?color=gold&labelColor=0a0a0f)](https://pypi.org/project/provably/)
+[![Python versions](https://img.shields.io/pypi/pyversions/provably?labelColor=0a0a0f)](https://pypi.org/project/provably/)
+[![License](https://img.shields.io/badge/license-MIT-green?labelColor=0a0a0f)](LICENSE)
+[![CI](https://github.com/awkronos/provably/actions/workflows/ci.yml/badge.svg)](https://github.com/awkronos/provably/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen?labelColor=0a0a0f)](https://github.com/awkronos/provably/actions/workflows/ci.yml)
+[![Typed](https://img.shields.io/badge/types-mypy%20strict-blue?labelColor=0a0a0f)](https://mypy.readthedocs.io/)
+[![Docs](https://img.shields.io/badge/docs-awkronos.github.io-blue?labelColor=0a0a0f)](https://awkronos.github.io/provably/)
+
+---
+
+```python
+from provably import verified
+
+@verified(
+    pre=lambda val, lo, hi: lo <= hi,
+    post=lambda val, lo, hi, result: (result >= lo) & (result <= hi),
+)
+def clamp(val: float, lo: float, hi: float) -> float:
+    if val < lo:
+        return lo
+    elif val > hi:
+        return hi
+    else:
+        return val
+
+clamp.__proof__.verified   # True — for ALL inputs where lo <= hi
+str(clamp.__proof__)       # "[Q.E.D.] clamp"
+```
+
+`verified=True` is a mathematical proof. Z3 determined that **no input** satisfying
+the precondition can violate the postcondition.
+
+## Install
+
+```bash
+pip install provably
+# or: uv add provably
+```
+
+## Examples
+
+### Pre/post contracts
+
+```python
+@verified(
+    pre=lambda a, b: b > 0,
+    post=lambda a, b, result: (result >= 0) & (result < b),
+)
+def modulo(a: int, b: int) -> int:
+    return a % b
+
+modulo.__proof__.verified        # True
+modulo.__proof__.solver_time_ms  # ~2ms
+```
+
+### Refinement types
+
+```python
+from typing import Annotated
+from provably.types import Between, Gt, NonNegative
+
+@verified(post=lambda p, x, result: result >= 0)
+def scale(
+    p: Annotated[float, Between(0, 1)],
+    x: Annotated[float, Gt(0)],
+) -> NonNegative:
+    return p * x
+
+scale.__proof__.verified  # True
+```
+
+### Counterexample extraction
+
+```python
+@verified(
+    pre=lambda n: n >= 0,
+    post=lambda n, result: result * result == n,  # wrong
+)
+def bad_sqrt(n: int) -> int:
+    return n // 2
+
+bad_sqrt.__proof__.counterexample  # {'n': 3, '__return__': 1}
+```
+
+### Compositionality
+
+```python
+@verified(
+    contracts={"my_abs": my_abs.__contract__},
+    post=lambda x, y, result: result >= 0,
+)
+def manhattan(x: float, y: float) -> float:
+    return my_abs(x) + my_abs(y)
+
+manhattan.__proof__.verified  # True
+```
+
+## Supported constructs
+
+| Construct | Supported |
+|---|---|
+| `+`, `-`, `*`, `//`, `/`, `%`, `**n` | Yes |
+| `<`, `<=`, `>`, `>=`, `==`, `!=` | Yes |
+| `and`, `or`, `not`, `&`, `\|`, `~` | Yes |
+| `if`/`elif`/`else`/ternary | Yes |
+| `min`, `max`, `abs` | Yes |
+| `Annotated` refinement types | Yes |
+| Calls via `contracts=` | Yes |
+| `while` loops, unbounded `for` | No |
+| `for i in range(N)` (literal N, max 256) | Yes (unrolled) |
+| Recursion | No |
+| `str`, `list`, `dict` | No |
+
+## Comparison
+
+| Library | Approach | Proof strength | Call-site overhead |
+|---|---|---|---|
+| **provably** | SMT / Z3 | Mathematical proof | Zero solver overhead |
+| `deal` | Runtime contracts | Bug finding | Per-call |
+| `icontract` | Runtime contracts | Bug finding | Per-call |
+| `CrossHair` | Symbolic execution | Property testing | Test-time |
+| `beartype` | Runtime types | Type checking | Per-call |
+
+## Links
+
+- [Documentation](https://awkronos.github.io/provably/)
+- [Getting started](https://awkronos.github.io/provably/getting-started/)
+- [How it works](https://awkronos.github.io/provably/concepts/how-it-works/)
+- [Self-proof](https://awkronos.github.io/provably/self-proof/)
+- [API reference](https://awkronos.github.io/provably/api/decorators/)
+- [Changelog](CHANGELOG.md) | [License](LICENSE) (MIT)

provably-0.1.0/README.md

@@ -0,0 +1,135 @@
+# provably
+
+**Z3-backed formal verification for Python -- via decorators and refinement types**
+
+[![PyPI version](https://img.shields.io/pypi/v/provably?color=gold&labelColor=0a0a0f)](https://pypi.org/project/provably/)
+[![Python versions](https://img.shields.io/pypi/pyversions/provably?labelColor=0a0a0f)](https://pypi.org/project/provably/)
+[![License](https://img.shields.io/badge/license-MIT-green?labelColor=0a0a0f)](LICENSE)
+[![CI](https://github.com/awkronos/provably/actions/workflows/ci.yml/badge.svg)](https://github.com/awkronos/provably/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen?labelColor=0a0a0f)](https://github.com/awkronos/provably/actions/workflows/ci.yml)
+[![Typed](https://img.shields.io/badge/types-mypy%20strict-blue?labelColor=0a0a0f)](https://mypy.readthedocs.io/)
+[![Docs](https://img.shields.io/badge/docs-awkronos.github.io-blue?labelColor=0a0a0f)](https://awkronos.github.io/provably/)
+
+---
+
+```python
+from provably import verified
+
+@verified(
+    pre=lambda val, lo, hi: lo <= hi,
+    post=lambda val, lo, hi, result: (result >= lo) & (result <= hi),
+)
+def clamp(val: float, lo: float, hi: float) -> float:
+    if val < lo:
+        return lo
+    elif val > hi:
+        return hi
+    else:
+        return val
+
+clamp.__proof__.verified   # True — for ALL inputs where lo <= hi
+str(clamp.__proof__)       # "[Q.E.D.] clamp"
+```
+
+`verified=True` is a mathematical proof. Z3 determined that **no input** satisfying
+the precondition can violate the postcondition.
+
+## Install
+
+```bash
+pip install provably
+# or: uv add provably
+```
+
+## Examples
+
+### Pre/post contracts
+
+```python
+@verified(
+    pre=lambda a, b: b > 0,
+    post=lambda a, b, result: (result >= 0) & (result < b),
+)
+def modulo(a: int, b: int) -> int:
+    return a % b
+
+modulo.__proof__.verified        # True
+modulo.__proof__.solver_time_ms  # ~2ms
+```
+
+### Refinement types
+
+```python
+from typing import Annotated
+from provably.types import Between, Gt, NonNegative
+
+@verified(post=lambda p, x, result: result >= 0)
+def scale(
+    p: Annotated[float, Between(0, 1)],
+    x: Annotated[float, Gt(0)],
+) -> NonNegative:
+    return p * x
+
+scale.__proof__.verified  # True
+```
+
+### Counterexample extraction
+
+```python
+@verified(
+    pre=lambda n: n >= 0,
+    post=lambda n, result: result * result == n,  # wrong
+)
+def bad_sqrt(n: int) -> int:
+    return n // 2
+
+bad_sqrt.__proof__.counterexample  # {'n': 3, '__return__': 1}
+```
+
+### Compositionality
+
+```python
+@verified(
+    contracts={"my_abs": my_abs.__contract__},
+    post=lambda x, y, result: result >= 0,
+)
+def manhattan(x: float, y: float) -> float:
+    return my_abs(x) + my_abs(y)
+
+manhattan.__proof__.verified  # True
+```
+
+## Supported constructs
+
+| Construct | Supported |
+|---|---|
+| `+`, `-`, `*`, `//`, `/`, `%`, `**n` | Yes |
+| `<`, `<=`, `>`, `>=`, `==`, `!=` | Yes |
+| `and`, `or`, `not`, `&`, `\|`, `~` | Yes |
+| `if`/`elif`/`else`/ternary | Yes |
+| `min`, `max`, `abs` | Yes |
+| `Annotated` refinement types | Yes |
+| Calls via `contracts=` | Yes |
+| `while` loops, unbounded `for` | No |
+| `for i in range(N)` (literal N, max 256) | Yes (unrolled) |
+| Recursion | No |
+| `str`, `list`, `dict` | No |
+
+## Comparison
+
+| Library | Approach | Proof strength | Call-site overhead |
+|---|---|---|---|
+| **provably** | SMT / Z3 | Mathematical proof | Zero solver overhead |
+| `deal` | Runtime contracts | Bug finding | Per-call |
+| `icontract` | Runtime contracts | Bug finding | Per-call |
+| `CrossHair` | Symbolic execution | Property testing | Test-time |
+| `beartype` | Runtime types | Type checking | Per-call |
+
+## Links
+
+- [Documentation](https://awkronos.github.io/provably/)
+- [Getting started](https://awkronos.github.io/provably/getting-started/)
+- [How it works](https://awkronos.github.io/provably/concepts/how-it-works/)
+- [Self-proof](https://awkronos.github.io/provably/self-proof/)
+- [API reference](https://awkronos.github.io/provably/api/decorators/)
+- [Changelog](CHANGELOG.md) | [License](LICENSE) (MIT)

provably-0.1.0/pyproject.toml

@@ -0,0 +1,123 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "provably"
+version = "0.1.0"
+description = "Proof-carrying Python functions via Z3 — annotate, verify, ship."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Tim Jacoby" },
+]
+keywords = ["formal-verification", "z3", "contracts", "refinement-types", "static-analysis"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+requires-python = ">=3.10"
+dependencies = ["z3-solver>=4.12"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=6.0",
+    "pytest-timeout>=2.2",
+    "pytest-asyncio>=0.23",
+    "hypothesis>=6.100",
+    "mypy>=1.9",
+    "ruff==0.14.0",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.24",
+    "mkdocs-autorefs>=1.0",
+]
+docs = [
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.24",
+    "mkdocs-autorefs>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/awkronos/provably"
+Documentation = "https://awkronos.github.io/provably"
+Repository = "https://github.com/awkronos/provably"
+"Bug Tracker" = "https://github.com/awkronos/provably/issues"
+Changelog = "https://github.com/awkronos/provably/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/LICENSE",
+    "/README.md",
+    "/CHANGELOG.md",
+    "/pyproject.toml",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/provably"]
+
+# ---------------------------------------------------------------------------
+# Ruff
+# ---------------------------------------------------------------------------
+
+[tool.ruff]
+src = ["src"]
+line-length = 99
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM", "TID"]
+ignore = ["E501", "SIM105"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "F401", "F811", "E402", "F841", "E731"]  # tests: assert, unused imports, redefined, late imports, unused vars, lambda assign
+
+# ---------------------------------------------------------------------------
+# Mypy
+# ---------------------------------------------------------------------------
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = false
+warn_unused_ignores = false
+mypy_path = "src"
+
+[[tool.mypy.overrides]]
+module = "z3.*"
+ignore_missing_imports = true
+
+# ---------------------------------------------------------------------------
+# Pytest
+# ---------------------------------------------------------------------------
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+asyncio_mode = "auto"
+
+# ---------------------------------------------------------------------------
+# Coverage
+# ---------------------------------------------------------------------------
+
+[tool.coverage.run]
+source = ["src/provably"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

provably-0.1.0/src/provably/__init__.py

@@ -0,0 +1,73 @@
+"""Provably — proof-carrying Python via Z3.
+
+Annotate functions with contracts, get automatic formal proofs.
+
+    from provably import verified
+    from typing import Annotated
+    from provably.types import Ge
+
+    @verified(
+        pre=lambda x: x >= 0,
+        post=lambda x, result: result >= x,
+    )
+    def double(x: float) -> float:
+        return x * 2
+
+    assert double.__proof__.verified  # Z3-proven for ALL inputs
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from z3 import And, Implies, Not, Or
+
+from .decorators import ContractViolationError, VerificationError, runtime_checked, verified
+from .engine import (
+    ProofCertificate,
+    Status,
+    clear_cache,
+    configure,
+    verify_function,
+    verify_module,
+)
+from .translator import TranslationError
+from .types import (
+    Between,
+    Ge,
+    Gt,
+    Le,
+    Lt,
+    NonNegative,
+    NotEq,
+    Positive,
+    UnitInterval,
+)
+
+__all__ = [
+    "verified",
+    "runtime_checked",
+    "VerificationError",
+    "ContractViolationError",
+    "TranslationError",
+    "verify_function",
+    "verify_module",
+    "ProofCertificate",
+    "Status",
+    "clear_cache",
+    "configure",
+    "Gt",
+    "Ge",
+    "Lt",
+    "Le",
+    "Between",
+    "NotEq",
+    "Positive",
+    "NonNegative",
+    "UnitInterval",
+    "And",
+    "Or",
+    "Not",
+    "Implies",
+    "__version__",
+]