memorymanagement 1.0.0__py3-none-any.whl

memorymanagement/__init__.py

@@ -0,0 +1,20 @@
+"""
+Provides memory management support.
+
+---
+## Module `cleaning`
+The class `Cleaner` flags the global references to erase them when commanded. References can be chosen to be excluded or included again in the process.
+## Module `pointers`
+A safe implementation of pointers for Python. Written in pure Python, this module includes two things:
+### 1. Class `Pointer`
+Creates a `Pointer` instance. These pointers point to a reference, not to an object in memory.
+If value for the reference is changed, so is the pointer value and *viceversa*.
+### 2. Decorator `pointerize`
+Allows a function to receive pointers instead of the normally expected values.
+"""
+# Imports
+from .cleaning import Cleaner
+from .pointers import Pointer,pointerize
+
+# Declare "__all__"
+__all__=["Cleaner","Pointer","pointerize"]

memorymanagement/cleaning/__init__.py

@@ -0,0 +1,2 @@
+# Imports
+from .cleaning import Cleaner

memorymanagement/cleaning/cleaning.py

@@ -0,0 +1,131 @@
+# Imports
+from sys import modules
+
+# Define the class "Cleaner"
+class Cleaner:
+    """
+    Class for references management. It keeps track of the names of the global variables to be deleted and deletes them when ordered.
+    
+    The cleaning process only deletes the flagged references to objects, but doesn't directly force the garbage collector to destroy the objects they are pointing to.
+    
+    ---
+    ## WARNING
+    THERE CAN ONLY BE **ONE** CLEANER OBJECT.\n
+    Initializing a new one will delete all global references to the previous one.
+    
+    ---
+    Attributes:
+        _not_delete (`list[str]`, Hidden): List of variables to never delete from memory. These cannot be included in the process even if ordered so.\n
+            These mainly are variables needed for the system to work and imports.
+        _excluded (`list[str]`, Hidden): List of variables excluded from the memory cleaning that can be included again if desired.
+        _flagged (`list[str]`, Hidden): List of variables to erase from memory. Variables can be put in and/or taken out through methods.
+    ---
+    
+    ## Methods
+        :update: *`MethodType`*
+        Updates the list of variables to erase from memory including all the new variables global variables not manually excluded.\n
+            It also allows to incorporate previously excluded variables.
+        :exclude: *`MethodType`*
+        Allows you to exclude variables from the cleaning process without need to use the `instance.update()` method.
+        :include: *`MethodType`*
+        Allows you to include variables in the cleaning process without need to use the `instance.update()` method.
+        :clean: *`MethodType`*
+        Erases all the flagged references from memory.
+    ---
+    
+    ## Properties
+        :not_delete: *`MethodType`*, *Getter*
+        Returns the list of variables that shouldn't be deleted and can't be included in the cleaning process.
+        :excluded: *`MethodType`*, *Getter*
+        Returns the list of variables excluded from the cleaning process but can be included again if ordered.
+        :flagged: *`MethodType`*, *Getter*
+        Returns the list of variables to be erased from memory.
+    None of this properties has setter or deleter. Those lists can only be manipulated through the class methods.
+    """
+    def __init__(self,not_delete:list[str]=list(vars(modules["__main__"])),excluded:list[str]=[],flagged:list[str]=[]):
+        """
+        Initializes the class instance.\n
+        It is recommended to initialize the instance right after all global imports at the beggining of the program so no argument is needed.
+        
+        ---
+        Arguments:
+            not_delete (`list[str]`, 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.
+        """
+        for key,value in vars(modules["__main__"]).copy().items():
+            if isinstance(value,Cleaner) and key in vars(modules["__main__"]).keys():
+                del vars(modules["__main__"])[key]
+        self._not_delete=not_delete.copy()
+        self._excluded=excluded.copy()
+        self._flagged=flagged.copy()
+        return
+    def update(self,exclude:str|list[str]|tuple[str]|None=None,include:str|list[str]|tuple[str]|None=None):
+        """
+        Flags all the new global variables' references that were not manually excluded here or before. You can also include previously excluded references.
+        
+        ---
+        Arguments:
+            exclude (`str`|`list[str]`|`tuple[str]`|`None`, Optional): Allows you to exclude a single (`str`) or multiple (`list` or `tuple`) variables.
+                `None` by default.
+            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 exclude:
+            if isinstance(exclude,str):
+                exclude=[exclude]
+            self._excluded.extend([var for var in exclude if var not in self._excluded])
+        if include:
+            if isinstance(include,str):
+                include=[include]
+            for var in include:
+                while var in self._excluded:
+                    self._excluded.remove(var)
+        self._flagged=[var for var in list(vars(modules["__main__"])) if var not in self._not_delete and var not in self._excluded]
+        return
+    @property
+    def not_delete(self):
+        return self._not_delete
+    @property
+    def excluded(self):
+        return self._excluded
+    @property
+    def flagged(self):
+        return self._flagged
+    def exclude(self,*exclude:str):
+        """
+        Allows to exclude the desired references from the cleaning process.
+        
+        ---
+        Arguments:
+            *exclude (`str`): Stream of references to be excluded.
+        """
+        for var in exclude:
+            while var in self._flagged:
+                self._flagged.remove(var)
+            if var not in self._excluded:
+                self._excluded.append(var)
+        return
+    def include(self,*include:str):
+        """
+        Allows to include the desired references (previously excluded) in the cleaning process.
+        
+        ---
+        Arguments:
+            *include (`str`): Stream of references to be included.
+        """
+        for var in include:
+            if var not in self._flagged:
+                self._flagged.append(var)
+            while var in self._excluded:
+                self._excluded.remove(var)
+        return
+    def clean(self):
+        """
+        Culminates the cleaning process. Erases all the flagged references.
+        """
+        for var in self._flagged:
+            if var in list(vars(modules["__main__"])):
+                del vars(modules["__main__"])[var]
+        self._flagged.clear()
+        return

memorymanagement/pointers/__init__.py

@@ -0,0 +1,3 @@
+# Import from modules
+from .core import Pointer # Class "Pointer"
+from .decorators import pointerize # Decorator "pointerize"

memorymanagement/pointers/core.py

@@ -0,0 +1,127 @@
+# Import "TypeVar" and "Generic"
+from typing import TypeVar,Generic
+# Import "modules" from "sys" package
+from sys import modules
+# Import "currentframe" from "inspect" package
+from inspect import currentframe
+
+# Create new generic type
+object_type=TypeVar("object_type")
+# Define the class "Pointer"
+class Pointer(Generic[object_type]):
+    """
+    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.
+    
+    When a Pointer instance is created, though it stores a value, it "points" to an specific reference, not the value in a memory adress.
+    This way, all references pointing to the same non-mutable object don't change when the pointer is updated, avoiding a potential mess.
+    
+    Non-mutable objects still change their memory adresses when re-referenced but the reference and the value stored in the pointer are forced to share memory adress.
+    
+    Value and memory adress updates are not made in real-time, but the methods update the non-coincident values:
+        * **Getter**: it updates its own value to the variable's one (if variable was given instead of literal).
+        * **Setter**: it updates the value of the variable to its own (if variable was given instead of literal).
+        * **Deleter**: it also deletes the original variable (if variable was given instead of literal).
+    ---
+    Attributes:
+        value (`Any`, Hidden): Object to point to.
+        attr (`str`|`None`, Hidden): Attribute of class instance. Only if `value` is a class instance.
+        name (`str`, Hidden): Name of the global variable to which the pointer is pointing.
+            Could require an input from the user to introduce the name of the variable if more than one is found.
+        vars_dict (`dict[str,Any]`, Hidden): Dictionary of variables.
+            `vars(modules["__main__"])` if pointing to a global variable and `inspect.currentframe().f_back.f_locals` if pointing to a local variable.
+    ---
+    
+    ## Methods
+        1. **Getter**: Gets the value.
+        2. **Setter**: Sets a new value.
+        3. **Deleter**: Deletes the value.
+    All three methods are part of the same property.
+    ---
+    ## Properties
+        :value: *`MethodType`*
+        Points to `value` (or `value.attr`). Called through `<instance>.value`. All three possible objects (getter, setter and deleter) have been declared.
+    
+    ---
+    
+    ## Currently supported
+    Both global and local variables can be pointed at.
+    
+    Literals are **not** supported because of it being useless. If you create a `Pointer` instance for a literal and works,
+    keep in mind that it is merely by accident and it is **not** the intended use it was designed for.
+    Currently, the only use for inserting a literal instead of a referenced value could be for the class code to display all the references pointing to that literal
+    and bind the instance to the desired reference.
+    """
+    def __init__(self,value=None,attr:str|None=None,*,local:bool=False):
+        """
+        Arguments:
+            value (`Any`,Optional): Object to point to. If want to point to a class instance atribute, introduce the class instance without the atribute.
+            attr (`str`|`None`, Optional): Atribute of the class instance to which you want to point. Leave empty if `value` is not a class instance.
+            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 local:
+            vars_dict=currentframe().f_back.f_locals
+        else:
+            vars_dict=vars(modules["__main__"])
+        self._value=value
+        self._vars_dict=vars_dict
+        self._attr=attr
+        name=None
+        name=[]
+        for key,v in vars_dict.items():
+            try:
+                if v is value:
+                    name.append(key)
+            except ValueError:
+                pass
+        if len(name)>1:
+            print(f"{name}\nMultiple variable names found for the 'value' parameter, introduce the correct one:")
+            while True:
+                name_aux=input()
+                if name_aux in name:
+                    break
+                else:
+                    print("Error, introduce the correct variable name for the 'value' parameter:")
+            name=name_aux
+            del name_aux
+        elif len(name)==1:
+            name=name[0]
+        elif len(name)==0:
+            name=None
+        self._name=name
+        return
+    @property
+    def value(self):
+        if self._attr:
+            if self._name and self._name not in list(self._vars_dict):
+                del self._value,self._attr
+                raise KeyError("The class instance has already been deleted, so the pointer no longer has access to it.")
+            elif self._attr not in dir(self._value):
+                raise AttributeError(f"The atribute '{self._attr}' has already been deleted, so the pointer no longer has access to it.")
+            return getattr(self._value,self._attr)
+        else:
+            if self._name:
+                if self._name not in list(self._vars_dict):
+                    del self._value
+                    raise KeyError("The variable has already been deleted, so the pointer no longer has access to it.")
+                if self._value is not self._vars_dict[self._name]:
+                    self._value=self._vars_dict[self._name]
+            return self._value
+    @value.setter
+    def value(self,value):
+        if self._attr:
+            setattr(self._value,self._attr,value)
+        else:
+            self._value=value
+            if self._name and value is not self._vars_dict[self._name]:
+                self._vars_dict[self._name]=value
+        return
+    @value.deleter
+    def value(self):
+        if self._attr:
+            delattr(self._value,self._attr)
+        else:
+            del self._value
+            if self._name:
+                del self._vars_dict[self._name]
+        return

memorymanagement/pointers/decorators.py

@@ -0,0 +1,77 @@
+# Imports
+from sys import settrace
+from inspect import signature
+from functools import wraps
+from .core import Pointer
+
+# Define the decorator
+def pointerize(func):
+    """
+    Allows the decorated function to receive pointers instead of the normally expected values.
+    
+    The decorated function is still able to receive its normally expected parameters.
+    
+    ---
+    Arguments:
+        func (`FunctionType`): Decorated function.
+    """
+    # Makes the decorating function to keep its identity
+    @wraps(func)
+    # Define the wrapper
+    def wrapper(*args,**kwargs):
+        # Obtain the signature (parameters and defaults) of the decorated function
+        sig=signature(func)
+        # Bind call arguments to the signature
+        bound=sig.bind(*args,**kwargs)
+        # Defaults all the arguments which haven't been passed
+        bound.apply_defaults()
+        
+        # Dictionary containing all the parameters
+        param_map=bound.arguments
+        
+        # Dictionary containing only the parameters that are pointers
+        pointer_map={
+            name:val for name,val in param_map.items()
+            if isinstance(val,Pointer)
+        }
+        
+        # List containing all the positional arguments to be passed to the decorated function
+        exec_args=[
+            val.value if isinstance(val,Pointer) else val
+            for val in bound.args
+        ]
+        # Dictionary containing all the keyword arguments to be passed to the decorated function
+        exec_kwargs={
+            k:v.value if isinstance(v,Pointer) else v
+            for k,v in bound.kwargs.items()
+        }
+        
+        # Empty dict, future source to update pointers' values
+        frame_data={}
+        
+        # Tracer function compatible with the sys.settrace API
+        def tracer(frame,event,arg):
+            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:
+            result=func(*exec_args,**exec_kwargs)
+        # Even if the program meets an error
+        finally:
+            # It deactivates tracing
+            settrace(None)
+        # If no exception or error is raised, the program continues from here
+        
+        # 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)
+            if name in frame_data:
+                # In which case, the pointer's value is updated
+                ptr.value=frame_data[name]
+        # Return the result of the decorated function
+        return result
+    # Return the wrapper
+    return wrapper

