wonka 0.1.2__py3-none-any.whl

wonka/__init__.py

@@ -0,0 +1,47 @@
+"""Flexible, accessible, extensible Python factories"""
+
+from __future__ import annotations
+
+__version__ = '0.1.2'
+
+__author__: str = 'Corey Rayburn Yung'
+
+__all__: list[str] = [
+    'Assembler',
+    'Classer',
+    'Delegate',
+    'Factory',
+    'Flexer',
+    'Instancer',
+    'Manager',
+    'Manufacturer',
+    'Producer',
+    'Registrar',
+    'Scribe',
+    'Sourcerer',
+    'Subclasser',
+    'finalize',
+    'inject_attributes',
+    'is_constructor',
+    'set_compatibility_rule',
+    'set_keyer',
+    'set_method_namer',
+    'set_overwrite_rule',
+    'set_verbose_rule']
+
+
+from .base import Factory, Manager, Producer
+from .configuration import (
+    set_compatibility_rule,
+    set_keyer,
+    set_method_namer,
+    set_overwrite_rule,
+    set_verbose_rule,
+)
+from .dispatchers import Delegate, Sourcerer
+from .managers import Assembler
+from .producers import Classer, Flexer, Instancer
+from .prototypers import Scribe
+from .registries import Registrar, Subclasser
+from .shared import finalize, inject_attributes, is_constructor
+from .storage import Manufacturer

wonka/base.py

@@ -0,0 +1,165 @@
+"""Base classes for `wonka` constructors.
+
+Contents:
+    Factory (`abc.ABC`): interface for basic `wonka` creation classes. A
+        `create` class method is required for subclasses.
+    Manager (`Iterable`, `abc.ABC`): iterable interface for complex construction
+        managers. A `manage` instance method is required for subclasses. For
+        compatibility as a `wonka` constructor, a `create` property is included
+        which automatically calls the `manage` method with all args and kwargs.
+    Producer (`abc.ABC`): mixin interface for classes that alter created items
+        before returning them. A `produce` class method is required for
+        subclasses.
+    Constructor (`TypeAlias`): type alias for a wonka-compatible constructor
+        type. By default, it includes a `Factory` subclass, a `Factory` subclass
+        instance, and a `Manager` subclass instance.
+
+"""
+
+from __future__ import annotations
+
+import abc
+import dataclasses
+from collections.abc import Hashable, Iterable, Iterator, MutableMapping
+from typing import Any, TypeAlias
+
+
+@dataclasses.dataclass
+class Factory(abc.ABC):
+    """Base for `wonka` constructors.
+
+    A `wonka` `Factory` can be subclassed into any constructer design (not just
+    those that fit the classical factory design pattern). So, for example, the
+    `wonka` package itself includes `Factory` subclasses that fit the prototype
+    (`Scribe`), registry (`Registar` and` Subclasser`), and traditional
+    (`Delegate` and `Sourcerer`) design patterns. Further, a `Manager` class
+    instance may act as the director in a builder design pattern.
+
+    One of the goals of `wonka`, though, is not be be wedded to or worried about
+    the underlying design pattern. Instead, all constructers follow the simple,
+    universal, and easily extensible interface of `Factory`.
+
+    If you want to add code that modifies output of a `Factory`'s `create` class
+    method, you can either include that in the subclass `create` method or by
+    mixing in a `Producer` class. Details on how to use `Producer` subclasses
+    are included in its documentation.
+
+    """
+
+    """ Required Subclass Methods """
+
+    @classmethod
+    @abc.abstractmethod
+    def create(cls, item: Any, *args: Any, **kwargs: Any) -> Any:
+        """Returns a created or modified item.
+
+        Args:
+            item: data for creation of an item or an item to be modified.
+            args: allows subclass to take args.
+            kwargs: allows subclass to take kwargs.
+
+        Returns:
+            Any: created or modified item.
+
+        """
+
+
+@dataclasses.dataclass
+class Manager(Iterable, abc.ABC):
+    """Base for manageing complex class or object construction.
+
+    Args:
+        contents: an iterable containing `Factory` subclasses or `Manager`
+            subclass instances.
+
+    """
+
+    contents: Iterable
+
+    """ Required Subclass Methods """
+
+    @abc.abstractmethod
+    def manage(self, item: Any, *args: Any, **kwargs: Any) -> Any:
+        """Manages construction and/or modification based on `item`.
+
+        Args:
+            item: item to be passed to factories in `contents`.
+            args: allows subclass to take args.
+            kwargs: allows subclass to take kwargs.
+
+        Returns:
+            Any: constructed item.
+
+        """
+
+    """ Properties """
+
+    @property
+    def create(self, *args: Any, **kwargs:  Any) -> Any:
+        """Calls `manage` method with args and kwargs.
+
+        This property is included as a convenience so that an instance of a
+        `Manager` can be used as a drop-in for a `Factory` subclass. `Manager`
+        cannot easily be made a subclass for `Factory` because it will often
+        need to rely on instance data for construction. So, every `Manager`
+        subclass should be designed such that an instance of that subclass could
+        be substituted for a `Factory` subclass. This allows other `Manager`
+        subclass instances to be stored in `contents` as part of an iterable
+        workflow.
+
+        """
+        return self.manage(*args, **kwargs)
+
+    """ Dunder Methods """
+
+    def __iter__(self) -> Iterator:
+        """Returns iterable of `contents`.
+
+        `Manager` is agnostic as to the type of iterable that is used in order
+        to accomodate simple sequences, complex graphs, nested trees, or any
+        other workflow design. As a general practice, though, any mapping should
+        probably return `items()` so that the interface for iteration never
+        requires any appended method call. But nothing in `wonka` precludes a
+        different rule or practice.
+
+        """
+        return iter(self.contents)
+
+
+@dataclasses.dataclass
+class Producer(abc.ABC):
+    """Base mixin for modifying items.
+
+    A `Producer`'s `produce` method will automatically be called if it is
+    mixed-in with any of the `Factory` classes in `wonka`. If you want a custom
+    `Factory` subclass to similarly automatically check for a `produce` method,
+    the easiest way to do that is to simply call the `finalize` function as your
+    return value for the `Factory`'s `create` method as follows:
+
+    ```python
+    return wonka.finalize(item = item, parameters = parameters)
+    ```
+    """
+
+    """ Required Subclass Methods """
+
+    @classmethod
+    @abc.abstractmethod
+    def produce(
+        cls,
+        item: Any,
+        parameters: MutableMapping[Hashable, Any] | None = None) -> Any:
+        """Modifies `item` and possibly incorporates `parameters`.
+
+        Args:
+            item: item to be modified.
+            parameters: keyword arguments to pass or add to a created instance.
+                Defaults to `None`.
+
+        Returns:
+            Any: modified item.
+
+        """
+
+
+Constructor: TypeAlias = Factory | type[Factory] | Manager

