pluginkit 0.4.0__tar.gz → 0.4.2__tar.gz

pluginkit-0.4.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Morten Hansen
+
+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.

{pluginkit-0.4.0 → pluginkit-0.4.2}/PKG-INFO

@@ -1,14 +1,14 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: pluginkit
-Version: 0.4.0
+Version: 0.4.2
 Summary: A strictly-typed, generics-first plugin framework for Python 3.13: hooks with derived return types
 Keywords: plugins,hooks,protocol,entry-points
 Author: Morten Hansen
 Author-email: Morten Hansen <morten@winterop.com>
-License: MIT
+License-Expression: MIT
+License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
@@ -38,7 +38,7 @@ hand-annotations and no drift. Zero runtime dependencies, a `py.typed` marker, a
 few readable files.
 
 ```bash
-pip install pluginkit   # or: uv add pluginkit
+uv add pluginkit   # or: pip install pluginkit
 ```
 
 ```python
@@ -87,16 +87,17 @@ print(greetings)                                     # ['hey Ada!']
 ```
 src/pluginkit/             the library (pure - no demo code)
 examples/                  everything that uses the library (not shipped):
-  recipes/                   standalone single-file scripts, run directly
+  cookbook/                  worked examples: bite-size scripts + full apps
   tour/                      pluginkit-tour: a guided CLI walkthrough
   external-plugin/           a separate distribution discovered via entry points
 docs/                      mkdocs + Material documentation
-tests/                     library, tour, and recipe tests
+tests/                     library, tour, and cookbook tests
 ```
 
-Everything that demonstrates the library lives under `examples/`. The **recipes**
-are independent scripts you run on their own; the **tour** is a guided walkthrough
-on one host; the **external-plugin** shows cross-package discovery via entry points.
+Everything that demonstrates the library lives under `examples/`. The **cookbook**
+holds standalone examples (from one-mechanism snippets to complete FastAPI/Click/pytest
+apps); the **tour** is a guided walkthrough on one host; the **external-plugin** shows
+cross-package discovery via entry points.
 
 ## Use it
 
@@ -118,14 +119,14 @@ make run DEMO=wrapper      # run one
 uv run pluginkit-tour list
 ```
 
-**The recipes** apply the library to different realistic domains - see
-[`examples/`](examples/README.md):
+**The cookbook** applies the library to realistic domains and frameworks - see
+[`examples/cookbook/`](examples/cookbook/README.md):
 
 ```bash
-uv run python examples/recipes/report_builder.py
-uv run python examples/recipes/notification_router.py
-uv run python examples/recipes/validation_rules.py
-uv run python examples/recipes/app_lifecycle.py
+uv run python examples/cookbook/report_builder.py
+uv run python examples/cookbook/fastapi_app.py
+uv run python examples/cookbook/cli_app.py --help
+uv run python examples/cookbook/app_lifecycle.py
 ```
 
 ## Documentation

{pluginkit-0.4.0 → pluginkit-0.4.2}/README.md

@@ -17,7 +17,7 @@ hand-annotations and no drift. Zero runtime dependencies, a `py.typed` marker, a
 few readable files.
 
 ```bash
-pip install pluginkit   # or: uv add pluginkit
+uv add pluginkit   # or: pip install pluginkit
 ```
 
 ```python
@@ -66,16 +66,17 @@ print(greetings)                                     # ['hey Ada!']
 ```
 src/pluginkit/             the library (pure - no demo code)
 examples/                  everything that uses the library (not shipped):
-  recipes/                   standalone single-file scripts, run directly
+  cookbook/                  worked examples: bite-size scripts + full apps
   tour/                      pluginkit-tour: a guided CLI walkthrough
   external-plugin/           a separate distribution discovered via entry points
 docs/                      mkdocs + Material documentation
-tests/                     library, tour, and recipe tests
+tests/                     library, tour, and cookbook tests
 ```
 
-Everything that demonstrates the library lives under `examples/`. The **recipes**
-are independent scripts you run on their own; the **tour** is a guided walkthrough
-on one host; the **external-plugin** shows cross-package discovery via entry points.
+Everything that demonstrates the library lives under `examples/`. The **cookbook**
+holds standalone examples (from one-mechanism snippets to complete FastAPI/Click/pytest
+apps); the **tour** is a guided walkthrough on one host; the **external-plugin** shows
+cross-package discovery via entry points.
 
 ## Use it
 
@@ -97,14 +98,14 @@ make run DEMO=wrapper      # run one
 uv run pluginkit-tour list
 ```
 