memorymanagement-1.0.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: memorymanagement
+Version: 1.0.0
+Summary: Adds support for memory management
+Home-page: https://github.com/Ricardo-Werner-Rivas/python-memory-management/tree/main
+Author: Ricardo Werner Rivas
+Author-email: ricardowernerrivas@gmail.com
+License: MIT
+Project-URL: Issues Page, https://github.com/Ricardo-Werner-Rivas/python-memory-management/issues
+Project-URL: Repository, https://github.com/Ricardo-Werner-Rivas/python-memory-management
+Classifier: Programming Language :: Python
+Classifier: Operating System :: Microsoft :: Windows
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# `memorymanagement`
+Provides memory management support.
+## Modules
+### `cleaning`
+Provides the class `Cleaner`, which allows you to flag references stored in memory to eventually erase them.
+It is also possible to modify the list of flagged references through its methods.
+### `pointers`
+Provides a safe implementation of pointers for Python.
+#### Class `Pointer`
+The pointer itself. Imitates the behaviour of C pointers. This pointer points to a reference, not to an object stored in memory.
+#### Decorator `pointerize`
+Allows functions to receive pointers instead of values.
+## Installation
+You can install the `memorymanager` package from PyPI as follows:
+```bash
+pip install memorymanagement
+```
+You can also install the `memorymanager` package (Test PyPI versión of `memorymanager`) from TestPyPI as follows:
+```bash
+pip install --index-url https://test.pypi.org/simple/ memorymanager
+```
+For TestPyPI versión, `--no-deps` option is not needed because it has no dependencies.
+## How to use
+### Class `Cleaner`
+```py
+# Imports
+# Make your imports here
+from memorymanagement import Cleaner # Importing class Cleaner
+```
+Right after imports are done, I recommend to initialize an instance of class `Cleaner`, so no arguments are needed. This is the optimal use this class was designed for.
+```py
+# Initialize cleaner object
+cleaner=Cleaner()
+```
+Create, for example, these global variables:
+```py
+value_1=10
+value_2=50
+value_3=100
+```
+Update the list of flagged references like one of the following:
+* Including all new global variables:
+    ```py
+    cleaner.update()
+    print(cleaner.flagged)
+    ```
+    Output:
+    ```sh
+    ["value_1","value_2","value_3"]
+    ```
+* Excluding some variables:
+    ```py
+    cleaner.update(exclude="value_2")
+    print(cleaner.flagged)
+    ```
+    Output:
+    ```sh
+    ["value_1","value_3"]
+    ```
+    ---
+    ```py
+    cleaner.update(exclude=["value_2","value_3"])
+    print(cleaner.flagged)
+    ```
+    Output:
+    ```sh
+    ["value_1"]
+    ```
+* Include again some variables:
+
+    After having excluded some variables
+    ```py
+    cleaner.update(exclude=["value_2","value_3"])
+    ```
+    You can reintroduce them
+    ```py
+    # Create a new variable and update
+    value_4=150
+    cleaner.update(exclude="value_4",include="value_2") # "include" can also be a list of strings
+    print(cleaner.flagged)
+    ```
+    Output:
+    ```sh
+    ["value_1","value_2"]
+    ```
+You can also directly include or exclude references like so:
+```py
+cleaner.exclude(<name_var_1>,<name_var_2>,...)
+```
+```py
+cleaner.include(<name_var_1>,<name_var_2>,...)
+```
+### Class `Pointer`
+Example:
+```py
+from memorymanagement import Pointer
+a=10
+x=Pointer(a)
+print(f"a:\n{a}\n\nPointer:\n{x.value}\n\n")
+a=20
+print(f"a:\n{a}\n\nPointer:\n{x.value}\n\n")
+a=10
+x.value=20
+print(f"a:\n{a}\n\nPointer:\n{x.value}")
+```
+Output:
+```sh
+a:
+10
+
+Pointer:
+10
+
+
+a:
+20
+
+Pointer:
+20
+
+
+a:
+20
+
+Pointer:
+20
+```
+### Decorator `pointerize`
+Example:
+```py
+from memorymanagement import pointerize
+@pointerize
+def myFunction(value:int):
+    value=20
+    return
+a=10
+print(f"Value: {a}")
+myFunction(Pointer(a))
+print(f"Value: {a}")
+```
+Output:
+```sh
+Value: 10
+Value: 20
+
+```

