Merge pull request #6 from atellaluca/feature/spymodel-property-variable-support

feat: add support for module variables and class/instance attributes in SpyModel and update docs

Author: atellaluca

README.rst

@@ -60,23 +60,40 @@ Here's a simple example showing how to use **ImportSpy** to validate that an imp
     from importspy.models import SpyModel, ClassModel
     from typing import List
 
-    # Define the rules for how your Python code should be used
+    # Define the rules for how your Python code should be structured and used by external modules
     class MyLibrarySpy(SpyModel):
-        functions: List[str] = ["required_function"]  # Required function in the importing module
+        # List of required variables that must be present in the importing module
+        variables: List[str] = ["required_var1", "required_var2"]  # Required variables
+
+        # List of required functions that must be defined in the importing module
+        functions: List[str] = ["required_function"]  # Required function
+
+        # Define the required classes, their attributes, and methods
         classes: List[ClassModel] = [
             ClassModel(
-                name="MyRequiredClass",  # Required class name
-                methods=["required_method1", "required_method2"]  # Required methods in the class
+                name="MyRequiredClass",  # Name of the required class
+
+                # Required class-level attributes (e.g., static variables)
+                class_attr=["attr_1", "attr_2"],  # Class attributes
+
+                # Required instance-level attributes (must exist in the class instances)
+                instance_attr=["attr_3"],  # Instance attributes
+
+                # Methods that the required class must implement
+                methods=["required_method1", "required_method2"]  # Required methods
             )
         ]
 
-    # Check if the importing module complies with the rules
+    # Use ImportSpy to check if the importing module complies with the defined rules
     module = Spy().importspy(spymodel=MyLibrarySpy)
 
+    # If the module passes validation, you can safely use it; otherwise, ImportSpy raises an error
     if module:
-        print(f"Module {module.__name__} is using your library correctly!")
+        print(f"Module '{module.__name__}' complies with the specified rules and is ready to use!")
     else:
-        print("The importing module is not complying with the rules.")
+        print("The importing module does not comply with the required structure.")
+
+    # Now you can access all the attributes of the module that imports your code
 
 Example of a Compliant Importing Python Module
 ==============================================

examples/plugin_based_architecture/extension.py

@@ -1,7 +1,14 @@
 import package
 from plugin_interface import Plugin
 
+plugin_name = "plugin name"
+plugin_description = "plugin description"
 class Extension(Plugin):
+
+    extension_name = "extension_name"
+
+    def __init__(self) -> None:
+        self.extension_instance_name = "extension_instance_name"
 
     def add_extension(self):
         print("Extension has added")

examples/plugin_based_architecture/package.py

@@ -4,8 +4,11 @@
 from typing import List
 
 class PluginSpy(SpyModel):
