memorymanagement 1.4.1__tar.gz → 1.4.2__tar.gz

{memorymanagement-1.4.1 → memorymanagement-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymanagement
-Version: 1.4.1
+Version: 1.4.2
 Summary: Adds support for memory management
 Home-page: https://github.com/Ricardo-Werner-Rivas/memorymanagement/tree/PyPI
 Author: Ricardo Werner Rivas

{memorymanagement-1.4.1 → memorymanagement-1.4.2}/memorymanagement/__init__.py

@@ -1,5 +1,4 @@
 """
-# `memorymanagement` package
 Provides memory management support.
 
 ---

{memorymanagement-1.4.1 → memorymanagement-1.4.2}/memorymanagement/cleaning/__init__.py

@@ -1,6 +1,5 @@
 """
-# Module `cleaning`
-Implements the class `Cleaner` to keep track of the references and erase it easily.
+Implements the class `Cleaner` to keep track of the references and erase them easily.
 ## Overview
 Initialize a `Cleaner` object:
 ```
@@ -36,6 +35,31 @@ Flagged: ["x","y","z"]
 Excluded: []
 
 Not delete: <list(vars(modules["main"]))> # Unchanged since initialization
+```
+To delete these variables from memory, use the `clean()` method:
+```
+# Cleans memory
+cleaner.clean()
+
+# Print again the `Cleaner` instance
+print(cleaner)
+```
+The output will now be:
+```
+Flagged: []
+
+Excluded: []
+
+Not delete: <list(vars(modules["main"]))> # Unchanged since initialization
+```
+And if we print the global variables:
+```
+print(list(globals()))
+```
+The output will be:
+```
+["Cleaner","cleaner"]
+```
 """
 # Imports
 from .core import Cleaner

{memorymanagement-1.4.1 → memorymanagement-1.4.2}/memorymanagement/cleaning/core.py

@@ -19,7 +19,6 @@ from sys import modules
 #* MAIN CLASS
 # Class "Cleaner"
 class Cleaner:
-    #& Code comments
     """
     Class for references management. It keeps track of the names of the global variables to be deleted and deletes them when ordered.
     
@@ -71,18 +70,23 @@ class Cleaner:
         
         Arguments
         ---------
-        not_delete : `list[str]`, Optional
+        not_delete : `list[str]`|`None`, Optional
             List of variables to never be deleted. It takes the list of global variables of the main module by default.
         excluded : `list[str]`, Optional
             List of variables to be excluded from the memory cleaning process. Empty list by default.
         flagged : `list[str]`, Optional
             List of variables to be erased from memory. Empty list by default.
         """
+        # If a "not_delete" list is not passed
         if not not_delete:
+            # Take the list of global variables of the main module
             not_delete=list(vars(modules["__main__"]))
+        # Loop through the global variables' dictionary of the main module
         for key,value in vars(modules["__main__"]).copy().items():
+            # Delete every other "Cleaner" object
             if isinstance(value,Cleaner) and key in vars(modules["__main__"]).keys():
                 del vars(modules["__main__"])[key]
+        # Declare the main attributes
         self._not_delete=not_delete.copy()
         self._excluded=excluded.copy()
         self._flagged=flagged.copy()
@@ -102,16 +106,26 @@ class Cleaner:
         include : `str`|`list[str]`|`tuple[str]`|`None`, Optional
             Allows you to include a single (`str`) or multiple (`list` or `tuple`) variables. `None` by default.
         """
+        # If there are variables to exclude
         if exclude:
+            # If "exclude" content is a string
             if isinstance(exclude,str):
+                # Make it a list
                 exclude=[exclude]
+            # Introduce the excluded variables into the corresponding lists
             self._excluded.extend([var for var in exclude if var not in self._excluded])
+        # If the are excluded variables to include
         if include:
+            # If "include" content is a string
             if isinstance(include,str):
+                # Make it a list
                 include=[include]
+            # Loop for "include"
             for var in include:
+                # Remove every occurrence of the variables to include from the "excluded" list
                 while var in self._excluded:
                     self._excluded.remove(var)
+        # Rebuild the "flagged" list
         self._flagged=[var for var in list(vars(modules["__main__"]))if var not in self.not_delete and var not in self.excluded]
     
     # Exclude
@@ -124,9 +138,12 @@ class Cleaner:
         exclude : `tuple[str]`
             Stream of references to be excluded.
         """
+        # Loop for the variables to exclude
         for var in exclude:
+            # Remove from the "flagged" list
             while var in self._flagged:
                 self._flagged.remove(var)
+            # Introduce variable into the "excluded" list
             if var not in self._excluded:
                 self._excluded.append(var)
     
@@ -140,9 +157,12 @@ class Cleaner:
         include : `tuple[str]`
             Stream of references to be included.
         """
+        # Loop for the variables to "include"
         for var in include:
+            # Introduce variable into the "flagged" list
             if var not in self._flagged:
                 self._flagged.append(var)
+            # Remove from excluded list
             while var in self._excluded:
                 self._excluded.remove(var)
     
@@ -156,13 +176,20 @@ class Cleaner:
         exclude : `str`|`list[str]`|`tuple[str]`|`None`, Optional
             Variables not to be included into the `flagged` list
         """
+        # Introduce excluded variables into the "flagged" list
         self._flagged.extend(self.excluded)
+        # Clear the "excluded" list
         self._excluded.clear()
         
+        # If the are exceptions
         if exclude:
+            # If "exclude" content is a string
             if isinstance(exclude,str):
+                # Exclude variable
                 self.exclude(exclude)
+            # Else
             else:
+                # Exclude variables (unpacking)
                 self.exclude(*exclude)
     
     # Exclude all flagged variables
@@ -175,13 +202,20 @@ class Cleaner:
         include : `str`|`list[str]`|`tuple[str]`|`None`, Optional
             Variables not to be excluded from the `flagged` list
         """
+        # Introduce excluded variables into the "excluded" list
         self._excluded.extend(self.flagged)
+        # Clear the "flagged" list
         self._flagged.clear()
         
+        # If there are exceptions
         if include:
+            # If "include" content is a string
             if isinstance(include,str):
+                # Include varianle
                 self.include(include)
+            # Else
             else:
+                # Include variables (unpacking)
                 self.include(*include)
     
     # Purge flagged and excluded variables
@@ -196,11 +230,17 @@ class Cleaner:
         excluded : `bool`, Optional
             Wether the `excluded` list should be purged (`True`) or not (`False`). `True` by default
         """
+        # If there is no list to be purged
         if not flagged and not excluded:
+            # Pass
             pass
+        # If "flagged" is set to be purged
         if flagged:
+            # Clear "flagged"
             self._flagged.clear()
+        # If "excluded" is set to be purged
         if excluded:
+            # Clear "excluded"
             self._excluded.clear()
     
     # Clean
@@ -209,9 +249,13 @@ class Cleaner:
         Culminates the cleaning process.
         Erases all the flagged references.
         """
+        # Loop for "flagged" list
         for var in self._flagged:
+            # If current variable name is between the global variables of "__main__"
             if var in list(vars(modules["__main__"])):
+                # Delete variable
                 del vars(modules["__main__"])[var]
+        # Clear "flagged" list
         self._flagged.clear()
     
     #* PROPERTIES
@@ -219,18 +263,31 @@ class Cleaner:
     @property
     # Getter
     def not_delete(self):
+        # If reference is not set or it doesn't point to the "Cleaner" object
         if not self._name or vars(modules["__main__"])[self._name] is not self:
+            # Loop for variables dictionary
             for key,value in vars(modules["__main__"]).items():
+                # If current value is the "Cleaner" object
                 if value is self:
+                    # Store the reference
                     self._name=key
+                    # Add it to the "not_delete" list
                     self._not_delete.append(self._name)
+                    # Break
                     break
+                # Else
                 else:
+                    # Reference is still empty
                     self._name=None
+            # If reference remains empty
             if not self._name:
+                # Raise a "ReferenceError"
                 raise ReferenceError("\"Cleaner\" object is not referenced")
+        # Else, if reference is not in the "not_delete" list
         elif self._name not in self._not_delete:
+            # Add reference to the "not_delete" list
             self._not_delete.append(self._name)
+        # Return a shallow copy of the "not_delete" list
         return self._not_delete.copy()
     #^ No setter
     #^ No deleter
@@ -239,6 +296,7 @@ class Cleaner:
     @property
     # Getter
     def excluded(self):
+        # Return a shallow copy of the "excluded" list
         return self._excluded.copy()
     #^ No setter
     #^ No deleter
@@ -247,6 +305,7 @@ class Cleaner:
     @property
     # Getter
     def flagged(self):
+        # Return a shallow copy of the "flagged" list
         return self._flagged.copy()
     #^ No setter
     #^ No deleter
@@ -254,6 +313,7 @@ class Cleaner:
     #* SCREEN DUNDER METHODS
     # __str__
     def __str__(self):
+        # Return a string with the instance's components
         return f"""
         Flagged: {self.flagged}
         
@@ -264,4 +324,5 @@ class Cleaner:
     
     # __repr__
     def __repr__(self):
+        # Return a string able to rebuild the instance if needed
         return f"{self.__class__.__name__}(not_delete={self.not_delete},excluded={self.excluded},flagged={self.flagged})"

{memorymanagement-1.4.1 → memorymanagement-1.4.2}/memorymanagement/pointers/__init__.py

@@ -1,5 +1,4 @@
 """
-# Module `pointers`
 A safe implementation of pointers written in pure Python.
 
 It is safe beacause it doesn't imitate the internal behaviour of C pointers because it could break the memory.

{memorymanagement-1.4.1 → memorymanagement-1.4.2}/memorymanagement/pointers/core.py

@@ -25,7 +25,6 @@ PT=TypeVar("PT")
 #* MAIN CLASS
 # Define the class "Pointer" with generic type
 class Pointer(Generic[PT]):
-    #& Missing code comments
     """
     Implements pointers in Python for both mutable (though unneded) and non-mutable objects.
     These pointers are completely safe and do not work internally as C's pointers, they are just an imitation of their behaviour.
@@ -102,31 +101,53 @@ class Pointer(Generic[PT]):
         local : `bool`, Optional
             Indicates if the value to point to is a local variable (`True` for yes and `False` for no). `False` by default.
         """
+        # If pointing to local variable
         if local:
+            # Take the local frame
             vars_dict=currentframe().f_back.f_locals
+        # Else
         else:
+            # Take the global frame
             vars_dict=vars(modules["__main__"])
-        self._value=value
-        self._vars_dict=vars_dict
-        self._attr=attr
+        
+        # Store hidden attributes
+        self._value=value # Pointer's value
+        self._vars_dict=vars_dict # Variables' frame
+        self._attr=attr # Instance attribute to point to
+        
+        # If there is an instance's attribute to point to and it doesn't belong to the given value
         if self._attr and self._attr not in dir(self._value):
+            # Raise an "AttributeError"
             raise AttributeError(f"\"{attr}\" is not an attribute of \"{self._value}\"")
+        # If a reference is given
         if reference:
+            # If the reference is in the variables' frame and points to the given value
             if reference in vars_dict and vars_dict[reference] is value:
+                # Store the reference in "name" local variable
                 name=reference
+            # Else, if the reference isn't in the variables' frame
             elif reference not in vars_dict:
+                # Raise a "NameError"
                 raise NameError(f"Name \"{reference}\" is not defined")
+            # Else, if the reference doesn't point to the given value
             elif vars_dict[reference] is not value:
+                # Raise a "ValueError"
                 raise ValueError(f"Name \"{reference}\" doesn't point to given value ({value})")
+        # Else
         else:
+            # Store every reference pointing to the given value
             name=[key for key,v in vars_dict.items() if v is value]
-            name=name if len(name)!=0 else [None]
+            # Set to "None" if no reference was found
+            name=name[0] if len(name)!=0 else None
+        # Store the reference in the hidden attribute "_name"
         self._name=name
+        # If there is no reference
         if self._name==None:
+            # Raise a "NameError"
             raise NameError(f"No reference is pointing to given value \"{self._value}\"")
     
     # Point to
-    def point_to(self,reference:str|None=None,value=None,*,attr:str|None=None):
+    def point_to(self,value=None,reference:str|None=None,*,attr:str|None=None):
         """
         Changes the address which the `Pointer` object points to.
         
@@ -139,48 +160,103 @@ class Pointer(Generic[PT]):
         attr : `str`|`None`, Optional
             Attribute of the class if class object was passed through `reference` or `value`.
         """
+        # If no reference or value is given
         if not reference and not value:
-            pass
+            # If an instance's attribute name is given
+            if attr:
+                # If the attribute belongs to the pointer's value
+                if attr in dir(self._value):
+                    # Store the attribute name into its corresponding hidden attribute
+                    self._attr=attr
+                # Else
+                else:
+                    # Raise an "AttributeError"
+                    raise AttributeError(f"\"{attr}\" isn't an attribute of the variable \"{self._name}\" with value \"{self._value}\" (\"{self._value.__class__.__name__}\")")
+            # Else
+            else:
+                # Raise a "ValueError"
+                raise ValueError("No argument was given")
+        # Else, if both reference and value are given
         elif reference and value:
+            # If the reference is in the variables' frame and it points to the given value
             if reference in self._vars_dict and self._vars_dict[reference] is value:
+                # Store both into their corresponding hidden attributes
                 self._name,self._value=reference,value
+                # If an attribute name is given
                 if attr:
+                    # If the attribute belongs to the given value
                     if attr in dir(self._value):
+                        # Store attribute name into its corresponding hidden attribute
                         self._attr=attr
+                    # Else
                     else:
+                        # Raise an "AttributeError"
                         raise AttributeError(f"\"{attr}\" is not an attribute of \"{self._value}\"")
+            # Else, if the reference isn't in the variables' frame
             elif reference not in self._vars_dict:
+                # Raise a "NameError"
                 raise NameError(f"Name \"{reference}\" is not defined")
+            # Else, if the reference doesn't point to the given value
             elif self._vars_dict[reference] is not value:
+                # Raise a "ValueError"
                 raise ValueError(f"Name \"{reference}\" doesn't point to given value \"{value}\"")
+        # Else, if only a reference is given
         elif reference:
+            # If the reference is in the variables' frame
             if reference in self._vars_dict:
+                # Store the reference and the value it is pointing to into their corresponding hidden attributes
                 self._name,self._value=reference,self._vars_dict[reference]
+                # If an instance's attribute name is given
                 if attr:
+                    # If the attribute belongs to the new value
                     if attr in dir(self._value):
+                        # Store the attribute name into its corresponding hidden attribute
                         self._attr=attr
+                    # Else
                     else:
+                        # Raise an "AttributeError"
                         raise AttributeError(f"\"{attr}\" is not an attribute of \"{self._value}\"")
+            # Else
             else:
+                # Raise a "NameError"
                 raise NameError(f"Name \"{reference}\" is not defined")
+        # Else, if only a value is given
         elif value:
+            # Store the given value and its references into their corresponding hidden attributes
             self._name,self._value=[key for key,v in self._vars_dict.items() if v is value],value
-            self._name=self._name if len(self._name)!=0 else [None]
+            # Modify the "_name" hidden attribute to be a string or "None"
+            self._name=self._name[0] if len(self._name)!=0 else None
+            # If no reference was found
             if self._name==None:
+                # Raise a "NameError"
                 raise NameError(f"No reference is pointing to given value \"{self._value}\"")
+            # If an instance's attribute name is given
             if attr:
+                # If the attribute belongs to the new value
                 if attr in dir(self._value):
+                    # Store the attribute name into its corresponding hidden attribute
                     self._attr=attr
+                # Else
                 else:
+                    # Raise an "AttributeError"
                     raise AttributeError(f"\"{attr}\" is not an attribute of \"{self._value}\"")
     
     # Get references
-    def get_refs(self):
+    def get_refs(self)->tuple[str]:
         """
         Gets all the references pointing to the same current value of the `Pointer` object.
         """
+        # Find and return all the references pointing to the pointer's value
         return tuple(key for key,v in self._vars_dict.items() if v is self._value)
     
+    # Print references
+    def print_refs(self):
+        """
+        Prints all the references pointing to the same current value of the pointer.
+        """
+        # Print all the references pointing to the pointer's value
+        print(tuple(key for key,v in self._vars_dict.items() if v is self._value))
+    
     # Switch reference
     def switch_ref(self,reference:str):
         """
@@ -191,65 +267,90 @@ class Pointer(Generic[PT]):
         reference : `str`
             Reference to switch the pointer to.
         """
+        # If the given reference is in the variables' frame but it doesn' point to current the pointer's value
         if reference in self._vars_dict and self._vars_dict[reference] is not self.value:
+            # Raise a "ValueError"
             raise ValueError(f"Name \"{reference}\" doesn't point to pointer's value \"{self.value}\"")
+        # Else, if the given reference is not in the variables' frame
         elif reference not in self._vars_dict:
+            # Raise a "NameError"
             raise NameError(f"Name \"{reference}\" is not defined")
+        # Store the reference into its corresponding hidden attribute
         self._name=reference
     
-    # Print references
-    def print_refs(self):
-        """
-        Prints all the references pointing to the same current value of the pointer.
-        """
-        print(tuple(key for key,v in self._vars_dict.items() if v is self._value))
-    
     #* PROPERTIES
     # Value
     @property
     # Getter
     def value(self):
+        # If an instance's attribute name is stored
         if self.attr:
+            # If the stored reference is not in the variables' frame
             if self.reference not in self._vars_dict:
+                # Delete the pointer's value and the stored attribute name
                 del self._value,self.attr
+                # Raise a "NameError"
                 raise NameError("The class instance has already been deleted, so the pointer no longer has access to it.")
+            # Else, if the stored attribute name doesn't belong to the pointer's value
             elif self.attr not in dir(self._value):
+                # Raise an "AttributeError"
                 raise AttributeError(f"The atribute \"{self._attr}\" has already been deleted, so the pointer no longer has access to it.")
+            # Return the instance attribute's value
             return getattr(self._value,self.attr)
+        # Else
         else:
+            # If the stored reference is not in the variables' frame
             if self.reference not in self._vars_dict:
+                # Delete the pointer's hidden attribute "_value"
                 del self._value
+                # Raise a "NameError"
                 raise NameError("The variable has already been deleted, so the pointer no longer has access to it.")
+            # If the original value differs from the stored one (because it was changed)
             if self._value is not self._vars_dict[self.reference]:
+                # Update the pointer's value
                 self._value=self._vars_dict[self.reference]
+            # Return the pointer's value
             return self._value
     # Setter
     @value.setter
     def value(self,value):
+        # If an attribute name is stored
         if self.attr:
+            # Set the instance' attribute to the new value
             setattr(self._value,self.attr,value)
+        # Else
         else:
+            # Set the pointers value to the new value
             self._value=value
+            # If the new pointer's value differs from the original variable
             if value is not self._vars_dict[self.reference]:
+                # Update the original variable setting it to the new value
                 self._vars_dict[self.reference]=value
     # Deleter
     @value.deleter
     def value(self):
+        # If an attribute name is stored
         if self.attr:
+            # Delete the attribute from the stored instance
             delattr(self._value,self.attr)
+        # Else
         else:
+            # Delete the "_value" pointer's hidden attribute
             del self._value
+            # Delete the corresponding variable
             del self._vars_dict[self.reference]
     
     # Reference
     @property
     # Getter
     def reference(self):
+        # Return the stored reference
         return self._name
     
     # Attribute
     @property
     def attr(self):
+        # Return the stored attribute name
         return self._attr
     
     #* INDEXATION
@@ -259,11 +360,9 @@ class Pointer(Generic[PT]):
     # Setter
     def __setitem__(self,index,value):
         self.value[index]=value
-        return
     # Deleter
     def __delitem__(self,index):
         del self.value[index]
-        return
     
     #* ARITHMETIC OPERATIONS
     # Addition

{memorymanagement-1.4.1 → memorymanagement-1.4.2}/memorymanagement/pointers/decorators.py

@@ -35,10 +35,14 @@ def pointerize(func):
     func : `FunctionType`
         Decorated function.
     """
+    #* IDENTITY MANAGEMENT
     # Makes the decorating function to keep its identity
     @wraps(func)
+    
+    #* WRAPPER
     # Define the wrapper
     def wrapper(*args,**kwargs):
+        #* SIGNATURE
         # Obtain the signature (parameters and defaults) of the decorated function
         sig=signature(func)
         # Bind call arguments to the signature
@@ -46,6 +50,7 @@ def pointerize(func):
         # Defaults all the arguments which haven't been passed
         bound.apply_defaults()
         
+        #* ARGUMENTS' MAPPING
         # Dictionary containing all the parameters
         param_map=bound.arguments
         
@@ -55,6 +60,7 @@ def pointerize(func):
             if isinstance(val,Pointer)
         }
         
+        #* EXECUTION ARGUMENTS
         # List containing all the positional arguments to be passed to the decorated function
         exec_args=[
             val.value if isinstance(val,Pointer) else val
@@ -66,7 +72,8 @@ def pointerize(func):
             for k,v in bound.kwargs.items()
         }
         
-        # Empty dict, future source to update pointers' values
+        #* TRACKING
+        # Empty dictionary, future source to update pointers' values
         frame_data={}
         
         # Tracer function compatible with the sys.settrace API
@@ -74,10 +81,12 @@ def pointerize(func):
             if event=="return" and frame.f_code is func.__code__:
                 frame_data.update(frame.f_locals)
             return tracer
+        
         # Activate tracing
         settrace(tracer)
-        # We try to execute the function
+        # Try to execute the function
         try:
+            # Storing its result
             result=func(*exec_args,**exec_kwargs)
         # Even if the program meets an error
         finally:
@@ -85,13 +94,16 @@ def pointerize(func):
             settrace(None)
         # If no exception or error is raised, the program continues from here
         
+        #* POINTERS' UPDATING
         # Iterates through the pointers
         for name,ptr in pointer_map.items():
-            # Checks if the parameter name is in the traced frame (of local variables of the decorated function)
+            # Check if the parameter name is in the traced frame (of local variables of the decorated function)
             if name in frame_data:
                 # In which case, the pointer's value is updated
                 ptr.value=frame_data[name]
+        #* RETURNS
         # Return the result of the decorated function
         return result
+    #* RETURNS
     # Return the wrapper
     return wrapper

{memorymanagement-1.4.1 → memorymanagement-1.4.2}/memorymanagement.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymanagement
-Version: 1.4.1
+Version: 1.4.2
 Summary: Adds support for memory management
 Home-page: https://github.com/Ricardo-Werner-Rivas/memorymanagement/tree/PyPI
 Author: Ricardo Werner Rivas

{memorymanagement-1.4.1 → memorymanagement-1.4.2}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = memorymanagement
-version = 1.4.1
+version = 1.4.2
 author = Ricardo Werner Rivas
 author_email = ricardowernerrivas@gmail.com
 description = Adds support for memory management