memorymanagement-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+memorymanagement/__init__.py,sha256=Clyt9uUH0DZW36BdmWCMYNg4R2uLYYsSdsn1UgeLSJs,816
+memorymanagement/cleaning/__init__.py,sha256=YnrtCkREJ01-FOGURPYQmlpWGT9TtreG40z5X0-WYJY,40
+memorymanagement/cleaning/cleaning.py,sha256=FjwfFw5nv-zGt2UdRTUE9NNaHs8ZXsIaMsXwEm4hye8,6237
+memorymanagement/pointers/__init__.py,sha256=mSC1rCofRafPigcndKzYncHT2KYV5NNjtOj0ixlLfjw,127
+memorymanagement/pointers/core.py,sha256=f9FBOCUX-_lCI-zgt2J7tUJb3JdkkECcYwpdXRHAFz0,6233
+memorymanagement/pointers/decorators.py,sha256=NDMlexU6s123jPU0Tqny8HkMdtPsfwrzVAgjCAYpy4A,2869
+memorymanagement-1.0.0.dist-info/licenses/LICENSE,sha256=YbbIWfIjYfz9q2bm60jGAfdvdIqD96jDLvz16YsFOOk,1077
+memorymanagement-1.0.0.dist-info/METADATA,sha256=HdZOYIds5L5rqrhEJ0sGTixBKunUWS4jrirbM74S0sA,3980
+memorymanagement-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+memorymanagement-1.0.0.dist-info/top_level.txt,sha256=7SwrpC3BY9Cm6sqwu082DJE5SteRBira0LGqziTO7eQ,17
+memorymanagement-1.0.0.dist-info/RECORD,,

memorymanagement-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

memorymanagement-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ricardo Werner Rivas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memorymanagement-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+memorymanagement