-**The recipes** apply the library to different realistic domains - see
-[`examples/`](examples/README.md):
+**The cookbook** applies the library to realistic domains and frameworks - see
+[`examples/cookbook/`](examples/cookbook/README.md):
 
 ```bash
-uv run python examples/recipes/report_builder.py
-uv run python examples/recipes/notification_router.py
-uv run python examples/recipes/validation_rules.py
-uv run python examples/recipes/app_lifecycle.py
+uv run python examples/cookbook/report_builder.py
+uv run python examples/cookbook/fastapi_app.py
+uv run python examples/cookbook/cli_app.py --help
+uv run python examples/cookbook/app_lifecycle.py
 ```
 
 ## Documentation

{pluginkit-0.4.0 → pluginkit-0.4.2}/pyproject.toml

@@ -1,16 +1,16 @@
 [project]
 name = "pluginkit"
-version = "0.4.0"
+version = "0.4.2"
 description = "A strictly-typed, generics-first plugin framework for Python 3.13: hooks with derived return types"
 readme = "README.md"
 authors = [{ name = "Morten Hansen", email = "morten@winterop.com" }]
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
 requires-python = ">=3.13"
 keywords = ["plugins", "hooks", "protocol", "entry-points"]
 classifiers = [
   "Development Status :: 4 - Beta",
   "Intended Audience :: Developers",
-  "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3.13",
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Typing :: Typed",
@@ -79,7 +79,7 @@ docstring-code-line-length = "dynamic"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-pythonpath = ["examples/recipes", "examples/integrations"]
+pythonpath = ["examples/cookbook"]
 norecursedirs = [".git", ".venv", "__pycache__"]
 
 [tool.mypy]
@@ -91,7 +91,7 @@ check_untyped_defs = true
 no_implicit_optional = true
 warn_unused_ignores = true
 strict_equality = true
-mypy_path = ["src", "examples/tour/src", "examples/recipes", "examples/integrations"]
+mypy_path = ["src", "examples/tour/src", "examples/cookbook"]
 
 [[tool.mypy.overrides]]
 module = "tests.*"
@@ -105,8 +105,8 @@ module = "pluginkit_tour.points"
 disable_error_code = ["empty-body"]
 
 [tool.pyright]
-include = ["src", "tests", "examples/recipes", "examples/integrations", "examples/tour/src"]
-extraPaths = ["examples/recipes", "examples/integrations", "examples/tour/src"]
+include = ["src", "tests", "examples/cookbook", "examples/tour/src"]
+extraPaths = ["examples/cookbook", "examples/tour/src"]
 exclude = ["**/.venv"]
 pythonVersion = "3.13"
 typeCheckingMode = "strict"

{pluginkit-0.4.0 → pluginkit-0.4.2}/src/pluginkit/aio.py

@@ -29,11 +29,11 @@ from pluginkit.markers import (
 class AsyncHookCaller(HookCaller):
     """A HookCaller whose calls are coroutines that await async implementations."""
 
-    async def __call__(self, **kwargs: Any) -> Any:
+    async def __call__(self, *args: Any, **kwargs: Any) -> Any:
         """Await the hook: a list, a single value (firstresult), or the threaded value (pipeline)."""
         if self.spec.historic:
             raise TypeError(f"historic hook {self.name!r} must be called via call_historic()")
-        kwargs = self.check_arguments(kwargs)
+        kwargs = self.check_arguments(self._bind(args, kwargs))
         return await self._execute_async(kwargs, self._nonwrappers)
 
     async def call_extra(self, functions: list[Callable[..., Any]], kwargs: dict[str, Any]) -> Any:

{pluginkit-0.4.0 → pluginkit-0.4.2}/src/pluginkit/manager.py

@@ -160,11 +160,27 @@ class HookCaller:
             extra.append(impl)
         return extra
 
-    def __call__(self, **kwargs: Any) -> Any:
+    def _bind(self, args: tuple[Any, ...], kwargs: dict[str, Any]) -> dict[str, Any]:
+        """Bind positional args to the spec's params (in order) and merge with kwargs.
+
+        Lets a typed caller be invoked positionally - `caller(value)` as well as
+        `caller(name=value)` - matching what the ParamSpec advertises.
+        """
+        if not args:
+            return kwargs
+        if len(args) > len(self.params):
+            raise TypeError(f"hook {self.name!r} takes at most {len(self.params)} positional argument(s)")
+        positional = dict(zip(self.params, args, strict=False))
+        clash = positional.keys() & kwargs.keys()
+        if clash:
+            raise TypeError(f"hook {self.name!r} got multiple values for {sorted(clash)}")
+        return {**positional, **kwargs}
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
         """Call the hook: a list, a single value (firstresult), or the threaded value (pipeline)."""
         if self.spec.historic:
             raise TypeError(f"historic hook {self.name!r} must be called via call_historic()")
-        kwargs = self.check_arguments(kwargs)
+        kwargs = self.check_arguments(self._bind(args, kwargs))
         return self._execute(kwargs, self._nonwrappers)
 
     def call_extra(self, functions: list[Callable[..., Any]], kwargs: dict[str, Any]) -> Any: