beware 0.1.0__py3-none-any.whl

beware/__init__.py

@@ -0,0 +1,4 @@
+from ._unsafe import Unsafe, unsafe, unsafe_context
+from .sanitization import sanitizes, sanitize_context
+
+__all__ = ["Unsafe", "sanitizes", "sanitize_context", "unsafe", "unsafe_context"]

beware/_unsafe/__init__.py

@@ -0,0 +1,4 @@
+from ._context import unsafe_context
+from ._descriptor import unsafe, Unsafe, UnsafeReferenceException
+
+__all__ = ["unsafe_context", "unsafe", "Unsafe", "UnsafeReferenceException"]

beware/_unsafe/_context.py

@@ -0,0 +1,48 @@
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from .._unsafe._context_vars import inside_unsafe_context
+from .._unsafe._descriptor import Unsafe
+
+
+@contextmanager
+def unsafe_context(*attrs: Unsafe) -> Generator[None, None, None]:
+    """Enable the unsafe access of the specified attributes inside the context.
+
+    Parameters
+    ----------
+    attrs : tuple[Unsafe, ...]
+            arguments that can be acessed without raising UnsafeReadException,
+
+
+    Raises
+    ------
+    TypeError
+        If the given attrs are not Unsafe descriptors
+
+
+    Examples
+    --------
+    >>> class MyClass:
+    ...     a = unsafe()
+    >>> obj = MyClass()
+    >>> with unsafe_context(MyClass.a):
+    ...     print(instance.a) # won't raise an exception, even if it is not sanitized
+    """
+
+    for attr in attrs:
+        if not isinstance(attr, Unsafe):
+            raise TypeError(
+                f"Invalid argument with type {type(attr)} expected Unsafe type"
+            )
+
+    token = inside_unsafe_context.set(True)
+    try:
+        for attr in attrs:
+            attr._read_by_context = True
+
+        yield
+    finally:
+        inside_unsafe_context.reset(token)
+        for attr in attrs:
+            attr._read_by_context = False

beware/_unsafe/_context_vars.py

@@ -0,0 +1,5 @@
+from contextvars import ContextVar
+
+inside_unsafe_context: ContextVar[bool] = ContextVar(
+    "inside_unsafe_context", default=False
+)

beware/_unsafe/_descriptor.py

@@ -0,0 +1,114 @@
+"""
+This module contains the Unsafe descriptor class and the factory function for returning
+descriptor instances
+"""
+
+from typing import Any, overload
+
+from beware._unsafe._context_vars import inside_unsafe_context
+from beware.exceptions import NameAssignmentException, UnsafeReferenceException
+
+# sentinel value to check if the default was provided
+_MISSING_DEFAULT = object()
+
+
+class Unsafe:
+    """Descriptor class used to control unsafe variables access"""
+
+    __slots__: tuple[str, ...] = (
+        "_read_by_context",
+        "_default",
+        "_sanitize_on_assignment",
+        "_sanitize_flag",  # pyright: ignore[reportUninitializedInstanceVariable]
+        "_owner",  # pyright: ignore[reportUninitializedInstanceVariable]
+        "_private_name",  # pyright: ignore[reportUninitializedInstanceVariable]
+        "_public_name",  # pyright: ignore[reportUninitializedInstanceVariable]
+    )
+
+    def __init__(self, default: Any | None = _MISSING_DEFAULT) -> None:
+
+        self._read_by_context: bool = False
+        """
+        Determine if the attribute read should check the inside_unsafe_context ContextVar
+        """
+
+        self._sanitize_on_assignment: bool = False
+        """
+        When it is True, calling __set__ will make the variable sanitized 
+        """
+
+        self._default: Any | None = default
+        """
+        Default values are used when the related object have not modified the 
+        corresponding attribute of the descriptor field
+        """
+
+    def __set_name__(self, owner: type[object], name: str):
+        if getattr(self, "_owner", None):
+            raise NameAssignmentException(
+                f"Descriptor already binded to '{self._public_name}' attribute in {self._owner}"
+            )
+
+        self._owner: type[object] = owner
+        self._public_name: str = name
+        self._private_name: str = f"_{name}_beware"
+        self._sanitize_flag: str = f"{self._private_name}_sanitized"
+
+    @overload
+    def __get__(self, obj: None, objtype: None) -> "Unsafe": ...
+
+    @overload
+    def __get__(self, obj: object, objtype: type[object]) -> Any: ...
+
+    def __get__(self, obj: Any, objtype: type[object] | None = None) -> "Unsafe|Any":
+        if obj is None:
+            return self
+
+        read_allowed = inside_unsafe_context.get() if self._read_by_context else False
+
+        # if the descriptor has a default value and it was not overriden, it should be
+        # returned.
+        # If not, the descriptor field tries to resolve the instance attribute
+
+        # default values don't need sanitization
+        val = getattr(obj, self._private_name, self._default)
+
+        if val is _MISSING_DEFAULT:
+            raise AttributeError(
+                f" '{type(obj).__name__}' object has no attribute {self._public_name}"
+            )
+        elif self._default == val:
+            return self._default
+        else:
+            if getattr(obj, self._sanitize_flag, False) or read_allowed:
+                return val
+            else:
+                raise UnsafeReferenceException
+
+    def __set__(self, obj: object, value: Any) -> None:
+        setattr(obj, self._private_name, value)
+        if self._sanitize_on_assignment:
+            setattr(obj, self._sanitize_flag, True)
+
+    def __delete__(self, instance: object):
+        try:
+            delattr(instance, self._private_name)
+            delattr(instance, self._sanitize_flag)
+        except AttributeError:
+            pass
+
+
+def unsafe(default: Any | None = _MISSING_DEFAULT) -> Any:
+    """Factory function for Unsafe descriptors
+
+    Parameters
+    -----
+    default: Any
+        The default value of the field, can be accessed in any context
+
+    Warnings
+    -----
+        Default values can be accessed normally
+    """
+
+    return Unsafe(default=default)

beware/exceptions/__init__.py

@@ -0,0 +1,6 @@
+class UnsafeReferenceException(Exception):
+    """Raised when an attribute is referenced without being sanitized first"""
+
+
+class NameAssignmentException(AttributeError):
+    """Raised when a descriptor instance is assigned to two different attributes on one or more classes"""

beware/sanitization/__init__.py

@@ -0,0 +1,4 @@
+from ._context import sanitize_context
+from ._decorator import sanitizes
+
+__all__ = ["sanitize_context", "sanitizes"]

beware/sanitization/_context.py

@@ -0,0 +1,36 @@
+from contextlib import contextmanager
+from typing import Any
+
+from beware._unsafe import unsafe_context
+
+
+@contextmanager
+def sanitize_context(*attrs: Any):
+    """Context manager for marking the specified attributes as sanitized after assignment
+
+    Parameters
+    ----------
+    attrs : tuple[Unsafe, ...]
+            arguments that are sanitized after an assignment
+
+    Examples
+    --------
+    >>> class MyClass:
+    ...     a = unsafe()
+    >>> obj = MyClass()
+    >>> with sanitize_context(MyClass.a):
+    ...     instance.a = "sanitized"
+    >>> instance.a # can be accessed outside an unsafe_context
+    "sanitized"
+    """
+
+    with unsafe_context(*attrs):
+        try:
+            for attr in attrs:
+                attr._sanitize_on_assignment = True
+
+            yield
+
+        finally:
+            for attr in attrs:
+                attr._sanitize_on_assignment = False

beware/sanitization/_decorator.py

@@ -0,0 +1,84 @@
+import inspect
+from functools import wraps
+from typing import Callable, ParamSpec, TypeVar, cast
+
+from beware._unsafe import Unsafe
+from ._context import sanitize_context
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def sanitizes(
+    *attrs: Unsafe,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Decorator factory that marks all given attrs as safe after the function executes without
+    exceptions.
+
+    Parameters
+    ----------
+    attrs : tuple[Unsafe, ...]
+            arguments that are sanitized on attribution,
+
+
+    Returns
+    -------
+    A decorated function that will sanitize all given unsafe attributes when modified
+    inside the function
+
+
+    Examples
+    --------
+    >>> class MyClass:
+    ...     a = unsafe()
+    ...
+    >>> @sanitizes(MyClass.a)
+    ... def sanitize_a(instance:MyClass):
+    ...     instance.a = "sanitized"
+    ...
+    >>> obj = MyClass()
+    >>> sanitize_a(MyClass.a):
+    ...     instance.a = "sanitized"
+    ...
+    >>> sanitize_a(obj)
+    >>> obj.a # can be accessed outside of an unsafe context
+    "sanitized"
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+
+        # mypy can't resolve the return type correctly when using functool.wraps, thus the casts
+        # Full thread: https://stackoverflow.com/questions/78807798/mypy-1-10-reports-error-when-functools-wraps-is-used-on-a-generic-function
+
+        if inspect.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def a_inner_function(*args: P.args, **kwargs: P.kwargs):
+                try:
+                    with sanitize_context(*attrs):
+                        result = await func(*args, **kwargs)
+
+                        return result
+                except:
+                    raise
+
+            return cast(Callable[P, R], a_inner_function)
+
+        elif callable(func):
+
+            @wraps(func)
+            def inner_function(*args: P.args, **kwargs: P.kwargs):
+                try:
+                    with sanitize_context(*attrs):
+                        result = func(*args, **kwargs)
+
+                        return result
+                except:
+                    raise
+
+            return cast(Callable[P, R], inner_function)
+
+        else:
+            raise TypeError  # pyright: ignore[reportUnreachable]
+
+    return decorator

beware-0.1.0.dist-info/METADATA

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: beware
+Version: 0.1.0
+Summary: A pure python package with zero dependencies that provides functions to track the usage of unsafe attributes on the code and perform sanitization.
+License: LGPLv3+
+License-File: LICENSE
+Keywords: sanitization,security
+Author: João Pedro
+Author-email: joaopedroph.dev@gmail.com
+Requires-Python: >=3.10
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Project-URL: Repository, https://github.com/Joao-Pedro-P-Holanda/beware
+Description-Content-Type: text/markdown
+
+# Beware
+![PyPI Version](https://img.shields.io/pypi/v/beware)
+![PyPI Python Versions](https://img.shields.io/pypi/pyversions/beware)
+
+Beware is a pure python package with zero dependencies that provides functions to track the usage of
+unsafe attributes on the code and perform sanitization.
+
+## Features
+
+- Define attributes that need to be sanitized with Python descriptors
+- Declare functions or blocks of code to perform sanitization
+
+
+## Alternatives
+
+- [ItsDangerous](https://itsdangerous.palletsprojects.com/en/stable/): use it if you need to transmit data through an unsafe medium and guarantee that it is not tampered
+
+## Roadmap
+
+- [ ] Publish code documentation
+- [ ] Add doctests for docstrings
+- [ ] Define a pytest plugin to allow easier checks of unsafe access without modifying the source code
+
+

beware-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+beware/__init__.py,sha256=euD8BndOHbzK5RFlNa1AMly3_KwiVRMuHn1oYwLA5ic,189
+beware/_unsafe/__init__.py,sha256=NIfBgldgRi4kZuPiL46njTK9hje47jSspHvKdc0cMA4,181
+beware/_unsafe/_context.py,sha256=Wlr4qW0-YPiLES9R6ivFUQhG9MZ3gmMyhML72NpeGmE,1258
+beware/_unsafe/_context_vars.py,sha256=zYD5tXB-qFXrRGcDDzBUX8nw-PXhs5oeIEq1MalTKZI,135
+beware/_unsafe/_descriptor.py,sha256=WshXoaZA2Pmt4Pp0w3OHuN6FNyZ5S8vr1AqDeNKImHg,3798
+beware/exceptions/__init__.py,sha256=NR40c8JOOqZkUVkJomzcVOLYAP6RsWWmF2jDhovd4to,278
+beware/sanitization/__init__.py,sha256=VuRdktzHoldEwQxiDISsHcesznI0hWCITDuFEWNUqlo,118
+beware/sanitization/_context.py,sha256=q5dg77hAbWCDO5KP0NO0l819NjeQ9LKqPoWlRLnbdSE,886
+beware/sanitization/_decorator.py,sha256=bQ_3J_1kAzybcES9r_ZoOcf3hNsdGMBodHEHEq8mH78,2300
+beware-0.1.0.dist-info/METADATA,sha256=LM1-lwJQtDLov91sz-bonG1ka6CCqIa1hFfxP_-1dhs,1682
+beware-0.1.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+beware-0.1.0.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
+beware-0.1.0.dist-info/RECORD,,

beware-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

beware-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.