wonka/configuration.py

@@ -0,0 +1,132 @@
+"""Configuration settings and convenience functions for changing those settings.
+
+Contents:
+    set_compatibility_rule: sets the global attribute compatibility rule.
+    set_keyer: sets the global default function used to name dict keys.
+    set_method_namer: sets the global default function used to name factory
+        creation methods.
+    set_overwrite_rule: sets the global attribute overwrite rule.
+    set_verbose_rule: sets the global attribute message verbosity rule.
+
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from . import utilities
+
+# Default naming function for non-str objects.
+_KEY_NAMER: Callable[[object | type[Any]], str] = utilities._namify
+# Default naming convention for dispatcher registry creation methods.
+_METHOD_NAMER: Callable[[object | type[Any]], str] = lambda x: f'from_{x}'
+# Whether to overwrite existing attributes when arguments are passed to create
+# an item that is already an instance or has class attributes of the same name
+# as in the passed arguments.
+_OVERWRITE: bool = True
+# Whether to validate an object as a subclass of a `wonka`-constructor or to
+# support duck typing by not validating an object before its use.
+_STRICT_COMPATIBILITY: bool = True
+# Whether to return more elaborate error messages and feedback.
+_VERBOSE: bool = False
+
+
+def set_compatibility_rule(compatibility: bool) -> None:
+    """Sets the global attribute compatibility rule.
+
+    Args:
+        compatibility: whether to require the `is_constructor` method to use
+            strict or relaxed validation.
+
+    Raises:
+        TypeError: if `compatibility` is not `bool`.
+
+    """
+    if isinstance(compatibility, bool):
+        globals()["_STRICT_COMPATIBILITY"] = compatibility
+    else:
+        raise TypeError('compatibility argument must be boolean')
+
+def set_keyer(keyer: Callable[[object | type[Any]], str]) -> None:
+    """Sets the global default function used to name `dict` keys.
+
+    Args:
+        keyer: function that returns a `str` name of any item passed.
+
+    Raises:
+        TypeError: if `keyer` is not callable.
+
+    """
+    if isinstance(keyer, Callable):
+        globals()["_KEY_NAMER"] = keyer
+    else:
+        raise TypeError('keyer argument must be a callable')
+
+def set_method_namer(namer: Callable[[object | type[Any]], str]) -> None:
+    """Sets the global default function used to name factory creation methods.
+
+    Args:
+        namer: function that returns a `str` name of any item passed.
+
+    Raises:
+        TypeError: if 'keyer' is not callable.
+
+    """
+    if isinstance(namer, Callable):
+        globals()["_METHOD_NAMER"] = namer
+    else:
+        raise TypeError('namer argument must be a callable')
+
+def set_overwrite_rule(overwrite: bool) -> None:
+    """Sets the global attribute overwrite rule.
+
+    Args:
+        overwrite: whether to set the default rule to overwrite existing
+            attributes.
+
+    Raises:
+        TypeError: if `overwrite` is not bool.
+
+    """
+    if isinstance(overwrite, bool):
+        globals()["_OVERWRITE"] = overwrite
+    else:
+        raise TypeError('overwrite argument must be boolean')
+
+def set_verbose_rule(verbose: bool) -> None:
+    """Sets the global attribute message verbosity rule.
+
+    Args:
+        verbose: whether to set the default rule to verbosity in logging and
+            messaging.
+
+    Raises:
+        TypeError: if `verbose` is not bool.
+
+    """
+    if isinstance(verbose, bool):
+        globals()["_VERBOSE"] = verbose
+    else:
+        raise TypeError('verbose argument must be boolean')
+
+
+# @dataclasses.dataclass
+# class _MISSING_VALUE(object):
+#     """Sentinel object for a missing data or parameter.
+
+#     This follows the same pattern as the '__MISSING_TYPE` class in the builtin
+#     dataclasses library.
+#     https://github.com/python/cpython/blob/3.10/Lib/dataclasses.py#L182-L186
+
+#     Because None is sometimes a valid argument or data option, this class
+#     provides an alternative that does not create the confusion that a default of
+#     None can sometimes lead to.
+
+#     """
+#     pass
+
+
+# # _MISSING, instance of _MISSING_VALUE, should be used for missing values as an
+# # alternative to None when None is a valid value for an argument. This provides
+# # a fuller repr and traceback.
+# _MISSING = _MISSING_VALUE()

