aliasing is a small utility library for python which adds aliases to class members using python descriptors.
This is the recommended way to use the library if you are going to call the generated members in your scripts, as it supports IDE completion.
Basic usage involves a similar process to the builtin @property and @<property_name>.getter/setter.
Instead we use @aliased to indicate the method whose register is being duplicated
and @<aliased_name>.alias to indicate which method's name should be used to point to the "aliased" method:
from aliasing import aliased
class Example:
@aliased
def method(self):
return "my method call"
@method.alias
def method_alias(self): ...
# elsewhere...
example = Example()
# note that `==` and `is` always returns False for function objects
# i.e., this is False:
# example.method == example.method
assert example.method.__code__ is example.method_alias.__code__
assert example.method_alias() == "my method call"Tip
To keep IDE completion for the methods marked with @<aliased_name>.alias the same
as the method marked with @aliased, you must keep the signatures the same for now.
So:
class Example:
@aliased
def method(self, args: str) -> str: ...
# This will NOT have the expected completion
@method.aliased
def method_alias1(self): ...
# But this will
@method.aliased
def method_alias2(self, args: str) -> str: ...I will investigate a solution for this, but it might not present itself.
This is not strictly recommended for use in most cases unless your class will be processed by some framework which relies on the class members to generate something an end-user might want.
Basic usage involves decorating your class's methods with @valiases and specifying the
names of however many aliases you want for that method.
For instance, if you want to make the function's old name available so as not to break the api, but remove it from IDE completion, you can add it as a virtual alias:
from aliasing import valiases
class Example:
@valiases("my_func_old_name")
def my_func(self):
return "foo"
# elsewhere
example = Example()
# this is available with auto-complete:
foo = example.my_func()
# this will _work_ but will give the user an "Unresolved attribute" warning:
foo_old = example.my_func_old_name()Warning
In the library's current state, it would be better to use other methods to mark the old function's name as deprecated, but in the future this library will hopefully be able to offer more support for this use-case.
This is a more convenient and shorter method of adding aliass to your
For example, in Google's python-fire cli tool, cli commands are "generated" using
the members of a class, so you can easily add several commands at once using this library's
@valiases decorator:
# fire_alias_example.py
import fire
from aliasing import valiases
class Example:
@valiases("c", "cfg", "conf")
def config(self):
return "foo"
if __name__ == "__main__":
fire.Fire(Example())Then from cli, the user can call the aliased method or its aliases to achieve the same result:
$ python fire_alias_example.py config
foo
$ python fire_alias_example.py cfg
foo
$ python fire_alias_example.py conf
foo
$ python fire_alias_example.py c
fooOr you might want to add names functions which do not follow PEP 8 naming conventions without disabling your linter or ide inspection settings. Perhaps this code will be called in another language, and you want to make sure the methods follow that language's style as well:
from aliasing import valiases
class Example:
@valiases("MyFunc", "myFunc", "MY_FUNC")
def my_func(self):
return "foo"Since alias objects are just python descriptors (docs), you can use them with more granularity too:
from aliasing import alias
class Example:
my_alias = alias(alias_for="prop")
def __init__(self, val):
self.prop = val
# elsewhere
example = Example(object())
assert example.prop is example.my_aliasYou can define them independently from classes then attach them to any number of classes without hierarchical relation.
class Foo:
def __init__(self, val):
self.prop = val
class Bar:
def __init__(self, val):
self._prop = val
@property
def prop(self):
return f"Bar.prop: {self._prop}"
# elsewhere
from aliasing import alias
prop_alias = alias(alias_for="prop", alias_name="my_alias")
prop_alias.attach(Foo)
prop_alias.attach(Bar)
# now both classes have the alias named "my_alias" pointing to "prop"
assert Foo('baz').my_alias == 'baz'
assert Bar('baz').my_alias == 'Bar.prop: baz'You can check out the tests to see some more examples of
alternative ways to attach alaiss to your classes.
You can also initialize aliased descriptors independently from classes:
from aliasing import aliased
By default, the aliasing library will raise a TrampleAliasError if you try to override
existing class attributes or members without specifying trample_ok for that alias.
For instance, this will fail when alias.attach is called:
class Foo:
def __init__(self, val):
self.prop = val
@staticmethod
def my_alias():
return "don't trample me"
# elsewhere
from aliasing import alias
prop_alias = alias(alias_for="prop", alias_name="my_alias")
# fails with TrampleAliasError("Owner calls Foo already has member with name my_alias. [..]")
prop_alias.attach(Foo)And this will fail whenever the class is imported:
from aliasing import valiases
class Foo:
# fails with TrampleAliasError("Owner class Foo already has member with name __str__. [..]")
@valiases("__str__")
def to_str(self): ...But you can pass trample_ok in a couple different ways to override this behavior.
For alias:
class Foo:
def __init__(self, val):
self.prop = val
@staticmethod
def my_alias():
return "don't trample me"
# elsewhere
from aliasing import alias
prop_alias = alias(alias_for="prop", alias_name="my_alias")
# trample_ok causes a warning TrampleAliasWarning, but no longer fails
prop_alias.attach(Foo, trample_ok=True)
assert Foo('change is good').my_alias == 'change is good'
# OR if you prefer you can set `trample_ok` on the alias itself:
prop_alias = alias(alias_for="prop", alias_name="new_alias", trample_ok=True)
prop_alias.attach(Foo)
assert Foo('this also works').new_alias == 'this also works'For valiases:
from aliasing import valiases
class Foo:
# trample_ok causes a warning TrampleAliasWarning, but no longer fails
@valiases("__str__", trample_ok=['__str__'])
def to_str(self):
return 'new __str__ for Foo'
# I would not recommend 'trampling' magic methods like __str__
# ... but it's your life
assert Foo().__str__() == 'new __str__ for Foo'The major benefit of this is that your can easily override several methods at once if they all do the same thing (like return "NotImplemented"):
import abc
from typing import Any
class CrudBase(abc.ABC):
@abc.abstractmethod
def create(self, name: str, data: Any) -> Any: ...
@abc.abstractmethod
def read(self, name: str) -> Any: ...
@abc.abstractmethod
def update(self, name: str, partial_data: Any) -> Any: ...
@abc.abstractmethod
def delete(self, name: str) -> Any: ...
# elsewhere
from aliasing import valiases
from some_persistence_lib import read_method
class ReadOnlyBase(CrudBase, abc.ABC):
options = {'arg': 'val'}
# now if any of these methods are called, they will get 'NotImplemented'
# this saves you from redefining the same 2-liner method 3 times.
# obviously the benefits are better the more methods there are to override
@valiases('create', 'update', 'delete', trample_ok=['create', 'update', 'delete'])
def _not_implemented(self, *args, **kwargs) -> Any:
return NotImplemented
def read(self, name: str) -> Any:
return read_method(name, **self.options)If you'd like to get in touch for any reason, the easiest thing is opening a GitHub issue.
Please give older issues (including closed!) a look before opening anything and I'll try to respond whenever I can.
Note
About feature requests, the plan for this library is to keep it extremely small. In its present state, I think it has a bit of room to grow, but it is designed with 1 thing in mind and 1 thing only: duplicating members of classes under different names.
I'm more than happy to accept any and all feature requests that keep with this theme, but I reserve the right to deny them for any reason. I'll keep it reasonable, and will always be respectful.
If there is a request for something that's a little outside the scope of the project but maybe is related enough, I'll consider adding an 'extensions' library.