orionis 0.436.0__py3-none-any.whl → 0.438.0__py3-none-any.whl

orionis/services/introspection/abstract/contracts/reflection.py

@@ -5,134 +5,145 @@ from orionis.services.introspection.dependencies.entities.class_dependencies imp
 from orionis.services.introspection.dependencies.entities.method_dependencies import MethodDependency
 
 class IReflectionAbstract(ABC):
+    """
+    Abstract base class for reflection operations on Python classes.
+
+    This interface defines the contract for introspecting and manipulating
+    class attributes, methods, properties, and dependencies through reflection.
+    Provides comprehensive functionality for examining class structure,
+    metadata, and behavior at runtime.
+    """
 
     @abstractmethod
     def getClass(self) -> Type:
         """
-        Returns the class type that this reflection concrete is based on.
+        Get the class type that this reflection instance is based on.
 
         Returns
         -------
         Type
-            The class type provided during initialization.
+            The class type provided during reflection initialization.
         """
         pass
 
     @abstractmethod
     def getClassName(self) -> str:
         """
-        Returns the name of the class type.
+        Get the name of the reflected class.
 
         Returns
         -------
         str
-            The name of the class type.
+            The simple name of the class without module qualification.
         """
         pass
 
     @abstractmethod
     def getModuleName(self) -> str:
         """
-        Returns the name of the module where the class is defined.
+        Get the name of the module where the reflected class is defined.
 
         Returns
         -------
         str
-            The name of the module.
+            The fully qualified module name where the class is defined.
         """
         pass
 
     @abstractmethod
     def getModuleWithClassName(self) -> str:
         """
-        Returns the module name concatenated with the class name.
+        Get the fully qualified class name including module path.
 
         Returns
         -------
         str
-            The module name followed by the class name.
+            The module name concatenated with the class name in the format 'module.ClassName'.
         """
         pass
 
     @abstractmethod
     def getDocstring(self) -> str:
         """
-        Returns the docstring of the class.
+        Get the docstring of the reflected class.
 
         Returns
         -------
         str or None
-            The docstring of the class, or None if not defined.
+            The class docstring if present, None if no docstring is defined.
         """
         pass
 
     @abstractmethod
     def getBaseClasses(self) -> list:
         """
-        Returns a list of base classes of the reflected class.
+        Get all base classes of the reflected class.
 
         Returns
         -------
         list
-            A list of base classes.
+            A list of base class types that the reflected class inherits from.
         """
         pass
 
     @abstractmethod
     def getSourceCode(self) -> str:
         """
-        Returns the source code of the class.
+        Get the source code of the reflected class.
 
         Returns
         -------
         str
-            The source code of the class.
+            The complete source code of the class as a string.
 
         Raises
         ------
         ReflectionValueError
-            If the source code cannot be retrieved.
+            If the source code cannot be retrieved (e.g., built-in classes, 
+            dynamically created classes, or unavailable source files).
         """
         pass
 
     @abstractmethod
     def getFile(self) -> str:
         """
-        Returns the file path where the class is defined.
+        Get the file path where the reflected class is defined.
 
         Returns
         -------
         str
-            The file path of the class definition.
+            The absolute file path of the class definition.
 
         Raises
         ------
         ReflectionValueError
-            If the file path cannot be retrieved.
+            If the file path cannot be retrieved (e.g., built-in classes 
+            or dynamically created classes).
         """
         pass
 
     @abstractmethod
     def getAnnotations(self) -> dict:
         """
-        Returns the type annotations of the class.
+        Get the type annotations of the reflected class.
 
         Returns
         -------
         dict
-            A dictionary of type annotations.
+            A dictionary mapping attribute names to their type annotations.
+            Returns empty dict if no annotations are present.
         """
         pass
 
     @abstractmethod
     def hasAttribute(self, attribute: str) -> bool:
         """
-        Checks if the class has a specific attribute.
+        Check if the reflected class has a specific attribute.
 
         Parameters
         ----------
         attribute : str
-            The name of the attribute to check.
+            The name of the attribute to check for existence.
 
         Returns
         -------
@@ -144,7 +155,7 @@ class IReflectionAbstract(ABC):
     @abstractmethod
     def getAttribute(self, attribute: str):
         """
