classicist 1.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

classicist/__init__.py

@@ -1,118 +1,50 @@
-import logging
-
-
-logger = logging.getLogger(__name__)
-
-
-class hybridmethod(object):
-    """The 'hybridmethod' decorator allows a method to be used as both a class method
-    and an instance method. The hybridmethod class decorator can wrap methods defined
-    in classes using the usual @decorator syntax. Methods defined in classes that are
-    decorated with the @hybridmethod decorator can be accessed as both class methods
-    and as instance methods, with the first argument passed to the method being the
-    reference to either the class when the method is called as a class method or to
-    the instance when the method is called as an instance method.
-
-    A check of the value of the first variable using isinstance(<variable>, <class>) can
-    be used within a hybrid method to determine if the call was made on an instance of
-    the class in which case the isinstance() call would evalute to True or if the call
-    was made on the class itself, in which case isinstance() would evaluate to False.
-    The variable passed as the first argument to the method may have any name, including
-    'self', as in Python, the use of 'self' as the name of the first argument on an
-    instance method is just customary and the name has no significance like it does in
-    other languages where the reference to the instance is provided automatically and
-    may go by 'self', 'this' or something else."""
-
-    def __init__(self, function: callable):
-        logger.debug(
-            "%s.__init__(function: %s)",
-            self.__class__.__name__,
-            function,
-        )
-
-        if not callable(function):
-            raise TypeError(
-                "The '%s' decorator can only be used to wrap callables!"
-                % (self.__class__.__name__)
-            )
-        elif not type(function).__name__ == "function":
-            raise TypeError(
-                "The '%s' decorator can only be used to wrap functions!"
-                % (self.__class__.__name__)
-            )
-
-        self.function: callable = function
-
-    def __get__(self, instance, owner) -> callable:
-        logger.debug(
-            "%s.__get__(self: %s, instance: %s, owner: %s)",
-            self.__class__.__name__,
-            self,
-            instance,
-            owner,
-        )
-
-        if instance is None:
-            return lambda *args, **kwargs: self.function(owner, *args, **kwargs)
-        else:
-            return lambda *args, **kwargs: self.function(instance, *args, **kwargs)
-
-
-class classproperty(property):
-    """The classproperty decorator transforms a method into a class-level property. This
-    provides access to the method as if it were a class attribute; this addresses the
-    removal of support for combining the @classmethod and @property decorators to create
-    class properties in Python 3.13, a change which was made due to some complexity in
-    the underlying interpreter implementation."""
-
-    def __init__(self, fget: callable, fset: callable = None, fdel: callable = None):
-        super().__init__(fget, fset, fdel)
-
-    def __get__(self, instance: object, klass: type = None):
-        if klass is None:
-            return self
-        return self.fget(klass)
-
-    def __set__(self, instance: object, value: object):
-        # Note that the __set__ descriptor cannot be used on class methods unless
-        # the class is created with a metaclass that implements this behaviour
-        raise NotImplemented
-
-    def __delete__(self, instance: object):
-        # Note that the __delete__ descriptor cannot be used on class methods unless
-        # the class is created with a metaclass that implements this behaviour
-        raise NotImplemented
-
-    def __getattr__(self, name: str):
-        if name in ATTRIBUTES:
-            return getattr(self.fget, name)
-        else:
-            raise AttributeError(
-                "The classproperty method '%s' does not have an '%s' attribute!"
-                % (
-                    self.fget.__name__,
-                    name,
-                )
-            )
-
-    # # For inspectability, provide access to the underlying function's metadata
-    # # including __module__, __name__, __qualname__, __doc__, and __annotations__
-    # @property
-    # def __module__(self):
-    #     return self.fget.__module__
-    #
-    # @property
-    # def __name__(self):
-    #     return self.fget.__name__
-    #
-    # @property
-    # def __qualname__(self):
-    #     return self.fget.__qualname__
-    #
-    # @property
-    # def __doc__(self):
-    #     return self.fget.__doc__
-    #
-    # @property
-    # def __annotations__(self):
-    #     return self.fget.__annotations__
+# Decorator Classes
+from classicist.decorators import (
+    alias,
+    annotate,
+    annotation,
+    annotations,
+    classproperty,
+    deprecated,
+    hybridmethod,
+    nocache,
+)
+
+# Decorator Helper Methods
+from classicist.decorators import (
+    is_aliased,
+    aliases,
+    is_deprecated,
+)
+
+# Meta Classes
+from classicist.metaclasses import (
+    aliased,
+    shadowproof,
+)
+
+# Exception Classes
+from classicist.exceptions import (
+    AttributeShadowingError,
+)
+
+__all__ = [
+    # Decorators
+    "alias",
+    "annotate",
+    "annotation",
+    "annotations",
+    "classproperty",
+    "deprecated",
+    "hybridmethod",
+    "nocache",
+    # Decorator Helper Methods
+    "is_aliased",
+    "aliases",
+    "is_deprecated",
+    # Meta Classes
+    "aliased",
+    "shadowproof",
+    # Exception Classes
+    "AttributeShadowingError",
+]

