orionis 0.656.0__py3-none-any.whl → 0.658.0__py3-none-any.whl

orionis/container/container.py

@@ -3,8 +3,7 @@ import asyncio
 import inspect
 import threading
 import typing
-from pathlib import Path
-from typing import Any, Callable, Optional
+from typing import Any, Callable, Optional, Union
 from orionis.container.context.manager import ScopeManager
 from orionis.container.context.scope import ScopedContext
 from orionis.container.contracts.container import IContainer
@@ -13,13 +12,7 @@ from orionis.container.enums.lifetimes import Lifetime
 from orionis.container.exceptions import OrionisContainerException
 from orionis.container.exceptions.container import OrionisContainerTypeError
 from orionis.container.validators import (
-    ImplementsAbstractMethods,
-    IsAbstractClass,
-    IsConcreteClass,
-    IsInstance,
     IsCallable,
-    IsSubclass,
-    IsNotSubclass,
     IsValidAlias,
     LifetimeValidator
 )
@@ -452,6 +445,7 @@ class Container(IContainer):
 
         # If an alias is provided, validate and use it directly
         if alias:
+
             # Check for None, empty string, or whitespace-only alias
             if alias is None or alias == "" or str(alias).isspace():
                 raise OrionisContainerTypeError(
@@ -477,6 +471,47 @@ class Container(IContainer):
         # If no alias is provided, generate a default alias using module and class name
         return f"{abstract.__module__}.{abstract.__name__}"
 
+    def __validateLifetime(self, lifetime: Union[str, Lifetime, Any]) -> Lifetime:
+        """
+        Validates and normalizes the provided lifetime value.
+
+        Parameters
+        ----------
+        lifetime : Union[str, Lifetime, Any]
+            The lifetime value to validate. Can be a Lifetime enum or a string
+            representing a valid lifetime.
+
+        Returns
+        -------
+        Lifetime
+            The validated Lifetime enum value.
+
+        Raises
+        ------
+        OrionisContainerTypeError
+            If the value is not a valid Lifetime enum or string representation,
+            or if the string doesn't match any valid Lifetime value.
+        """
+        # Already a Lifetime enum
+        if isinstance(lifetime, Lifetime):
+            return lifetime
+
+        # String that might represent a Lifetime
+        if isinstance(lifetime, str):
+            lifetime_key = lifetime.strip().upper()
+            if lifetime_key in Lifetime.__members__:
+                return Lifetime[lifetime_key]
+
+            valid_options = ', '.join(Lifetime.__members__.keys())
+            raise OrionisContainerTypeError(
+                f"Invalid lifetime '{lifetime}'. Valid options are: {valid_options}."
+            )
+
+        # Invalid type
+        raise OrionisContainerTypeError(
+            f"Lifetime must be of type str or Lifetime enum, got {type(lifetime).__name__}."
+        )
+
     def transient(
         self,
         abstract: Callable[..., Any],
@@ -879,155 +914,174 @@ class Container(IContainer):
         """
         Registers an instance of a class or interface in the container with scoped lifetime.
 
+        This method validates the abstract type, the instance, and the alias (if provided).
+        It ensures that the instance is a valid implementation of the abstract class or interface,
+        optionally enforces decoupling, and registers the instance in the container under both
+        the abstract type and the alias. The registered instance will be available only within
+        the current active scope context.
+
         Parameters
         ----------
         abstract : Callable[..., Any]
-            The abstract class or interface to associate with the instance.
+            The abstract class or interface to associate with the instance. Must be an abstract class.
         instance : Any
-            The concrete instance to register.
+            The concrete instance to register. Must be a valid instance of the abstract type.
         alias : str, optional
-            An optional alias to register the instance under. If not provided,
-            the abstract's `__name__` attribute will be used as the alias if available.
+            An optional alias to register the instance under. If not provided, a default alias is generated
+            using the abstract's module and class name.
         enforce_decoupling : bool, optional
-            Whether to enforce decoupling between abstract and concrete types.
+            If True, enforces that the instance's class does NOT inherit from the abstract class.
+            If False, requires that the instance's class is a subclass of the abstract.
 
         Returns
         -------
-        bool
-            True if the instance was successfully registered.
+        bool or None
+            Returns True if the instance was successfully registered in the container and scope.
+            Returns None if registration fails due to an exception.
 
         Raises
         ------
-        TypeError
+        OrionisContainerTypeError
             If `abstract` is not an abstract class or if `alias` is not a valid string.
-        ValueError
-            If `instance` is not a valid instance of `abstract`.
         OrionisContainerException
-            If no active scope is found.
+            If the instance is not a valid implementation, fails decoupling check,
+            or if registration fails for any other reason.
+        OrionisContainerException
+            If no active scope is found when attempting to store the instance in the scope.
 
         Notes
         -----
-        This method registers the instance with scoped lifetime, meaning it will be
-        available only within the current active scope. If no scope is active,
-        an exception will be raised.
+        - The instance is registered with scoped lifetime, meaning it will be available only
+          within the current active scope context.
+        - All abstract methods must be implemented by the instance.
+        - If a service is already registered under the same abstract or alias, it is removed
+          before registering the new instance.
+        - If no scope is active, the instance will not be stored in any scope context.
         """
 
-        # Ensure that the abstract is an abstract class
-        IsAbstractClass(abstract, f"Instance {Lifetime.SCOPED}")
+        try:
 
-        # Ensure that the instance is a valid instance
-        IsInstance(instance)
+            # Ensure that the abstract is an abstract class
+            ReflectionAbstract.ensureIsAbstractClass(abstract)
 
-        # Ensure that instance is NOT a subclass of abstract
-        if enforce_decoupling:
-            IsNotSubclass(abstract, instance.__class__)
-        else:
-            # Validate that instance is a subclass of abstract
-            IsSubclass(abstract, instance.__class__)
+            # Ensure that the instance is a valid instance of the abstract
+            ReflectionInstance.ensureIsInstance(instance)
 
-        # Ensure implementation
-        ImplementsAbstractMethods(
-            abstract=abstract,
-            instance=instance
-        )
+            # Enforce decoupling or subclass relationship as specified
+            self.__decouplingCheck(abstract, instance.__class__, enforce_decoupling)
 
-        # Ensure that the alias is a valid string if provided
-        if alias:
-            IsValidAlias(alias)
-        else:
-            alias = f"{abstract.__module__}.{abstract.__name__}"
-
-        # If the service is already registered in container bindings, drop it
-        self.drop(abstract, alias)
-
-        # Register the binding in the container for future scope resolutions
-        self.__bindings[abstract] = Binding(
-            contract=abstract,
-            instance=instance,
-            lifetime=Lifetime.SCOPED,
-            enforce_decoupling=enforce_decoupling,
-            alias=alias
-        )
+            # Ensure all abstract methods are implemented by the instance
+            self.__implementsAbstractMethods(
+                abstract=abstract,
+                instance=instance
+            )
 
-        # Register the alias
-        self.__aliases[alias] = self.__bindings[abstract]
+            # Validate and generate the alias key (either provided or default)
+            alias = self.__makeAliasKey(abstract, alias)
 
-        # Store the instance directly in the current scope
-        scope = ScopedContext.getCurrentScope()
-        if scope:
-            scope[abstract] = instance
-            if alias != abstract:
-                scope[alias] = instance
+            # Remove any existing binding for this abstract or alias
+            self.drop(abstract, alias)
 
-        # Return True to indicate successful registration
-        return True
+            # Register the instance with scoped lifetime in the container bindings
+            self.__bindings[abstract] = Binding(
+                contract=abstract,
+                instance=instance,
+                lifetime=Lifetime.SCOPED,
+                enforce_decoupling=enforce_decoupling,
+                alias=alias
+            )
+
+            # Register the alias for lookup
+            self.__aliases[alias] = self.__bindings[abstract]
+
+            # Store the instance directly in the current scope, if a scope is active
+            scope = ScopedContext.getCurrentScope()
+            if scope:
+                scope[abstract] = instance
+                scope[alias] = scope[abstract]
 
-    
+            # Return True to indicate successful registration
+            return True
+
+        except Exception as e:
+
+            # Raise a container exception with details if registration fails
+            raise OrionisContainerException(
+                f"Unexpected error registering scoped instance: {e}"
+            ) from e
 
     def callable(
         self,
-        alias: str,
         fn: Callable[..., Any],
         *,
-        lifetime: Lifetime = Lifetime.TRANSIENT
+        alias: str
     ) -> Optional[bool]:
         """
-        Registers a function or factory under a given alias.
+        Registers a function or factory under a given alias with transient lifetime.
+
+        This method registers a callable (function or factory) in the container and associates it with a unique alias.
+        The registered function will be resolved with transient lifetime, meaning a new result is produced each time it is invoked.
+        The alias is validated for uniqueness and correctness, and any previous registration under the same alias is removed.
 
         Parameters
         ----------
-        alias : str
-            The alias to register the function under.
         fn : Callable[..., Any]
-            The function or factory to register.
-        lifetime : Lifetime, optional
-            The lifetime of the function registration (default is TRANSIENT).
+            The function or factory to register. Must be a valid Python callable.
+        alias : str
+            The alias to register the function under. Must be a non-empty, valid string.
 
         Returns
         -------
-        bool
-            True if the function was registered successfully.
+        bool or None
+            Returns True if the function was registered successfully.
+            Returns None if registration fails due to an exception.
 
         Raises
         ------
         OrionisContainerTypeError
             If the alias is invalid or the function is not callable.
         OrionisContainerException
-            If the lifetime is not allowed for the function signature.
-        """
+            If an unexpected error occurs during registration.
 
-        # Normalize and validate the lifetime parameter
-        lifetime = LifetimeValidator(lifetime)
+        Notes
+        -----
+        - The function is registered with transient lifetime, so each invocation produces a new result.
+        - If a service is already registered under the same alias, it is removed before registering the new function.
+        - The alias is validated for uniqueness and correctness.
+        """
 
-        # Ensure that the alias is a valid string
-        IsValidAlias(alias)
+        try:
+            # Validate and normalize the alias using the internal alias key generator
+            alias = self.__makeAliasKey(lambda: None, alias)
 
-        # Validate that the function is callable
-        IsCallable(fn)
+            # Ensure the provided fn is actually callable
+            if not callable(fn):
+                raise OrionisContainerTypeError(
+                    f"Expected a callable type, but got {type(fn).__name__} instead."
+                )
 
-        # Inspect the function signature
-        params: ResolveArguments = ReflectionCallable(fn).getDependencies()
+            # Remove any existing registration under this alias
+            self.drop(None, alias)
 
-        # If the function requires arguments, only allow TRANSIENT
-        if (len(params.resolved) + len(params.unresolved)) > 0 and lifetime != Lifetime.TRANSIENT:
-            raise OrionisContainerException(
-                "Functions that require arguments can only be registered with a TRANSIENT lifetime."
+            # Register the function in the bindings dictionary with transient lifetime
+            self.__bindings[alias] = Binding(
+                function=fn,
+                lifetime=Lifetime.TRANSIENT,
+                alias=alias
             )
 
-        # If the service is already registered, drop it
-        self.drop(None, alias)
+            # Register the alias for lookup in the aliases dictionary
+            self.__aliases[alias] = self.__bindings[alias]
 
-        # Register the function with the specified alias and lifetime
-        self.__bindings[alias] = Binding(
-            function=fn,
-            lifetime=lifetime,
-            alias=alias
-        )
+            # Return True to indicate successful registration
+            return True
 
-        # Register the function as a binding
-        self.__aliases[alias] = self.__bindings[alias]
+        except Exception as e:
 
-        return True
+            # Raise a container exception with details if registration fails
+            raise OrionisContainerException(
+                f"Unexpected error registering callable: {e}"
+            ) from e
 
     def bound(
         self,
@@ -2954,4 +3008,4 @@ class Container(IContainer):
             except TypeError:
                 raise OrionisContainerException(
                     f"Failed to call method '{method.__name__}': {reflection_error}"
-                ) from reflection_error
+                ) from reflection_error

orionis/metadata/framework.py

@@ -5,7 +5,7 @@
 NAME = "orionis"
 
 # Current version of the framework
-VERSION = "0.656.0"
+VERSION = "0.658.0"
 
 # Full name of the author or maintainer of the project
 AUTHOR = "Raul Mauricio Uñate Castro"

{orionis-0.656.0.dist-info → orionis-0.658.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionis
-Version: 0.656.0
+Version: 0.658.0
 Summary: Orionis Framework – Elegant, Fast, and Powerful.
 Home-page: https://github.com/orionis-framework/framework
 Author: Raul Mauricio Uñate Castro

{orionis-0.656.0.dist-info → orionis-0.658.0.dist-info}/RECORD

@@ -67,7 +67,7 @@ orionis/console/stubs/listener.stub,sha256=DbX-ghx2-vb73kzQ6L20lyg5vSKn58jSLTwFu
 orionis/console/tasks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/console/tasks/schedule.py,sha256=ZeeuQ9Tbu5KNowKC5oIk7yWeJXzlDQiQ278mWEgoCXc,87989
 orionis/container/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/container/container.py,sha256=wykXRHbXuj5uR_dLWSGV2dP6HJhat9O22xhZ1qrJ710,112458
+orionis/container/container.py,sha256=I6cTRRlDW0kf_7MMKIKXdeNXRur-slMfUTtLRNFyzbA,115945
 orionis/container/context/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/container/context/manager.py,sha256=I08K_jKXSKmrq18Pv33qYyMKIlAovVOwIgmfiVm-J7c,2971
 orionis/container/context/scope.py,sha256=p_oCzR7dDz-5ZAd16ab4vfLc3gBf34CaN0f4iR9D0bQ,1155
@@ -217,7 +217,7 @@ orionis/foundation/providers/scheduler_provider.py,sha256=IrPQJwvQVLRm5Qnz0Cxon4
 orionis/foundation/providers/testing_provider.py,sha256=eI1p2lUlxl25b5Z487O4nmqLE31CTDb4c3Q21xFadkE,1615
 orionis/foundation/providers/workers_provider.py,sha256=GdHENYV_yGyqmHJHn0DCyWmWId5xWjD48e6Zq2PGCWY,1674
 orionis/metadata/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/metadata/framework.py,sha256=uH6CGiZrnrIE3TYvHlpii4F1uxO9t1BN4Id6KNwWxJk,4089
+orionis/metadata/framework.py,sha256=KfWV8jwgxZcdeY4hlBEHan1VFrSifKQbbvgnOH4dY64,4089
 orionis/metadata/package.py,sha256=k7Yriyp5aUcR-iR8SK2ec_lf0_Cyc-C7JczgXa-I67w,16039
 orionis/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/services/asynchrony/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -404,8 +404,8 @@ orionis/test/validators/workers.py,sha256=rWcdRexINNEmGaO7mnc1MKUxkHKxrTsVuHgbnI
 orionis/test/view/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/test/view/render.py,sha256=R55ykeRs0wDKcdTf4O1YZ8GDHTFmJ0IK6VQkbJkYUvo,5571
 orionis/test/view/report.stub,sha256=QLqqCdRoENr3ECiritRB3DO_MOjRQvgBh5jxZ3Hs1r0,28189
-orionis-0.656.0.dist-info/licenses/LICENCE,sha256=JhC-z_9mbpUrCfPjcl3DhDA8trNDMzb57cvRSam1avc,1463
-orionis-0.656.0.dist-info/METADATA,sha256=79-r5BwwIuNJpbXoN6ATvQMgwYDppodZ7F9pWmW4-9Y,4772
-orionis-0.656.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-orionis-0.656.0.dist-info/top_level.txt,sha256=lyXi6jArpqJ-0zzNqd_uwsH-z9TCEBVBL-pC3Ekv7hU,8
-orionis-0.656.0.dist-info/RECORD,,
+orionis-0.658.0.dist-info/licenses/LICENCE,sha256=JhC-z_9mbpUrCfPjcl3DhDA8trNDMzb57cvRSam1avc,1463
+orionis-0.658.0.dist-info/METADATA,sha256=pmVWTkhfAxoTOYGL1SFjGeLl-Kat1Un9nPNGZvp56rE,4772
+orionis-0.658.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+orionis-0.658.0.dist-info/top_level.txt,sha256=lyXi6jArpqJ-0zzNqd_uwsH-z9TCEBVBL-pC3Ekv7hU,8
+orionis-0.658.0.dist-info/RECORD,,