-        Returns the value of a specific class attribute.
+        Get the value of a specific class attribute.
 
         Parameters
         ----------
@@ -166,32 +177,42 @@ class IReflectionAbstract(ABC):
     @abstractmethod
     def setAttribute(self, name: str, value) -> bool:
         """
-        Set an attribute value.
+        Set the value of a class attribute.
 
         Parameters
         ----------
         name : str
-            The attribute name
+            The name of the attribute to set.
         value : Any
-            The value to set
+            The value to assign to the attribute.
+
+        Returns
+        -------
+        bool
+            True if the attribute was successfully set.
 
         Raises
         ------
         ReflectionValueError
-            If the attribute is read-only or invalid
+            If the attribute is read-only or the operation is invalid.
         """
         pass
 
     @abstractmethod
     def removeAttribute(self, name: str) -> bool:
         """
-        Remove an attribute from the class.
+        Remove an attribute from the reflected class.
 
         Parameters
         ----------
         name : str
             The name of the attribute to remove.
 
+        Returns
+        -------
+        bool
+            True if the attribute was successfully removed.
+
         Raises
         ------
         ReflectionValueError
@@ -202,137 +223,122 @@ class IReflectionAbstract(ABC):
     @abstractmethod
     def getAttributes(self) -> dict:
         """
-        Returns a dictionary of all class attributes (not instance attributes).
-
-        Parameters
-        ----------
-        None
+        Get all non-callable class attributes.
 
         Returns
         -------
         dict
-            A dictionary where keys are the names of class attributes and values are their corresponding values.
-            Only attributes that are not callable, not static/class methods, not properties, and do not start with
-            underscores (including dunder, protected, or private) are included.
+            A dictionary mapping attribute names to their values. Includes only 
+            class attributes that are not callable, not static/class methods, 
+            not properties, and do not start with underscores.
         """
         pass
 
     @abstractmethod
     def getPublicAttributes(self) -> dict:
         """
-        Returns a dictionary of public class attributes (not instance attributes).
-
-        Parameters
-        ----------
-        None
+        Get all public class attributes.
 
         Returns
         -------
         dict
-            A dictionary where keys are the names of public class attributes and values are their corresponding values.
-            Only attributes that are not callable, not static/class methods, not properties, and do not start with
-            underscores (including dunder, protected, or private) are included.
+            A dictionary mapping public attribute names to their values. 
+            Includes only class attributes that are not callable, not 
+            static/class methods, not properties, and do not start with underscores.
         """
         pass
 
     @abstractmethod
     def getProtectedAttributes(self) -> dict:
         """
-        Returns a dictionary of protected class attributes (not instance attributes).
-
-        Parameters
-        ----------
-        None
+        Get all protected class attributes.
 
         Returns
         -------
         dict
-            A dictionary where keys are the names of protected class attributes and values are their corresponding values.
-            Only attributes that are not callable, not static/class methods, not properties, and start with a single underscore
-            (indicating protected visibility) are included.
+            A dictionary mapping protected attribute names to their values.
+            Includes only class attributes that are not callable, not 
+            static/class methods, not properties, and start with a single 
+            underscore (indicating protected visibility).
         """
         pass
 
     @abstractmethod
     def getPrivateAttributes(self) -> dict:
         """
-        Returns a dictionary of private class attributes (not instance attributes).
-
-        Parameters
-        ----------
-        None
+        Get all private class attributes.
 
         Returns
         -------
         dict
-            A dictionary where keys are the names of private class attributes and values are their corresponding values.
-            Only attributes that are not callable, not static/class methods, not properties, and start with double underscores
-            (indicating private visibility) are included.
+            A dictionary mapping private attribute names to their values.
+            Includes only class attributes that are not callable, not 
+            static/class methods, not properties, and start with double 
+            underscores (indicating private visibility).
         """
         pass
 
     @abstractmethod
     def getDunderAttributes(self) -> dict:
         """
-        Returns a dictionary of dunder (double underscore) class attributes (not instance attributes).
-
-        Parameters
-        ----------
-        None
+        Get all dunder (double underscore) class attributes.
 
         Returns
         -------
         dict
-            A dictionary where keys are the names of dunder class attributes and values are their corresponding values.
-            Only attributes that are not callable, not static/class methods, not properties, and start with double underscores
-            (indicating dunder visibility) are included.
+            A dictionary mapping dunder attribute names to their values.
+            Includes only class attributes that are not callable, not 
+            static/class methods, not properties, and follow the dunder 
+            naming pattern (__attribute__).
         """
         pass
 
     @abstractmethod
     def getMagicAttributes(self) -> dict:
         """
-        Returns a dictionary of magic (dunder) class attributes (not instance attributes).
-
-        Parameters
-        ----------
-        None
+        Get all magic (dunder) class attributes.
 
         Returns
         -------
         dict
-            A dictionary where keys are the names of magic class attributes and values are their corresponding values.
-            Only attributes that are not callable, not static/class methods, not properties, and start with double underscores
-            (indicating magic visibility) are included.
+            A dictionary mapping magic attribute names to their values.
+            Includes only class attributes that are not callable, not 
+            static/class methods, not properties, and follow the magic 
+            method naming pattern (__attribute__).
         """
         pass
 
     @abstractmethod
     def hasMethod(self, name: str) -> bool:
         """
-        Check if the instance has a specific method.
+        Check if the reflected class has a specific method.
 
         Parameters
         ----------
         name : str
-            The method name to check
+            The name of the method to check for existence.
 
         Returns
         -------
         bool
-            True if the method exists, False otherwise
+            True if the method exists, False otherwise.
         """
         pass
 
     @abstractmethod
     def removeMethod(self, name: str) -> bool:
         """
-        Remove a method from the class.
+        Remove a method from the reflected class.
 
         Parameters
         ----------
         name : str
-            The method name to remove
+            The name of the method to remove.
+
+        Returns
+        -------
+        bool
+            True if the method was successfully removed.
 
         Raises
         ------
@@ -344,17 +350,17 @@ class IReflectionAbstract(ABC):
     @abstractmethod
     def getMethodSignature(self, name: str) -> inspect.Signature:
         """
-        Get the signature of a method.
+        Get the signature of a specific method.
 
         Parameters
         ----------
         name : str
-            The method name to get the signature for
+            The name of the method to get the signature for.
 
         Returns
         -------
-        str
-            The signature of the method
+        inspect.Signature
+            The signature object containing parameter information for the method.
 
         Raises
         ------
@@ -366,469 +372,425 @@ class IReflectionAbstract(ABC):
     @abstractmethod
     def getMethods(self) -> List[str]:
         """
-        Get all method names of the instance.
+        Get all method names of the reflected class.
 
         Returns
         -------
         List[str]
-            List of method names
+            A list containing the names of all methods in the class.
         """
         pass
 
     @abstractmethod
     def getPublicMethods(self) -> list:
         """
-        Returns a list of public class methods (not instance methods).
-
-        Parameters
-        ----------
-        None
+        Get all public method names of the reflected class.
 
         Returns
         -------
-        dict
-            A list where each element is the name of a public class method.
+        list
+            A list containing the names of all public methods (not starting with underscore).
         """
         pass
 
     @abstractmethod
     def getPublicSyncMethods(self) -> list:
         """
-        Get all public synchronous method names of the class.
+        Get all public synchronous method names of the reflected class.
 
         Returns
         -------
         list
-            List of public synchronous method names
+            A list containing the names of all public synchronous (non-async) methods.
         """
         pass
 
     @abstractmethod
     def getPublicAsyncMethods(self) -> list:
         """
-        Get all public asynchronous method names of the class.
+        Get all public asynchronous method names of the reflected class.
 
         Returns
         -------
         list
-            List of public asynchronous method names
+            A list containing the names of all public asynchronous methods.
         """
         pass
 
     @abstractmethod
     def getProtectedMethods(self) -> list:
         """
-        Returns a list of protected class methods (not instance methods).
-
-        Parameters
-        ----------
-        None
+        Get all protected method names of the reflected class.
 
         Returns
         -------
-        dict
-            A list where each element is the name of a protected class method.
+        list
+            A list containing the names of all protected methods (starting with single underscore).
         """
         pass
 
     @abstractmethod
     def getProtectedSyncMethods(self) -> list:
         """
-        Get all protected synchronous method names of the class.
+        Get all protected synchronous method names of the reflected class.
 
         Returns
         -------
         list
-            List of protected synchronous method names
+            A list containing the names of all protected synchronous methods.
         """
         pass
 
     @abstractmethod
     def getProtectedAsyncMethods(self) -> list:
         """
-        Get all protected asynchronous method names of the class.
+        Get all protected asynchronous method names of the reflected class.
 
         Returns
         -------
         list
-            List of protected asynchronous method names
+            A list containing the names of all protected asynchronous methods.
         """
         pass
 
     @abstractmethod
     def getPrivateMethods(self) -> list:
         """
-        Returns a list of private class methods (not instance methods).
-
-        Parameters
-        ----------
-        None
+        Get all private method names of the reflected class.
 
         Returns
         -------
         list
-            A list where each element is the name of a private class method.
+            A list containing the names of all private methods (starting with double underscore).
         """
         pass
 
     @abstractmethod
     def getPrivateSyncMethods(self) -> list:
         """
-        Get all private synchronous method names of the class.
+        Get all private synchronous method names of the reflected class.
 
         Returns
         -------
         list
-            List of private synchronous method names
+            A list containing the names of all private synchronous methods.
         """
         pass
 
     @abstractmethod
     def getPrivateAsyncMethods(self) -> list:
         """
-        Get all private asynchronous method names of the class.
+        Get all private asynchronous method names of the reflected class.
 
         Returns
         -------
         list
-            List of private asynchronous method names
+            A list containing the names of all private asynchronous methods.
         """
         pass
 
     @abstractmethod
     def getPublicClassMethods(self) -> list:
         """
-        Returns a list of public class methods (not instance methods).
-
-        Parameters
-        ----------
-        None
+        Get all public class method names of the reflected class.
 
         Returns
         -------
         list
-            A list where each element is the name of a public class method.
+            A list containing the names of all public class methods (decorated with @classmethod).
         """
         pass
 
     @abstractmethod
     def getPublicClassSyncMethods(self) -> list:
         """
-        Get all public synchronous class method names of the class.
+        Get all public synchronous class method names of the reflected class.
 
         Returns
         -------
         list
-            List of public synchronous class method names
+            A list containing the names of all public synchronous class methods.
         """
         pass
 
     @abstractmethod
     def getPublicClassAsyncMethods(self) -> list:
         """
-        Get all public asynchronous class method names of the class.
+        Get all public asynchronous class method names of the reflected class.
 
         Returns
         -------
         list
-            List of public asynchronous class method names
+            A list containing the names of all public asynchronous class methods.
         """
         pass
 
     @abstractmethod
     def getProtectedClassMethods(self) -> list:
         """
-        Returns a list of protected class methods (not instance methods).
-
-        Parameters
-        ----------
-        None
+        Get all protected class method names of the reflected class.
 
         Returns
         -------
         list
-            A list where each element is the name of a protected class method.
+            A list containing the names of all protected class methods (starting with single underscore).
         """
         pass
 
     @abstractmethod
     def getProtectedClassSyncMethods(self) -> list:
         """
-        Get all protected synchronous class method names of the class.
+        Get all protected synchronous class method names of the reflected class.
 
         Returns
         -------
         list
-            List of protected synchronous class method names
+            A list containing the names of all protected synchronous class methods.
         """
         pass
 
     @abstractmethod
     def getProtectedClassAsyncMethods(self) -> list:
         """
-        Get all protected asynchronous class method names of the class.
+        Get all protected asynchronous class method names of the reflected class.
 
         Returns
         -------
         list
-            List of protected asynchronous class method names
+            A list containing the names of all protected asynchronous class methods.
         """
         pass
 
     @abstractmethod
     def getPrivateClassMethods(self) -> list:
         """
-        Returns a list of private class methods (not instance methods).
-
-        Parameters
-        ----------
-        None
+        Get all private class method names of the reflected class.
 
         Returns
         -------
         list
-            A list where each element is the name of a private class method.
+            A list containing the names of all private class methods (starting with double underscore).
         """
         pass
 
     @abstractmethod
     def getPrivateClassSyncMethods(self) -> list:
         """
-        Get all private synchronous class method names of the class.
+        Get all private synchronous class method names of the reflected class.
 
         Returns
         -------
         list
