orionis 0.312.0__py3-none-any.whl → 0.314.0__py3-none-any.whl

orionis/services/introspection/concretes/reflection_concrete.py

@@ -14,14 +14,35 @@ from orionis.services.introspection.instances.reflection_instance import Reflect
 
 class ReflectionConcrete(IReflectionConcrete):
 
-    def __init__(self, concrete: Type) -> None:
+    @staticmethod
+    def isConcreteClass(concrete: Type) -> bool:
         """
-        Initialize the ReflectionConcrete with the provided class type.
+        Checks if the provided concrete type is a valid ReflectionConcrete type.
 
         Parameters
         ----------
         concrete : Type
-            The class type to be reflected upon.
+            The class type to be validated.
+
+        Returns
+        -------
+        bool
+            True if the class is a valid ReflectionConcrete type, False otherwise.
+        """
+        try:
+            return ReflectionConcrete.ensureIsConcreteClass(concrete)
+        except (ReflectionTypeError, ReflectionValueError):
+            return False
+
+    @staticmethod
+    def ensureIsConcreteClass(concrete: Type) -> bool:
+        """
+        Ensures that the provided concrete type is a valid ReflectionConcrete type.
+
+        Parameters
+        ----------
+        concrete : Type
+            The class type to be validated.
 
         Raises
         ------
@@ -29,35 +50,57 @@ class ReflectionConcrete(IReflectionConcrete):
             If the provided argument is not a class type or is already an instance.
         ReflectionValueError
             If the provided class is a built-in/primitive type, abstract class, or interface.
-
-        Notes
-        -----
-        - Built-in and primitive types (e.g., int, str, list) are not allowed.
-        - Abstract classes and interfaces (classes with abstract methods) are not allowed.
         """
+        # Check if the concrete is a class type
         if not isinstance(concrete, type):
             raise ReflectionTypeError(f"Expected a class, got {type(concrete)}")
 
+        # Define a set of built-in and primitive types
         builtin_types = {
             int, float, str, bool, bytes, type(None), complex,
             list, tuple, dict, set, frozenset
         }
 
+        # Check if the concrete class is a built-in or primitive type
         if concrete in builtin_types:
             raise ReflectionValueError(f"Class '{concrete.__name__}' is a built-in or primitive type and cannot be used.")
 
-        # Check for abstract classes (including interfaces)
-        if hasattr(concrete, '__abstractmethods__') and len(concrete.__abstractmethods__) > 0:
-            raise ReflectionValueError(f"Class '{concrete.__name__}' is abstract or an interface and cannot be used.")
-
         # Prevent instantiating if it's already an instance
         if not isinstance(concrete, type):
             raise ReflectionTypeError(f"Expected a class type, got instance of '{type(concrete).__name__}'.")
 
         # Optionally, check for ABCMeta to catch interfaces
-        if isinstance(concrete, abc.ABCMeta) and getattr(concrete, '__abstractmethods__', False):
+        if abc.ABC in concrete.__bases__:
             raise ReflectionValueError(f"Class '{concrete.__name__}' is an interface and cannot be used.")
 
+        return True
+
+    def __init__(self, concrete: Type) -> None:
+        """
+        Initialize the ReflectionConcrete with the provided class type.
+
+        Parameters
+        ----------
+        concrete : Type
+            The class type to be reflected upon.
+
+        Raises
+        ------
+        ReflectionTypeError
+            If the provided argument is not a class type or is already an instance.
+        ReflectionValueError
+            If the provided class is a built-in/primitive type, abstract class, or interface.
+
+        Notes
+        -----
+        - Built-in and primitive types (e.g., int, str, list) are not allowed.
+        - Abstract classes and interfaces (classes with abstract methods) are not allowed.
+        """
+
+        # Ensure the provided concrete type is a valid ReflectionConcrete class
+        ReflectionConcrete.ensureIsConcreteClass(concrete)
+
+        # Set the concrete class in the instance
         self._concrete = concrete
         self.__instance = None
 

orionis/services/introspection/instances/reflection_instance.py

@@ -12,35 +12,103 @@ from orionis.services.introspection.contracts.reflection_instance import IReflec
 
 class ReflectionInstance(IReflectionInstance):
 
