# Object Extensions
###### A basic framework for implementing an extension pattern
## Summary
The point of this framework is to provide a more modular alternative to object inheritance.
**Consider the following use case:** You have an abstract class `Car` intended to represent a car, and need a pattern that allows you to *optionally* add more features.
For example, you may want to add a convertible roof or a touchscreen on the dashboard, but these features will not necessarily be added to every subclass of `Car` you create.
Applying standard OOP here means you would need to make a subclass every time a new combination of these optional features is needed.
In the above case, you may need one subclass for a car with a convertible roof, one subclass for a car with a touchscreen, and one that has both features. As the amount of optional features increases,
the amount of possible combinations skyrockets. This is not a scalable solution to the problem.
Object Extensions is an elegant way to handle scenarios such as this one. Rather than creating a new subclass for each possible combination,
you create one extension representing each feature. When you need to create a car with a particular set of features,
you take the parent class and pass it the exact set of extensions you want to apply via the `.with_extensions()` method as the need arises.
Note that this pattern is intended to be used alongside inheritance, not to replace it entirely. The two can be mixed without issue, such that
(for example) a subclass could extend a parent class that has pre-applied extensions like so:
```python
class SpecificCarModel(Car.with_extensions(TouchscreenDash)):
pass
```
## Quickstart
### Setup
Below is an example of an extendable class, and an example extension that can be applied to it.
```python
from objectextensions import Extendable
class HashList(Extendable):
"""
A basic example class with some data and methods.
Inheriting Extendable allows this class to be modified with extensions
"""
def __init__(self, iterable=()):
super().__init__()
self.values = {}
self.list = []
for value in iterable:
self.append(value)
def append(self, item):
self.list.append(item)
self.values[item] = self.values.get(item, []) + [len(self.list) - 1]
def index(self, item):
"""
Returns all indexes containing the specified item.
Much lower time complexity than in a typical list due to dict lookup usage
"""
if item not in self.values:
raise ValueError(f"{item} is not in hashlist")
return self.values[item]
```
```python
from objectextensions import Extension
class Listener(Extension):
"""
This extension class is written to apply a counter to the HashList class,
which increments any time .append() is called
"""
@staticmethod
def can_extend(target_cls):
return issubclass(target_cls, HashList)
@staticmethod
def extend(target_cls):
Extension._set(target_cls, "increment_append_count", Listener.__increment_append_count)
Extension._wrap(target_cls, "__init__", Listener.__wrap_init)
Extension._wrap(target_cls, 'append', Listener.__wrap_append)
def __wrap_init(self, *args, **kwargs):
Extension._set(self, "append_count", 0)
yield
def __wrap_append(self, *args, **kwargs):
yield
self.increment_append_count()
def __increment_append_count(self):
self.append_count += 1
```
### Instantiation
```python
HashListWithListeners = HashList.with_extensions(Listener)
my_hashlist = HashListWithListeners(iterable=[5,2,4])
```
or, for shorthand:
```python
my_hashlist = HashList.with_extensions(Listener)(iterable=[5,2,4])
```
### Result
```python
>>> my_hashlist.append_count # Attribute that was added by the Listener extension
3
>>> my_hashlist.append(7) # Listener has wrapped this method with logic which increments .append_count
>>> my_hashlist.append_count
4
```
## Functionality
### Properties
Extendable.**extensions**
Returns a reference to a tuple containing any applied extensions.
Extendable.**extension_data**
Returns a snapshot of the instance's extension data.
This is intended to hold metadata optionally provided by extensions for the sake of introspection,
and for communication between extensions.
### Methods
Extendable.**with_extensions**(*cls, \*extensions: Type[Extension]*)
Returns a subclass with the provided extensions applied to it.
Extension.**can_extend**(*target_cls: Type[Extendable]*)
Abstract staticmethod which must be overridden.
Should return a bool indicating whether this Extension can be applied to the target class.
Extension.**extend**(*target_cls: Type[Extendable]*)
Abstract staticmethod which must be overridden.
Any modification of the target class should take place in this function.
Extension.**\_wrap**(*target_cls: Type[Extendable], method_name: str,*
*gen_func: Callable[..., Generator[None, Any, None]]*)
Used to wrap an existing method on the target class.
Passes copies of the method parameters to the generator function provided.
The generator function should yield once,
with the yield statement receiving a copy of the result of executing the core method.
Extension.**\_set**(*target: Union[Type[Extendable], Extendable], attribute_name: str, value: Any*)
Used to safely add a new attribute to an extendable class.
*Note: It is possible but not recommended to modify an instance rather than a class using this method.*
*Will raise an error if the attribute already exists (for example, if another extension has already added it)*
*to ensure compatibility issues are flagged and can be dealt with easily.*
Extension.**\_set_property**(*target: Union[Type[Extendable], Extendable], property_name: str, value: Callable[[Extendable], Any]*)
Used to safely add a new property to an extendable class.
*Note: It is possible but not recommended to modify an instance rather than a class using this method.*
*Will raise an error if the attribute already exists (for example, if another extension has already added it)*
*to ensure compatibility issues are flagged and can be dealt with easily.*
Extension.**\_set_setter**(*target: Union[Type[Extendable], Extendable], setter_name: str, linked_property_name: str,*
*value: Callable[[Extendable, Any], Any]*)
Used to safely add a new setter to an extendable class.
*Note: It is possible but not recommended to modify an instance rather than a class using this method.*
*If the property this setter is paired with does not use the same attribute name,*
*and the setter's name already exists on the class (for example, if another extension has already added it),*
*an error will be raised. This is to ensure compatibility issues are flagged and can be dealt with easily.*
## Additional Info
- As extensions do not properly invoke name mangling, adding private members via extensions is discouraged; doing so may lead to unintended behaviour.
Using protected members instead is encouraged, as name mangling does not come into play in this case.
Raw data
{
"_id": null,
"home_page": "https://github.com/immijimmi/objectextensions",
"name": "objectextensions",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "extensions,plugins",
"author": "immijimmi",
"author_email": "immijimmi1@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7c/eb/346811030a24941ec1b4b639c812103aeec5ba2c9f79517efb94adf25867/objectextensions-2.0.2.tar.gz",
"platform": null,
"description": "# Object Extensions\r\n\r\n###### A basic framework for implementing an extension pattern\r\n\r\n## Summary\r\n\r\nThe point of this framework is to provide a more modular alternative to object inheritance.\r\n\r\n**Consider the following use case:** You have an abstract class `Car` intended to represent a car, and need a pattern that allows you to *optionally* add more features.\r\nFor example, you may want to add a convertible roof or a touchscreen on the dashboard, but these features will not necessarily be added to every subclass of `Car` you create.\r\n\r\nApplying standard OOP here means you would need to make a subclass every time a new combination of these optional features is needed.\r\nIn the above case, you may need one subclass for a car with a convertible roof, one subclass for a car with a touchscreen, and one that has both features. As the amount of optional features increases,\r\nthe amount of possible combinations skyrockets. This is not a scalable solution to the problem.\r\n\r\nObject Extensions is an elegant way to handle scenarios such as this one. Rather than creating a new subclass for each possible combination,\r\nyou create one extension representing each feature. When you need to create a car with a particular set of features,\r\nyou take the parent class and pass it the exact set of extensions you want to apply via the `.with_extensions()` method as the need arises.\r\n\r\nNote that this pattern is intended to be used alongside inheritance, not to replace it entirely. The two can be mixed without issue, such that\r\n(for example) a subclass could extend a parent class that has pre-applied extensions like so:\r\n```python\r\nclass SpecificCarModel(Car.with_extensions(TouchscreenDash)):\r\n pass\r\n```\r\n\r\n## Quickstart\r\n\r\n### Setup\r\n\r\nBelow is an example of an extendable class, and an example extension that can be applied to it.\r\n\r\n```python\r\nfrom objectextensions import Extendable\r\n\r\n\r\nclass HashList(Extendable):\r\n \"\"\"\r\n A basic example class with some data and methods.\r\n Inheriting Extendable allows this class to be modified with extensions\r\n \"\"\"\r\n\r\n def __init__(self, iterable=()):\r\n super().__init__()\r\n\r\n self.values = {}\r\n self.list = []\r\n\r\n for value in iterable:\r\n self.append(value)\r\n\r\n def append(self, item):\r\n self.list.append(item)\r\n self.values[item] = self.values.get(item, []) + [len(self.list) - 1]\r\n\r\n def index(self, item):\r\n \"\"\"\r\n Returns all indexes containing the specified item.\r\n Much lower time complexity than in a typical list due to dict lookup usage\r\n \"\"\"\r\n\r\n if item not in self.values:\r\n raise ValueError(f\"{item} is not in hashlist\")\r\n\r\n return self.values[item]\r\n```\r\n```python\r\nfrom objectextensions import Extension\r\n\r\n\r\nclass Listener(Extension):\r\n \"\"\"\r\n This extension class is written to apply a counter to the HashList class,\r\n which increments any time .append() is called\r\n \"\"\"\r\n\r\n @staticmethod\r\n def can_extend(target_cls):\r\n return issubclass(target_cls, HashList)\r\n\r\n @staticmethod\r\n def extend(target_cls):\r\n Extension._set(target_cls, \"increment_append_count\", Listener.__increment_append_count)\r\n\r\n Extension._wrap(target_cls, \"__init__\", Listener.__wrap_init)\r\n Extension._wrap(target_cls, 'append', Listener.__wrap_append)\r\n\r\n def __wrap_init(self, *args, **kwargs):\r\n Extension._set(self, \"append_count\", 0)\r\n yield\r\n\r\n def __wrap_append(self, *args, **kwargs):\r\n yield\r\n self.increment_append_count()\r\n\r\n def __increment_append_count(self):\r\n self.append_count += 1\r\n```\r\n\r\n### Instantiation\r\n```python\r\nHashListWithListeners = HashList.with_extensions(Listener)\r\nmy_hashlist = HashListWithListeners(iterable=[5,2,4])\r\n```\r\nor, for shorthand:\r\n```python\r\nmy_hashlist = HashList.with_extensions(Listener)(iterable=[5,2,4])\r\n```\r\n\r\n### Result\r\n```python\r\n>>> my_hashlist.append_count # Attribute that was added by the Listener extension\r\n3\r\n>>> my_hashlist.append(7) # Listener has wrapped this method with logic which increments .append_count\r\n>>> my_hashlist.append_count\r\n4\r\n```\r\n\r\n## Functionality\r\n\r\n### Properties\r\n\r\nExtendable.**extensions** \r\n Returns a reference to a tuple containing any applied extensions. \r\n \r\n\r\nExtendable.**extension_data** \r\n Returns a snapshot of the instance's extension data. \r\n This is intended to hold metadata optionally provided by extensions for the sake of introspection, \r\n and for communication between extensions. \r\n \r\n\r\n### Methods\r\n\r\nExtendable.**with_extensions**(*cls, \\*extensions: Type[Extension]*) \r\n Returns a subclass with the provided extensions applied to it. \r\n \r\n\r\nExtension.**can_extend**(*target_cls: Type[Extendable]*) \r\n Abstract staticmethod which must be overridden. \r\n Should return a bool indicating whether this Extension can be applied to the target class. \r\n \r\n\r\nExtension.**extend**(*target_cls: Type[Extendable]*) \r\n Abstract staticmethod which must be overridden. \r\n Any modification of the target class should take place in this function. \r\n \r\n\r\nExtension.**\\_wrap**(*target_cls: Type[Extendable], method_name: str,* \r\n *gen_func: Callable[..., Generator[None, Any, None]]*) \r\n Used to wrap an existing method on the target class. \r\n Passes copies of the method parameters to the generator function provided. \r\n The generator function should yield once, \r\n with the yield statement receiving a copy of the result of executing the core method. \r\n \r\n\r\nExtension.**\\_set**(*target: Union[Type[Extendable], Extendable], attribute_name: str, value: Any*) \r\n Used to safely add a new attribute to an extendable class. \r\n\r\n*Note: It is possible but not recommended to modify an instance rather than a class using this method.* \r\n *Will raise an error if the attribute already exists (for example, if another extension has already added it)* \r\n *to ensure compatibility issues are flagged and can be dealt with easily.* \r\n \r\n\r\nExtension.**\\_set_property**(*target: Union[Type[Extendable], Extendable], property_name: str, value: Callable[[Extendable], Any]*) \r\n Used to safely add a new property to an extendable class. \r\n\r\n*Note: It is possible but not recommended to modify an instance rather than a class using this method.* \r\n *Will raise an error if the attribute already exists (for example, if another extension has already added it)* \r\n *to ensure compatibility issues are flagged and can be dealt with easily.* \r\n \r\n\r\nExtension.**\\_set_setter**(*target: Union[Type[Extendable], Extendable], setter_name: str, linked_property_name: str,* \r\n *value: Callable[[Extendable, Any], Any]*) \r\n Used to safely add a new setter to an extendable class. \r\n\r\n*Note: It is possible but not recommended to modify an instance rather than a class using this method.* \r\n *If the property this setter is paired with does not use the same attribute name,* \r\n *and the setter's name already exists on the class (for example, if another extension has already added it),* \r\n *an error will be raised. This is to ensure compatibility issues are flagged and can be dealt with easily.* \r\n \r\n\r\n## Additional Info\r\n\r\n- As extensions do not properly invoke name mangling, adding private members via extensions is discouraged; doing so may lead to unintended behaviour.\r\nUsing protected members instead is encouraged, as name mangling does not come into play in this case.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A basic framework for implementing an extension pattern",
"version": "2.0.2",
"project_urls": {
"Download": "https://github.com/immijimmi/objectextensions/archive/refs/tags/v2.0.2.tar.gz",
"Homepage": "https://github.com/immijimmi/objectextensions"
},
"split_keywords": [
"extensions",
"plugins"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7ceb346811030a24941ec1b4b639c812103aeec5ba2c9f79517efb94adf25867",
"md5": "1a8931a70ee6361096b35a9f91895d68",
"sha256": "74c3ca202f668bcca372d489816745c20d501a9bb503cf0e61963c15b6ae82f6"
},
"downloads": -1,
"filename": "objectextensions-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "1a8931a70ee6361096b35a9f91895d68",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6901,
"upload_time": "2023-06-24T03:59:00",
"upload_time_iso_8601": "2023-06-24T03:59:00.583462Z",
"url": "https://files.pythonhosted.org/packages/7c/eb/346811030a24941ec1b4b639c812103aeec5ba2c9f79517efb94adf25867/objectextensions-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-24 03:59:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "immijimmi",
"github_project": "objectextensions",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "objectextensions"
}
JSON
