crackerjack 0.19.7__py3-none-any.whl → 0.20.0__py3-none-any.whl

crackerjack/py313.py

@@ -0,0 +1,221 @@
+"""Python 3.13+ specific features and enhancements.
+
+This module contains implementations that leverage the latest Python 3.13+ features.
+It serves as a showcase for modern Python capabilities including:
+- Pattern matching
+- PEP 695 type parameter syntax
+- Self type annotations
+- More precise type hints
+"""
+
+import subprocess
+import typing
+from enum import Enum, auto
+from pathlib import Path
+from typing import Any, Self, TypedDict
+
+
+class CommandRunner[TReturn]:
+    def run_command(self, cmd: list[str], **kwargs: Any) -> TReturn: ...
+
+
+class CommandResult(TypedDict):
+    success: bool
+    exit_code: int
+    stdout: str
+    stderr: str
+    command: list[str]
+    duration_ms: float
+
+
+def process_command_output(result: CommandResult) -> tuple[bool, str]:
+    match result:
+        case {"success": True, "stdout": stdout} if stdout.strip():
+            return True, stdout
+
+        case {"success": True}:
+            return True, "Command completed successfully with no output"
+
+        case {"success": False, "exit_code": code, "stderr": stderr} if code == 127:
+            return False, f"Command not found: {stderr}"
+
+        case {"success": False, "exit_code": code} if code > 0:
+            return False, f"Command failed with exit code {code}: {result['stderr']}"
+
+        case _:
+            pass
+
+    return False, "Unknown command result pattern"
+
+
+class HookStatus(Enum):
+    SUCCESS = auto()
+    FAILURE = auto()
+    SKIPPED = auto()
+    ERROR = auto()
+
+
+class HookResult(TypedDict):
+    status: HookStatus
+    hook_id: str
+    output: str
+    files: list[str]
+
+
+def analyze_hook_result(result: HookResult) -> str:
+    match result:
+        case {"status": HookStatus.SUCCESS, "hook_id": hook_id}:
+            return f"✅ Hook {hook_id} passed successfully"
+
+        case {"status": HookStatus.FAILURE, "hook_id": hook_id, "output": output} if (
+            "fixable" in output
+        ):
+            return f"🔧 Hook {hook_id} failed with fixable issues"
+
+        case {"status": HookStatus.FAILURE, "hook_id": hook_id}:
+            return f"❌ Hook {hook_id} failed"
+
+        case {"status": HookStatus.SKIPPED, "hook_id": hook_id}:
+            return f"⏩ Hook {hook_id} was skipped"
+
+        case {"status": HookStatus.ERROR, "hook_id": hook_id, "output": output}:
+            return f"💥 Hook {hook_id} encountered an error: {output}"
+
+        case _:
+            pass
+
+    return "Unknown hook result pattern"
+
+
+class ModernConfigManager:
+    def __init__(self, config_path: Path) -> None:
+        self.config_path = config_path
+        self.config: dict[str, Any] = {}
+
+    def load(self) -> Self:
+        return self
+
+    def update(self, key: str, value: Any) -> Self:
+        self.config[key] = value
+        return self
+
+    def save(self) -> Self:
+        return self
+
+
+def categorize_file(file_path: Path) -> str:
+    path_str = str(file_path)
+    name = file_path
+
+    match path_str:
+        case s if name.suffix == ".py" and "/tests/" in s:
+            return "Python Test File"
+
+        case s if name.suffix == ".py" and "__init__.py" in name.name:
+            return "Python Module Init"
+
+        case s if name.suffix == ".py":
+            return "Python Source File"
+
+        case s if name.suffix in {".md", ".rst", ".txt"}:
+            return "Documentation File"
+
+        case s if name.stem.startswith(".") or name.name in {
+            ".gitignore",
+            ".pre-commit-config.yaml",
+        }:
+            return "Configuration File"
+
+        case _:
+            pass
+
+    return "Unknown File Type"
+
+
+def process_hook_results[T, R](
+    results: list[T],
+    success_handler: typing.Callable[[T], R],
+    failure_handler: typing.Callable[[T], R],
+) -> list[R]:
+    processed_results = []
+
+    for result in results:
+        if isinstance(result, dict) and result.get("status") == HookStatus.SUCCESS:
+            processed_results.append(success_handler(result))
+        else:
+            processed_results.append(failure_handler(result))
+
+    return processed_results
+
+
+class EnhancedCommandRunner:
+    def __init__(self, working_dir: Path | None = None) -> None:
+        self.working_dir = working_dir
+
+    def run(self, cmd: list[str], **kwargs: Any) -> CommandResult:
+        import time
+
+        start_time = time.time()
+
+        try:
+            process = subprocess.run(
+                cmd, capture_output=True, text=True, cwd=self.working_dir, **kwargs
+            )
+
+            duration_ms = (time.time() - start_time) * 1000
+
+            return CommandResult(
+                success=(process.returncode == 0),
+                exit_code=process.returncode,
+                stdout=process.stdout,
+                stderr=process.stderr,
+                command=cmd,
+                duration_ms=duration_ms,
+            )
+
+        except subprocess.SubprocessError as e:
+            duration_ms = (time.time() - start_time) * 1000
+
+            return CommandResult(
+                success=False,
+                exit_code=-1,
+                stdout="",
+                stderr=str(e),
+                command=cmd,
+                duration_ms=duration_ms,
+            )
+
+    def handle_result(self, result: CommandResult) -> tuple[bool, str]:
+        return process_command_output(result)
+
+
+def clean_python_code(code: str) -> str:
+    lines = code.splitlines()
+    cleaned_lines = []
+
+    for line in lines:
+        match line.strip():
+            case "":
+                if not cleaned_lines or cleaned_lines[-1].strip():
+                    cleaned_lines.append("")
+
+            case s if s.startswith(("import ", "from ")):
+                cleaned_lines.append(line)
+
+            case s if s.startswith("#"):
+                continue
+
+            case s if "#" in s and not any(
+                skip in s for skip in ("# noqa", "# type:", "# pragma", "# skip")
+            ):
+                code_part = line.split("#", 1)[0].rstrip()
+                if code_part:
+                    cleaned_lines.append(code_part)
+
+            case s if s.startswith('"""') or s.startswith("'''"):
+                continue
+
+            case _:
+                cleaned_lines.append(line)
+
+    return "\n".join(cleaned_lines)

