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

classicist/decorators/aliased/__init__.py

@@ -6,20 +6,29 @@ from typing import Callable
 from functools import wraps
 
 import keyword
+import inspect
+import sys
 
 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."""
+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) == 0:
+        elif len(name := name.strip()) == 0:
             raise AliasError(
                 "All @alias decorator name arguments must be valid Python identifier values; empty strings cannot be used!"
             )
@@ -32,19 +41,107 @@ def alias(*names: tuple[str]) -> Callable:
                 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)
+    def decorator(thing: object, *args, **kwargs) -> object:
+        nonlocal scope
 
-        if isinstance(aliases := getattr(function, "_classicist_aliases", None), tuple):
-            setattr(function, "_classicist_aliases", tuple([*aliases, *names]))
-        else:
-            setattr(function, "_classicist_aliases", names)
+        thing = unwrap(thing)
 
-        @wraps(function)
-        def wrapper(*args, **kwargs):
-            return function(*args, **kwargs)
+        logger.debug(f"@alias({names}) called on {thing}")
 
-        return wrapper
+        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
+
+        @wraps(thing)
+        def wrapper_method(*args, **kwargs):
+            return thing(*args, **kwargs)
+
+        @wraps(thing)
+        def wrapper_function(*args, **kwargs):
+            return thing
+
+        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__")
+
+                # 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.debug(
+                        "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.debug(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 aliases!"
+                )
+
+            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
 

classicist/metaclasses/aliased/__init__.py

@@ -1,4 +1,5 @@
 from classicist.logging import logger
+from classicist.exceptions.decorators.aliased import AliasError
 
 logger = logger.getChild(__name__)
 
@@ -30,7 +31,7 @@ class aliased(type):
             if aliases := getattr(value, "_classicist_aliases", None):
                 for alias in aliases:
                     if hasattr(cls, alias):
-                        raise AttributeError(
+                        raise AliasError(
                             f"Cannot create alias '{alias}' for method '{name}' as '{cls.__name__}.{alias}' already exists!"
                         )
 

classicist/version.txt

@@ -1 +1 @@
-1.0.1
+1.0.3

{classicist-1.0.1.dist-info → classicist-1.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: classicist
-Version: 1.0.1
+Version: 1.0.3
 Summary: Classy class decorators for Python.
 Author: Daniel Sissman
 License-Expression: MIT
@@ -21,7 +21,7 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
 Provides-Extra: development
-Requires-Dist: black==24.10.*; extra == "development"
+Requires-Dist: black==26.1.*; extra == "development"
 Requires-Dist: pytest==8.3.*; extra == "development"
 Requires-Dist: pytest-codeblocks==0.17.0; extra == "development"
 Requires-Dist: pyflakes; extra == "development"
@@ -39,7 +39,7 @@ The Classicist library provides several useful decorators and helper methods inc
  * `@classproperty` – a decorator that allow class methods to be accessed as class properties;
  * `@annotation` – a decorator that can be used to apply arbitrary annotations to code objects;
  * `@deprecated` – a decorator that can be used to mark functions, classes and methods as being deprecated;
- * `@alias` – a decorator that can be used to add aliases to class methods;
+ * `@alias` – a decorator that can be used to add aliases to classes, methods defined within classes, module-level functions, and nested functions when overriding the aliasing scope;
  * `@nocache` – a decorator that can be used to mark functions and methods as not being suitable for caching;
  * `shadowproof` – a metaclass that can be used to protect subclasses from class-level attributes
   being overwritten (or shadowed) which can otherwise negatively affect class behaviour in some cases.
@@ -263,30 +263,72 @@ exampleclass.greeting = "goodbye"
 assert exampleclass.greeting == "goodbye"
 ```
 
-#### Class Method Alias Decorator & Metaclass: Add Aliases to Methods
+#### Alias Decorator & Metaclass: Add Aliases to Classes, Methods & Functions
 
-The `@alias` decorator can be used to add method name aliases to methods defined within
-classes, such that both the original name and any defined aliases can be used to access
-the method at runtime. The `@alias` decorator cannot be used for methods defined outside
-of classes as the aliases are created as additional class attributes scoped to the class.
+The `@alias` decorator can be used to add aliases to classes, methods defined within
+classes, module-level functions, and nested functions when overriding the aliasing scope,
+such that both the original name and any defined aliases can be used to access the same
+code object at runtime.
 
-To use the `@alias` decorator, it is necessary to set the containing class' metaclass to
-the `aliased` metaclass provided by the `classicist` library; the metaclass iterates
-through the class namespace during parse time and sets up the aliases as additional
-attributes on the class so that the aliased methods are available at runtime via both
-their original name and their aliases.
+To alias a class or a module-level function, that is a function defined at the top-level
+of a module file (rather than nested within a function or class), simply decorate the 
+class or module-level function with the `@alias(...)` decorator and specify the one or
+more name aliases for the class or function as one or more string arguments passed into
+the decorator method.
 
-The example below demonstrates adding an alias to a method defined within a class, and
-using the `aliased` metaclass when defining the class to ensure that the alias is parsed
-and translated to an additional class attribute so that the method is accessible via its
-original name and the alias at runtime.
+To use the `@alias` decorator on methods defined within a class, it is also necessary to
+set the containing class' metaclass to the `aliased` metaclass provided by the `classicist`
+library; the metaclass iterates through the class' namespace during parse time and sets up
+the aliases as additional attributes on the class so that the aliased methods are available
+at runtime via both their original name and any aliases.
+
+The examples below demonstrate adding an alias to a module-level function, a class and a
+method defined within a class, and using the `aliased` metaclass when defining a class
+that contains aliased methods to ensure that any aliases are parsed and translated to
+additional class attributes so that the method is accessible via its original name and
+any alias at runtime.
+
+If control over the scope is required, usually for nested functions, the optional `scope`
+keyword-only argument can be used to specify the scope into which to apply the alias; this
+must be a reference to `globals()` or `locals()` at the point in code where the `@alias(...)`
+decorator is applied to the nested function.
 
 ```python
 from classicist import aliased, alias, is_aliased, aliases
 
-class Welcome(object, metaclass=aliased):
+# Define an alias on a module-level method; as this demonstration occurs
+# within the README file which is parsed by and run within an external
+# scope by pytest and pytest-codeblocks, we override the scope within
+# which to apply the alias otherwise the alias would be assigned within
+# an external scope which would prevent the alias from working; however
+# it is rare to need to override the inferred scope, and aliasing of
+# module-level functions defined within actual modules will work normally;
+# for rare cases where overriding scope is necessary the optional `scope`
+# keyword-only argument can be used as shown below.
+@alias("sums", scope=globals())
+def adds(a: int, b: int) -> int:
+    return a + b
+
+assert globals().get("adds") is adds
+assert globals().get("sums") is sums
+assert adds is sums
+assert adds(1, 2) == 3
+assert sums(1, 2) == 3
+
+# Define an alias on a class
+@alias("Color")
+class Colour(object):
+    pass
+
+assert Colour is Color
+
+# Define an alias on a method defined within a class;
+# this also requires the use of the aliased metaclass
+# which is responsible for adding the aliases within
+# the scope of the class once the class has been parsed
+class Welcome(metaclass=aliased):
     @alias("greet")
-    def hello(self, name: str):
+    def hello(self, name: str) -> str:
         return f"Hello {name}!"
 
 assert is_aliased(Welcome.hello) is True
@@ -305,7 +347,9 @@ assert welcome.greet("you") == "Hello you!"
 
 ⚠️ Note: Aliases must be valid Python identifiers, following the same rules as for all
 other function and method names and aliases cannot be reserved keywords. If an invalid
-alias is specified an `AliasError` exception will be raised at runtime.
+alias is specified an `AliasError` exception will be raised at runtime. Furthermore, if
+a name has already been used in the current scope, an `AliasError` exception will be
+raised at runtime.
 
 #### Annotation Decorator: Add Arbitrary Annotations to Code Objects
 

{classicist-1.0.1.dist-info → classicist-1.0.3.dist-info}/RECORD

@@ -1,7 +1,7 @@
 classicist/__init__.py,sha256=Rkm1Vx0Z-BHPH1FSzFLrAxwkFEt1xvMxZz-mC8FJSDc,834
-classicist/version.txt,sha256=1R5uyUBYVUqEVYpbQC7m71_fVFXjXJAv7aYc2odSlDo,5
+classicist/version.txt,sha256=INLLCW0atBpBQCRtEvB79rjLdD_UgSK3JTLAPUTFwUo,5
 classicist/decorators/__init__.py,sha256=wplcs2JnyGMOh72626-x-WyVotVoT7nvk-dpjeTXQ88,600
-classicist/decorators/aliased/__init__.py,sha256=4g5MBnyypHunvETGLxFHUFr85ZGyTEYkCtL3tG9jtj8,2461
+classicist/decorators/aliased/__init__.py,sha256=vW1P9jbGkOD_m9GvgEXF0Uni-Dt6rfVXDVF5D4wC1GY,6926
 classicist/decorators/annotation/__init__.py,sha256=20WwmrXDxT85sItpDiCdC-hZjbyDR6E2mLPMSKQgm8g,1796
 classicist/decorators/classproperty/__init__.py,sha256=ED37_20UeAGKX1ahsv16wTg0JAJT4UBLqiNRbKAp2KE,1646
 classicist/decorators/deprecated/__init__.py,sha256=aAPFQoT-pJf1nauQGiPADkPBREMvEQJaUQc3kjA48Rg,2764
@@ -16,11 +16,11 @@ classicist/exceptions/metaclasses/shadowproof/__init__.py,sha256=QT-QFRnjlnVexl9
 classicist/inspector/__init__.py,sha256=Z8Se9CLkZ4WNRDX9Ui31Kt3BklZMYBpDRo7WWTsCQ_g,1309
 classicist/logging/__init__.py,sha256=LJ-Nih1LacPrO2TvTT6l84So-pgw84AHJ8IhzYKl5rw,57
 classicist/metaclasses/__init__.py,sha256=mYhR5rM7cnJlaNUlgoQWOo44RQSORteRjYd0y0BajxQ,159
-classicist/metaclasses/aliased/__init__.py,sha256=82YryLpG-SRmiI6m_Q8pqhHACodoBKyNu0PZ4RMucvE,1973
+classicist/metaclasses/aliased/__init__.py,sha256=grs4Z8dMY6R2fCFn4UCPdCzEJtVaAv-tsWFwY1DCUpI,2033
 classicist/metaclasses/shadowproof/__init__.py,sha256=d55uNjcaCorD3MdDUv7aRVpk2MlE8JzMjint6Vvf_Yc,1492
-classicist-1.0.1.dist-info/licenses/LICENSE.md,sha256=qBmrjPmSCp0YFyaIl2G3FU3rniFD31YC0Yd3MrO1wEg,1070
-classicist-1.0.1.dist-info/METADATA,sha256=065CjOBWs9ImW8f5Oo3r-e1_Lb_zCppmwNkxqdjUD9g,22994
-classicist-1.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-classicist-1.0.1.dist-info/top_level.txt,sha256=beG3ZuwObnmnY_mgNSN5CaVIWpI2VKszjVdKHPgZBhc,11
-classicist-1.0.1.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-classicist-1.0.1.dist-info/RECORD,,
+classicist-1.0.3.dist-info/licenses/LICENSE.md,sha256=qBmrjPmSCp0YFyaIl2G3FU3rniFD31YC0Yd3MrO1wEg,1070
+classicist-1.0.3.dist-info/METADATA,sha256=iZaQqjD9wd84Bb_Dx_Se-RMYgZTvvf2Hkf2idrnswgk,25128
+classicist-1.0.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+classicist-1.0.3.dist-info/top_level.txt,sha256=beG3ZuwObnmnY_mgNSN5CaVIWpI2VKszjVdKHPgZBhc,11
+classicist-1.0.3.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+classicist-1.0.3.dist-info/RECORD,,

{classicist-1.0.1.dist-info → classicist-1.0.3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any