classicist 1.0.1__tar.gz → 1.0.3__tar.gz

{classicist-1.0.1/source/classicist.egg-info → classicist-1.0.3}/PKG-INFO

@@ -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 → classicist-1.0.3}/README.md

@@ -6,7 +6,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.
@@ -230,30 +230,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
@@ -272,7 +314,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 → classicist-1.0.3}/requirements.development.txt

@@ -1,5 +1,5 @@
 # Classicist Library: Development & Test Dependencies
-black==24.10.*
+black==26.1.*
 pytest==8.3.*
 pytest-codeblocks==0.17.0
 pyflakes

classicist-1.0.3/source/classicist/decorators/aliased/__init__.py

@@ -0,0 +1,171 @@
+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.debug(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
+
+        @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
+
+
+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-1.0.1 → classicist-1.0.3}/source/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-1.0.3/source/classicist/version.txt

@@ -0,0 +1 @@
+1.0.3

{classicist-1.0.1 → classicist-1.0.3/source/classicist.egg-info}/PKG-INFO

@@ -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 → classicist-1.0.3}/source/classicist.egg-info/requires.txt

@@ -1,6 +1,6 @@
 
 [development]
-black==24.10.*
+black==26.1.*
 pytest==8.3.*
 pytest-codeblocks==0.17.0
 pyflakes

{classicist-1.0.1 → classicist-1.0.3}/tests/test_aliased.py

@@ -2,29 +2,123 @@ from classicist import aliased, alias, aliases, is_aliased
 from classicist.exceptions.decorators.aliased import AliasError
 
 import pytest
+import sys
+import types
+import conftest
+
+# Obtain a reference to the current module
+module = sys.modules[__name__]
+assert isinstance(module, types.ModuleType)
+assert module.__name__ == __name__
+
+
+# Define and alias a module-level function for testing below
+@alias("doubled")
+def doubler(value: int) -> int:
+    """Sample method that doubles and returns the provided number."""
+
+    return value * 2
+
+
+def test_alias_function():
+    """Test using the @alias decorator on a  module-level function."""
+
+    # Ensure that both the original function "doubler" and its alias exist in the module
+    assert hasattr(module, "doubler")
+    assert hasattr(module, "doubled")
+
+    # Ensure that the module attributes directly reference the function objects
+    # and ensure that the function names both exist in scope; by ensuring that
+    # the aliased name also exists equally in scope and has the same visibility
+    # we ensure that the module-level alias is working correctly
+    assert getattr(module, "doubler") is doubler
+    assert getattr(module, "doubled") is doubled
+
+    assert doubler is doubled
+
+    assert doubler(1) == 2
+    assert doubled(2) == 4
+
+
+def test_alias_function_defined_in_an_imported_module():
+    """Test using the @alias decorator on an imported module-level function."""
+
+    # Ensure that both the original function "halves" and its alias exist in the module
+    assert hasattr(conftest, "halves")
+    assert hasattr(conftest, "divide")
+
+    # Ensure that the module attributes directly reference the function object and
+    # that the original and aliased function names both exist in scope; by ensuring
+    # that the aliased name exists equally in scope and has the same visibility as
+    # the original function object, we confirm that the alias is working correctly
+    assert getattr(conftest, "halves") is conftest.halves
+    assert getattr(conftest, "divide") is conftest.divide
+
+    # Ensure that the original and the alias refer to the same object in memory
+    assert conftest.halves is conftest.divide
+
+    # Test the original and aliased function names
+    assert conftest.halves(2) == 1
+    assert conftest.divide(4) == 2
+
+    # Ensure that both the original and aliased function can be imported
+    from conftest import halves, divide
+
+    # Ensure that the imported names refer to the same object in memory
+    assert conftest.halves is halves
+    assert conftest.divide is divide
+
+    # Test the original and aliased function names
+    assert halves(2) == 1
+    assert divide(4) == 2
+
+
+def test_alias_class():
+    """Test using the @alias decorator on a class."""
+
+    @alias("Greeter")
+    class Welcome(object):
+        pass
+
+    # Ensure that both the original and the aliased names exists
+    assert isinstance(Welcome, type)
+    assert isinstance(Greeter, type)
+
+    # Ensure both the original and the aliased names refer to the same object in memory
+    assert Welcome is Greeter
+    assert Greeter is Welcome
 
 
 def test_alias_class_method():
     """Test using the @alias decorator on a method."""
 
