classicist 1.0.1__py3-none-any.whl → 1.0.2__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,113 @@ 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.info(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  # (*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
 

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.2

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: classicist
-Version: 1.0.1
+Version: 1.0.2
 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"
@@ -265,28 +265,67 @@ assert exampleclass.greeting == "goodbye"
 
 #### Class Method Alias Decorator & Metaclass: Add Aliases to Methods
 
-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, and module-level functions, 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 code object as one or more string arguments passed into the
+decorator method.
+
+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 their aliases.
 
 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.
 
+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 must be a reference to
+the globals() or locals() at the point in code where the `@alias()` decorator is used.
+
 ```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 +344,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.2.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=v-wuNFg62n5q8stzmT-3Wj9xR6bJQ-X_X1xClPxXe5A,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=e62ENmJh_kH4Ufh9duAYWg93cfmINIcpzeP0haJo7cw,7132
 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.2.dist-info/licenses/LICENSE.md,sha256=qBmrjPmSCp0YFyaIl2G3FU3rniFD31YC0Yd3MrO1wEg,1070
+classicist-1.0.2.dist-info/METADATA,sha256=g3SDEBecgGq15CnHFUVr2mfyhFNQ3tG752I5OSMaAbk,24825
+classicist-1.0.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+classicist-1.0.2.dist-info/top_level.txt,sha256=beG3ZuwObnmnY_mgNSN5CaVIWpI2VKszjVdKHPgZBhc,11
+classicist-1.0.2.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+classicist-1.0.2.dist-info/RECORD,,

{classicist-1.0.1.dist-info → classicist-1.0.2.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