crackerjack 0.14.9__py3-none-any.whl → 0.15.0__py3-none-any.whl

crackerjack/__init__.py

@@ -1,5 +1,5 @@
-from typing import Sequence
+import typing as t
 
-from .crackerjack import Crackerjack, crackerjack_it
+from .crackerjack import Crackerjack, create_crackerjack_runner
 
-__all__: Sequence[str] = ["crackerjack_it", "Crackerjack"]
+__all__: t.Sequence[str] = ["create_crackerjack_runner", "Crackerjack"]

crackerjack/__main__.py

@@ -1,10 +1,9 @@
-import typing as t
 from enum import Enum
 
 import typer
 from pydantic import BaseModel, field_validator
 from rich.console import Console
-from crackerjack import crackerjack_it
+from crackerjack import create_crackerjack_runner
 
 console = Console(force_terminal=True)
 app = typer.Typer(
@@ -26,17 +25,17 @@ class Options(BaseModel):
     interactive: bool = False
     doc: bool = False
     no_config_updates: bool = False
-    publish: t.Optional[BumpOption] = None
-    bump: t.Optional[BumpOption] = None
+    publish: BumpOption | None = None
+    bump: BumpOption | None = None
     verbose: bool = False
     update_precommit: bool = False
     clean: bool = False
     test: bool = False
-    all: t.Optional[BumpOption] = None
+    all: BumpOption | None = None
 
     @classmethod
     @field_validator("publish", "bump", mode="before")
-    def validate_bump_options(cls, value: t.Optional[str]) -> t.Optional[BumpOption]:
+    def validate_bump_options(cls, value: str | None) -> BumpOption | None:
         if value is None:
             return None
         try:
@@ -92,10 +91,6 @@ cli_options = {
 }
 
 
-def create_options(**kwargs: t.Any) -> Options:
-    return Options(**kwargs)
-
-
 @app.command()
 def main(
     commit: bool = cli_options["commit"],
@@ -104,13 +99,13 @@ def main(
     no_config_updates: bool = cli_options["no_config_updates"],
     update_precommit: bool = cli_options["update_precommit"],
     verbose: bool = cli_options["verbose"],
-    publish: t.Optional[BumpOption] = cli_options["publish"],
-    all: t.Optional[BumpOption] = cli_options["all"],
-    bump: t.Optional[BumpOption] = cli_options["bump"],
+    publish: BumpOption | None = cli_options["publish"],
+    all: BumpOption | None = cli_options["all"],
+    bump: BumpOption | None = cli_options["bump"],
     clean: bool = cli_options["clean"],
     test: bool = cli_options["test"],
 ) -> None:
-    options = create_options(
+    options = Options(
         commit=commit,
         interactive=interactive,
         doc=doc,
@@ -123,7 +118,9 @@ def main(
         test=test,
         all=all,
     )
-    crackerjack_it(options)
+
+    runner = create_crackerjack_runner(console=console)
+    runner.process(options)
 
 
 if __name__ == "__main__":

crackerjack/crackerjack.py

@@ -20,6 +20,28 @@ interactive_hooks = ("refurb", "bandit", "pyright")
 default_python_version = "3.13"
 
 
+@t.runtime_checkable
+class CommandRunner(t.Protocol):
+    def execute_command(
+        self, cmd: list[str], **kwargs: t.Any
+    ) -> subprocess.CompletedProcess[str]: ...
+
+
+@t.runtime_checkable
+class OptionsProtocol(t.Protocol):
+    commit: bool
+    interactive: bool
+    doc: bool
+    no_config_updates: bool
+    verbose: bool
+    update_precommit: bool
+    clean: bool
+    test: bool
+    publish: t.Any | None
+    bump: t.Any | None
+    all: t.Any | None
+
+
 @dataclass
 class CodeCleaner:
     console: Console
@@ -430,7 +452,7 @@ class Crackerjack:
         self.project_manager.pkg_name = self.pkg_name
         self.project_manager.pkg_dir = self.pkg_dir
 
-    def _update_project(self, options: t.Any) -> None:
+    def _update_project(self, options: OptionsProtocol) -> None:
         if not options.no_config_updates:
             self.project_manager.update_pkg_configs()
             result: CompletedProcess[str] = self.execute_command(
@@ -443,16 +465,16 @@ class Crackerjack:
                     "\n\n❌ PDM installation failed. Is PDM is installed? Run `pipx install pdm` and try again.\n\n"
                 )
 
-    def _update_precommit(self, options: t.Any) -> None:
+    def _update_precommit(self, options: OptionsProtocol) -> None:
         if self.pkg_path.stem == "crackerjack" and options.update_precommit:
             self.execute_command(["pre-commit", "autoupdate"])
 
-    def _run_interactive_hooks(self, options: t.Any) -> None:
+    def _run_interactive_hooks(self, options: OptionsProtocol) -> None:
         if options.interactive:
             for hook in interactive_hooks:
                 self.project_manager.run_interactive(hook)
 
-    def _clean_project(self, options: t.Any) -> None:
+    def _clean_project(self, options: OptionsProtocol) -> None:
         if options.clean:
             if self.pkg_dir:
                 self.code_cleaner.clean_files(self.pkg_dir)
@@ -461,7 +483,7 @@ class Crackerjack:
                 self.console.print("\nCleaning tests directory...\n")
                 self.code_cleaner.clean_files(tests_dir)
 
-    def _run_tests(self, options: t.Any) -> None:
+    def _run_tests(self, options: OptionsProtocol) -> None:
         if options.test:
             self.console.print("\n\nRunning tests...\n")
             test = ["pytest"]
@@ -477,13 +499,13 @@ class Crackerjack:
                 raise SystemExit(1)
             self.console.print("\n\n✅ Tests passed successfully!\n")
 
-    def _bump_version(self, options: t.Any) -> None:
+    def _bump_version(self, options: OptionsProtocol) -> None:
         for option in (options.publish, options.bump):
             if option:
                 self.execute_command(["pdm", "bump", option])
                 break
 
-    def _publish_project(self, options: t.Any) -> None:
+    def _publish_project(self, options: OptionsProtocol) -> None:
         if options.publish:
             if platform.system() == "Darwin":
                 authorize = self.execute_command(
@@ -504,7 +526,7 @@ class Crackerjack:
                 raise SystemExit(1)
             self.execute_command(["pdm", "publish", "--no-build"])
 
-    def _commit_and_push(self, options: t.Any) -> None:
+    def _commit_and_push(self, options: OptionsProtocol) -> None:
         if options.commit:
             commit_msg = input("\nCommit message: ")
             self.execute_command(
@@ -520,7 +542,7 @@ class Crackerjack:
             return CompletedProcess(cmd, 0, "", "")
         return execute(cmd, **kwargs)
 
-    def process(self, options: t.Any) -> None:
+    def process(self, options: OptionsProtocol) -> None:
         if options.all:
             options.clean = True
             options.test = True
@@ -536,7 +558,20 @@ class Crackerjack:
         self._bump_version(options)
         self._publish_project(options)
         self._commit_and_push(options)
-        self.console.print("\nCrackerjack complete!\n")
-
-
-crackerjack_it = Crackerjack().process
+        self.console.print("\n🍺 Crackerjack complete!\n")
+
+
+def create_crackerjack_runner(
+    console: Console | None = None,
+    our_path: Path | None = None,
+    pkg_path: Path | None = None,
+    python_version: str = default_python_version,
+    dry_run: bool = False,
+) -> Crackerjack:
+    return Crackerjack(
+        console=console or Console(force_terminal=True),
+        our_path=our_path or Path(__file__).parent,
+        pkg_path=pkg_path or Path.cwd(),
+        python_version=python_version,
+        dry_run=dry_run,
+    )

crackerjack/pyproject.toml

@@ -149,7 +149,7 @@ pythonPlatform = "Darwin"
 
 [project]
 name = "crackerjack"
-version = "0.14.8"
+version = "0.14.9"
 description = "Default template for PDM package"
 requires-python = ">=3.13"
 readme = "README.md"

{crackerjack-0.14.9.dist-info → crackerjack-0.15.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: crackerjack
-Version: 0.14.9
+Version: 0.15.0
 Summary: Default template for PDM package
 Keywords: black,ruff,mypy,creosote,refurb
 Author-Email: lesleslie <les@wedgwoodwebworks.com>
@@ -125,15 +125,17 @@ Crackerjack automatically installs and manages these pre-commit hooks:
 Crackerjack projects adhere to these guidelines:
 
 -   **Static Typing:** Use type hints consistently throughout your code.
+-   **Modern Type Hints:** Use the pipe operator (`|`) for union types (e.g., `Path | None` instead of `Optional[Path]`).
 -   **Explicit Naming:** Choose clear, descriptive names for classes, functions, variables, and other identifiers.
 -   **Markdown for Documentation:** Use Markdown (`.md`) for all documentation, READMEs, etc.
 -   **Pathlib:** Use `pathlib.Path` for handling file and directory paths instead of `os.path`.
--   **Consistent Imports:** Use `import typing as t` for type hinting.
+-   **Consistent Imports:** Use `import typing as t` for type hinting and prefix all typing references with `t.`.
+-   **Protocol-Based Design:** Use `t.Protocol` for interface definitions instead of abstract base classes.
 -   **Constants and Config:** Do not use all-caps for constants or configuration settings.
 -   **Path Parameters:** Functions that handle file operations should accept `pathlib.Path` objects as parameters.
 -   **Dependency Management:** Use PDM for dependency management, package building, and publishing.
 -   **Testing:** Use pytest as your testing framework.
--   **Python Version:** Crackerjack projects support the latest Python versions.
+-   **Python Version:** Crackerjack projects target Python 3.13+ and use the latest language features.
 -   **Clear Code:** Avoid overly complex code.
 -   **Modular:** Functions should do one thing well.
 
@@ -155,10 +157,48 @@ Crackerjack projects adhere to these guidelines:
 
 ## Usage
 
+### Command Line
+
 Run Crackerjack from the root of your Python project using:
 
     python -m crackerjack
 
+### Programmatic API
+
+You can also use Crackerjack programmatically in your Python code:
+
+```python
+import typing as t
+from pathlib import Path
+from rich.console import Console
+from crackerjack import create_crackerjack_runner
+
+# Create a custom options object
+class MyOptions:
+    def __init__(self):
+        self.commit = False
+        self.interactive = True
+        self.doc = False
+        self.no_config_updates = False
+        self.verbose = True
+        self.update_precommit = False
+        self.clean = True
+        self.test = True
+        self.publish = None
+        self.bump = "micro"
+        self.all = None
+
+# Create a Crackerjack runner with custom settings
+runner = create_crackerjack_runner(
+    console=Console(force_terminal=True),
+    pkg_path=Path.cwd(),
+    python_version="3.13"
+)
+
+# Run Crackerjack with your options
+runner.process(MyOptions())
+```
+
 
 ### Command-Line Options
 
@@ -244,6 +284,17 @@ This ensures your code meets all quality standards before submission.
 
 This project is licensed under the terms of the BSD 3-Clause license.
 
+## Architecture
+
+Crackerjack is designed with modern Python principles in mind:
+
+- **Factory Pattern:** Uses a factory function (`create_crackerjack_runner`) to create instances with proper dependency injection
+- **Protocol-Based Design:** Defines clear interfaces using `t.Protocol` for better flexibility and testability
+- **Dependency Injection:** Components can be easily replaced with custom implementations
+- **Separation of Concerns:** CLI interface is separate from core logic
+- **Type Safety:** Comprehensive type hints throughout the codebase
+- **Testability:** Designed to be easily testable with mock objects
+
 ## Acknowledgments
 
 -   **PDM:** For excellent dependency and virtual environment management.
@@ -251,14 +302,14 @@ This project is licensed under the terms of the BSD 3-Clause license.
 -   **pre-commit:** For the robust hook management system.
 -   **pytest:** For the flexible and powerful testing framework.
 -   **uv:** For greatly improving PDM speeds.
-- **bandit:** For finding security vulnerabilities.
-- **vulture:** for dead code detection.
-- **creosote:** For unused dependency detection.
-- **flynt:** For f-string conversion.
-- **codespell:** For spelling correction.
-- **autotyping:** For automatically adding type hints.
-- **refurb:** For code improvement suggestions.
-- **pyright:** For static type checking.
-- **Typer:** For the creation of the CLI.
+-   **bandit:** For finding security vulnerabilities.
+-   **vulture:** For dead code detection.
+-   **creosote:** For unused dependency detection.
+-   **flynt:** For f-string conversion.
+-   **codespell:** For spelling correction.
+-   **autotyping:** For automatically adding type hints.
+-   **refurb:** For code improvement suggestions.
+-   **pyright:** For static type checking.
+-   **Typer:** For the creation of the CLI.
 
 ---

{crackerjack-0.14.9.dist-info → crackerjack-0.15.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
-crackerjack-0.14.9.dist-info/METADATA,sha256=51Y-eUXW4uIivey-a-xrVEuQmexAGuYNnqP5wObGGwU,11034
-crackerjack-0.14.9.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
-crackerjack-0.14.9.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
-crackerjack-0.14.9.dist-info/licenses/LICENSE,sha256=fDt371P6_6sCu7RyqiZH_AhT1LdN3sN1zjBtqEhDYCk,1531
+crackerjack-0.15.0.dist-info/METADATA,sha256=iaO-taRUDnYZX96TflzDZiPWu-9VO-XVYl-Y8ZNdrx8,12863
+crackerjack-0.15.0.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
+crackerjack-0.15.0.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+crackerjack-0.15.0.dist-info/licenses/LICENSE,sha256=fDt371P6_6sCu7RyqiZH_AhT1LdN3sN1zjBtqEhDYCk,1531
 crackerjack/.coverage,sha256=dLzPzp72qZEXohNfxnOAlRwvM9dqF06-HoFqfvXZd1U,53248
 crackerjack/.gitignore,sha256=l8ErBAypC3rI6N9lhc7ZMdOw87t0Tz69ZW5C6uj15Wg,214
 crackerjack/.libcst.codemod.yaml,sha256=a8DlErRAIPV1nE6QlyXPAzTOgkB24_spl2E9hphuf5s,772
@@ -19,7 +19,7 @@ crackerjack/.ruff_cache/0.1.4/10355199064880463147,sha256=kmqNg5WySQYPeAqa5elfaV
 crackerjack/.ruff_cache/0.1.6/15140459877605758699,sha256=oQy5boAXeskdm5M0Abh_nyBtitWj5N5wtx_4gsDgu7c,248
 crackerjack/.ruff_cache/0.1.7/1790508110482614856,sha256=De7Puq32XF0925xrGehWSKX6cw5Wi2bpt1cnqh__f54,248
 crackerjack/.ruff_cache/0.1.9/17041001205004563469,sha256=tKP_k8HaHhQJyrHbDfJ93kM7vahjrU8cKQ1f_-OUzZY,248
-crackerjack/.ruff_cache/0.11.2/4070660268492669020,sha256=Op16lNybLTJgeVZVIeTGnKIEeiGrzBwOwh0Nh1pN_Ss,224
+crackerjack/.ruff_cache/0.11.2/4070660268492669020,sha256=vqJ78zDU4OSZumr4xwG-k2cPXu_ATHqYmBc78aW33-o,224
 crackerjack/.ruff_cache/0.2.0/10047773857155985907,sha256=j9LNa_RQ4Plor7go1uTYgz17cEENKvZQ-dP6b9MX0ik,248
 crackerjack/.ruff_cache/0.2.1/8522267973936635051,sha256=u_aPBMibtAp_iYvLwR88GMAECMcIgHezxMyuapmU2P4,248
 crackerjack/.ruff_cache/0.2.2/18053836298936336950,sha256=Xb_ebP0pVuUfSqPEZKlhQ70so_vqkEfMYpuHQ06iR5U,248
@@ -47,8 +47,8 @@ crackerjack/.ruff_cache/0.9.3/13948373885254993391,sha256=kGhtIkzPUtKAgvlKs3D8j4
 crackerjack/.ruff_cache/0.9.9/12813592349865671909,sha256=tmr8_vhRD2OxsVuMfbJPdT9fDFX-d5tfC5U9jgziyho,224
 crackerjack/.ruff_cache/0.9.9/8843823720003377982,sha256=e4ymkXfQsUg5e_mtO34xTsaTvs1uA3_fI216Qq9qCAM,136
 crackerjack/.ruff_cache/CACHEDIR.TAG,sha256=WVMVbX4MVkpCclExbq8m-IcOZIOuIZf5FrYw5Pk-Ma4,43
-crackerjack/__init__.py,sha256=XTWW_XQkWR6dSydFSLg-T--eY3TPKUp4jUwZP11kgwY,142
-crackerjack/__main__.py,sha256=7SHrcRFYhMaSV0S-EG8q2w8udURwdvIsS7vi9AW4naU,3784
-crackerjack/crackerjack.py,sha256=xjGDSUIl0vbNA9SfsP0lzs7eWD33yk0yeXxnmvQz3Qg,21365
-crackerjack/pyproject.toml,sha256=5FBnczdH9wR4u9EooqzyHXQd6eK1vI1GJ5Vm3G-xh04,4089
-crackerjack-0.14.9.dist-info/RECORD,,
+crackerjack/__init__.py,sha256=r9SuEjHUrW99hFWifRk4ofmYPSgf9rblcnzqhdV5bP0,157
+crackerjack/__main__.py,sha256=iwoUyUB9j3e5lC5ViNAqW00eeoIx0xljNmWC04AiPaw,3707
+crackerjack/crackerjack.py,sha256=alZ44ZldvqTpKo2RkAA0kq9RTueFeYeq__YbRlLN1Vg,22355
+crackerjack/pyproject.toml,sha256=Q00BGPOeoESTrTbRFUFNXmoskntjP36eypSEDmYAMzk,4089
+crackerjack-0.15.0.dist-info/RECORD,,