crackerjack 0.18.12__tar.gz → 0.19.0__tar.gz

crackerjack-0.18.12/README.md → crackerjack-0.19.0/PKG-INFO

@@ -1,3 +1,45 @@
+Metadata-Version: 2.1
+Name: crackerjack
+Version: 0.19.0
+Summary: Crackerjack: code quality toolkit
+Keywords: bandit,black,creosote,mypy,pyright,pytest,refurb,ruff
+Author-Email: lesleslie <les@wedgwoodwebworks.com>
+Maintainer-Email: lesleslie <les@wedgwoodwebworks.com>
+License: BSD-3-CLAUSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Project-URL: documentation, https://github.com/lesleslie/crackerjack
+Project-URL: homepage, https://github.com/lesleslie/crackerjack
+Project-URL: repository, https://github.com/lesleslie/crackerjack
+Requires-Python: >=3.13
+Requires-Dist: autotyping>=24.9
+Requires-Dist: pdm>=2.24.2
+Requires-Dist: pdm-bump>=0.9.12
+Requires-Dist: pre-commit>=4.2
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: pytest>=8.3.5
+Requires-Dist: pytest-asyncio>=1
+Requires-Dist: pytest-benchmark>=5.1
+Requires-Dist: pytest-cov>=6.1.1
+Requires-Dist: pytest-mock>=3.14.1
+Requires-Dist: pytest-timeout>=2.4
+Requires-Dist: pytest-xdist>=3.7
+Requires-Dist: rich>=14
+Requires-Dist: tomli-w>=1.2
+Requires-Dist: typer>=0.16
+Requires-Dist: uv>=0.7.9
+Description-Content-Type: text/markdown
+
 # Crackerjack: Elevate Your Python Development
 
 [![Code style: crackerjack](https://img.shields.io/badge/code%20style-crackerjack-000042)](https://github.com/lesleslie/crackerjack)
@@ -135,6 +177,44 @@ Crackerjack projects adhere to these guidelines:
 -   **Clear Code:** Avoid overly complex code.
 -   **Modular:** Functions should do one thing well.
 
+## Testing Features
+
+Crackerjack provides advanced testing capabilities powered by pytest:
+
+### Standard Testing
+
+- **Parallel Test Execution:** Tests run in parallel by default using pytest-xdist for faster execution
+- **Timeout Protection:** All tests have a default 60-second timeout to prevent hanging tests
+- **Coverage Reports:** Automatically generates test coverage reports with configurable thresholds
+
+### Benchmark Testing
+
+Crackerjack includes benchmark testing capabilities:
+
+- **Performance Measurement:** Run tests with `--benchmark` to measure execution time and performance
+- **Regression Testing:** Use `--benchmark-regression` to detect performance regressions
+- **Configurable Thresholds:** Set custom regression thresholds with `--benchmark-regression-threshold`
+- **Compatibility Management:** Automatically disables parallel execution when running benchmarks
+- **CI Integration:** Track performance across commits with benchmark history
+
+When benchmarks are run, Crackerjack:
+1. Disables parallel test execution (as pytest-benchmark is incompatible with pytest-xdist)
+2. Configures the pytest-benchmark plugin with optimized settings
+3. Compares benchmark results against previous runs when regression testing is enabled
+4. Fails tests if performance decreases beyond the specified threshold
+
+Example benchmark usage:
+```bash
+# Run benchmarks
+python -m crackerjack -t --benchmark
+
+# Run benchmarks with regression testing (fail if >5% slower)
+python -m crackerjack -t --benchmark-regression
+
+# Run benchmarks with custom regression threshold (10%)
+python -m crackerjack -t --benchmark-regression --benchmark-regression-threshold=10.0
+```
+
 ## Installation
 
 1.  **Python:** Ensure you have Python 3.13 installed.
@@ -185,6 +265,9 @@ class MyOptions:
         # Process options
         self.clean = True            # Clean code (remove docstrings, comments, etc.)
         self.test = True             # Run tests using pytest
+        self.benchmark = False       # Run tests in benchmark mode
+        self.benchmark_regression = False  # Fail tests if benchmarks regress beyond threshold
+        self.benchmark_regression_threshold = 5.0  # Threshold percentage for benchmark regression
         self.skip_hooks = False      # Skip running pre-commit hooks
 
         # Version and publishing options
@@ -225,6 +308,9 @@ runner.process(MyOptions())
 -   `-s`, `--skip-hooks`: Skip running pre-commit hooks (useful with `-t`).
 -   `-x`, `--clean`: Clean code by removing docstrings, line comments, and extra whitespace.
 -   `-t`, `--test`: Run tests using `pytest`.
+-   `--benchmark`: Run tests in benchmark mode (disables parallel execution).
+-   `--benchmark-regression`: Fail tests if benchmarks regress beyond threshold.
+-   `--benchmark-regression-threshold`: Set threshold percentage for benchmark regression (default 5.0%).
 -   `-a`, `--all`: Run with `-x -t -p <micro|minor|major> -c` development options.
 -   `--ai-agent`: Enable AI agent mode with structured output (see [AI Agent Integration](#ai-agent-integration)).
 -   `--help`: Display help.

crackerjack-0.18.12/PKG-INFO → crackerjack-0.19.0/README.md

@@ -1,44 +1,3 @@
-Metadata-Version: 2.1
-Name: crackerjack
-Version: 0.18.12
-Summary: Default template for PDM package
-Keywords: black,ruff,mypy,creosote,refurb,pyright,bandit,pytest
-Author-Email: lesleslie <les@wedgwoodwebworks.com>
-Maintainer-Email: lesleslie <les@wedgwoodwebworks.com>
-License: BSD-3-CLAUSE
-Classifier: Environment :: Console
-Classifier: Operating System :: POSIX
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Development Status :: 4 - Beta
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Software Development :: Quality Assurance
-Classifier: Topic :: Software Development :: Testing
-Classifier: Topic :: Utilities
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: License :: OSI Approved :: BSD License
-Classifier: Typing :: Typed
-Project-URL: homepage, https://github.com/lesleslie/crackerjack
-Project-URL: documentation, https://github.com/lesleslie/crackerjack
-Project-URL: repository, https://github.com/lesleslie/crackerjack
-Requires-Python: >=3.13
-Requires-Dist: autotyping>=24.9.0
-Requires-Dist: pre-commit>=4.2.0
-Requires-Dist: pytest>=8.3.5
-Requires-Dist: pydantic>=2.11.5
-Requires-Dist: pdm-bump>=0.9.12
-Requires-Dist: pdm>=2.24.2
-Requires-Dist: uv>=0.7.9
-Requires-Dist: pytest-cov>=6.1.1
-Requires-Dist: pytest-mock>=3.14.1
-Requires-Dist: tomli-w>=1.2.0
-Requires-Dist: pytest-asyncio>=1.0.0
-Requires-Dist: rich>=14.0.0
-Requires-Dist: typer>=0.16.0
-Requires-Dist: pytest-timeout>=2.4.0
-Requires-Dist: pytest-xdist>=3.7.0
-Description-Content-Type: text/markdown
-
 # Crackerjack: Elevate Your Python Development
 
 [![Code style: crackerjack](https://img.shields.io/badge/code%20style-crackerjack-000042)](https://github.com/lesleslie/crackerjack)
@@ -176,6 +135,44 @@ Crackerjack projects adhere to these guidelines:
 -   **Clear Code:** Avoid overly complex code.
 -   **Modular:** Functions should do one thing well.
 
+## Testing Features
+
+Crackerjack provides advanced testing capabilities powered by pytest:
+
+### Standard Testing
+
+- **Parallel Test Execution:** Tests run in parallel by default using pytest-xdist for faster execution
+- **Timeout Protection:** All tests have a default 60-second timeout to prevent hanging tests
+- **Coverage Reports:** Automatically generates test coverage reports with configurable thresholds
+
+### Benchmark Testing
+
+Crackerjack includes benchmark testing capabilities:
+
+- **Performance Measurement:** Run tests with `--benchmark` to measure execution time and performance
+- **Regression Testing:** Use `--benchmark-regression` to detect performance regressions
+- **Configurable Thresholds:** Set custom regression thresholds with `--benchmark-regression-threshold`
+- **Compatibility Management:** Automatically disables parallel execution when running benchmarks
+- **CI Integration:** Track performance across commits with benchmark history
+
+When benchmarks are run, Crackerjack:
+1. Disables parallel test execution (as pytest-benchmark is incompatible with pytest-xdist)
+2. Configures the pytest-benchmark plugin with optimized settings
+3. Compares benchmark results against previous runs when regression testing is enabled
+4. Fails tests if performance decreases beyond the specified threshold
+
+Example benchmark usage:
+```bash
+# Run benchmarks
+python -m crackerjack -t --benchmark
+
+# Run benchmarks with regression testing (fail if >5% slower)
+python -m crackerjack -t --benchmark-regression
+
+# Run benchmarks with custom regression threshold (10%)
+python -m crackerjack -t --benchmark-regression --benchmark-regression-threshold=10.0
+```
+
 ## Installation
 
 1.  **Python:** Ensure you have Python 3.13 installed.
@@ -226,6 +223,9 @@ class MyOptions:
         # Process options
         self.clean = True            # Clean code (remove docstrings, comments, etc.)
         self.test = True             # Run tests using pytest
+        self.benchmark = False       # Run tests in benchmark mode
+        self.benchmark_regression = False  # Fail tests if benchmarks regress beyond threshold
+        self.benchmark_regression_threshold = 5.0  # Threshold percentage for benchmark regression
         self.skip_hooks = False      # Skip running pre-commit hooks
 
         # Version and publishing options
@@ -266,6 +266,9 @@ runner.process(MyOptions())
 -   `-s`, `--skip-hooks`: Skip running pre-commit hooks (useful with `-t`).
 -   `-x`, `--clean`: Clean code by removing docstrings, line comments, and extra whitespace.
 -   `-t`, `--test`: Run tests using `pytest`.
+-   `--benchmark`: Run tests in benchmark mode (disables parallel execution).
+-   `--benchmark-regression`: Fail tests if benchmarks regress beyond threshold.
+-   `--benchmark-regression-threshold`: Set threshold percentage for benchmark regression (default 5.0%).
 -   `-a`, `--all`: Run with `-x -t -p <micro|minor|major> -c` development options.
 -   `--ai-agent`: Enable AI agent mode with structured output (see [AI Agent Integration](#ai-agent-integration)).
 -   `--help`: Display help.

{crackerjack-0.18.12 → crackerjack-0.19.0}/crackerjack/.pre-commit-config.yaml

@@ -3,12 +3,14 @@ repos:
     rev: 2.24.2  # a PDM release exposing the hook
     hooks:
       - id: pdm-lock-check
-#      - id: pdm-export
-#        args: [ '-o', 'requirements.txt', '--without-hashes' ]
-#        files: ^pdm.lock$
       - id: pdm-sync
         additional_dependencies:
           - keyring
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.7.9
+    hooks:
+      - id: uv-lock
+        files: ^pyproject\.toml$
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
@@ -22,11 +24,24 @@ repos:
         name: check-toml
       - id: check-added-large-files
         name: check-added-large-files
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        exclude: "pdm.lock"
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.24.1
+    hooks:
+      - id: validate-pyproject
+  - repo: https://github.com/tox-dev/pyproject-fmt
+    rev: "v2.6.0"
+    hooks:
+      - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.11.12
     hooks:
-      - id: ruff-format
       - id: ruff-check
+      - id: ruff-format
   - repo: https://github.com/jendrikseipp/vulture
     rev: 'v2.14'
     hooks:
@@ -35,10 +50,6 @@ repos:
     rev: v4.0.3
     hooks:
       - id: creosote
-  - repo: https://github.com/ikamensh/flynt/
-    rev: '1.0.1'
-    hooks:
-      - id: flynt
   - repo: https://github.com/codespell-project/codespell
     rev: v2.4.1
     hooks:
@@ -74,11 +85,6 @@ repos:
     rev: v1.1.401
     hooks:
       - id: pyright
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.12
-    hooks:
-      - id: ruff-check
-      - id: ruff-format
   #  - repo: https://github.com/pdoc3/pdoc
   #    rev: master
   #    hooks:

{crackerjack-0.18.12 → crackerjack-0.19.0}/crackerjack/__main__.py

@@ -32,6 +32,8 @@ class Options(BaseModel):
     clean: bool = False
     test: bool = False
     benchmark: bool = False
+    benchmark_regression: bool = False
+    benchmark_regression_threshold: float = 5.0
     all: BumpOption | None = None
     ai_agent: bool = False
     create_pr: bool = False
@@ -90,6 +92,16 @@ cli_options = {
         "--benchmark",
         help="Run tests in benchmark mode (disables parallel execution).",
     ),
+    "benchmark_regression": typer.Option(
+        False,
+        "--benchmark-regression",
+        help="Fail tests if benchmarks regress beyond threshold.",
+    ),
+    "benchmark_regression_threshold": typer.Option(
+        5.0,
+        "--benchmark-regression-threshold",
+        help="Maximum allowed performance regression percentage (default: 5.0%).",
+    ),
     "skip_hooks": typer.Option(
         False,
         "-s",
@@ -132,6 +144,10 @@ def main(
     clean: bool = cli_options["clean"],
     test: bool = cli_options["test"],
     benchmark: bool = cli_options["benchmark"],
+    benchmark_regression: bool = cli_options["benchmark_regression"],
+    benchmark_regression_threshold: float = cli_options[
+        "benchmark_regression_threshold"
+    ],
     skip_hooks: bool = cli_options["skip_hooks"],
     create_pr: bool = cli_options["create_pr"],
     ai_agent: bool = cli_options["ai_agent"],
@@ -148,6 +164,8 @@ def main(
         clean=clean,
         test=test,
         benchmark=benchmark,
+        benchmark_regression=benchmark_regression,
+        benchmark_regression_threshold=benchmark_regression_threshold,
         skip_hooks=skip_hooks,
         all=all,
         ai_agent=ai_agent,

{crackerjack-0.18.12 → crackerjack-0.19.0}/crackerjack/crackerjack.py

@@ -39,7 +39,9 @@ class OptionsProtocol(t.Protocol):
     update_precommit: bool
     clean: bool
     test: bool
-    benchmark: bool = False
+    benchmark: bool
+    benchmark_regression: bool
+    benchmark_regression_threshold: float
     publish: t.Any | None
     bump: t.Any | None
     all: t.Any | None
@@ -295,10 +297,10 @@ class ConfigManager:
                     for k, v in {
                         x: self.swap_package_name(y)
                         for x, y in value.items()
-                        if isinstance(y, (str, list)) and "crackerjack" in str(y)
+                        if isinstance(y, str | list) and "crackerjack" in str(y)
                     }.items():
                         settings[setting][k] = v
-                elif isinstance(value, (str, list)) and "crackerjack" in str(value):
+                elif isinstance(value, str | list) and "crackerjack" in str(value):
                     value = self.swap_package_name(value)
                     settings[setting] = value
                 if setting in (
@@ -492,9 +494,27 @@ class Crackerjack:
                 self.code_cleaner.clean_files(tests_dir)
 
     def _prepare_pytest_command(self, options: OptionsProtocol) -> list[str]:
+        """Prepare pytest command with appropriate options.
+
+        Configures pytest command with:
+        - Standard options for formatting and output control
+        - Benchmark options when benchmark mode is enabled
+        - Benchmark regression options when regression testing is enabled
+        - Parallel execution via xdist for non-benchmark tests
+
+        Benchmark and parallel execution (xdist) are incompatible, so the command
+        automatically disables parallelism when benchmarks are enabled.
+
+        Args:
+            options: Command options with benchmark and test settings
+
+        Returns:
+            List of command-line arguments for pytest
+        """
         test = ["pytest"]
         if options.verbose:
             test.append("-v")
+
         test.extend(
             [
                 "--capture=fd",  # Capture stdout/stderr at file descriptor level
@@ -505,9 +525,27 @@ class Crackerjack:
                 "--timeout=60",  # 1-minute timeout for tests
             ]
         )
-        # Add benchmark flag if enabled (disables parallel execution)
-        if options.benchmark:
-            test.append("--benchmark")
+
+        # Benchmarks and parallel testing are incompatible
+        # Handle them mutually exclusively
+        if options.benchmark or options.benchmark_regression:
+            # When running benchmarks, avoid parallel execution
+            # and apply specific benchmark options
+            if options.benchmark:
+                test.append("--benchmark")
+
+            # Add benchmark regression testing options if enabled
+            if options.benchmark_regression:
+                test.extend(
+                    [
+                        "--benchmark-regression",
+                        f"--benchmark-regression-threshold={options.benchmark_regression_threshold}",
+                    ]
+                )
+        else:
+            # No benchmarks - use parallel execution for speed
+            test.append("-xvs")
+
         return test
 
     def _setup_test_environment(self) -> None:

crackerjack-0.19.0/crackerjack/pyproject.toml

@@ -0,0 +1,233 @@
+[build-system]
+build-backend = "pdm.backend"
+requires = [ "pdm-backend" ]
+
+[project]
+name = "crackerjack"
+version = "0.18.12"
+description = "Crackerjack: code quality toolkit"
+readme = "README.md"
+keywords = [
+  "bandit",
+  "black",
+  "creosote",
+  "mypy",
+  "pyright",
+  "pytest",
+  "refurb",
+  "ruff",
+]
+license.text = "BSD-3-CLAUSE"
+maintainers = [
+  { name = "lesleslie", email = "les@wedgwoodwebworks.com" },
+]
+
+authors = [
+  { name = "lesleslie", email = "les@wedgwoodwebworks.com" },
+]
+requires-python = ">=3.13"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "License :: OSI Approved :: BSD License",
+  "Operating System :: POSIX",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Software Development :: Testing",
+  "Topic :: Utilities",
+  "Typing :: Typed",
+]
+dependencies = [
+  "autotyping>=24.9",
+  "pdm>=2.24.2",
+  "pdm-bump>=0.9.12",
+  "pre-commit>=4.2",
+  "pydantic>=2.11.5",
+  "pytest>=8.3.5",
+  "pytest-asyncio>=1",
+  "pytest-benchmark>=5.1",
+  "pytest-cov>=6.1.1",
+  "pytest-mock>=3.14.1",
+  "pytest-timeout>=2.4",
+  "pytest-xdist>=3.7",
+  "rich>=14",
+  "tomli-w>=1.2",
+  "typer>=0.16",
+  "uv>=0.7.9",
+]
+urls.documentation = "https://github.com/lesleslie/crackerjack"
+urls.homepage = "https://github.com/lesleslie/crackerjack"
+urls.repository = "https://github.com/lesleslie/crackerjack"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 88
+fix = true
+unsafe-fixes = true
+
+show-fixes = true
+output-format = "full"
+format.docstring-code-format = true
+lint.extend-select = [
+  "C901",
+  "D",
+  "F",    # pyflakes
+  "I",
+  "UP",   # pyupgrade (includes F-string conversion)
+]
+lint.ignore = [
+  "D100",
+  "D101",
+  "D102",
+  "D103",
+  "D104",
+  "D105",
+  "D106",
+  "D107",
+  "F821",
+]
+lint.fixable = [ "ALL" ]
+lint.unfixable = [  ]
+lint.isort.no-lines-before = [
+  "first-party",
+]
+lint.mccabe.max-complexity = 13
+lint.pydocstyle.convention = "google"
+
+[tool.codespell]
+skip = "*/data/*"
+quiet-level = 3
+ignore-words-list = "crate,uptodate,nd"
+
+[tool.pytest.ini_options]
+# Core pytest configuration
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+python_files = [ "test_*.py", "*_test.py" ]
+testpaths = [ "tests", "crackerjack" ]
+python_classes = [ "Test*" ]
+python_functions = [ "test_*" ]
+
+# Markers
+markers = [
+  "unit: marks test as a unit test",
+  "benchmark: mark test as a benchmark (disables parallel execution)",
+]
+
+# Default timeout settings
+timeout = 60
+timeout_method = "thread"
+
+# Test command options
+addopts = "--cov=crackerjack --cov-report=term --cov-fail-under=80"
+
+[tool.pytest.benchmark]
+disable_gc = true
+warmup = false
+warmup_iterations = 0
+
+[tool.coverage.run]
+branch = false
+source = [ "crackerjack" ]
+data_file = ".coverage"
+parallel = false
+omit = [
+  "*/tests/*",
+  "*/site-packages/*",
+  "*/__pycache__/*",
+  "*/__init__.py",
+  "*/_version.py",
+  "*/conftest.py",
+  "*/test_*.py",
+  "*/_test.py",
+]
+
+[tool.coverage.report]
+exclude_also = [
+  "pragma: no cover",
+  "def __repr__",
+  "raise NotImplementedError",
+  "if __name__ == .__main__.:",
+  "pass",
+  "raise ImportError",
+  "except ImportError",
+  "def __str__",
+  "@abstractmethod",
+]
+ignore_errors = false
+
+[tool.pyright]
+verboseOutput = true
+include = [
+  "crackerjack",
+]
+exclude = [
+  "scratch",
+]
+extraPaths = [
+  ".venv/lib/python3.13/site-packages/",
+]
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+reportOptionalMemberAccess = false
+reportOptionalCall = false
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+reportUnknownArgumentType = false
+reportInvalidTypeForm = false
+reportUnknownLambdaType = false
+reportUnknownParameterType = "warning"
+reportPrivateUsage = false
+pythonVersion = "3.13"
+pythonPlatform = "Darwin"
+
+[tool.vulture]
+min_confidence = 86
+paths = [ "crackerjack" ]
+ignore_names = [ "cls" ]
+
+[tool.creosote]
+paths = [
+  "crackerjack",
+]
+deps-file = "pyproject.toml"
+exclude-deps = [
+  "pdm-bump",
+  "autotyping",
+  "pre-commit",
+  "pytest",
+  "pytest-asyncio",
+  "pytest-cov",
+  "pytest-mock",
+  "pytest-xdist",
+  "pytest-benchmark",
+  "pdm",
+  "pyfiglet",
+  "pyyaml",
+  "uv",
+  "tomli-w",
+  "google-crc32c",
+  "pytest-timeout",
+]
+
+[tool.refurb]
+enable_all = true
+
+[tool.bandit]
+target = [
+  "crackerjack",
+]
+skips = [
+  "B101",
+  "B301",
+  "B311",
+  "B403",
+  "B404",
+  "B602",
+  "B603",
+  "B607",
+  "B704",
+]