raceway 0.2__tar.gz → 0.2.2__tar.gz

raceway-0.2.2/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: raceway
+Version: 0.2.2
+Summary: Simple dependency injection system. 
+Project-URL: GitHub, https://github.com/ianjosephwilson/raceway
+Author-email: Ian Wilson <ian@gardentheory.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.14
+Provides-Extra: venusian
+Requires-Dist: venusian; extra == 'venusian'
+Description-Content-Type: text/x-rst
+
+raceway
+#########
+
+Minimal dependency injection, DI, system ideal for smaller systems that still need DI.
+
+Overview
+--------
+
+  - Defining: Define protocols and implementations.
+  - Loading: Load registrations extracted from implementations into planner.
+  - Starting: Run startup to create container from planner.
+  - Wrapping: Use injector to wrap task handlers to prepare for injection.
+  - Running: Create task for each "runner" and use it with the container to execute each injection enabled task handler.
+
+Example
+-------
+
+This library is meant to be used with an external framework but this example
+uses python's stdlib threading to demonstrate how the pieces fit together.
+
+.. code-block:: python
+
+    import threading
+    import time
+    from dataclasses import dataclass
+    from typing import Protocol
+    from random import random
+
+    from raceway.extractor import configure_extractor
+    from raceway.registration import Registration
+    from raceway.planner import configure_planner
+    from raceway.starter import startup
+    from raceway.injector import configure_injector
+    from raceway.protocols import IContainer, ITask, IInjector, IExtractor
+
+    class ICrawlJob(ITask, Protocol):
+        def get_link(self) -> str: ...
+
+    @dataclass
+    class CrawlJob(ICrawlJob):
+        def __hash__(self):
+            return id(self)
+        def __eq__(self, other: object):
+            return self is other
+        id: int
+        link: str
+        def get_link(self) -> str:
+            return self.link
+
+    class ICrawler(Protocol):
+        def crawl(self, delay: float) -> str: ...
+
+    @dataclass
+    class CrawlerService(ICrawler):
+        job: ICrawlJob
+        def crawl(self, delay: float) -> str:
+            return f"Crawled {self.job.get_link()} in {delay}s."
+
+    def run_job(crawler_api: ICrawler) -> None:
+        delay = 3*random()
+        time.sleep(delay)  # Blocking I/O (simulating a network request)
+        print (crawler_api.crawl(delay))
+
+
+    def main():
+        #
+        # Setup
+        #
+        extractor_api =  configure_extractor()
+        injector_api = configure_injector(extractor=extractor_api, task_proto=ICrawlJob)
+        planner = configure_planner(task_proto=ICrawlJob)
+        planner.queue_registration(
+            ICrawler,
+            Registration(
+                CrawlerService, extractor_api.extract(CrawlerService), scope="task"
+            ),
+        )
+        container_api = startup(planner=planner)
+
+        # Prepare job runner for injection.
+        wrapped_with_inject = injector_api.wrap_in_inject(run_job)
+
+        #
+        # Payloads
+        #
+        links = [
+            "https://python.org",
+            "https://docs.python.org",
+            "https://peps.python.org",
+            *[f"https://example.com/{v}" for v in range(20)],
+        ]
+
+
+        #
+        # Start threads for each link
+        #
+        threads = []
+        for link_id, link in enumerate(links):
+            # Using `args` to pass positional arguments and `kwargs` for keyword arguments
+            # ... in our case we are passing the args the inject function will need.
+            job = CrawlJob(link_id, link)
+            t = threading.Thread(
+                target=wrapped_with_inject,
+                args=(container_api, job),
+            )
+            threads.append(t)
+
+        # Start each thread
+        for t in threads:
+            t.start()
+
+        # Wait for all threads to finish
+        for t in threads:
+            t.join()
+
+
+    if __name__ == '__main__':
+        main()

raceway-0.2.2/README.rst

