aspyx 1.4.0__tar.gz → 1.4.1__tar.gz

{aspyx-1.4.0/src/aspyx.egg-info → aspyx-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspyx
-Version: 1.4.0
+Version: 1.4.1
 Summary: A DI and AOP library for Python
 Author-email: Andreas Ernst <andreas.ernst7@gmail.com>
 License: MIT License
@@ -40,12 +40,14 @@ Dynamic: license-file
 ![License](https://img.shields.io/github/license/coolsamson7/aspyx)
 ![coverage](https://img.shields.io/badge/coverage-94%25-brightgreen)
 [![PyPI](https://img.shields.io/pypi/v/aspyx)](https://pypi.org/project/aspyx/)
-[![Docs](https://img.shields.io/badge/docs-online-blue?logo=github)](https://coolsamson7.github.io/aspyx/)
+[![Docs](https://img.shields.io/badge/docs-online-blue?logo=github)](https://coolsamson7.github.io/aspyx/index/introduction)
+
+![image](https://github.com/user-attachments/assets/e808210a-b1a4-4fd0-93f1-b5f9845fa520)
 
 ## Table of Contents 
 
 - [Motivation](#motivation)
-- [Introduction](#introduction)
+- [Overview](#overview)
 - [Installation](#installation)
 - [Registration](#registration)
   - [Class](#class)
@@ -71,16 +73,19 @@ Dynamic: license-file
 
 While working on AI-related projects in Python, I was looking for a dependency injection (DI) framework. After evaluating existing options, my impression was that the most either lacked key features — such as integrated AOP — or had APIs that felt overly technical and complex, which made me develop a library on my own with the following goals
 
-- bring both di and AOP features together in a lightweight library,
+- bring both di and AOP features together in a lightweight library ( still only about 2T loc),
 - be as minimal invasive as possible,
 - offering mechanisms to easily extend and customize features without touching the core,
-- while still offering a _simple_ and _readable_ api that doesnt overwhelm developers
+- while still offering a _simple_ and _readable_ api that doesnt overwhelm developers and only requires a minimum initial learning curve
+
+The AOP integration, in particular, makes a lot of sense because:
 
-Especially the AOP integration definitely makes sense, as aspects on their own also usually require a context, which in a DI world is simply injected.
+- Aspects typically require context, which is naturally provided through DI,
+- And they should only apply to objects managed by the container, rather than acting globally.
 
-# Introduction
+# Overview
 
-Aspyx is a lightweight Python library that provides both Dependency Injection (DI) and Aspect-Oriented Programming (AOP) support.
+Aspyx is a lightweight - still only about 2T LOC- Python library that provides both Dependency Injection (DI) and Aspect-Oriented Programming (AOP) support.
 
 The following DI features are supported 
 - constructor and setter injection
@@ -89,13 +94,13 @@ The following DI features are supported
 - post processors
 - support for factory classes and methods
 - support for eager and lazy construction
-- support for scopes singleton, request and thread
+- support for scopes "singleton", "request" and "thread"
 - possibility to add custom scopes
 - conditional registration of classes and factories ( aka profiles in spring )
 - lifecycle events methods `on_init`, `on_destroy`, `on_running`
-- bundling of injectable objects according to their module location including recursive imports and inheritance
-- instantiation of - possibly multiple - container instances - so called environments - that manage the lifecycle of related objects
-- hierarchical environments
+- Automatic discovery and bundling of injectable objects based on their module location, including support for recursive imports
+- Instantiation of one or possible more isolated container instances — called environments — each managing the lifecycle of a related set of objects,
+ - Support for hierarchical environments, enabling structured scoping and layered object management.
 
 With respect to AOP:
 - support for before, around, after and error aspects 
@@ -107,7 +112,8 @@ The library is thread-safe and heavily performance optimized as most of the runt
 Let's look at a simple example
 
 ```python
-from aspyx.di import injectable, on_init, on_destroy, environment, Environment
+from aspyx.di import injectable, on_init, on_destroy, module, Environment
+
 
 @injectable()
 class Foo:
@@ -117,27 +123,28 @@ class Foo:
     def hello(self, msg: str):
         print(f"hello {msg}")
 
+
 @injectable()  # eager and singleton by default
 class Bar:
-    def __init__(self, foo: Foo): # will inject the Foo dependency
+    def __init__(self, foo: Foo):  # will inject the Foo dependency
         self.foo = foo
 
-    @on_init() # a lifecycle callback called after the constructor and all possible injections
+    @on_init()  # a lifecycle callback called after the constructor and all possible injections
     def init(self):
         ...
 
 
-# this class will register all - specifically decorated - classes and factories in the own module
-# In this case Foo and Bar
+# this class will discover and manage all - specifically decorated - classes and factories that are part of the own module
 
-@environment()
-class SampleEnvironment:
+@module()
+class SampleModule:
     def __init__(self):
         pass
 
+
 # create environment
 
-environment = Environment(SampleEnvironment)
+environment = Environment(SampleModule)
 
 # fetch an instance
 
@@ -171,12 +178,7 @@ class SampleAdvice:
         return invocation.proceed()
 ```
 
-The invocation parameter stores the complete context of the current execution, which are
-- the method
-- args
-- kwargs
-- the result
-- the possible caught error
+While features like DI and AOP are often associated with enterprise applcations, this example hopefully demonstrates that they work just as well in small- to medium-sized projects—without introducing significant overhead—while still providing powerful tools for achieving clean architecture, resulting in maintainable and easily testable code.
 
 Let's look at the details
 
@@ -280,21 +282,26 @@ Valid conditions are created by:
 
 ## Definition
 
-An `Environment` is the container that manages the lifecycle of objects. The set of classes and instances is determined by a constructor argument that controls the class registry.
+An `Environment` is the container that manages the lifecycle of objects. 
+The set of classes and instances is determined by a 
+constructor type argument called `module`.
 
 **Example**: 
 ```python
-@environment()
-class SampleEnvironment:
+@module()
+class SampleModule:
     def __init__(self):
         pass
-
-environment = Environment(SampleEnvironment)
 ```
 
-The default is that all eligible classes, that are implemented in the containing module or in any submodule will be managed.
-THe container will import the module and its children automatically. No need to add artificial import statements!
+A module is a regular injectable class decorated with `@module` that controls the discovery of injectable classes, by filtering classes according to their module location relative to this class. 
+  All eligible classes, that are implemented in the containing module or in any submodule will be managed.
 
+In a second step the real container - the environment - is created based on a module:
+
+```python
+environment = Environment(SampleModule, features=["dev"])
+```
 
 By adding the parameter `features: list[str]`, it is possible to filter injectables by evaluating the corresponding `@conditional` decorators.
 
@@ -307,21 +314,21 @@ class DevOnly:
      def __init__(self):
         pass
 
-@environment()
-class SampleEnvironmen():
+@module()
+class SampleModule():
     def __init__(self):
         pass
 
-environment = Environment(SampleEnvironment, features=["dev"])
+environment = Environment(SampleModule, features=["dev"])
 ```
 
 
-By adding an `imports: list[Type]` parameter, specifying other environment types, it will register the appropriate classes recursively.
+By adding an `imports: list[Type]` parameter, specifying other module types, it will register the appropriate classes recursively.
 
 **Example**: 
 ```python
-@environment()
-class SampleEnvironmen(imports=[OtherEnvironment]):
+@module()
+class SampleModule(imports=[OtherModule]):
     def __init__(self):
         pass
 ```
@@ -330,8 +337,9 @@ Another possibility is to add a parent environment as an `Environment` construct
 
 **Example**: 
 ```python
-rootEnvironment = Environment(RootEnvironment)
-environment = Environment(SampleEnvironment, parent=rootEnvironment)
+rootEnvironment = Environment(RootModule)
+
+environment = Environment(SampleModule, parent=rootEnvironment)
 ```
 
 The difference is, that in the first case, class instances of imported modules will be created in the scope of the _own_ environment, while in the second case, it will return instances managed by the parent.
@@ -464,7 +472,9 @@ class SingletonScope(Scope):
 
 It is possible to define different aspects, that will be part of method calling flow. This logic fits nicely in the library, since the DI framework controls the instantiation logic and can handle aspects within a regular post processor. 
 
-Advice classes need to be part of classes that add a `@advice()` decorator and can define methods that add aspects.
+On the other hand, advices are also regular DI objects, as they will usually require some kind of - injected - context.
+
+Advices are regular classes decorated with `@advice` that define aspect methods.
 
 ```python
 @advice
@@ -516,7 +526,7 @@ All methods are expected to have single `Invocation` parameter, that stores
 - `result` the result ( initially `None`)
 - `exception` a possible caught exception ( initially `None`)
 
-⚠️ **Attention:** It is essential for `around` methods to call `proceed()` on the invocation, which will call the next around method in the chain and finally the original method.
+⚠️ **Note:** It is essential for `around` methods to call `proceed()` on the invocation, which will call the next around method in the chain and finally the original method.
 
 If the `proceed` is called with parameters, they will replace the original parameters! 
 
@@ -562,6 +572,12 @@ class TransactionAdvice:
 
 With respect to async methods, you need to make sure, to replace a `proceed()` with a `await proceed_async()` to have the overall chain async!
 
+## Advice Lifecycle and visibility.
+
+Advices are always part of a specific environment, and only modify methods of objects managed by exactly this environment.
+
+An advice of a parent environment will for example not see classes of inherited environments. What is done instead, is to recreate the advice - more technically speaking, a processor that will collect and apply the advices -  in every child environment, and let it operate on the local objects. With this approach different environments are completely isolated from each other with no side effects whatsoever.   
+
 # Threading
 
 A handy decorator `@synchronized` in combination with the respective advice is implemented that automatically synchronizes methods with a `RLock` associated with the instance.
@@ -652,8 +668,8 @@ Two specific source are already implemented:
 Typically you create the required configuration sources in an environment class, e.g.
 
 ```python
-@environment()
-class SampleEnvironment:
+@module()
+class SampleModule:
     # constructor
 
     def __init__(self):
@@ -725,8 +741,8 @@ class DerivedException(Exception):
     def __init__(self):
         pass
 
-@environment()
-class SampleEnvironment:
+@module()
+class SampleModule:
     # constructor
 
     def __init__(self):
@@ -820,6 +836,10 @@ class ExceptionAdvice:
 - bugfixes
 - added `@ExceptionManager`
 
+**1.4.1**
+
+- mkdocs
+
 
       
 

{aspyx-1.4.0 → aspyx-1.4.1}/README.md

@@ -6,12 +6,14 @@
 ![License](https://img.shields.io/github/license/coolsamson7/aspyx)
 ![coverage](https://img.shields.io/badge/coverage-94%25-brightgreen)
 [![PyPI](https://img.shields.io/pypi/v/aspyx)](https://pypi.org/project/aspyx/)
-[![Docs](https://img.shields.io/badge/docs-online-blue?logo=github)](https://coolsamson7.github.io/aspyx/)
+[![Docs](https://img.shields.io/badge/docs-online-blue?logo=github)](https://coolsamson7.github.io/aspyx/index/introduction)
+
+![image](https://github.com/user-attachments/assets/e808210a-b1a4-4fd0-93f1-b5f9845fa520)
 
 ## Table of Contents 
 
 - [Motivation](#motivation)
-- [Introduction](#introduction)
+- [Overview](#overview)
 - [Installation](#installation)
 - [Registration](#registration)
   - [Class](#class)
@@ -37,16 +39,19 @@
 
 While working on AI-related projects in Python, I was looking for a dependency injection (DI) framework. After evaluating existing options, my impression was that the most either lacked key features — such as integrated AOP — or had APIs that felt overly technical and complex, which made me develop a library on my own with the following goals
 
-- bring both di and AOP features together in a lightweight library,
+- bring both di and AOP features together in a lightweight library ( still only about 2T loc),
 - be as minimal invasive as possible,
 - offering mechanisms to easily extend and customize features without touching the core,
-- while still offering a _simple_ and _readable_ api that doesnt overwhelm developers
+- while still offering a _simple_ and _readable_ api that doesnt overwhelm developers and only requires a minimum initial learning curve
+
+The AOP integration, in particular, makes a lot of sense because:
 
-Especially the AOP integration definitely makes sense, as aspects on their own also usually require a context, which in a DI world is simply injected.
+- Aspects typically require context, which is naturally provided through DI,
+- And they should only apply to objects managed by the container, rather than acting globally.
 
-# Introduction
+# Overview
 
-Aspyx is a lightweight Python library that provides both Dependency Injection (DI) and Aspect-Oriented Programming (AOP) support.
+Aspyx is a lightweight - still only about 2T LOC- Python library that provides both Dependency Injection (DI) and Aspect-Oriented Programming (AOP) support.
 
 The following DI features are supported 
 - constructor and setter injection
@@ -55,13 +60,13 @@ The following DI features are supported
 - post processors
 - support for factory classes and methods
 - support for eager and lazy construction
-- support for scopes singleton, request and thread
+- support for scopes "singleton", "request" and "thread"
 - possibility to add custom scopes
 - conditional registration of classes and factories ( aka profiles in spring )
 - lifecycle events methods `on_init`, `on_destroy`, `on_running`
-- bundling of injectable objects according to their module location including recursive imports and inheritance
-- instantiation of - possibly multiple - container instances - so called environments - that manage the lifecycle of related objects
-- hierarchical environments
+- Automatic discovery and bundling of injectable objects based on their module location, including support for recursive imports
+- Instantiation of one or possible more isolated container instances — called environments — each managing the lifecycle of a related set of objects,
+ - Support for hierarchical environments, enabling structured scoping and layered object management.
 
 With respect to AOP:
 - support for before, around, after and error aspects 
@@ -73,7 +78,8 @@ The library is thread-safe and heavily performance optimized as most of the runt
 Let's look at a simple example
 
 ```python
-from aspyx.di import injectable, on_init, on_destroy, environment, Environment
+from aspyx.di import injectable, on_init, on_destroy, module, Environment
+
 
 @injectable()
 class Foo:
@@ -83,27 +89,28 @@ class Foo:
     def hello(self, msg: str):
         print(f"hello {msg}")
 
+
 @injectable()  # eager and singleton by default
 class Bar:
-    def __init__(self, foo: Foo): # will inject the Foo dependency
+    def __init__(self, foo: Foo):  # will inject the Foo dependency
         self.foo = foo
 
-    @on_init() # a lifecycle callback called after the constructor and all possible injections
+    @on_init()  # a lifecycle callback called after the constructor and all possible injections
     def init(self):
         ...
 
 
-# this class will register all - specifically decorated - classes and factories in the own module
-# In this case Foo and Bar
+# this class will discover and manage all - specifically decorated - classes and factories that are part of the own module
 
-@environment()
-class SampleEnvironment:
+@module()
+class SampleModule:
     def __init__(self):
         pass
 
+
 # create environment
 
-environment = Environment(SampleEnvironment)
+environment = Environment(SampleModule)
 
 # fetch an instance
 
@@ -137,12 +144,7 @@ class SampleAdvice:
         return invocation.proceed()
 ```
 
-The invocation parameter stores the complete context of the current execution, which are
-- the method
-- args
-- kwargs
-- the result
-- the possible caught error
+While features like DI and AOP are often associated with enterprise applcations, this example hopefully demonstrates that they work just as well in small- to medium-sized projects—without introducing significant overhead—while still providing powerful tools for achieving clean architecture, resulting in maintainable and easily testable code.
 
 Let's look at the details
 
@@ -246,21 +248,26 @@ Valid conditions are created by:
 
 ## Definition
 
-An `Environment` is the container that manages the lifecycle of objects. The set of classes and instances is determined by a constructor argument that controls the class registry.
+An `Environment` is the container that manages the lifecycle of objects. 
+The set of classes and instances is determined by a 
+constructor type argument called `module`.
 
 **Example**: 
 ```python
-@environment()
-class SampleEnvironment:
+@module()
+class SampleModule:
     def __init__(self):
         pass
-
-environment = Environment(SampleEnvironment)
 ```
 
-The default is that all eligible classes, that are implemented in the containing module or in any submodule will be managed.
-THe container will import the module and its children automatically. No need to add artificial import statements!
+A module is a regular injectable class decorated with `@module` that controls the discovery of injectable classes, by filtering classes according to their module location relative to this class. 
+  All eligible classes, that are implemented in the containing module or in any submodule will be managed.
 
+In a second step the real container - the environment - is created based on a module:
+
+```python
+environment = Environment(SampleModule, features=["dev"])
+```
 
 By adding the parameter `features: list[str]`, it is possible to filter injectables by evaluating the corresponding `@conditional` decorators.
 
@@ -273,21 +280,21 @@ class DevOnly:
      def __init__(self):
         pass
 
-@environment()
-class SampleEnvironmen():
+@module()
+class SampleModule():
     def __init__(self):
         pass
 
-environment = Environment(SampleEnvironment, features=["dev"])
+environment = Environment(SampleModule, features=["dev"])
 ```
 
 
-By adding an `imports: list[Type]` parameter, specifying other environment types, it will register the appropriate classes recursively.
+By adding an `imports: list[Type]` parameter, specifying other module types, it will register the appropriate classes recursively.
 
 **Example**: 
 ```python
-@environment()
-class SampleEnvironmen(imports=[OtherEnvironment]):
+@module()
+class SampleModule(imports=[OtherModule]):
     def __init__(self):
         pass
 ```
@@ -296,8 +303,9 @@ Another possibility is to add a parent environment as an `Environment` construct
 
 **Example**: 
 ```python
-rootEnvironment = Environment(RootEnvironment)
-environment = Environment(SampleEnvironment, parent=rootEnvironment)
+rootEnvironment = Environment(RootModule)
+
+environment = Environment(SampleModule, parent=rootEnvironment)
 ```
 
 The difference is, that in the first case, class instances of imported modules will be created in the scope of the _own_ environment, while in the second case, it will return instances managed by the parent.
@@ -430,7 +438,9 @@ class SingletonScope(Scope):
 
 It is possible to define different aspects, that will be part of method calling flow. This logic fits nicely in the library, since the DI framework controls the instantiation logic and can handle aspects within a regular post processor. 
 
-Advice classes need to be part of classes that add a `@advice()` decorator and can define methods that add aspects.
+On the other hand, advices are also regular DI objects, as they will usually require some kind of - injected - context.
+
+Advices are regular classes decorated with `@advice` that define aspect methods.
 
 ```python
 @advice
@@ -482,7 +492,7 @@ All methods are expected to have single `Invocation` parameter, that stores
 - `result` the result ( initially `None`)
 - `exception` a possible caught exception ( initially `None`)
 
-⚠️ **Attention:** It is essential for `around` methods to call `proceed()` on the invocation, which will call the next around method in the chain and finally the original method.
+⚠️ **Note:** It is essential for `around` methods to call `proceed()` on the invocation, which will call the next around method in the chain and finally the original method.
 
 If the `proceed` is called with parameters, they will replace the original parameters! 
 
@@ -528,6 +538,12 @@ class TransactionAdvice:
 
 With respect to async methods, you need to make sure, to replace a `proceed()` with a `await proceed_async()` to have the overall chain async!
 
+## Advice Lifecycle and visibility.
+
+Advices are always part of a specific environment, and only modify methods of objects managed by exactly this environment.
+
+An advice of a parent environment will for example not see classes of inherited environments. What is done instead, is to recreate the advice - more technically speaking, a processor that will collect and apply the advices -  in every child environment, and let it operate on the local objects. With this approach different environments are completely isolated from each other with no side effects whatsoever.   
+
 # Threading
 
 A handy decorator `@synchronized` in combination with the respective advice is implemented that automatically synchronizes methods with a `RLock` associated with the instance.
@@ -618,8 +634,8 @@ Two specific source are already implemented:
 Typically you create the required configuration sources in an environment class, e.g.
 
 ```python
-@environment()
-class SampleEnvironment:
+@module()
+class SampleModule:
     # constructor
 
     def __init__(self):
@@ -691,8 +707,8 @@ class DerivedException(Exception):
     def __init__(self):
         pass
 
-@environment()
-class SampleEnvironment:
+@module()
+class SampleModule:
     # constructor
 
     def __init__(self):
@@ -786,6 +802,10 @@ class ExceptionAdvice:
 - bugfixes
 - added `@ExceptionManager`
 
+**1.4.1**
+
+- mkdocs
+
 
       
 

{aspyx-1.4.0 → aspyx-1.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aspyx"
-version = "1.4.0"
+version = "1.4.1"
 description = "A DI and AOP library for Python"
 authors = [{ name = "Andreas Ernst", email = "andreas.ernst7@gmail.com" }]
 readme = "README.md"

{aspyx-1.4.0 → aspyx-1.4.1}/src/aspyx/di/__init__.py

@@ -1,7 +1,7 @@
 """
 This module provides dependency injection and aop capabilities for Python applications.
 """
-from .di import conditional, requires_class, requires_feature, DIException, AbstractCallableProcessor, LifecycleCallable, Lifecycle, Providers, Environment, ClassInstanceProvider, injectable, factory, environment, inject, order, create, on_init, on_running, on_destroy, inject_environment, Factory, PostProcessor
+from .di import conditional, requires_class, requires_feature, DIException, AbstractCallableProcessor, LifecycleCallable, Lifecycle, Providers, Environment, ClassInstanceProvider, injectable, factory, module, inject, order, create, on_init, on_running, on_destroy, inject_environment, Factory, PostProcessor
 
 # import something from the subpackages, so that the decorators are executed
 
@@ -17,7 +17,7 @@ __all__ = [
     "Environment",
     "injectable",
     "factory",
-    "environment",
+    "module",
     "inject",
     "create",
     "order",

aspyx-1.4.1/src/aspyx/di/aop/__init__.py

@@ -0,0 +1,28 @@
+"""
+The AOP module gives you the possibility to define aspects that will participate in method execution flows.
+
+**Example**: all method executions of methods named "foo" will include a `before` aspect, that will be executed before the original method
+
+```python
+@advice
+class Advice:
+   @before(methods().named("foo"))
+   def before_call(self, invocation: Invocation):
+      ...
+
+```
+
+Note, that this requires that both the advice and the targeted methods need to be managed by an environment.
+"""
+from .aop import before, after, classes, around, error, advice, methods, Invocation, AspectTarget
+__all__ = [
+    "before",
+    "after",
+    "around",
+    "error",
+    "advice",
+    "classes",
+    "methods",
+    "Invocation",
+    "AspectTarget"
+]