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

orionis/services/introspection/concretes/reflection.py

@@ -3,7 +3,7 @@ import inspect
 import keyword
 from typing import Any, Callable, List, Type
 from orionis.services.asynchrony.coroutines import Coroutine
-from orionis.services.introspection.concretes.contracts.concrete import IReflectionConcrete
+from orionis.services.introspection.concretes.contracts.reflection import IReflectionConcrete
 from orionis.services.introspection.dependencies.entities.class_dependencies import ClassDependency
 from orionis.services.introspection.dependencies.entities.method_dependencies import MethodDependency
 from orionis.services.introspection.dependencies.reflection import ReflectDependencies
@@ -15,21 +15,29 @@ from orionis.services.introspection.exceptions import (
 from orionis.services.introspection.instances.reflection import ReflectionInstance
 
 class ReflectionConcrete(IReflectionConcrete):
+    """
+    A concrete implementation for reflecting on class types and their members.
+
+    This class provides comprehensive introspection capabilities for analyzing class
+    structures, attributes, methods, properties, and dependencies. It supports
+    dynamic manipulation of class members while maintaining type safety and
+    validation.
+    """
 
     @staticmethod
     def isConcreteClass(concrete: Type) -> bool:
         """
-        Checks if the provided concrete type is a valid ReflectionConcrete type.
+        Check if the provided type is a valid concrete class for reflection.
 
         Parameters
         ----------
         concrete : Type
-            The class type to be validated.
+            The class type to validate for reflection compatibility.
 
         Returns
         -------
         bool
-            True if the class is a valid ReflectionConcrete type, False otherwise.
+            True if the class is valid for reflection, False otherwise.
         """
         try:
             return ReflectionConcrete.ensureIsConcreteClass(concrete)
@@ -39,20 +47,30 @@ class ReflectionConcrete(IReflectionConcrete):
     @staticmethod
     def ensureIsConcreteClass(concrete: Type) -> bool:
         """
-        Ensures that the provided concrete type is a valid ReflectionConcrete type.
+        Validate that the provided type is a concrete class suitable for reflection.
+
+        This method performs comprehensive validation to ensure the type can be
+        safely used for reflection operations. It checks for proper class type,
+        excludes built-in types, and prevents abstract classes.
 
         Parameters
         ----------
         concrete : Type
-            The class type to be validated.
+            The class type to validate.
+
+        Returns
+        -------
+        bool
+            True if validation passes.
 
         Raises
         ------
         ReflectionTypeError
-            If the provided argument is not a class type or is already an instance.
+            If the argument is not a class type or is an instance.
         ReflectionValueError
-            If the provided class is a built-in/primitive type, abstract class, or interface.
+            If the class is built-in, primitive, abstract, or an interface.
         """
+
         # Check if the concrete is a class type
         if not isinstance(concrete, type):
             raise ReflectionTypeError(f"Expected a class, got {type(concrete)}")
@@ -83,24 +101,27 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def __init__(self, concrete: Type) -> None:
         """
-        Initialize the ReflectionConcrete with the provided class type.
+        Initialize the reflection concrete with a validated class type.
+
+        Performs validation on the provided class type and initializes the
+        reflection instance with the concrete class for subsequent operations.
 
         Parameters
         ----------
         concrete : Type
-            The class type to be reflected upon.
+            The class type to reflect upon.
 
         Raises
         ------
         ReflectionTypeError
-            If the provided argument is not a class type or is already an instance.
+            If the argument is not a class type or is an instance.
         ReflectionValueError
-            If the provided class is a built-in/primitive type, abstract class, or interface.
+            If the class is built-in, primitive, abstract, or an 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.
+        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
@@ -112,7 +133,11 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getInstance(self, *args, **kwargs):
         """
-        Returns an instance of the reflected class.
+        Create and return an instance of the reflected class.
+
+        Instantiates the reflected class using the provided arguments and
+        performs validation to ensure the instance is compatible with
+        reflection operations.
 
         Parameters
         ----------
@@ -124,13 +149,14 @@ class ReflectionConcrete(IReflectionConcrete):
         Returns
         -------
         object
-            An instance of the class type provided during initialization.
+            An instance of the reflected class.
 
         Raises
         ------
         ReflectionValueError
-            If instantiation fails or if the class defines an asynchronous __str__ method.
+            If instantiation fails or the class has an asynchronous __str__ method.
         """
+
         try:
 
             # Try to instantiate the class
@@ -156,7 +182,7 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getClass(self) -> Type:
         """
-        Returns the class type that this reflection concrete is based on.
+        Get the class type being reflected upon.
 
         Returns
         -------
@@ -167,72 +193,72 @@ class ReflectionConcrete(IReflectionConcrete):
 
     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.
         """
         return self._concrete.__name__
 
     def getModuleName(self) -> str:
         """
-        Returns the name of the module where the class is defined.
+        Get the module name where the reflected class is defined.
 
         Returns
         -------
         str
-            The name of the module.
+            The fully qualified module name containing the class.
         """
         return self._concrete.__module__
 
     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, separated by a dot.
         """
         return f"{self.getModuleName()}.{self.getClassName()}"
 
     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 defined, None otherwise.
         """
         return self._concrete.__doc__ if self._concrete.__doc__ else None
 
     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 containing all base classes in the method resolution order.
         """
         return self._concrete.__bases__
 
     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 definition.
 
         Raises
         ------
         ReflectionValueError
-            If the source code cannot be retrieved.
+            If the source code cannot be retrieved (e.g., built-in classes).
         """
         try:
             return inspect.getsource(self._concrete)
@@ -241,17 +267,17 @@ class ReflectionConcrete(IReflectionConcrete):
 
     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 containing the class definition.
 
         Raises
         ------
         ReflectionValueError
-            If the file path cannot be retrieved.
+            If the file path cannot be determined (e.g., dynamically created classes).
         """
         try:
             return inspect.getfile(self._concrete)
@@ -260,37 +286,41 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getAnnotations(self) -> dict:
         """
-        Returns the type annotations of the class.
+        Get type annotations defined on the reflected class.
+
+        Processes and returns the type annotations with proper name mangling
+        resolution for private attributes.
 
         Returns
         -------
         dict
-            A dictionary of type annotations.
+            A dictionary mapping attribute names to their type annotations.
         """
         annotations = {}
         for k, v in getattr(self._concrete, '__annotations__', {}).items():
+            # Remove private attribute name mangling for cleaner output
             annotations[str(k).replace(f"_{self.getClassName()}", "")] = v
         return annotations
 
     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.
 
         Returns
         -------
         bool
-            True if the class has the specified attribute, False otherwise.
+            True if the attribute exists, False otherwise.
         """
         return attribute in self.getAttributes()
 
     def getAttribute(self, attribute: str):
         """
-        Returns the value of a specific class attribute.
+        Get the value of a specific class attribute.
 
         Parameters
         ----------
@@ -300,7 +330,7 @@ class ReflectionConcrete(IReflectionConcrete):
         Returns
         -------
         Any
-            The value of the specified class attribute.
+            The value of the specified attribute, or None if not found.
 
         Raises
         ------
@@ -312,19 +342,27 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def setAttribute(self, name: str, value) -> bool:
         """
-        Set an attribute value.
+        Set a class attribute to the specified value.
+
+        Validates the attribute name and value before setting. Handles private
+        attribute name mangling automatically.
 
         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 name is invalid or the value is callable.
         """
 
         # Ensure the name is a valid attr name with regular expression
@@ -347,18 +385,27 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def removeAttribute(self, name: str) -> bool:
         """
-        Remove an attribute from the class.
+        Remove an attribute from the reflected class.
+
+        Handles private attribute name mangling automatically before removal.
 
         Parameters
         ----------
         name : str
             The name of the attribute to remove.
 
+        Returns
+        -------
+        bool
+            True if the attribute was successfully removed.
+
         Raises
         ------
         ReflectionValueError
             If the attribute does not exist or cannot be removed.
         """
+
+        # Check if the attribute exists
         if not self.hasAttribute(name):
             raise ReflectionValueError(f"Attribute '{name}' does not exist in class '{self.getClassName()}'.")
 
@@ -367,25 +414,27 @@ class ReflectionConcrete(IReflectionConcrete):
             class_name = self.getClassName()
             name = f"_{class_name}{name}"
 
+        # Delete the attribute from the class itself
         delattr(self._concrete, name)
 
+        # Return True to indicate successful removal
         return True
 
     def getAttributes(self) -> dict:
         """
-        Returns a dictionary of all class attributes (not instance attributes).
+        Get all class attributes regardless of visibility.
 
-        Parameters
-        ----------
-        None
+        Combines public, protected, private, and dunder attributes into a
+        single dictionary for comprehensive attribute access.
 
         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, including
+            all visibility levels (public, protected, private, dunder).
         """
+
+        # Combine all attribute types into a single dictionary
         return {
             **self.getPublicAttributes(),
             **self.getProtectedAttributes(),
@@ -395,18 +444,16 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getPublicAttributes(self) -> dict:
         """
-        Returns a dictionary of public class attributes (not instance attributes).
+        Get all public class attributes.
 
-        Parameters
-        ----------
-        None
+        Retrieves class attributes that do not start with underscores,
+        excluding callables, static methods, class methods, and properties.
 
         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.
+            Excludes dunder, protected, and private attributes.
         """
         class_name = self.getClassName()
         attributes = self._concrete.__dict__
@@ -428,18 +475,16 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getProtectedAttributes(self) -> dict:
         """
-        Returns a dictionary of protected class attributes (not instance attributes).
+        Get all protected class attributes.
 
-        Parameters
-        ----------
-        None
+        Retrieves class attributes that start with a single underscore,
+        indicating protected visibility in Python convention.
 
         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 attributes starting with single underscore.
         """
         class_name = self.getClassName()
         attributes = self._concrete.__dict__
@@ -461,18 +506,16 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getPrivateAttributes(self) -> dict:
         """
-        Returns a dictionary of private class attributes (not instance attributes).
+        Get all private class attributes.
 
-        Parameters
-        ----------
-        None
+        Retrieves class attributes that use Python's name mangling convention
+        for private attributes (double underscore prefix).
 
         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 (with mangling removed)
+            to their values.
         """
         class_name = self.getClassName()
         attributes = self._concrete.__dict__
@@ -483,24 +526,23 @@ class ReflectionConcrete(IReflectionConcrete):
             if callable(value) or isinstance(value, staticmethod) or isinstance(value, classmethod) or isinstance(value, property):
                 continue
             if attr.startswith(f"_{class_name}"):
+                # Remove name mangling for cleaner output
                 private[str(attr).replace(f"_{class_name}", "")] = value
 
         return private
 
     def getDunderAttributes(self) -> dict:
         """
-        Returns a dictionary of dunder (double underscore) class attributes (not instance attributes).
+        Get all dunder (magic) class attributes.
 
-        Parameters
-        ----------
-        None
+        Retrieves class attributes that follow the double underscore naming
+        convention, excluding common built-in dunder 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.
+            Excludes standard Python dunder attributes like __class__, __dict__, etc.
         """
         attributes = self._concrete.__dict__
         dunder = {}
@@ -526,59 +568,59 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getMagicAttributes(self) -> dict:
         """
-        Returns a dictionary of magic (dunder) class attributes (not instance attributes).
+        Get all magic (dunder) class attributes.
 
-        Parameters
-        ----------
-        None
+        This is an alias for getDunderAttributes() providing alternative naming
+        for accessing double underscore 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.
         """
         return self.getDunderAttributes()
 
     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.
 
         Returns
         -------
         bool
-            True if the method exists, False otherwise
+            True if the method exists in the class, False otherwise.
         """
         return name in self.getMethods()
 
     def callMethod(self, name: str, *args, **kwargs):
         """
-        Call a method of the instance with the provided arguments.
+        Call a method on the class instance with provided arguments.
+
+        Requires that an instance has been created using getInstance().
+        Automatically handles asynchronous methods using the Coroutine wrapper.
 
         Parameters
         ----------
         name : str
-            The method name to call
+            The name of the method to call.
         *args : tuple
-            Positional arguments to pass to the method
+            Positional arguments to pass to the method.
         **kwargs : dict
-            Keyword arguments to pass to the method
+            Keyword arguments to pass to the method.
 
         Returns
         -------
         Any
-            The return value of the method call
+            The return value of the method call.
 
         Raises
         ------
         ReflectionValueError
-            If the method does not exist or is not callable.
+            If the method does not exist, instance is not initialized, or method call fails.
         """
         if not self.hasMethod(name):
             raise ReflectionValueError(f"Method '{name}' does not exist in class '{self.getClassName()}'.")
@@ -599,19 +641,27 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def setMethod(self, name: str, method: Callable) -> bool:
         """
-        Set a method on the class.
+        Add a new method to the reflected class.
+
+        Validates the method name and callable before adding it to the class.
+        Handles private method name mangling automatically.
 
         Parameters
         ----------
         name : str
-            The method name to set
-        method : callable
-            The method to set
+            The name for the new method.
+        method : Callable
+            The callable object to set as a method.
+
+        Returns
+        -------
+        bool
+            True if the method was successfully added.
 
         Raises
         ------
         ReflectionValueError
-            If the method is not callable or if the name is invalid.
+            If the method name already exists, is invalid, or the object is not callable.
         """
         # Check if the method already exists
         if name in self.getMethods():
@@ -637,12 +687,19 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def removeMethod(self, name: str) -> bool:
         """
-        Remove a method from the class.
+        Remove a method from the reflected class.
+
+        Handles private method name mangling automatically before removal.
 
         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
         ------
@@ -665,17 +722,17 @@ class ReflectionConcrete(IReflectionConcrete):
 
     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 inspect.
 
         Returns
         -------
-        str
-            The signature of the method
+        inspect.Signature
+            The signature object containing parameter and return information.
 
         Raises
         ------
@@ -696,12 +753,15 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getMethods(self) -> List[str]:
         """
-        Get all method names of the instance.
+        Get all method names from the reflected class.
+
+        Combines all types of methods including instance methods, class methods,
+        and static methods with different visibility levels.
 
         Returns
         -------
         List[str]
-            List of method names
+            A comprehensive list of all method names in the class.
         """
         return [
             *self.getPublicMethods(),
@@ -717,16 +777,15 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getPublicMethods(self) -> list:
         """
-        Returns a list of public class methods (not instance methods).
+        Get all public instance method names from the reflected class.
 
-        Parameters
-        ----------
-        None
+        Retrieves methods that are callable, not static or class methods,
+        not properties, and do not start with underscores.
 
         Returns
         -------
-        dict
-            A list where each element is the name of a public class method.
+        list
+            A list of public instance method names.
         """
         class_name = self.getClassName()
         attributes = self._concrete.__dict__
@@ -747,12 +806,14 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getPublicSyncMethods(self) -> list:
         """
-        Get all public synchronous method names of the class.
+        Get all public synchronous method names from the reflected class.
+
+        Filters public methods to include only those that are not coroutine functions.
 
         Returns
         -------
         list
-            List of public synchronous method names
+            A list of public synchronous method names.
         """
         methods = self.getPublicMethods()
         sync_methods = []
@@ -763,12 +824,14 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getPublicAsyncMethods(self) -> list:
         """
-        Get all public asynchronous method names of the class.
+        Get all public asynchronous method names from the reflected class.
+
+        Filters public methods to include only those that are coroutine functions.
 
         Returns
         -------
         list
-            List of public asynchronous method names
+            A list of public asynchronous method names.
         """
         methods = self.getPublicMethods()
         async_methods = []
@@ -779,16 +842,15 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getProtectedMethods(self) -> list:
         """
-        Returns a list of protected class methods (not instance methods).
+        Get all protected instance method names from the reflected class.
 
-        Parameters
-        ----------
-        None
+        Retrieves methods that start with a single underscore, indicating
+        protected visibility according to Python naming conventions.
 
         Returns
         -------
-        dict
-            A list where each element is the name of a protected class method.
+        list
+            A list of protected instance method names.
         """
         class_name = self.getClassName()
         attributes = self._concrete.__dict__
@@ -804,12 +866,14 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getProtectedSyncMethods(self) -> list:
         """
-        Get all protected synchronous method names of the class.
+        Get all protected synchronous method names from the reflected class.
+
+        Filters protected methods to include only those that are not coroutine functions.
 
         Returns
         -------
         list
-            List of protected synchronous method names
+            A list of protected synchronous method names.
         """
         methods = self.getProtectedMethods()
         sync_methods = []
@@ -820,12 +884,14 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getProtectedAsyncMethods(self) -> list:
         """
-        Get all protected asynchronous method names of the class.
+        Get all protected asynchronous method names from the reflected class.
+
+        Filters protected methods to include only those that are coroutine functions.
 
         Returns
         -------
         list
-            List of protected asynchronous method names
+            A list of protected asynchronous method names.
         """
         methods = self.getProtectedMethods()
         async_methods = []
@@ -836,16 +902,15 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getPrivateMethods(self) -> list:
         """
-        Returns a list of private class methods (not instance methods).
+        Get all private instance method names from the reflected class.
 
-        Parameters
-        ----------
-        None
+        Retrieves methods that use Python's name mangling convention
+        for private methods (class name prefix), with name mangling resolved.
 
         Returns
         -------
         list
-            A list where each element is the name of a private class method.
+            A list of private instance method names with mangling removed.
         """
         class_name = self.getClassName()
         attributes = self._concrete.__dict__
@@ -855,6 +920,7 @@ class ReflectionConcrete(IReflectionConcrete):
         for attr, value in attributes.items():
             if callable(value) and not isinstance(value, (staticmethod, classmethod)) and not isinstance(value, property):
                 if attr.startswith(f"_{class_name}"):
+                    # Remove name mangling for cleaner output
                     private_methods.append(str(attr).replace(f"_{class_name}", ""))
 
         return private_methods
@@ -1245,16 +1311,15 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getDunderMethods(self) -> list:
         """
-        Returns a list of dunder (double underscore) methods of the class.
+        Get all dunder (magic) method names from the reflected class.
 
-        Parameters
-        ----------
-        None
+        Retrieves methods that follow the double underscore naming convention,
+        excluding built-in Python methods and non-callable attributes.
 
         Returns
         -------
         list
-            A list where each element is the name of a dunder method.
+            A list of dunder method names available in the class.
         """
         attributes = self._concrete.__dict__
         dunder_methods = []
@@ -1270,44 +1335,49 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getMagicMethods(self) -> list:
         """
-        Returns a list of magic (dunder) methods of the class.
+        Get all magic (dunder) method names from the reflected class.
 
-        Parameters
-        ----------
-        None
+        This is an alias for getDunderMethods() providing alternative naming
+        for accessing double underscore methods.
 
         Returns
         -------
         list
-            A list where each element is the name of a magic method.
+            A list of magic method names available in the class.
         """
         return self.getDunderMethods()
 
     def getProperties(self) -> List:
         """
-        Get all properties of the instance.
+        Get all property names from the reflected class.
+
+        Scans the class dictionary for property objects and returns their names
+        with private attribute name mangling resolved.
 
         Returns
         -------
         List[str]
-            List of property names
+            A list of all property names in the class.
         """
-
         properties = []
         for name, prop in self._concrete.__dict__.items():
             if isinstance(prop, property):
+                # Remove private attribute name mangling for cleaner output
                 name_prop = name.replace(f"_{self.getClassName()}", "")
                 properties.append(name_prop)
         return properties
 
     def getPublicProperties(self) -> List:
         """
-        Get all public properties of the instance.
+        Get all public property names from the reflected class.
+
+        Retrieves properties that do not start with underscores, indicating
+        public visibility according to Python naming conventions.
 
         Returns
         -------
-        List:
-            List of public property names and their values
+        List[str]
+            A list of public property names with name mangling resolved.
         """
         properties = []
         cls_name = self.getClassName()
@@ -1319,12 +1389,15 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getProtectedProperties(self) -> List:
         """
-        Get all protected properties of the instance.
+        Get all protected property names from the reflected class.
+
+        Retrieves properties that start with a single underscore but are not
+        private (double underscore) attributes.
 
         Returns
         -------
-        List
-            List of protected property names and their values
+        List[str]
+            A list of protected property names.
         """
         properties = []
         for name, prop in self._concrete.__dict__.items():
@@ -1335,12 +1408,15 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getPrivateProperties(self) -> List:
         """
-        Get all private properties of the instance.
+        Get all private property names from the reflected class.
+
+        Retrieves properties that use Python's name mangling convention
+        for private attributes (class name prefix).
 
         Returns
         -------
-        List
-            List of private property names and their values
+        List[str]
+            A list of private property names with name mangling resolved.
         """
         properties = []
         for name, prop in self._concrete.__dict__.items():
@@ -1351,17 +1427,20 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getProperty(self, name: str) -> Any:
         """
-        Get a specific property of the instance.
+        Get the value of a specific property from the reflected class.
+
+        Handles private property name mangling and validates that the
+        requested attribute is actually a property object.
 
         Parameters
         ----------
         name : str
-            The name of the property to retrieve
+            The name of the property to retrieve.
 
         Returns
         -------
         Any
-            The value of the property
+            The current value of the property.
 
         Raises
         ------
@@ -1384,17 +1463,17 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getPropertySignature(self, name: str) -> inspect.Signature:
         """
-        Get the signature of a property.
+        Get the signature of a specific property's getter method.
 
         Parameters
         ----------
         name : str
-            The property name to get the signature for
+            The name of the property to inspect.
 
         Returns
         -------
         inspect.Signature
-            The signature of the property
+            The signature of the property's getter function.
 
         Raises
         ------
@@ -1417,17 +1496,17 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getPropertyDocstring(self, name: str) -> str:
         """
-        Get the docstring of a property.
+        Get the docstring of a specific property's getter method.
 
         Parameters
         ----------
         name : str
-            The property name to get the docstring for
+            The name of the property to inspect.
 
         Returns
         -------
-        str
-            The docstring of the property
+        str or None
+            The docstring of the property's getter function, or None if not defined.
 
         Raises
         ------
@@ -1450,45 +1529,55 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def getConstructorSignature(self) -> inspect.Signature:
         """
-        Get the signature of the constructor of the instance's class.
+        Get the signature of the class constructor.
 
         Returns
         -------
         inspect.Signature
-            The signature of the constructor
+            The signature of the __init__ method containing parameter information.
         """
         return inspect.signature(self._concrete.__init__)
 
     def getConstructorDependencies(self) -> ClassDependency:
         """
-        Get the resolved and unresolved dependencies from the constructor of the instance's class.
+        Get dependency analysis for the class constructor.
+
+        Analyzes the constructor parameters to identify resolved and unresolved
+        dependencies based on type annotations and default values.
 
         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 containing resolved dependencies
+            (with default values/annotations) and unresolved dependencies
+            (parameters without defaults or type information).
         """
         return ReflectDependencies(self._concrete).getConstructorDependencies()
 
     def getMethodDependencies(self, method_name: str) -> MethodDependency:
         """
-        Get the resolved and unresolved dependencies from a method of the instance's class.
+        Get dependency analysis for a specific method.
+
+        Analyzes the method parameters to identify resolved and unresolved
+        dependencies, handling private method name mangling automatically.
 
         Parameters
         ----------
         method_name : str
-            The name of the method to inspect
+            The name of the method to analyze.
 
         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 containing resolved dependencies
+            (with default values/annotations) and unresolved dependencies
+            (parameters without defaults or type information).
 
+        Raises
+        ------
+        ReflectionAttributeError
+            If the method does not exist in the class.
+        """
         # Ensure the method name is a valid identifier
         if not self.hasMethod(method_name):
             raise ReflectionAttributeError(f"Method '{method_name}' does not exist on '{self.getClassName()}'.")
@@ -1503,12 +1592,20 @@ class ReflectionConcrete(IReflectionConcrete):
 
     def reflectionInstance(self) -> ReflectionInstance:
         """
-        Get the reflection instance of the concrete class.
+        Get a reflection wrapper for the current class instance.
+
+        Provides access to instance-level reflection capabilities for the
+        instantiated object.
 
         Returns
         -------
         ReflectionInstance
-            An instance of ReflectionInstance for the concrete class
+            A reflection wrapper for instance-level introspection operations.
+
+        Raises
+        ------
+        ReflectionValueError
+            If no instance has been created using getInstance().
         """
         if not self.__instance:
             raise ReflectionValueError(f"Instance of class '{self.getClassName()}' is not initialized. Use getInstance() to create an instance before calling methods.")