-            List of private synchronous class method names
+            A list containing the names of all private synchronous class methods.
         """
         pass
 
     @abstractmethod
     def getPrivateClassAsyncMethods(self) -> list:
         """
-        Get all private asynchronous class method names of the class.
+        Get all private asynchronous class method names of the reflected class.
 
         Returns
         -------
         list
-            List of private asynchronous class method names
+            A list containing the names of all private asynchronous class methods.
         """
         pass
 
     @abstractmethod
     def getPublicStaticMethods(self) -> list:
         """
-        Returns a list of public static methods of the class.
-
-        Parameters
-        ----------
-        None
+        Get all public static method names of the reflected class.
 
         Returns
         -------
         list
-            A list where each element is the name of a public static method.
+            A list containing the names of all public static methods (decorated with @staticmethod).
         """
         pass
 
     @abstractmethod
     def getPublicStaticSyncMethods(self) -> list:
         """
-        Get all public synchronous static method names of the class.
+        Get all public synchronous static method names of the reflected class.
 
         Returns
         -------
         list
-            List of public synchronous static method names
+            A list containing the names of all public synchronous static methods.
         """
         pass
 
     @abstractmethod
     def getPublicStaticAsyncMethods(self) -> list:
         """
-        Get all public asynchronous static method names of the class.
+        Get all public asynchronous static method names of the reflected class.
 
         Returns
         -------
         list
-            List of public asynchronous static method names
+            A list containing the names of all public asynchronous static methods.
         """
         pass
 
     @abstractmethod
     def getProtectedStaticMethods(self) -> list:
         """
-        Returns a list of protected static methods of the class.
-
-        Parameters
-        ----------
-        None
+        Get all protected static method names of the reflected class.
 
         Returns
         -------
         list
-            A list where each element is the name of a protected static method.
+            A list containing the names of all protected static methods (starting with single underscore).
         """
         pass
 
     @abstractmethod
     def getProtectedStaticSyncMethods(self) -> list:
         """
-        Get all protected synchronous static method names of the class.
+        Get all protected synchronous static method names of the reflected class.
 
         Returns
         -------
         list
-            List of protected synchronous static method names
+            A list containing the names of all protected synchronous static methods.
         """
         pass
 
     @abstractmethod
     def getProtectedStaticAsyncMethods(self) -> list:
         """
-        Get all protected asynchronous static method names of the class.
+        Get all protected asynchronous static method names of the reflected class.
 
         Returns
         -------
         list
-            List of protected asynchronous static method names
+            A list containing the names of all protected asynchronous static methods.
         """
         pass
 
     @abstractmethod
     def getPrivateStaticMethods(self) -> list:
         """
-        Returns a list of private static methods of the class.
-
-        Parameters
-        ----------
-        None
+        Get all private static method names of the reflected class.
 
         Returns
         -------
         list
-            A list where each element is the name of a private static method.
+            A list containing the names of all private static methods (starting with double underscore).
         """
         pass
 
     @abstractmethod
     def getPrivateStaticSyncMethods(self) -> list:
         """
-        Get all private synchronous static method names of the class.
+        Get all private synchronous static method names of the reflected class.
 
         Returns
         -------
         list
-            List of private synchronous static method names
+            A list containing the names of all private synchronous static methods.
         """
         pass
 
     @abstractmethod
     def getPrivateStaticAsyncMethods(self) -> list:
         """
-        Get all private asynchronous static method names of the class.
+        Get all private asynchronous static method names of the reflected class.
 
         Returns
         -------
         list
-            List of private asynchronous static method names
+            A list containing the names of all private asynchronous static methods.
         """
         pass
 
     @abstractmethod
     def getDunderMethods(self) -> list:
         """
-        Returns a list of dunder (double underscore) methods of the class.
-
-        Parameters
-        ----------
-        None
+        Get all dunder (double underscore) method names of the reflected class.
 
         Returns
         -------
         list
-            A list where each element is the name of a dunder method.
+            A list containing the names of all dunder methods following the __method__ pattern.
         """
         pass
 
     @abstractmethod
     def getMagicMethods(self) -> list:
         """
-        Returns a list of magic (dunder) methods of the class.
-
-        Parameters
-        ----------
-        None
+        Get all magic (dunder) method names of the reflected class.
 
         Returns
         -------
         list