classicist/decorators/__init__.py

@@ -0,0 +1,20 @@
+from classicist.decorators.aliased import alias, aliases, is_aliased
+from classicist.decorators.annotation import annotate, annotation, annotations
+from classicist.decorators.classproperty import classproperty
+from classicist.decorators.deprecated import deprecated, is_deprecated
+from classicist.decorators.hybridmethod import hybridmethod
+from classicist.decorators.nocache import nocache
+
+__all__ = [
+    "alias",
+    "aliases",
+    "annotate",
+    "annotation",
+    "annotations",
+    "classproperty",
+    "deprecated",
+    "is_aliased",
+    "is_deprecated",
+    "hybridmethod",
+    "nocache",
+]

classicist/decorators/aliased/__init__.py

@@ -0,0 +1,74 @@
+from classicist.logging import logger
+from classicist.exceptions.decorators.aliased import AliasError
+from classicist.inspector import unwrap
+
+from typing import Callable
+from functools import wraps
+
+import keyword
+
+logger = logger.getChild(__name__)
+
+
+def alias(*names: tuple[str]) -> Callable:
+    """Decorator that marks a method with one or more alias names. The decorator does
+    not modify the function – it simply records the aliases on the function object."""
+
+    for name in names:
+        if not isinstance(name, str):
+            raise AliasError(
+                "All @alias decorator name arguments must have a string value; non-string values cannot be used!"
+            )
+        elif len(name) == 0:
+            raise AliasError(
+                "All @alias decorator name arguments must be valid Python identifier values; empty strings cannot be used!"
+            )
+        elif not name.isidentifier():
+            raise AliasError(
+                f"All @alias decorator name arguments must be valid Python identifier values; strings such as '{name}' are not considered valid identifiers by Python!"
+            )
+        elif keyword.iskeyword(name):
+            raise AliasError(
+                f"All @alias decorator name arguments must be valid Python identifier values; reserved keywords, such as '{name}' cannot be used!"
+            )
+
+    def decorator(function: Callable) -> Callable:
+        function = unwrap(function)
+
+        if isinstance(aliases := getattr(function, "_classicist_aliases", None), tuple):
+            setattr(function, "_classicist_aliases", tuple([*aliases, *names]))
+        else:
+            setattr(function, "_classicist_aliases", names)
+
+        @wraps(function)
+        def wrapper(*args, **kwargs):
+            return function(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def is_aliased(function: callable) -> bool:
+    """The is_aliased() helper method can be used to determine if a class method has
+    been aliased."""
+
+    function = unwrap(function)
+
+    return isinstance(getattr(function, "_classicist_aliases", None), tuple)
+
+
+def aliases(function: callable) -> list[str]:
+    """The aliases() helper method can be used to obtain any class method aliases."""
+
+    function = unwrap(function)
+
+    if isinstance(aliases := getattr(function, "_classicist_aliases", None), tuple):
+        return list(aliases)
+
+
+__all__ = [
+    "alias",
+    "is_aliased",
+    "aliases",
+]

classicist/decorators/annotation/__init__.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from classicist.logging import logger
+from classicist.exceptions.decorators.annotation import AnnotationError
+
+import builtins
+
+logger = logger.getChild(__name__)
+
+
+def annotate(thing: object, **annotations: dict[str, object]) -> callable:
+    """Supports associating arbitrary annotations with the provided code object."""
+
+    if isinstance(thing, object) and not thing in [None, True, False]:
+        if hasattr(thing, "_classicist_annotations") and isinstance(
+            thing._classicist_annotations, dict
+        ):
+            thing._classicist_annotations.update(annotations)
+        else:
+            try:
+                thing._classicist_annotations = annotations
+            except AttributeError as exception:
+                raise AnnotationError(
+                    "Cannot assign annotations to an object of type %s: %s!"
+                    % (builtins.type(thing), str(exception))
+                )
+
+    return thing
+
+
+def annotation(**annotations: dict[str, object]) -> callable:
+    """Supports associating arbitrary annotations with a code object via a decorator."""
+
+    def decorator(thing: object) -> object:
+        return annotate(thing, **annotations)
+
+    return decorator
+
+
+def annotations(thing: object, metadata: bool = False) -> dict[str, object] | None:
+    """Supports obtaining arbitrary annotations for a code object."""
+
+    if isinstance(thing, object) and hasattr(thing, "_classicist_annotations"):
+        if isinstance(annotations := thing._classicist_annotations, dict):
+            if metadata is True:
+                annotations["__name__"] = thing.__name__
+                annotations["__type__"] = type(thing)
+            return annotations
+
+
+__all__ = [
+    "annotate",
+    "annotation",
+    "annotations",
+]

classicist/decorators/classproperty/__init__.py

@@ -0,0 +1,41 @@
+from classicist.logging import logger
+
+logger = logger.getChild(__name__)
+
+
+class classproperty(property):
+    """The classproperty decorator transforms a method into a class-level property. This
+    provides access to the method as if it were a class attribute; this addresses the
+    removal of support for combining the @classmethod and @property decorators to create
+    class properties in Python 3.13, a change which was made due to some complexity in
+    the underlying interpreter implementation."""
+
+    def __init__(self, fget: callable, fset: callable = None, fdel: callable = None):
+        super().__init__(fget, fset, fdel)
+
+    def __get__(self, instance: object, klass: type = None):
+        if klass is None:
+            return self
+        return self.fget(klass)
+
+    def __set__(self, instance: object, value: object):
+        # Note that the __set__ descriptor cannot be used on class methods unless
+        # the class is created with a metaclass that implements this behaviour.
+        raise NotImplementedError
+
+    def __delete__(self, instance: object):
+        # Note that the __delete__ descriptor cannot be used on class methods unless
+        # the class is created with a metaclass that implements this behaviour.
+        raise NotImplementedError
+
+    def __getattr__(self, name: str):
+        if hasattr(self.fget, name):
+            return getattr(self.fget, name)
+        else:
+            raise AttributeError(
+                "The classproperty method '%s' does not have an '%s' attribute!"
+                % (
+                    self.fget.__name__,
+                    name,
+                )
+            )

classicist/decorators/deprecated/__init__.py

@@ -0,0 +1,101 @@
+from classicist.logging import logger
+from classicist.decorators.annotation import annotate
+
+from functools import wraps, partial
+from datetime import datetime
+
+logger = logger.getChild(__name__)
+
+
+def deprecated(
+    thing: object = None,
+    /,
+    reason: str = None,
+    since: str = None,
+    removal: str = None,
+    replacement: str = None,
+    advice: str = None,
+    ticket: str = None,
+    **annotations: dict[str, object],
+) -> object:
+    """The @deprecated decorator provides support for marking code objects as having
+    been deprecated. The decorator also provides support for adding additional arbitrary
+    annotations to the object beyond the directly supported annotations."""
+
+    if reason is None:
+        pass
+    elif isinstance(reason, str):
+        annotations["reason"] = reason
+    else:
+        raise TypeError(
+            "The 'reason' argument, if specified, must have a string value!"
+        )
+
+    if replacement is None:
+        pass
+    elif isinstance(replacement, str):
+        annotations["replacement"] = replacement
+    else:
+        raise TypeError(
+            "The 'replacement' argument, if specified, must have a string value!"
+        )
+
+    if since is None:
+        pass
+    elif isinstance(since, (str, datetime)):
+        annotations["since"] = since
+    else:
+        raise TypeError(
+            "The 'since' argument, if specified, must have a string or datetime value!"
+        )
+
+    if removal is None:
+        pass
+    elif isinstance(removal, (str, datetime)):
+        annotations["removal"] = removal
+    else:
+        raise TypeError(
+            "The 'removal' argument, if specified, must have a string or datetime value!"
+        )
+
+    if advice is None:
+        pass
+    elif isinstance(advice, str):
+        annotations["advice"] = advice
+    else:
+        raise TypeError(
+            "The 'advice' argument, if specified, must have a string value!"
+        )
+
+    if ticket is None:
+        pass
+    elif isinstance(ticket, str):
+        annotations["ticket"] = ticket
+    else:
+        raise TypeError(
+            "The 'ticket' argument, if specified, must have a string value!"
+        )
+
+    if thing is None:
+        return partial(deprecated, **annotations)
+
+    @wraps(thing)
+    def decorator() -> object:
+        if not hasattr(thing, "_classicist_deprecated"):
+            setattr(thing, "_classicist_deprecated", True)
+        return annotate(thing, **annotations)
+
+    return decorator()
+
+
+def is_deprecated(thing: object) -> bool:
+    """The is_deprecated() helper method can be used to determine if an object or class
+    has been marked as deprecated."""
+
+    return getattr(thing, "_classicist_deprecated", False) is True
+
+
+__all__ = [
+    "deprecated",
+    "is_deprecated",
+]

classicist/decorators/hybridmethod/__init__.py

@@ -0,0 +1,57 @@
+from classicist.logging import logger
+
+logger = logger.getChild(__name__)
+
+
+class hybridmethod(object):
+    """The 'hybridmethod' decorator allows a method to be used as both a class method
+    and an instance method. The hybridmethod class decorator can wrap methods defined
+    in classes using the usual @decorator syntax. Methods defined in classes that are
+    decorated with the @hybridmethod decorator can be accessed as both class methods
+    and as instance methods, with the first argument passed to the method being the
+    reference to either the class when the method is called as a class method or to
+    the instance when the method is called as an instance method.
+
+    A check of the value of the first variable using isinstance(<variable>, <class>) can
+    be used within a hybrid method to determine if the call was made on an instance of
+    the class in which case the isinstance() call would evalute to True or if the call
+    was made on the class itself, in which case isinstance() would evaluate to False.
+    The variable passed as the first argument to the method may have any name, including
+    'self', as in Python, the use of 'self' as the name of the first argument on an
+    instance method is just customary and the name has no significance like it does in
+    other languages where the reference to the instance is provided automatically and
+    may go by 'self', 'this' or something else."""
+
+    def __init__(self, function: callable):
+        logger.debug(
+            "%s.__init__(function: %s)",
+            self.__class__.__name__,
+            function,
+        )
+
+        if not callable(function):
+            raise TypeError(
+                "The '%s' decorator can only be used to wrap callables!"
+                % (self.__class__.__name__)
+            )
+        elif not type(function).__name__ == "function":
+            raise TypeError(
+                "The '%s' decorator can only be used to wrap functions!"
+                % (self.__class__.__name__)
+            )
+
+        self.function: callable = function
+
+    def __get__(self, instance, owner) -> callable:
+        logger.debug(
+            "%s.__get__(self: %s, instance: %s, owner: %s)",
+            self.__class__.__name__,
+            self,
+            instance,
+            owner,
+        )
+
+        if instance is None:
+            return lambda *args, **kwargs: self.function(owner, *args, **kwargs)
+        else:
+            return lambda *args, **kwargs: self.function(instance, *args, **kwargs)

classicist/decorators/nocache/__init__.py

@@ -0,0 +1,10 @@
+from classicist.logging import logger
+
+logger = logger.getChild(__name__)
+
+
+def nocache(function: callable):
+    """A no-cache decorator to specifically call out functions and properties that must
+    not be cached using the functools.cache decorator or similar."""
+
+    return function

classicist/exceptions/__init__.py

@@ -0,0 +1,12 @@
+from classicist.exceptions.decorators import (
+    AnnotationError,
+)
+
+from classicist.exceptions.metaclasses import (
+    AttributeShadowingError,
+)
+
+__all__ = [
+    "AnnotationError",
+    "AttributeShadowingError",
+]

classicist/exceptions/decorators/__init__.py

@@ -0,0 +1,7 @@
+from classicist.exceptions.decorators.aliased import AliasError
+from classicist.exceptions.decorators.annotation import AnnotationError
+
+__all__ = [
+    "AliasError",
+    "AnnotationError",
+]

classicist/exceptions/decorators/aliased/__init__.py

@@ -0,0 +1,2 @@
+class AliasError(AttributeError):
+    pass

classicist/exceptions/decorators/annotation/__init__.py

@@ -0,0 +1,2 @@
+class AnnotationError(AttributeError):
+    pass

classicist/exceptions/metaclasses/__init__.py

@@ -0,0 +1,5 @@
+from classicist.exceptions.metaclasses.shadowproof import AttributeShadowingError
+
+__all__ = [
+    "AttributeShadowingError",
+]

classicist/exceptions/metaclasses/shadowproof/__init__.py

@@ -0,0 +1,2 @@
+class AttributeShadowingError(AttributeError):
+    pass

classicist/inspector/__init__.py

@@ -0,0 +1,38 @@
+from classicist.logging import logger
+
+import sys
+
+logger = logger.getChild(__name__)
+
+
+def unwrap(function: callable) -> callable:
+    """Support unwrapping methods decorated with @property and other descriptor protocol
+    decorators such as @classmethod and @staticmethod as well as function decorators
+    that follow best-practice and have a __wrapped__ attribute referencing the original
+    function, so that the original function can be found by unwrapping via the chain of
+    the __wrapped__ and fget attributes.
+
+    This implementation is based on the standard library's inspect.unwrap() method."""
+
+    original: callable = function
+
+    functionids: dict[id, callable] = {id(function): function}
+
+    recursion_limit: int = sys.getrecursionlimit()
+
+    while (w := hasattr(function, "__wrapped__")) or (d := hasattr(function, "fget")):
+        if w is True:
+            function = getattr(function, "__wrapped__")
+        elif d is True:
+            function = getattr(function, "fget")
+
+        functionid: int = id(function)
+
+        if (functionid in functionids) or (len(functionids) >= recursion_limit):
+            raise ValueError(
+                "Found wrapper loop while unwrapping {!r}!".format(original)
+            )
+
+        functionids[functionid] = function
+
+    return function

classicist/logging/__init__.py

@@ -0,0 +1,3 @@
+import logging
+
+logger = logging.getLogger("classicist")

classicist/metaclasses/__init__.py

@@ -0,0 +1,7 @@
+from classicist.metaclasses.aliased import aliased
+from classicist.metaclasses.shadowproof import shadowproof
+
+__all__ = [
+    "aliased",
+    "shadowproof",
+]

classicist/metaclasses/aliased/__init__.py

@@ -0,0 +1,40 @@
+from classicist.logging import logger
+
+logger = logger.getChild(__name__)
+
+
+class aliased(type):
+    """Metaclass that looks for methods that have been decorated with @alias(...) and
+    automatically creates the corresponding aliases for those methods on the class."""
+
+    def __new__(cls: object, name: str, bases: tuple[object], namespace: dict):
+        # Create the class first
+        cls = super().__new__(cls, name, bases, namespace)
+
+        # Walk through the class body (namespace) and install the aliases
+        for name, value in namespace.items():
+            original: object = value
+
+            # If a function has been wrapped by a well behaved decorator, unwrap it, to
+            # get to the original function, and thus to the alias annotation we need to
+            # create the function aliases in the class; without access to the annotation
+            # the aliases cannot be created, so any decorators used should follow best
+            # practice and apply the __wrapped__ attribute to point back to the wrapped
+            # function using functools.wraps or similar or use property getter practice:
+            while (w := hasattr(value, "__wrapped__")) or (p := hasattr(value, "fget")):
+                if w is True:  # Get the original wrapped function
+                    value = getattr(value, "__wrapped__")
+                elif p is True:  # Get the original property function
+                    value = getattr(value, "fget")
+
+            if aliases := getattr(value, "_classicist_aliases", None):
+                for alias in aliases:
+                    if hasattr(cls, alias):
+                        raise AttributeError(
+                            f"Cannot create alias '{alias}' for method '{name}' as '{cls.__name__}.{alias}' already exists!"
+                        )
+
+                    # The alias points to the original function or property accessor
+                    setattr(cls, alias, original)
+
+        return cls