crackerjack/pyproject.toml

@@ -4,59 +4,59 @@ requires = [ "pdm-backend" ]
 
 [project]
 name = "crackerjack"
-version = "0.19.6"
+version = "0.19.8"
 description = "Crackerjack: code quality toolkit"
 readme = "README.md"
 keywords = [
-  "bandit",
-  "black",
-  "creosote",
-  "mypy",
-  "pyright",
-  "pytest",
-  "refurb",
-  "ruff",
+    "bandit",
+    "black",
+    "creosote",
+    "mypy",
+    "pyright",
+    "pytest",
+    "refurb",
+    "ruff",
 ]
 license.text = "BSD-3-CLAUSE"
 maintainers = [
-  { name = "lesleslie", email = "les@wedgwoodwebworks.com" },
+    { name = "lesleslie", email = "les@wedgwoodwebworks.com" },
 ]
 
 authors = [
-  { name = "lesleslie", email = "les@wedgwoodwebworks.com" },
+    { 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",
+    "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.4",
-  "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.10",
+    "autotyping>=24.9",
+    "pdm>=2.24.2",
+    "pdm-bump>=0.9.12",
+    "pre-commit>=4.2",
+    "pydantic>=2.11.5",
+    "pytest>=8.4",
+    "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.10",
 ]
 urls.documentation = "https://github.com/lesleslie/crackerjack"
 urls.homepage = "https://github.com/lesleslie/crackerjack"
@@ -72,28 +72,28 @@ 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)
+    "C901",
+    "D",
+    "F",    # pyflakes
+    "I",
+    "UP",   # pyupgrade (includes F-string conversion)
 ]
 lint.ignore = [
-  "D100",
-  "D101",
-  "D102",
-  "D103",
-  "D104",
-  "D105",
-  "D106",
-  "D107",
-  "F821",
-  "UP040",
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "D105",
+    "D106",
+    "D107",
+    "F821",
+    "UP040",
 ]
 lint.fixable = [ "ALL" ]
 lint.unfixable = [  ]
 lint.isort.no-lines-before = [
-  "first-party",
+    "first-party",
 ]
 lint.mccabe.max-complexity = 13
 lint.pydocstyle.convention = "google"
@@ -105,7 +105,7 @@ ignore-words-list = "crate,uptodate,nd"
 
 [tool.pyproject-fmt]
 column_width = 120
-indent = 2
+indent = 4
 
 [tool.pytest.ini_options]
 # Core pytest configuration
@@ -118,9 +118,9 @@ python_functions = [ "test_*" ]
 
 # Markers
 markers = [
-  "unit: marks test as a unit test",
-  "benchmark: mark test as a benchmark (disables parallel execution)",
-  "integration: marks test as an integration test",
+    "unit: marks test as a unit test",
+    "benchmark: mark test as a benchmark (disables parallel execution)",
+    "integration: marks test as an integration test",
 ]
 
 # Default timeout settings
@@ -141,40 +141,40 @@ source = [ "crackerjack" ]
 data_file = ".coverage"
 parallel = false
 omit = [
-  "*/tests/*",
-  "*/site-packages/*",
-  "*/__pycache__/*",
-  "*/__init__.py",
-  "*/_version.py",
-  "*/conftest.py",
-  "*/test_*.py",
-  "*/_test.py",
+    "*/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",
+    "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",
+    "crackerjack",
 ]
 exclude = [
-  "scratch",
+    "scratch",
 ]
 extraPaths = [
-  ".venv/lib/python3.13/site-packages/",
+    ".venv/lib/python3.13/site-packages/",
 ]
 typeCheckingMode = "strict"
 reportMissingTypeStubs = false