+    variables: List[str] = ["plugin_name", "plugin_description"]
     classes: List[ClassModel] = [
         ClassModel(
+            class_attr=["extension_name"],
+            instance_attr=["extension_instance_name"],
             methods=["add_extension", "remove_extension", "http_get_request"],
             superclasses=["Plugin"]
         ),

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "importspy"
-version = "0.1.7"
+version = "0.1.8"
 description = "ImportSpy is a lightweight Python library that enables proactive control over how your code is used when imported by other modules or packages. It allows developers to define rules that importing modules must follow, ensuring proper use and preventing misuse or errors."
 license = "MIT"
 authors = ["Luca Atella <atellaluca@outlook.it>"]

src/importspy/models.py

@@ -17,6 +17,8 @@ class ClassModel(BaseModel):
 
     ## Attributes:
     - **name** (`Optional[str]`): The name of the class. This can be `None` if the class name is unavailable. Defaults to `None`.
+    - **class_attr* (`Optional[List[str]]`): A list of class attributes names that are expected to be present in the class. Defaults to an empty list.
+    - *instance_attr* (`Optional[List[str]]`): A list of class isntance attributes names that are expected to be present in the class. Defaults to an empty list.
     - **methods** (`Optional[List[str]]`): A list of method names that are expected to be present in the class. Defaults to an empty list.
     - **superclasses** (`Optional[List[str]]`): A list of names of the superclasses from which this class inherits. Defaults to an empty list.
 
@@ -32,6 +34,8 @@ class ClassModel(BaseModel):
     and inherit from `BaseClass`. External modules importing your code can then be validated to follow this structure.
     """
     name: Optional[str] = None
+    class_attr: Optional[List[str]] = []
+    instance_attr: Optional[List[str]] = []
     methods: Optional[List[str]] = []
     superclasses: Optional[List[str]] = []
 
@@ -47,6 +51,7 @@ class SpyModel(BaseModel):
     ## Attributes:
     - **filename** (`Optional[str]`): The name of the module file. If the name is unavailable, it can be `None`. Defaults to `None`.
     - **version** (`Optional[str]`): The expected version of the module. Defaults to `None` if the version is not available.
+    - **variables** (`Optional[List[str]]`): A list of variables names that are expected to be defined within the module. Defaults to an empty list.
     - **functions** (`Optional[List[str]]`): A list of function names that are expected to be defined within the module. Defaults to an empty list.
     - **classes** (`Optional[List[ClassModel]]`): A list of class definitions within the module, represented by `ClassModel`. Defaults to an empty list.
 
@@ -84,8 +89,9 @@ class SpyModel(BaseModel):
     This will extract the necessary metadata from `my_module` and create a `SpyModel` instance that describes the module's 
     structure, which can then be compared to the expected structure defined by the developer.
     """
-    filename: Optional[str] = None
-    version: Optional[str] = None
+    filename: Optional[str] = ""
+    version: Optional[str] = ""
+    variables: Optional[List[str]] = []
     functions: Optional[List[str]] = []
     classes: Optional[List[ClassModel]] = []
 
@@ -118,17 +124,30 @@ def from_module(cls, info_module: ModuleType):
         logger.debug(f"Create SpyModel from info_module: {ModuleType}")
         filename = "/".join(info_module.__file__.split('/')[-1:])
         version = spy_module_utils.extract_version(info_module)
+        variables = spy_module_utils.extract_variables(info_module)
         functions = spy_module_utils.extract_functions(info_module)
         classes = [
-            ClassModel(name=name, methods=methods, superclasses=superclasses)
-            for name, methods, superclasses in spy_module_utils.extract_classes(info_module)
+            ClassModel(name=name, 
+                       class_attr=class_attr, 
+                       instance_attr=instance_attr,
+                       methods=methods,
+                       superclasses=superclasses)
+            for 
+            name,
+            class_attr,
+            instance_attr,
+            methods,
+            superclasses 
+            in spy_module_utils.extract_classes(info_module)
         ]
         spy_module_utils.unload_module(info_module)
         logger.debug("Unload module")
-        logger.debug(f"filename: {filename}, version: {version}, functions: {functions}, classes: {classes}")
+        logger.debug(f"filename: {filename}, version: {version}, \
+                     functions: {functions}, classes: {classes}")
         return cls(
             filename=filename,
             version=version,
+            variables=variables,
             functions=functions,
             classes=classes
         )

src/importspy/utils/spy_model_utils.py

@@ -35,33 +35,29 @@ def is_subset(spy_model_1: SpyModel, spy_model_2: SpyModel) -> bool:
     This function helps ensure that any importing module respects the rules set by the developer, 
     reducing the risk of improper usage and integration issues.
     """
-    
-    # Check if the filenames match, if provided
     if spy_model_1.filename and spy_model_1.filename != spy_model_2.filename:
         return False
-
-    # Check if the versions match, if provided
     if spy_model_1.version and spy_model_1.version != spy_model_2.version:
         return False
-
-    # Check if all functions in spy_model_1 are present in spy_model_2
+    if spy_model_1.variables:
+        if not set(spy_model_1.variables).issubset(spy_model_2.variables):
+            return False
     if spy_model_1.functions:
         if not set(spy_model_1.functions).issubset(spy_model_2.functions):
             return False
-
-    # Check if all classes in spy_model_1 are present in spy_model_2
     for class_1 in spy_model_1.classes:
-        # Find the corresponding class in spy_model_2
         class_2 = next((cls for cls in spy_model_2.classes if cls.name == class_1.name or class_1.name is None), None)
         if not class_2:
             return False
-        
-        # Check if all methods in class_1 are present in class_2
+        if class_1.class_attr:
+            if not set(class_1.class_attr).issubset(class_2.class_attr):
+                return False
+        if class_1.instance_attr:
+            if not set(class_1.instance_attr).issubset(class_2.instance_attr):
+                return False
         if class_1.methods:
             if not set(class_1.methods).issubset(class_2.methods):
                 return False
-
-        # Check if all superclasses in class_1 are present in class_2
         if class_1.superclasses:
             if not set(class_1.superclasses).issubset(class_2.superclasses):
                 return False

src/importspy/utils/spy_module_utils.py

@@ -10,7 +10,13 @@
 logger = logging.getLogger(__name__)
 logger.addHandler(logging.NullHandler())
 
-ClassInfo = namedtuple('ClassInfo', ['name', 'methods', 'superclasses'])
+ClassInfo = namedtuple('ClassInfo', [
+    'name',
+    'class_attr',
+    'instance_attr',
+    'methods',
+    'superclasses'
+    ])
 
 def inspect_module() -> tuple:
     """
@@ -135,54 +141,88 @@ def extract_version(info_module: ModuleType) -> str | None:
     except importlib.metadata.PackageNotFoundError:
         return None
 
-def extract_functions(info_module: ModuleType) -> List[str] | None:
+def extract_variables(info_module:ModuleType) -> List[str]:
     """
-    Extract a list of function names defined in a module, ensuring that external modules adhere to
-    the expected function structure.
+    Extract a list of variables names defined in a module.
+
+    This function retrieves all variables names defined within the specified module, allowing
+    developers to verify the variables defined in the module.
+
+    Parameters:
+    -----------
+    - **info_module** (`ModuleType`): The module from which to extract function names.
+
+    Returns:
+    --------
+    - **List[str]: A list of variables names defined in the module.
+    """
+    return [
+        var_name
+        for var_name, obj in inspect.getmembers(info_module)
+        if not callable(obj)
+        and not isinstance(obj, ModuleType)
+        and not (var_name.startswith("__") and var_name.endswith("__"))
+    ]
+
+
+def extract_functions(info_module: ModuleType) -> List[str]:
+    """
+    Extract a list of function names defined in a module.
 
     This function retrieves all function names defined within the specified module, allowing
-    developers to verify the functions implemented in the module and ensure they align with expectations.
+    developers to verify the functions implemented in the module.
 
     Parameters:
     -----------
     - **info_module** (`ModuleType`): The module from which to extract function names.
 
     Returns:
     --------
-    - **List[str] | None**: A list of function names defined in the module, or `None` if no functions are found.
+    - **List[str]: A list of function names defined in the module.
     """
-    functions = [
+    return [
         func_name
         for func_name, obj in inspect.getmembers(info_module, inspect.isfunction)
         if obj.__module__ == info_module.__name__
     ]
-    return functions
 
 def extract_classes(info_module: ModuleType) -> List[ClassInfo]:
     """
-    Extract information about classes in a module, including their methods and superclasses, 
-    providing a clear picture of the module's class structure.
+    Extract information about classes in a module, including their methods, class attributes, 
+    instance attributes, and superclasses, providing a clear picture of the module's class structure.
 
     This function retrieves class information from the specified module, including class names, 
-    the methods they define, and their superclasses. This can be used to ensure that the module's 
-    class structure adheres to predefined expectations.
+    class attributes, instance attributes, methods they define, and their superclasses.
 
     Parameters:
     -----------
     - **info_module** (`ModuleType`): The module from which to extract class information.
 
     Returns:
     --------
-    - **List[ClassInfo]**: A list of `ClassInfo` namedtuples containing class names, methods, and superclasses.
+    - **List[ClassInfo]**: A list of `ClassInfo` namedtuples containing class names, class_attr, instance_attr, methods, and superclasses.
     """
     classes = []
     for class_name, cls_obj in inspect.getmembers(info_module, inspect.isclass):
         if cls_obj.__module__ == info_module.__name__:
+            class_attr = [
+                attr_name for attr_name, attr_value in cls_obj.__dict__.items() 
+                if not callable(attr_value) and not attr_name.startswith('__')
+            ]
+            instance_attr = []
+            init_method = cls_obj.__dict__.get('__init__')
+            if init_method:
+                source_lines = inspect.getsourcelines(init_method)[0]
+                for line in source_lines:
+                    line = line.strip()
+                    if line.startswith('self.') and '=' in line:
+                        attr_name = line.split('=')[0].strip().split('.')[1]
+                        instance_attr.append(attr_name)
             methods = [
                 method_name for method_name, _ in inspect.getmembers(cls_obj, inspect.isfunction)
             ]
             superclasses = [base.__name__ for base in cls_obj.__bases__]
-            current_class = ClassInfo(class_name, methods, superclasses)
+            current_class = ClassInfo(class_name, class_attr, instance_attr, methods, superclasses)
             classes.append(current_class)
     return classes
 
@@ -211,4 +251,4 @@ def extract_superclasses(module: ModuleType) -> List[str]:
                 superclasses.add(base.__name__)
                 logger.debug(f"Added {base.__name__} to superclasses set")
     logger.debug(f"Superclasses: {superclasses}")
-    return list(superclasses)
+    return list(superclasses)