@@ -0,0 +1,118 @@
+raceway
+#########
+
+Minimal dependency injection, DI, system ideal for smaller systems that still need DI.
+
+Overview
+--------
+
+  - Defining: Define protocols and implementations.
+  - Loading: Load registrations extracted from implementations into planner.
+  - Starting: Run startup to create container from planner.
+  - Wrapping: Use injector to wrap task handlers to prepare for injection.
+  - Running: Create task for each "runner" and use it with the container to execute each injection enabled task handler.
+
+Example
+-------
+
+This library is meant to be used with an external framework but this example
+uses python's stdlib threading to demonstrate how the pieces fit together.
+
+.. code-block:: python
+
+    import threading
+    import time
+    from dataclasses import dataclass
+    from typing import Protocol
+    from random import random
+
+    from raceway.extractor import configure_extractor
+    from raceway.registration import Registration
+    from raceway.planner import configure_planner
+    from raceway.starter import startup
+    from raceway.injector import configure_injector
+    from raceway.protocols import IContainer, ITask, IInjector, IExtractor
+
+    class ICrawlJob(ITask, Protocol):
+        def get_link(self) -> str: ...
+
+    @dataclass
+    class CrawlJob(ICrawlJob):
+        def __hash__(self):
+            return id(self)
+        def __eq__(self, other: object):
+            return self is other
+        id: int
+        link: str
+        def get_link(self) -> str:
+            return self.link
+
+    class ICrawler(Protocol):
+        def crawl(self, delay: float) -> str: ...
+
+    @dataclass
+    class CrawlerService(ICrawler):
+        job: ICrawlJob
+        def crawl(self, delay: float) -> str:
+            return f"Crawled {self.job.get_link()} in {delay}s."
+
+    def run_job(crawler_api: ICrawler) -> None:
+        delay = 3*random()
+        time.sleep(delay)  # Blocking I/O (simulating a network request)
+        print (crawler_api.crawl(delay))
+
+
+    def main():
+        #
+        # Setup
+        #
+        extractor_api =  configure_extractor()
+        injector_api = configure_injector(extractor=extractor_api, task_proto=ICrawlJob)
+        planner = configure_planner(task_proto=ICrawlJob)
+        planner.queue_registration(
+            ICrawler,
+            Registration(
+                CrawlerService, extractor_api.extract(CrawlerService), scope="task"
+            ),
+        )
+        container_api = startup(planner=planner)
+
+        # Prepare job runner for injection.
+        wrapped_with_inject = injector_api.wrap_in_inject(run_job)
+
+        #
+        # Payloads
+        #
+        links = [
+            "https://python.org",
+            "https://docs.python.org",
+            "https://peps.python.org",
+            *[f"https://example.com/{v}" for v in range(20)],
+        ]
+
+
+        #
+        # Start threads for each link
+        #
+        threads = []
+        for link_id, link in enumerate(links):
+            # Using `args` to pass positional arguments and `kwargs` for keyword arguments
+            # ... in our case we are passing the args the inject function will need.
+            job = CrawlJob(link_id, link)
+            t = threading.Thread(
+                target=wrapped_with_inject,
+                args=(container_api, job),
+            )
+            threads.append(t)
+
+        # Start each thread
+        for t in threads:
+            t.start()
+
+        # Wait for all threads to finish
+        for t in threads:
+            t.join()
+
+
+    if __name__ == '__main__':
+        main()

{raceway-0.2 → raceway-0.2.2}/pyproject.toml

@@ -1,11 +1,12 @@
 [tool.black]
-line-length = 80
 target-version = ['py314']
 
+
 [tool.pytest.ini_options]
 addopts = [
     "--import-mode=importlib",
 ]