+    # Create a sample class that aliases a method; due to the way that Python classes
+    # are parsed by the interpreter, it is necessary to use a metaclass or custom base
+    # class to apply the method aliases to the class scope, thus the use of the aliased
+    # metaclass in the class definition below; this special metaclass scans the class'
+    # methods, looking for any with assigned aliases, and then adds the aliases to the
+    # class' scope so that the methods can be accessed both via their original name and
+    # any aliases that have been defined; without the metaclass the aliases won't exist.
     class Welcome(metaclass=aliased):
         @alias("sweet", "greet")
         def hello(self, name: str) -> str:
             return f"hello: {name}"
 
+    # Ensure both the original and the aliased names refer to the same object in memory
     assert Welcome.hello is Welcome.sweet
     assert Welcome.hello is Welcome.greet
 
+    # Ensure both the original and the aliased names report as having been aliased
     assert is_aliased(Welcome.hello) is True
     assert is_aliased(Welcome.sweet) is True
     assert is_aliased(Welcome.greet) is True
 
-    assert aliases(Welcome.hello) == ["sweet", "greet"]
+    # Check that the class method object reports its aliases correctly
     assert aliases(Welcome.hello) == ["sweet", "greet"]
 
 
 def test_alias_class_method_property():
-    """Test using the @alias decorator with a @property decorator."""
+    """Test using the @alias decorator with @property and @classmethod decorators."""
 
     class Welcome(metaclass=aliased):
         @property
@@ -33,14 +127,16 @@ def test_alias_class_method_property():
         def hello(self, name: str) -> str:
             return f"hello: {name}"
 
+    # Ensure both the original and the aliased names refer to the same object in memory
     assert Welcome.hello is Welcome.sweet
     assert Welcome.hello is Welcome.greet
 
+    # Ensure both the original and the aliased names report as having been aliased
     assert is_aliased(Welcome.hello) is True
     assert is_aliased(Welcome.sweet) is True
     assert is_aliased(Welcome.greet) is True
 
-    assert aliases(Welcome.hello) == ["sweet", "greet"]
+    # Check that the class method object reports its aliases correctly
     assert aliases(Welcome.hello) == ["sweet", "greet"]
 
 
@@ -70,23 +166,34 @@ def test_alias_class_method_alias_with_valid_identifier():
     assert welcome.hello("me") == "hello: me"
     assert welcome.greet("me") == "hello: me"
 
+    # Ensure that aliases are inherited by subclasses
     class SubWelcome(Welcome):
         pass
 
+    # Ensure that aliases are inherited by subclasses
     assert hasattr(SubWelcome, "hello") is True
     assert hasattr(SubWelcome, "greet") is True
 
+    # Ensure that aliases are inherited by subclass instances
     subwelcome = SubWelcome()
 
+    # Ensure that aliases are inherited by subclass instances
     assert hasattr(subwelcome, "hello") is True
     assert hasattr(subwelcome, "greet") is True
 
     # Ensure that the aliased method functionality operates as expected
     assert subwelcome.hello("me") == "hello: me"
-
-    # Ensure when the alias hasn't been registered that access raises an AttributeError
     assert subwelcome.greet("me") == "hello: me"
 
+    # Ensure when an alias hasn't been registered that access raises an AttributeError
+    with pytest.raises(AttributeError) as exception:
+        assert subwelcome.sweet("me") == "hello: me"
+
+        assert (
+            str(exception)
+            == "AttributeError: 'SubWelcome' object has no attribute 'sweet'. Did you mean: 'greet'?"
+        )
+
 
 def test_alias_class_method_with_invalid_identifier():
     """Test using the @alias decorator with an invalid identifier."""

classicist-1.0.1/source/classicist/decorators/aliased/__init__.py

@@ -1,74 +0,0 @@
-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-1.0.1/source/classicist/version.txt

@@ -1 +0,0 @@
-1.0.1