-            A list where each element is the name of a magic method.
+            A list containing the names of all magic methods following the __method__ pattern.
         """
         pass
 
     @abstractmethod
-    def getProperties(self) -> List:
+    def getProperties(self) -> List[str]:
         """
-        Get all properties of the instance.
+        Get all property names of the reflected class.
 
         Returns
         -------
         List[str]
-            List of property names
+            A list containing the names of all properties defined in the class.
         """
         pass
 
     @abstractmethod
-    def getPublicProperties(self) -> List:
+    def getPublicProperties(self) -> List[str]:
         """
-        Get all public properties of the instance.
+        Get all public property names of the reflected class.
 
         Returns
         -------
-        List:
-            List of public property names and their values
+        List[str]
+            A list containing the names of all public properties (not starting with underscore).
         """
         pass
 
     @abstractmethod
-    def getProtectedProperties(self) -> List:
+    def getProtectedProperties(self) -> List[str]:
         """
-        Get all protected properties of the instance.
+        Get all protected property names of the reflected class.
 
         Returns
         -------
-        List
-            List of protected property names and their values
+        List[str]
+            A list containing the names of all protected properties (starting with single underscore).
         """
         pass
 
     @abstractmethod
-    def getPrivateProperties(self) -> List:
+    def getPrivateProperties(self) -> List[str]:
         """
-        Get all private properties of the instance.
+        Get all private property names of the reflected class.
 
         Returns
         -------
-        List
-            List of private property names and their values
+        List[str]
+            A list containing the names of all private properties (starting with double underscore).
         """
         pass
 
     @abstractmethod
     def getPropertySignature(self, name: str) -> inspect.Signature:
         """
-        Get the signature of a property.
+        Get the signature of a specific property.
 
         Parameters
         ----------
         name : str
-            The property name to get the signature for
+            The name of the property to get the signature for.
 
         Returns
         -------
         inspect.Signature
-            The signature of the property
+            The signature object containing parameter information for the property.
 
         Raises
         ------
@@ -840,17 +802,17 @@ class IReflectionAbstract(ABC):
     @abstractmethod
     def getPropertyDocstring(self, name: str) -> str:
         """
-        Get the docstring of a property.
+        Get the docstring of a specific property.
 
         Parameters
         ----------
         name : str
-            The property name to get the docstring for
+            The name of the property to get the docstring for.
 
         Returns
         -------
         str
-            The docstring of the property
+            The docstring of the specified property if present, None if no docstring is defined.
 
         Raises
         ------
@@ -862,32 +824,37 @@ class IReflectionAbstract(ABC):
     @abstractmethod
     def getConstructorDependencies(self) -> ClassDependency:
         """
-        Get the resolved and unresolved dependencies from the constructor of the instance's class.
+        Get the resolved and unresolved dependencies from the constructor of the reflected class.
 
         Returns
         -------
         ClassDependency
-            A structured representation of the constructor dependencies, containing:
-            - resolved: Dictionary of resolved dependencies with their names and values.
-            - unresolved: List of unresolved dependencies (parameter names without default values or annotations).
+            A structured representation of the constructor dependencies containing:
+            - resolved: Dictionary of resolved dependencies with their names and values
+            - unresolved: List of unresolved dependencies (parameter names without default values or annotations)
         """
         pass
 
     @abstractmethod
     def getMethodDependencies(self, method_name: str) -> MethodDependency:
         """
-        Get the resolved and unresolved dependencies from a method of the instance's class.
+        Get the resolved and unresolved dependencies from a specific method of the reflected class.
 
         Parameters
         ----------
         method_name : str
-            The name of the method to inspect
+            The name of the method to inspect for dependencies.
 
         Returns
         -------
         MethodDependency
-            A structured representation of the method dependencies, containing:
-            - resolved: Dictionary of resolved dependencies with their names and values.
-            - unresolved: List of unresolved dependencies (parameter names without default values or annotations).
+            A structured representation of the method dependencies containing:
+            - resolved: Dictionary of resolved dependencies with their names and values
+            - unresolved: List of unresolved dependencies (parameter names without default values or annotations)
+
+        Raises
+        ------
+        ReflectionValueError
+            If the method does not exist or is not accessible.
         """
         pass