+
 [tool.pyright]
 include = [
     "src/raceway/**/*.py"
@@ -15,6 +16,7 @@ exclude = [
 ]
 
 [tool.hatch]
+installer = "pip"
 
 [tool.hatch.env]
 
@@ -35,10 +37,38 @@ packages = ["src/raceway"]
 requires = ["hatchling >= 1.26"]
 build-backend = "hatchling.build"
 
+[tool.hatch.envs.default]
+dependencies = [
+    "pytest",
+    "pyright",
+    "flake8",
+    "flake8-bugbear",
+    "black",
+    "twine",
+]
+
+[tool.hatch.envs.default.scripts]
+testit="pytest tests"
+checkit=["pyright src tests"]
+lintit=["flake8 src tests"]
+shapeit=["black src tests"]
+buildit=[
+    "python -m build --wheel",
+    "python -m build --sdist",
+    "twine check dist/*.whl"
+]
+tagit=[
+    "git tag -a v`hatch version` -m Version' '`hatch version`",
+    "git push origin v`hatch version`"
+]
+releaseit=[
+    "twine upload dist/*",
+]
 
 [project]
 name = "raceway"
 description = "Simple dependency injection system. "
+readme = "README.rst"
 dynamic = ["version"]
 dependencies = []
 authors = [
@@ -51,4 +81,9 @@ classifiers = [
 ]
 license = "MIT"
 license-files = ["LICEN[CS]E*"]
-homepage="https://github.com/ianjosephwilson/raceway"
+
+[project.urls]
+GitHub="https://github.com/ianjosephwilson/raceway"
+
+[project.optional-dependencies]
+venusian = ["venusian"]

raceway-0.2.2/src/raceway/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.2.2"

raceway-0.2.2/src/raceway/callbacks.py

@@ -0,0 +1,103 @@
+"""
+This module provides decorators that attach callbacks that venusian can find.
+"""
+
+from collections.abc import Callable
+from contextvars import ContextVar
+from dataclasses import dataclass, is_dataclass
+from inspect import isclass
+
+from .exc import RacewayError
+from .protocols import ILoader, IPlanner, IExtractor, ScopeType
+from .registration import Registration
+
+DEFAULT_CATEGORY = "raceway.service"
+
+
+# @TODO: Make sure this the latest and greatest pattern for doing this.
+# We don't want to raise unless someone tries to use the actual
+# decorators without another attach.
+try:
+    import venusian
+
+    venusian_attach = venusian.attach
+except ImportError:
+    venusian_attach = None
+
+
+LoaderCtx: ContextVar[ILoader | None] = ContextVar("LoaderCtx")
+"""ContextVar that holds the loader during scanning for callbacks."""
+
+
+class CallbackError(RacewayError):
+    pass
+
+
+@dataclass
+class Loader(ILoader):
+    planner: IPlanner
+    extractor: IExtractor
+
+
+def configure_loader(planner: IPlanner, extractor: IExtractor) -> ILoader:
+    return Loader(planner=planner, extractor=extractor)
+
+
+def feed_loader(
+    loader: ILoader,
+    feed: Callable[[], None],
+    cv: ContextVar[ILoader | None] = LoaderCtx,
+):
+    """Setup the loader context and then call feed."""
+    with cv.set(loader):
+        feed()
+
+
+def configure_as_service[T](
+    register_proto: type[T],
+    cv: ContextVar[ILoader | None] = LoaderCtx,
+    attach: Callable | None = venusian_attach,
+    scope: ScopeType = "task",
+    wrap_in_dataclass: bool = True,
+    category: str = DEFAULT_CATEGORY,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Decorate a service factory with a callback that can be executed to feed
+    its registration to a loader.
+
+    @NOTE: The `cv` must be set with a loader during callback's execution. This
+    can be done by passing a `feed()` function into `feed_loader` along with
+    a configured loader.
+    """
+    if attach is None:
+        raise CallbackError("Venusian must be installed to use callbacks.")
+
+    def wrapper(
+        service_factory: Callable[..., T],
+    ) -> Callable[..., T]:
+        # Wrap the service class in a dataclass here in case it is needed
+        # at anypoint in the future.  This is almost just for convenience
+        # and maybe it should be moved to an extended decorator.
+        if (
+            wrap_in_dataclass
+            and isclass(service_factory)
+            and not is_dataclass(service_factory)
+        ):
+            service_factory = dataclass(service_factory)
+
+        def callback(*_):
+            """Callback for venusian scan."""
+            loader = cv.get()
+            if loader is None:
+                raise CallbackError(
+                    f"{cv} context variable must be set when callback fires."
+                )
+            dep_specs = loader.extractor.extract(service_factory)
+            loader.planner.queue_registration(
+                register_proto, Registration(service_factory, dep_specs, scope=scope)
+            )
+
+        attach(service_factory, callback, category=category)
+        return service_factory
+
+    return wrapper

raceway-0.2.2/src/raceway/container.py

@@ -0,0 +1,149 @@
+from dataclasses import dataclass
+from weakref import WeakKeyDictionary, WeakValueDictionary
+
+from .exc import RacewayError
+from .protocols import (
+    IContainer,
+    IRegistry,
+    IRegistration,
+    IDepSpec,
+    ScopeType,
+)
+from .rules import can_depend_on
+
+
+class ContainerError(RacewayError):
+    """General error during container operations."""
+
+    pass
+
+
+class NotSet:
+    pass
+
+
+NOT_SET = NotSet()
+
+
+def create_task_cache() -> WeakValueDictionary:
+    return WeakValueDictionary()
+
+
+def create_container_cache() -> WeakKeyDictionary:
+    return WeakKeyDictionary()
+
+
+def configure_container[V, W](
+    registry: IRegistry,
+    startup_task: W,
+    task_proto: type[V],
+) -> IContainer[V, W]:
+    cache = create_container_cache()
+    return Container(
+        cache=cache, registry=registry, startup_task=startup_task, task_proto=task_proto
+    )
+
+
+@dataclass
+class Container[V, W](IContainer[V, W]):
+
+    cache: WeakKeyDictionary
+
+    registry: IRegistry
+
+    startup_task: W
+
+    task_proto: type[V]
+
+    def validate_dep_specs(
+        self,
+        dep_specs: tuple[tuple[str, IDepSpec], ...],
+        scope: ScopeType = "call",
+    ) -> None:
+        for _, dep_spec in dep_specs:
+            reg = self.registry.find(dep_spec.proto)
+            if reg is None:
+                raise ContainerError(
+                    f"Cannot find registration for given protocol: {dep_spec.proto}"
+                )
+            dep_scope = reg.scope
+            if not can_depend_on(scope, dep_scope):
+                raise ContainerError(
+                    f"Scope mismatch: {scope} cannot depend on {dep_spec.proto}:{dep_scope}"  # noqa B950
+                )
+
+    def resolve_deps(  # @TODO: Should be dep specs too
+        self,
+        dep_specs: tuple[tuple[str, IDepSpec], ...],
+        task: V | None = None,
+    ) -> tuple[tuple[str, object], ...]:
+        resolved = []
+        for dep_name, dep_spec in dep_specs:
+            result = self.find_service(dep_spec.proto, task=task)
+            if dep_spec.attr:
+                result = getattr(result, dep_spec.attr)
+            if dep_spec.key:
+                result = result[dep_spec.key]  # type: ignore
+            if dep_spec.call_kwargs is not None or dep_spec.call_args is not None:
+                call_kwargs = (
+                    dict(dep_spec.call_kwargs)
+                    if dep_spec.call_kwargs is not None
+                    else {}
+                )
+                call_args = dep_spec.call_args if dep_spec.call_args is not None else ()
+                result = result(*call_args, **call_kwargs)  # type: ignore
+            resolved.append((dep_name, result))
+        return tuple(resolved)
+
+    def make_service[T](
+        self,
+        reg: IRegistration[T],
+        task: V | None = None,
+    ) -> T:
+        deps = dict(self.resolve_deps(reg.dep_specs, task=task))
+        return reg.factory(**deps)
+
+    def find_service[T](
+        self,
+        proto: type[T],
+        task: V | None = None,
+    ) -> T:
+        if proto is self.task_proto:
+            if task is None:
+                raise ContainerError("Cannot find task because no task was provided!")
+            return task  # type: ignore @TODO: Resolve this when we rewrite all the types.
+        reg = self.registry.find(proto)
+        if reg is None:
+            raise ContainerError(
+                f"Cannot find registration for given protocol: {proto}"
+            )
+        if reg.scope == "startup":
+            if self.startup_task in self.cache:
+                task_cache = self.cache[self.startup_task]
+            else:
+                maybe_cache = create_task_cache()
+                # We use the *result* of setdefault to try to avoid the race condition.
+                task_cache = self.cache.setdefault(self.startup_task, maybe_cache)
+            v = task_cache.get(proto, NOT_SET)
+            if v is NOT_SET:
+                maybe_v = self.make_service(reg, task=task)
+                v = task_cache.setdefault(proto, maybe_v)
+            return v
+        elif reg.scope == "task":
+            if task is None:
+                raise ContainerError(
+                    "Cannot access task cache without providing a task!"
+                )
+            if task in self.cache:
+                task_cache = self.cache[task]
+            else:
+                # We use the *result* of setdefault to try to avoid the race condition.
+                maybe_cache = create_task_cache()
+                task_cache = self.cache.setdefault(task, maybe_cache)
+            v = task_cache.get(proto, NOT_SET)
+            if v is NOT_SET:
+                maybe_v = self.make_service(reg, task=task)
+                v = task_cache.setdefault(proto, maybe_v)
+            return v
+        else:
+            return self.make_service(reg, task=task)