@@ -196,26 +196,26 @@ ignore_names = [ "cls" ]
 
 [tool.creosote]
 paths = [
-  "crackerjack",
+    "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",
+    "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]
@@ -224,16 +224,16 @@ quiet = true
 
 [tool.bandit]
 target = [
-  "crackerjack",
+    "crackerjack",
 ]
 skips = [
-  "B101",
-  "B301",
-  "B311",
-  "B403",
-  "B404",
-  "B602",
-  "B603",
-  "B607",
-  "B704",
+    "B101",
+    "B301",
+    "B311",
+    "B403",
+    "B404",
+    "B602",
+    "B603",
+    "B607",
+    "B704",
 ]

{crackerjack-0.19.7.dist-info → crackerjack-0.20.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: crackerjack
-Version: 0.19.7
+Version: 0.20.0
 Summary: Crackerjack: code quality toolkit
 Keywords: bandit,black,creosote,mypy,pyright,pytest,refurb,ruff
 Author-Email: lesleslie <les@wedgwoodwebworks.com>
@@ -82,7 +82,7 @@ Crackerjack integrates powerful tools like Ruff, PDM, pre-commit, pytest, and mo
 ### Quick Start
 
 If you're new to Crackerjack, follow these steps:
-1. **Install Python 3.13:** Ensure you have Python 3.13 installed.
+1. **Install Python 3.13:** Ensure you have Python 3.13 or higher installed.
 2. **Install PDM:**
     ```
     pipx install pdm
@@ -98,6 +98,11 @@ If you're new to Crackerjack, follow these steps:
     python -m crackerjack
     ```
 
+    Or use the interactive Rich UI:
+    ```
+    python -m crackerjack --rich-ui
+    ```
+
 ---
 
 ## The Crackerjack Philosophy
@@ -137,9 +142,12 @@ Crackerjack is built on the following core principles:
 
 ### Developer Experience
 - **Command-Line Interface:** Simple, intuitive CLI with comprehensive options
+- **Interactive Rich UI:** Visual workflow with real-time task tracking, progress visualization, and interactive prompts
+- **Structured Error Handling:** Clear error messages with error codes, detailed explanations, and recovery suggestions
 - **Programmatic API:** Can be integrated into your own Python scripts and workflows
 - **AI Agent Integration:** Structured output format for integration with AI assistants, with complete style rules available in [RULES.md](RULES.md) for AI tool customization
 - **Verbose Mode:** Detailed output for debugging and understanding what's happening
+- **Python 3.13+ Features:** Leverages the latest Python language features including PEP 695 type parameter syntax, Self type annotations, and structural pattern matching
 
 ## Pre-commit Hooks
 
@@ -217,7 +225,7 @@ python -m crackerjack -t --benchmark-regression --benchmark-regression-threshold
 
 ## Installation
 
-1.  **Python:** Ensure you have Python 3.13 installed.
+1.  **Python:** Ensure you have Python 3.13 or higher installed.
 2.  **PDM:** Install [PDM](https://pdm.fming.dev/) using `pipx`:
 
     ```
@@ -231,6 +239,11 @@ python -m crackerjack -t --benchmark-regression --benchmark-regression-threshold
     python -m crackerjack
     ```
 
+    Or with the interactive Rich UI:
+    ```
+    python -m crackerjack --rich-ui
+    ```
+
 ## Usage
 
 ### Command Line
@@ -312,6 +325,7 @@ runner.process(MyOptions())
 -   `--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.
+-   `--rich-ui`: Enable the interactive Rich UI for a more user-friendly experience with visual progress tracking and interactive prompts.
 -   `--ai-agent`: Enable AI agent mode with structured output (see [AI Agent Integration](#ai-agent-integration)).
 -   `--help`: Display help.
 
@@ -387,6 +401,11 @@ runner.process(MyOptions())
   python -m crackerjack -i
   ```
 
+- **Rich Interactive Mode** - Run with the interactive Rich UI:
+  ```bash
+  python -m crackerjack --rich-ui
+  ```
+
 - **AI Integration** - Run with structured output for AI tools:
   ```bash
   python -m crackerjack --ai-agent --test
@@ -413,6 +432,79 @@ python -m crackerjack --ai-agent --test
 
 For detailed information about using Crackerjack with AI agents, including the structured output format and programmatic usage, see [README-AI-AGENT.md](README-AI-AGENT.md).
 
+## Interactive Rich UI
+
+Crackerjack now offers an enhanced interactive experience through its Rich UI:
+
+- **Visual Workflow:** See a visual representation of the entire task workflow with dependencies
+- **Real-time Progress:** Track task progress with interactive progress bars and status indicators
+- **Task Management:** Confirm tasks before execution and view detailed status information
+- **Error Visualization:** Errors are presented in a structured, easy-to-understand format with recovery suggestions
+- **File Selection:** Interactive file browser for operations that require selecting files
+
+To use the Rich UI, run Crackerjack with the `--rich-ui` flag:
+
+```bash
+python -m crackerjack --rich-ui
+```
+
+This launches an interactive terminal interface where you can:
+1. View all available tasks and their dependencies
+2. Confirm each task before execution
+3. Get detailed status information for running tasks
+4. See a summary of completed, failed, and skipped tasks
+5. Visualize error details with recovery suggestions
+
+## Structured Error Handling
+
+Crackerjack implements a comprehensive error handling system that provides:
+
+- **Error Categories:** Errors are categorized by type (configuration, execution, testing, etc.)
+- **Error Codes:** Each error has a unique numeric code for easy reference
+- **Detailed Messages:** Clear, descriptive messages explain what went wrong
+- **Recovery Suggestions:** Where possible, errors include recovery suggestions to help resolve issues
+- **Rich Formatting:** Errors are presented with clear visual formatting (when using Rich UI or verbose mode)
+
+Error types include:
+- Configuration errors (1000-1999)
+- Execution errors (2000-2999)
+- Test errors (3000-3999)
+- Publishing errors (4000-4999)
+- Git errors (5000-5999)
+- File operation errors (6000-6999)
+- Code cleaning errors (7000-7999)
+- Generic errors (9000-9999)
+
+Use the `-v` or `--verbose` flag to see more detailed error information:
+
+```bash
+python -m crackerjack -v
+```
+
+For the most comprehensive error details with visual formatting, combine verbose mode with the Rich UI:
+
+```bash
+python -m crackerjack --rich-ui -v
+```
+
+## Python 3.13+ Features
+
+Crackerjack is designed to leverage the latest Python 3.13+ language features:
+
+- **Type Parameter Syntax (PEP 695):** Uses the new, more concise syntax for generic type parameters
+- **Self Type:** Leverages the `Self` type for better method chaining and builder patterns
+- **Structural Pattern Matching:** Uses pattern matching for cleaner code, especially in configuration and command processing
+- **Enhanced Type Hints:** More precise type hints with union types using the pipe operator
+- **Modern Dictionary Patterns:** Leverages structural pattern matching with dictionaries for cleaner data handling
+
+These modern Python features contribute to:
+- More readable and maintainable code
+- Better static type checking with tools like pyright
+- Cleaner, more concise implementations
+- Enhanced error handling and pattern recognition
+
+Crackerjack provides examples of these features in action, serving as a reference for modern Python development practices.
+
 ## Contributing
 
 Crackerjack is an evolving project. Contributions are welcome! Please open a pull request or issue.