invar-tools 1.7.1__py3-none-any.whl → 1.10.0__py3-none-any.whl

invar/templates/examples/{contracts.py → python/contracts.py}

@@ -1,13 +1,14 @@
+# ruff: noqa: ERA001
 """
 Invar Contract Examples
 
 Reference patterns for @pre/@post contracts and doctests.
 Managed by Invar - do not edit directly.
 """
+# @invar:allow partial_contract: Educational file showing multiple @pre pattern
 
-# For lambda-based contracts, use deal directly
-# invar_runtime.pre/post are for Contract objects (NonEmpty, IsInstance, etc.)
-from deal import post, pre
+# invar_runtime supports both lambda and Contract objects
+from invar_runtime import post, pre
 
 # =============================================================================
 # GOOD: Complete Contract
@@ -80,7 +81,7 @@ def normalize_keys(data: dict[str, int]) -> dict[str, int]:
 # DON'T: Empty contract tells nothing
 # @pre(lambda: True)
 # @post(lambda result: True)
-# def process(x): ...  # noqa: ERA001
+# def process(x): ...
 
 # DON'T: Missing edge cases in doctests
 # def divide(a, b):
@@ -111,3 +112,79 @@ def range_size(start: int, end: int) -> int:
     1
     """
     return end - start
+
+
+# =============================================================================
+# CRITICAL: Default Parameters in Contracts
+# =============================================================================
+# Lambda signatures MUST include ALL parameters, including defaults!
+# This is a common mistake that causes silent contract failures.
+
+
+# DON'T: Missing default parameter in lambda
+# @pre(lambda x: x >= 0)  # BAD: 'y' is missing!
+# def calc_bad(x: int, y: int = 0) -> int:
+#     return x + y
+
+
+# DO: Include all parameters with their defaults
+@pre(lambda x, y=0: x >= 0 and y >= 0)
+@post(lambda result: result >= 0)
+def calculate_with_default(x: int, y: int = 0) -> int:
+    """
+    Calculate sum with optional y.
+
+    The lambda MUST include y=0 to match the function signature.
+
+    >>> calculate_with_default(5)
+    5
+    >>> calculate_with_default(5, 3)
+    8
+    >>> calculate_with_default(0, 0)  # Edge: both zero
+    0
+    """
+    return x + y
+
+
+# =============================================================================
+# CRITICAL: @post Cannot Access Parameters
+# =============================================================================
+# @post only receives the return value, not the original parameters!
+
+
+# DON'T: Reference parameters in @post
+# @post(lambda result: result > x)  # BAD: 'x' is not available!
+# def double_bad(x: int) -> int:
+#     return x * 2
+
+
+# DO: @post only validates the result itself
+@pre(lambda x: x >= 0)
+@post(lambda result: result >= 0)  # GOOD: only uses 'result'
+def double_positive(x: int) -> int:
+    """
+    Double a positive number.
+
+    @post can only validate result properties, not relationships to inputs.
+
+    >>> double_positive(5)
+    10
+    >>> double_positive(0)  # Edge: zero
+    0
+    """
+    return x * 2
+
+
+# =============================================================================
+# Decorator Order with @pre/@post
+# =============================================================================
+# When combining with other decorators, @pre/@post should be closest to function.
+
+
+# DO: @pre/@post closest to function
+# @other_decorator
+# @pre(lambda x: x > 0)
+# @post(lambda result: result > 0)
+# def my_func(x: int) -> int: ...
+
+# This ensures contracts run BEFORE other decorators modify behavior.

invar/templates/examples/python/core_shell.py

@@ -0,0 +1,227 @@
+# ruff: noqa: ERA001
+"""
+Invar Core/Shell Separation Examples
+
+Reference patterns for Core vs Shell architecture.
+Managed by Invar - do not edit directly.
+"""
+# @invar:allow forbidden_import: Example file demonstrates Shell pattern with pathlib
+# @invar:allow missing_contract: Shell functions intentionally without contracts to show pattern
+# @invar:allow contract_quality_ratio: Educational file with Shell examples
+
+from pathlib import Path
+
+# invar_runtime supports both lambda and Contract objects
+from invar_runtime import post, pre
+from returns.result import Failure, Result, Success
+
+# =============================================================================
+# CORE: Pure Logic (no I/O)
+# =============================================================================
+# Location: src/*/core/
+# Requirements: @pre/@post, doctests, no I/O imports
+# =============================================================================
+
+
+# @invar:allow shell_result: Example file - demonstrates Core pattern
+# @shell_orchestration: Example file - demonstrates Core pattern
+@pre(lambda content: content is not None)  # Accepts any string including empty
+@post(lambda result: all(line.strip() == line and line for line in result))  # No whitespace, non-empty
+def parse_lines(content: str) -> list[str]:
+    """
+    Parse content into non-empty lines.
+
+    >>> parse_lines("a\\nb\\nc")
+    ['a', 'b', 'c']
+    >>> parse_lines("")
+    []
+    >>> parse_lines("  \\n  ")  # Edge: whitespace only
+    []
+    """
+    return [line.strip() for line in content.split("\n") if line.strip()]
+
+
+# @invar:allow shell_result: Example file - demonstrates Core pattern
+# @shell_orchestration: Example file - demonstrates Core pattern
+@pre(lambda items: all(isinstance(i, str) for i in items))  # All items must be strings
+@post(lambda result: all(v > 0 for v in result.values()))  # All counts are positive
+def count_items(items: list[str]) -> dict[str, int]:
+    """
+    Count occurrences of each item.
+
+    >>> sorted(count_items(['a', 'b', 'a']).items())
+    [('a', 2), ('b', 1)]
+    >>> count_items([])
+    {}
+    """
+    counts: dict[str, int] = {}
+    for item in items:
+        counts[item] = counts.get(item, 0) + 1
+    return counts
+
+
+# =============================================================================
+# SHELL: I/O Operations
+# =============================================================================
+# Location: src/*/shell/
+# Requirements: Result[T, E] return type, calls Core for logic
+# =============================================================================
+
+
+def read_file(path: Path) -> Result[str, str]:
+    """
+    Read file content.
+
+    Shell handles I/O, returns Result for error handling.
+    """
+    try:
+        return Success(path.read_text())
+    except FileNotFoundError:
+        return Failure(f"File not found: {path}")
+    except PermissionError:
+        return Failure(f"Permission denied: {path}")
+
+
+def count_lines_in_file(path: Path) -> Result[dict[str, int], str]:
+    """
+    Count lines in file - demonstrates Core/Shell integration.
+
+    Shell reads file → Core parses content → Shell returns result.
+    """
+    # Shell: I/O operation
+    content_result = read_file(path)
+
+    if isinstance(content_result, Failure):
+        return content_result
+
+    content = content_result.unwrap()
+
+    # Core: Pure logic (no I/O)
+    lines = parse_lines(content)
+    counts = count_items(lines)
+
+    # Shell: Return result
+    return Success(counts)
+
+
+# =============================================================================
+# ANTI-PATTERNS
+# =============================================================================
+
+# DON'T: I/O in Core
+# def parse_file(path: Path):  # BAD: Path in Core
+#     content = path.read_text()  # BAD: I/O in Core
+#     return parse_lines(content)
+
+# DO: Core receives content, not paths
+# def parse_content(content: str):  # GOOD: receives data
+#     return parse_lines(content)
+
+
+# DON'T: Missing Result in Shell
+# def load_config(path: Path) -> dict:  # BAD: no Result type
+#     return json.loads(path.read_text())  # Exceptions not handled
+
+# DO: Return Result[T, E]
+# def load_config(path: Path) -> Result[dict, str]:  # GOOD
+#     try:
+#         return Success(json.loads(path.read_text()))
+#     except Exception as e:
+#         return Failure(str(e))
+
+
+# =============================================================================
+# FastAPI Integration Pattern
+# =============================================================================
+# Demonstrates how to use Result with FastAPI endpoints.
+# Shell (API handler) → Core (business logic) → Shell (HTTP response)
+
+# NOTE: This is pseudocode - requires FastAPI to be installed
+# from fastapi import FastAPI, HTTPException
+# from pydantic import BaseModel
+
+# class UserResponse(BaseModel):
+#     id: str
+#     name: str
+
+# app = FastAPI()
+
+# CORE: Pure business logic
+# @pre(lambda user_id: len(user_id) > 0)
+# @post(lambda result: result.get("name") is not None)
+# def get_user_data(user_id: str) -> dict:
+#     """Core function - pure logic, receives string ID."""
+#     # Business logic here (no HTTP, no database I/O)
+#     return {"id": user_id, "name": "Demo User"}
+
+# SHELL: I/O layer - database
+# def fetch_user_from_db(user_id: str) -> Result[dict, str]:
+#     """Shell function - database I/O, returns Result."""
+#     try:
+#         # In real code: query database
+#         if user_id == "not-found":
+#             return Failure("User not found")
+#         return Success({"id": user_id, "name": "DB User"})
+#     except Exception as e:
+#         return Failure(f"Database error: {e}")
+
+# SHELL: I/O layer - HTTP endpoint
+# @app.get("/users/{user_id}", response_model=UserResponse)
+# def get_user_endpoint(user_id: str):
+#     """
+#     FastAPI endpoint - Shell layer.
+#
+#     Pattern: Shell → Core → Shell
+#     1. Shell receives HTTP request
+#     2. Core processes business logic
+#     3. Shell converts Result to HTTP response
+#     """
+#     result = fetch_user_from_db(user_id)
+#
+#     # Convert Result to HTTP response
+#     match result:
+#         case Success(user):
+#             return UserResponse(**user)
+#         case Failure(error):
+#             if "not found" in error.lower():
+#                 raise HTTPException(status_code=404, detail=error)
+#             raise HTTPException(status_code=500, detail=error)
+
+
+# =============================================================================
+# Result → HTTP Response Mapping
+# =============================================================================
+# Common pattern for converting Result errors to HTTP status codes:
+#
+# | Error Type      | HTTP Status | When to Use                    |
+# |-----------------|-------------|--------------------------------|
+# | NotFoundError   | 404         | Resource doesn't exist         |
+# | ValidationError | 400         | Invalid input from client      |
+# | AuthError       | 401/403     | Authentication/authorization   |
+# | ConflictError   | 409         | Resource state conflict        |
+# | InternalError   | 500         | Unexpected server error        |
+#
+# Example error types:
+# @dataclass(frozen=True)
+# class NotFoundError:
+#     resource: str
+#     id: str
+#
+# @dataclass(frozen=True)
+# class ValidationError:
+#     field: str
+#     message: str
+#
+# AppError = NotFoundError | ValidationError | str
+#
+# def result_to_response(result: Result[T, AppError]) -> T:
+#     """Convert Result to HTTP response or raise appropriate HTTPException."""
+#     match result:
+#         case Success(value):
+#             return value
+#         case Failure(NotFoundError(resource, id)):
+#             raise HTTPException(404, f"{resource} {id} not found")
+#         case Failure(ValidationError(field, message)):
+#             raise HTTPException(400, f"Invalid {field}: {message}")
+#         case Failure(error):
+#             raise HTTPException(500, str(error))