classicist 1.0.0__py3-none-any.whl → 1.0.2__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,177 @@
+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
+import inspect
+import sys
+
+logger = logger.getChild(__name__)
+
+
+def alias(*names: tuple[str], scope: object = None) -> Callable:
+    """Decorator that applies one or more alias names to a class, function or method.
+    The decorator records the assigned aliases on the class, method or function object,
+    and where possible creates aliases in the same scope as the original class or module
+    level function directly as the decorator call runs. Methods within classes cannot be
+    aliased directly by the `@alias` decorator, but instead require the assistance of the
+    corresponding `aliased` metaclass that must be specified on the class definition. If
+    control over the scope is required, the optional `scope` keyword argument can be used
+    to specify the scope into which to apply the alias, this should be a reference to the
+    globals() or locals() at the site in code where the `@alias()` decorator is used."""
+
+    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 := name.strip()) == 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(thing: object, *args, **kwargs) -> object:
+        nonlocal scope
+
+        thing = unwrap(thing)
+
+        logger.info(f"@alias({names}) called on {thing}")
+
+        if isinstance(aliases := getattr(thing, "_classicist_aliases", None), tuple):
+            setattr(thing, "_classicist_aliases", tuple([*aliases, *names]))
+        else:
+            setattr(thing, "_classicist_aliases", names)
+
+        @wraps(thing)
+        def wrapper_class(*args, **kwargs):
+            return thing  # (*args, **kwargs)
+
+        @wraps(thing)
+        def wrapper_method(*args, **kwargs):
+            return thing(*args, **kwargs)
+
+        @wraps(thing)
+        def wrapper_function(*args, **kwargs):
+            return thing  # (*args, **kwargs)
+
+        if inspect.isclass(thing):
+            if not scope:
+                scope = sys.modules.get(thing.__module__ or "__main__")
+
+            if isinstance(scope, object):
+                for name in names:
+                    if hasattr(scope, name):
+                        raise AliasError(
+                            "Cannot create alias '%s' for %s class in the %s module as an object with that name already exists!"
+                            % (
+                                name,
+                                thing,
+                                scope,
+                            )
+                        )
+
+                    # Create a module-level alias for the class
+                    if isinstance(scope, dict):
+                        scope[name] = thing
+                    else:
+                        setattr(scope, name, thing)
+
+            return wrapper_class(*args, **kwargs)
+        elif inspect.ismethod(thing) or isinstance(thing, classmethod):
+            return wrapper_method
+        elif inspect.isfunction(thing):
+            if not scope:
+                scope = sys.modules.get(thing.__module__ or "__main__")
+
+            if not scope:
+                logger.warning(f"No module found for {thing.__module__}!")
+
+                for module in sys.modules:
+                    logger.debug(f" => module => {module}")
+
+            # The qualified name for module-level functions only contain the name of the
+            # function, whereas functions nested within other functions or classes have
+            # names comprised of multiple parts separated by the "." character; because
+            # it is only currently possible to alias module-level functions, any nested
+            # or class methods are ignored during this stage of the aliasing process.
+            if len(thing.__qualname__.split(".")) > 1:
+                logger.warning(
+                    "Unable to apply alias to functions defined beyond the top-level of a module: %s!"
+                    % (thing.__qualname__)
+                )
+
+                return wrapper_function(*args, **kwargs)
+
+            # if signature := inspect.signature(thing):
+            #     if len(parameters := signature.parameters) > 0 and "self" in parameters:
+            #         return wrapper_function(*args, **kwargs)
+
+            if isinstance(scope, object):
+                # At this point we should only be left with module-level functions to alias
+                for name in names:
+                    # Ensure the scope doesn't already contain an object of the same name
+                    if hasattr(scope, name):
+                        raise AliasError(
+                            "Cannot create alias '%s' for %s function in the %s module as an object with that name already exists!"
+                            % (
+                                name,
+                                thing,
+                                scope,
+                            )
+                        )
+
+                    logger.info(f"Added alias '{name}' to {scope}.{thing}")
+
+                    if isinstance(scope, dict):
+                        scope[name] = thing
+                    elif isinstance(scope, object):
+                        setattr(scope, name, thing)
+            else:
+                logger.warning(
+                    f"No scope was found or specified for {thing} into which to assign the alias!"
+                )
+
+            return wrapper_function(*args, **kwargs)
+        else:
+            raise AliasError(
+                "The @alias decorator can only be applied to classes, methods and functions, not %s!"
+                % (type(thing))
+            )
+
+    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