-    def __init__(self, instance: Any) -> None:
+    @staticmethod
+    def isInstance(instance: Any) -> bool:
         """
-        Initialize the ReflectionInstance with a given object instance.
+        Check if the given object is a valid instance according to ReflectionInstance rules.
 
         Parameters
         ----------
         instance : Any
-            The object instance to be reflected upon.
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a valid instance, False otherwise.
+
+        Notes
+        -----
+        This method catches and handles exceptions internally; it does not raise.
+        """
+        try:
+            return ReflectionInstance.ensureIsInstance(instance)
+        except (ReflectionTypeError, ReflectionValueError):
+            return False
+
+    @staticmethod
+    def ensureIsInstance(instance: Any) -> bool:
+        """
+        Validate that the provided object is a proper instance of a user-defined class.
+
+        Parameters
+        ----------
+        instance : Any
+            The object to validate.
+
+        Returns
+        -------
+        bool
+            True if the instance passes all checks.
 
         Raises
         ------
         ReflectionTypeError
-            If the provided instance is not a valid object instance.
+            If the input is not a valid object instance.
         ReflectionValueError
-            If the instance belongs to a built-in, abstract base class, or '__main__' module.
+            If the instance belongs to a disallowed module ('builtins', 'abc') or originates from '__main__'.
+
+        Notes
+        -----
+        This method performs the following checks:
+            1. Ensures the input is an object instance (not a class/type).
+            2. Disallows instances of types defined in the 'builtins' or 'abc' modules.
+            3. Disallows instances originating from the '__main__' module, requiring importable module origins.
         """
+
+        # Ensure the provided instance is a valid object instance
         if not (isinstance(instance, object) and not isinstance(instance, type)):
             raise ReflectionTypeError(
                 f"Expected an object instance, got {type(instance).__name__!r}: {instance!r}"
             )
+
+        # Check if the instance belongs to a built-in or abstract base class
         module = type(instance).__module__
         if module in {'builtins', 'abc'}:
             raise ReflectionValueError(
                 f"Instance of type '{type(instance).__name__}' belongs to disallowed module '{module}'."
             )
+
+        # Check if the instance originates from '__main__'
         if module == '__main__':
             raise ReflectionValueError(
                 "Instance originates from '__main__'; please provide an instance from an importable module."
             )
+
+        # If all checks pass, return True
+        return True
+
+    def __init__(self, instance: Any) -> None:
+        """
+        Initialize the ReflectionInstance with a given object instance.
+
+        Parameters
+        ----------
+        instance : Any
+            The object instance to be reflected upon.
+
+        Raises
+        ------
+        ReflectionTypeError
+            If the provided instance is not a valid object instance.
+        ReflectionValueError
+            If the instance belongs to a built-in, abstract base class, or '__main__' module.
+        """
+
+        # Ensure the instance is valid
+        ReflectionInstance.ensureIsInstance(instance)
+
+        # Store the instance for reflection
         self._instance = instance
 
     def getInstance(self) -> Any:

orionis/services/introspection/reflection.py

@@ -1,3 +1,4 @@
+import inspect
 from typing import Any, Type
 from orionis.services.introspection.abstract.reflection_abstract import ReflectionAbstract
 from orionis.services.introspection.concretes.reflection_concrete import ReflectionConcrete
@@ -11,80 +12,429 @@ class Reflection:
     This class offers factory methods to obtain specialized reflection objects for instances,
     abstract classes, concrete classes, and modules. Each method returns an object that
     encapsulates the target and provides introspection capabilities.
-
-    Methods
-    -------
-    instance(instance: Any) -> ReflectionInstance
-        Create a reflection object for a class instance.
-    abstract(abstract: Type) -> ReflectionAbstract
-        Create a reflection object for an abstract class.
-    concrete(concrete: Type) -> ReflectionConcrete
-        Create a reflection object for a concrete class.
-    module(module: str) -> ReflectionModule
-        Create a reflection object for a module.
     """
 
     @staticmethod
     def instance(instance: Any) -> 'ReflectionInstance':
         """
-        Create a reflection object for a class instance.
+        Create a ReflectionInstance for the given object instance.
 
         Parameters
         ----------
         instance : Any
-            The instance to reflect upon.
+            The object instance to reflect.
 
         Returns
         -------
         ReflectionInstance
-            A reflection object encapsulating the instance.
+            A reflection object for the given instance.
         """
         return ReflectionInstance(instance)
 
     @staticmethod
     def abstract(abstract: Type) -> 'ReflectionAbstract':
-        """Create a reflection object for an abstract class.
+        """
+        Create a ReflectionAbstract for the given abstract class.
 
         Parameters
         ----------
         abstract : Type
-            The abstract class to reflect upon
+            The abstract class to reflect.
 
         Returns
         -------
         ReflectionAbstract
-            A reflection object encapsulating the abstract class
+            A reflection object for the given abstract class.
         """
         return ReflectionAbstract(abstract)
 
     @staticmethod
     def concrete(concrete: Type) -> 'ReflectionConcrete':
-        """Create a reflection object for a concrete class.
+        """
+        Create a ReflectionConcrete for the given concrete class.
 
         Parameters
         ----------
         concrete : Type
-            The concrete class to reflect upon
+            The concrete class to reflect.
 
         Returns
         -------
         ReflectionConcrete
-            A reflection object encapsulating the concrete class
+            A reflection object for the given concrete class.
         """
         return ReflectionConcrete(concrete)
 
     @staticmethod
     def module(module: str) -> 'ReflectionModule':
-        """Create a reflection object for a module.
+        """
+        Create a ReflectionModule for the given module name.
 
         Parameters
         ----------
         module : str
-            The module name to reflect upon
+            The name of the module to reflect.
 
         Returns
         -------
         ReflectionModule
-            A reflection object encapsulating the module
+            A reflection object for the given module.
         """
         return ReflectionModule(module)