wonka/dispatchers.py

@@ -0,0 +1,191 @@
+"""Dispatchers: factory classes that call other constructors.
+
+Contents:
+    Delegate (`base.Factory`): builds classes and/or instances using methods
+        that follow a naming convention and the `str` names of the types of the
+        first argument passed to the `create` class method.
+    Sourcerer (`base.Factory`): builds classes and/or instances using methods
+        that follow a naming convention (set at `configuration._METHOD_NAMER`)
+        and a `dict` of types stored in the `sources` class attribute.
+
+"""
+from __future__ import annotations
+
+import abc
+import dataclasses
+import inspect
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from . import base, configuration, shared
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Hashable, MutableMapping
+
+
+@dataclasses.dataclass
+class Delegate(base.Factory):
+    """Builds based on the str name of the type passed.
+
+    This factory acts as a dispatcher to call creation methods based on the type
+    or name of the type passed in a manner identical to `Sourcerer`. However,
+    unlike `Sourcerer`, `Delegate` only finds a matching creation method if the
+    `str` name of the type of `item` matches a substring of the creation method
+    name using the format of `configuration._METHOD_NAMER`.
+
+    """
+
+    """ Class Methods """
+
+    @classmethod
+    def create(
+        cls,
+        item: Any,
+        parameters: MutableMapping[Hashable, Any] | None = None,
+        **kwargs: Any) -> Any:
+        """Creates an item based on `item` and possibly `parameters`.
+
+        Args:
+            item: data for construction of the returned item.
+            parameters: keyword arguments to pass or add to a created instance.
+            kwargs: allows subclass to take kwargs.
+
+        Raises:
+            AttributeError: If an appropriate method does not exist for the
+                data type of `item.`
+            KeyError: If a corresponding subclass does not exist for `item.`
+
+        Returns:
+            Created item.
+
+        """
+        builder = _get_creation_method_name(item)
+        item = _get_from_builder_method(
+            factory = cls,
+            method = builder,
+            source = item,
+            **kwargs)
+        return shared.finalize(item = item, parameters = parameters)
+
+
+@dataclasses.dataclass
+class Sourcerer(base.Factory, abc.ABC):
+    """Builds based on compatibility with keys in the `sources` class attribute.
+
+    This factory acts as a dispatcher to call other methods based on the type
+    passed. Unlike `Delegate`, `Sourcerer` is more forgiving by allowing the
+    type passed to a subtype or instance of the type listed as a key in the
+    `sources` class attribute.
+
+    The name for a `Sourcerer` is spelled the way it is instead of "Sorcerer"
+    because the `sources` attribute is used. This is inspired by the "Divinity:
+    Original Sin" games where the magic users are called "Sourcerers" because
+    they may manipulate the magical energy known as "source".
+    https://divinity.fandom.com/wiki/Sourcerer
+
+    Attributes:
+        sources: `dict` with keys that are types and values are substrings of
+            the names of methods to call when the key type is passed to the
+            `create` method. Defaults to an empty `dict`.
+
+    """
+
+    sources: ClassVar[MutableMapping[type[Any], str]] = {}
+
+    """ Class Methods """
+
+    @classmethod
+    def create(
+        cls,
+        item: Any,
+        parameters: MutableMapping[Hashable, Any] | None = None,
+        **kwargs: Any) -> Any:
+        """Creates an item based on `item` and possibly `parameters`.
+
+        Args:
+            item: data for construction of the returned item.
+            parameters: keyword arguments to pass or add to a created instance.
+            kwargs: allows subclass to add additional parameters.
+
+        Raises:
+            AttributeError: if the value matching the key `item` does not
+                correspond to a method in the `Sourcerer` subclass.
+            KeyError: if there is no key in `sources` matching the type for
+                `item`.
+
+        Returns:
+            Created item.
+
+        """
+        for kind, substring in cls.sources.items():
+            if _is_kind(item, kind):
+                builder = _get_creation_method_name(substring)
+                item = _get_from_builder_method(
+                    factory = cls,
+                    method = builder,
+                    source = item,
+                    **kwargs)
+                return shared.finalize(item = item, parameters = parameters)
+        raise KeyError(f'{item} does not match any recognized types')
+
+
+def _get_creation_method_name(
+    source: Any,
+    method_namer: Callable[[object | type[Any]], str] | None = None) -> str:
+    """Returns the creation method name for factories that call other methods.
+
+    Args:
+        source: source data for creating a method name.
+        method_namer: callable to create the creation method name. Defaults to
+            `None`.  If it is `None`, the global namer stored in
+            `configuration._METHOD_NAMER` will be used.
+
+    Returns:
+        Name of the creation method to use.
+
+    """
+    if not isinstance(source, str):
+        source = configuration._KEY_NAMER(source)
+    namer = method_namer or configuration._METHOD_NAMER
+    return namer(source)
+
+def _is_kind(item: Any, kind: type[Any]) -> bool:
+    """Returns if `item` is an instance or subclass of `kind`.
+
+    Args:
+        item (Any): item to evalute.
+        kind (type[Any]): type to compare `item` to.
+
+    Returns:
+        Whether `item` is an instance or subclass of `kind`.
+
+    """
+    return (
+        isinstance(item, kind)
+        or (inspect.isclass(item and issubclass(item, kind))))
+
+def _get_from_builder_method(
+    factory: Any,
+    method: str,
+    source: Any,
+    **kwargs: Any) -> Any:
+    """Returns constructed item from a builder method of `factory`.
+
+    Args:
+        factory: factory class or instance.
+        method : name of the method to use to construct an item.
+        source: the `source` data used to create item.
+        kwargs: allows subclass to take kwargs.
+
+    Raises:
+        AttributeError: if `factory` has no method named `method`.
+
+
+    Returns:
+        Constructed item.
+
+    """
+    try:
+        builder = getattr(factory, method)
+        return builder(source, **kwargs)
+    except AttributeError as e:
+        raise AttributeError(f'{method} does not exist in {factory}') from e