+
+    @staticmethod
+    def isAbstract(obj: Any) -> bool:
+        """
+        Check if the object is an abstract base class.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is abstract, False otherwise.
+        """
+        return inspect.isabstract(obj)
+
+    @staticmethod
+    def isAsyncGen(obj: Any) -> bool:
+        """
+        Check if the object is an asynchronous generator.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is an async generator, False otherwise.
+        """
+        return inspect.isasyncgen(obj)
+
+    @staticmethod
+    def isAsyncGenFunction(obj: Any) -> bool:
+        """
+        Check if the object is an asynchronous generator function.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is an async generator function, False otherwise.
+        """
+        return inspect.isasyncgenfunction(obj)
+
+    @staticmethod
+    def isAwaitable(obj: Any) -> bool:
+        """
+        Check if the object can be awaited.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is awaitable, False otherwise.
+        """
+        return inspect.isawaitable(obj)
+
+    @staticmethod
+    def isBuiltin(obj: Any) -> bool:
+        """
+        Check if the object is a built-in function or method.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a built-in, False otherwise.
+        """
+        return inspect.isbuiltin(obj)
+
+    @staticmethod
+    def isClass(obj: Any) -> bool:
+        """
+        Check if the object is a class.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a class, False otherwise.
+        """
+        return inspect.isclass(obj)
+
+    @staticmethod
+    def isCode(obj: Any) -> bool:
+        """
+        Check if the object is a code object.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a code object, False otherwise.
+        """
+        return inspect.iscode(obj)
+
+    @staticmethod
+    def isCoroutine(obj: Any) -> bool:
+        """
+        Check if the object is a coroutine.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a coroutine, False otherwise.
+        """
+        return inspect.iscoroutine(obj)
+
+    @staticmethod
+    def isCoroutineFunction(obj: Any) -> bool:
+        """
+        Check if the object is a coroutine function.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a coroutine function, False otherwise.
+        """
+        return inspect.iscoroutinefunction(obj)
+
+    @staticmethod
+    def isDataDescriptor(obj: Any) -> bool:
+        """
+        Check if the object is a data descriptor.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a data descriptor, False otherwise.
+        """
+        return inspect.isdatadescriptor(obj)
+
+    @staticmethod
+    def isFrame(obj: Any) -> bool:
+        """
+        Check if the object is a frame object.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a frame object, False otherwise.
+        """
+        return inspect.isframe(obj)
+
+    @staticmethod
+    def isFunction(obj: Any) -> bool:
+        """
+        Check if the object is a Python function.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a function, False otherwise.
+        """
+        return inspect.isfunction(obj)
+
+    @staticmethod
+    def isGenerator(obj: Any) -> bool:
+        """
+        Check if the object is a generator.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a generator, False otherwise.
+        """
+        return inspect.isgenerator(obj)
+
+    @staticmethod
+    def isGeneratorFunction(obj: Any) -> bool:
+        """
+        Check if the object is a generator function.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a generator function, False otherwise.
+        """
+        return inspect.isgeneratorfunction(obj)
+
+    @staticmethod
+    def isGetSetDescriptor(obj: Any) -> bool:
+        """
+        Check if the object is a getset descriptor.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a getset descriptor, False otherwise.
+        """
+        return inspect.isgetsetdescriptor(obj)
+
+    @staticmethod
+    def isMemberDescriptor(obj: Any) -> bool:
+        """
+        Check if the object is a member descriptor.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a member descriptor, False otherwise.
+        """
+        return inspect.ismemberdescriptor(obj)
+
+    @staticmethod
+    def isMethod(obj: Any) -> bool:
+        """
+        Check if the object is a method.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a method, False otherwise.
+        """
+        return inspect.ismethod(obj)
+
+    @staticmethod
+    def isMethodDescriptor(obj: Any) -> bool:
+        """
+        Check if the object is a method descriptor.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a method descriptor, False otherwise.
+        """
+        return inspect.ismethoddescriptor(obj)
+
+    @staticmethod
+    def isModule(obj: Any) -> bool:
+        """
+        Check if the object is a module.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a module, False otherwise.
+        """
+        return inspect.ismodule(obj)
+
+    @staticmethod
+    def isRoutine(obj: Any) -> bool:
+        """
+        Check if the object is a user-defined or built-in function or method.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a routine, False otherwise.
+        """
+        return inspect.isroutine(obj)
+
+    @staticmethod
+    def isTraceback(obj: Any) -> bool:
+        """
+        Check if the object is a traceback object.
+
+        Parameters
+        ----------
+        obj : Any
+            The object to check.
+
+        Returns
+        -------
+        bool
+            True if the object is a traceback object, False otherwise.
+        """
+        return inspect.istraceback(obj)