devstatusdecos 0.0.0.0__py3-none-any.whl

devstatusdecos/__init__.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python
+
+"""
+    devstatusdecos
+
+    Decorators, warnings, and exceptions related to documentation
+    of the development statuses of classes, functions, and other objects.
+"""
+
+__all__ = ["deprecated",
+           "superseded",
+           "insecure",
+           "pending_deprecation",
+           "experimental",
+           "todo",
+           "TODO",
+           "fixme",
+           "FIXME",
+           "InsecureError",
+           "FatallyInsecureError",
+           "ExperimentalWarning",
+           "TodoWarning",
+           "TodoError"
+           ]
+
+__version__ = "v0.0.0.0"
+
+from .devstatusdecos import *

devstatusdecos/_type_imports.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python
+
+"""
+    _type_imports
+
+    Various imports related to type annotations.
+    Not expected to be imported on it's own.
+"""
+# pylint:disable=unused-import
+
+
+from sys import version_info
+
+
+try:
+    from typing import LiteralString  # noqa:F401
+except ImportError:
+    from typing_extensions import LiteralString  # noqa:F401
+
+
+try:
+    from typing import Type  # noqa:F401
+except ImportError:
+    from typing_extensions import Type  # noqa:F401
+
+
+try:
+    from typing import Generic  # noqa:F401
+except ImportError:
+    from typing_extensions import Generic  # noqa:F401
+
+
+try:
+    from typing import TypeVar  # noqa:F401
+except ImportError:
+    from typing_extensions import TypeVar  # noqa:F401
+
+
+try:
+    from typing import overload
+except ImportError:
+    from typing_extensions import overload  # noqa:F401
+
+
+try:
+    from typing import Callable
+except ImportError:
+    from typing_extensions import Callable  # noqa:F401
+
+
+try:
+    from typing import Any  # noqa:F401
+except ImportError:
+    from typing_extensions import Any  # noqa:F401
+
+
+try:
+    from typing import ParamSpec  # noqa:F401
+except ImportError:
+    from typing_extensions import ParamSpec  # noqa:F401
+
+
+try:
+    from typing import Never  # noqa:F401
+except ImportError:
+    from typing_extensions import Never  # noqa:F401
+
+
+try:
+    from typing import cast  # noqa:F401
+except ImportError:
+    from typing_extensions import cast  # noqa:F401
+
+
+try:
+    from typing import TypeAlias  # noqa:F401
+except ImportError:
+    from typing_extensions import TypeAlias  # noqa:F401
+
+
+try:
+    from typing import Tuple  # noqa:F401
+except ImportError:
+    from typing_extensions import Tuple  # noqa:F401
+
+
+try:
+    from typing import NoReturn  # noqa:F401
+except ImportError:
+    from typing_extensions import NoReturn  # noqa:F401
+
+
+VersionInfoTuple:TypeAlias = (Tuple[int, int, int, LiteralString, int] |
+                              Tuple[int, int, int, LiteralString] |
+                              Tuple[int, int, int] |
+                              Tuple[int, int] |
+                              Tuple[int] |
+                              Tuple[()] |
+                              None
+                              )
+
+
+T = TypeVar("T")
+
+
+PS = ParamSpec("PS")
+
+
+if version_info >= (3, 13):
+    RT = TypeVar("RT", default=None)  # type:ignore
+else:
+    RT = TypeVar("RT")
+
+
+if version_info >= (3, 13):
+    VersionInfoTupleT = TypeVar("VersionInfoTupleT",
+                                bound = VersionInfoTuple,
+                                default = None  # type:ignore
+                                )
+else:
+    VersionInfoTupleT = TypeVar("VersionInfoTupleT",
+                                bound = VersionInfoTuple
+                                )
+
+
+del version_info

devstatusdecos/devstatusdecos.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python
+
+"""
+    devstatusdecos
+
+    Decorators, warnings, and exceptions related to documentation
+    of the development statuses of classes, functions, and other objects.
+"""
+
+__all__ = ["deprecated",
+           "superseded",
+           "insecure",
+           "pending_deprecation",
+           "experimental",
+           "todo",
+           "TODO",
+           "fixme",
+           "FIXME",
+           "InsecureError",
+           "FatallyInsecureError",
+           "ExperimentalWarning",
+           "TodoWarning",
+           "TodoError"
+           ]
+
+from warnings import simplefilter
+from functools import wraps
+from sys import version_info
+
+from ._type_imports import *  # pylint:disable=wildcard-import,unused-wildcard-import
+
+try:
+    from typing_extensions import deprecated
+except ImportError as e:
+    if version_info < (3, 13, 3):
+        raise e  # there is a bug in __new__ for previous versions
+    else:
+        # pylint:disable-next=ungrouped-imports
+        from warnings import deprecated  # pyright:ignore[reportAttributeAccessIssue]
+deprecated = cast(Type, deprecated)
+superseded = deprecated
+
+
+class InsecureError(RuntimeError):
+    """
+    An exception raised when a `insecure` Callable is executed.
+
+    This is a subclass of `RuntimeError`
+    and is used to indicate that a function or class is in some way insecure
+    and should not be allowed to execute further.
+    This exception is used mainly by the `insecure` decorator.
+    """
+
+
+class FatallyInsecureError(InsecureError, SystemExit):
+    """
+    An extention of `InsecureError`, raised in conditions where a function or class
+    should raise an error that attempts to force termination of execution via an exception.
+    """
+    def __init__(self, *args: object, code:int = 1) -> None:
+        super(InsecureError, self).__init__(*args)
+        self.code = code
+
+
+class ExperimentalWarning(Warning):
+    """A warning used to indicate that a function or class
+    is experimental and may change at any time."""
+
+
+simplefilter('default', ExperimentalWarning)
+
+
+class TodoWarning(ExperimentalWarning):
+    """A warning used to indicate that a function or class
+    contains something todo and likely is missing a key part of
+    its functionality and may change at any time or even be removed.
+    This will also always be raised as a error when a `todo`
+    `Callable` is called."""
+
+
+simplefilter('always', TodoWarning)
+
+
+class TodoError(NotImplementedError):
+    """
+    An exception raised when a `todo` Callable is executed.
+
+    This is a subclass of `NotImplementedError` and is used to indicate that
+    a function or class contains a todo and is likely missing a key part of
+    its functionality. This exception is used mainly by the `todo` decorator.
+    """
+
+
+class insecure():  # pylint:disable=invalid-name
+    """A decorator that marks a class,
+    function or method as insecure, indicating that it
+    should not be allowed to execute further.
+    Unlike other dev stats decorators,
+    this replaces the a decorated callable or type entirely with
+    a callable that raises an error,
+    which may confuse some type checkers.
+
+    While not intended for use on things besides types or callables,
+    the exception will be raised immediately in cases there the decorated
+    object is not callable.
+    """
+
+    def __init__(self,
+                 message:str,
+                 fatal:bool,
+                 code:int = 1,
+                 ):
+        self.exc = FatallyInsecureError(message, code = code)
+        if not fatal:
+            self.exc = InsecureError(message)
+        self.code = code
+
+    def __call__(self, arg:Any) -> Callable[..., NoReturn]:  # noqa:F811, E301
+        if not callable(arg):
+            # its already possibly to late, but lets stop anyway
+            raise self.exc
+
+        def __wrapper(*_, **__):
+            raise self.exc
+
+        return __wrapper
+
+
+class pending_deprecation(deprecated, Generic[VersionInfoTupleT]):  # pylint:disable=invalid-name
+    """A decorator that indicates that the decorated class, function,
+    or method is pending deprecation.
+
+    Note that this inherits the native `deprecated` decorator,
+    so some introspective tools might falsely flag this as
+    a deprecated function instead."""
+
+    def __init__(self,
+                 message:LiteralString,
+                 /,
+                 *,
+                 pending_category:Type[DeprecationWarning | PendingDeprecationWarning
+                                       ]|None = PendingDeprecationWarning,
+                 deprecated_category:Any = ...,  # pylint:disable=unused-argument
+                 stacklevel:int = 1,
+                 deprecate_py_ver:Any = ...  # pylint:disable=unused-argument
+                 ):
+        super().__init__(message, category=pending_category, stacklevel=stacklevel)
+
+    def __new__(cls,
+                message:LiteralString,
+                /,
+                *,
+                pending_category:Type[DeprecationWarning | PendingDeprecationWarning
+                                      ]|None = PendingDeprecationWarning,
+                deprecated_category:Type[DeprecationWarning
+                                         ]|None = DeprecationWarning,
+                stacklevel:int = 1,
+                deprecate_py_ver:VersionInfoTupleT = None
+                ):
+        if deprecate_py_ver is not None and version_info >= deprecate_py_ver:
+            return deprecated(message, category=deprecated_category, stacklevel=stacklevel)
+        return super().__new__(cls)
+
+
+class experimental(deprecated):  # pylint:disable=invalid-name
+    """A decorator that marks a class,
+    function or method as experimental and should be used with caution.
+    Note that this inherits the native `deprecated` decorator,
+    so some introspective tools might falsely flag this as
+    a deprecated function instead."""
+
+    def __init__(self,
+                 message:LiteralString,
+                 /,
+                 *,
+                 category:Type[Warning]|None = ExperimentalWarning,
+                 stacklevel:int = 1):
+        super().__init__(message, category=category, stacklevel=stacklevel)
+
+
+class todo(experimental):  # pylint:disable=invalid-name
+    """
+    A decorator that marks a class, function, or method as todo and is
+    presumed to be missing a key part of it's functionality.
+    It may change at any time or even removed.
+
+    This will always raise a `TodoError` when a `todo`
+    Callable is called (or Type is initalized),
+    unless `error_condition`
+    is truthy or a callable that will return `True`.
+    `error_condition` will always be checked when the wrapped
+    function is called.
+
+    The constructor matches the same parameters as `deprecated`,
+    in exception for the fact that the default warning type is a
+    `TodoWarning` and that 'TODO:' is always appended to the message.
+    """
+
+    # Sadly there is not way to easily make type checkers
+    # recognise this besides making a plugin for this,
+    # so we have to piggyback off of the deprecation
+    # detection in all the type checkers for now.
+
+    TODO_PREFIX:LiteralString = "TODO: "
+
+    def __init__(self,
+                 message:LiteralString,
+                 error_condition:Callable[[Any], bool] | None = None,
+                 /,
+                 *,
+                 category:Type[Warning] | None = TodoWarning,
+                 stacklevel:int = 1
+                 ):
+        if not message.startswith(self.TODO_PREFIX):
+            message = self.TODO_PREFIX + message
+        super().__init__(message,
+                         category=category,
+                         stacklevel=stacklevel
+                         )
+        self.error_condition = error_condition
+
+    @overload
+    def __call__(self,  # noqa:F811, E302
+                 arg:Callable[PS, RT],
+                 /,
+                 ) -> Callable[PS, RT|Never]:
+        ...
+
+    @overload  # noqa:E301
+    def __call__(self, arg:T, /) -> T:  # noqa:F811, E302
+        ...
+
+    def __call__(self, arg:Any, /) -> Any:  # noqa:F811, E301
+        arg = super().__call__(arg)
+        d = f"{self.message}\n{getattr(arg, '__doc__', '')}".strip()
+        setattr(arg, "__doc__", d)
+        if callable(arg):
+            @wraps(arg, assigned=("__module__", "__name__", "__qualname__", "__doc__"))
+            def __wrapper(*args, **kwargs):
+                if self.error_condition is not None and self.error_condition(arg):
+                    raise TodoError(self.message)
+                return arg(*args, **kwargs)
+            return __wrapper
+        return arg
+
+
+TODO = todo
+fixme = todo  # pylint:disable=invalid-name
+FIXME = todo

devstatusdecos-0.0.0.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: devstatusdecos
+Version: 0.0.0.0
+Summary: Decorators, warnings, and exceptions for explicitly marking the development status of Python objects
+Author-email: Markus Hammer <107761433+MarkusHammer@users.noreply.github.com>
+License: Copyright © 2026 Markus Hammer
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/MarkusHammer/devstatusdecos
+Project-URL: Documentation, https://MarkusHammer.gthub.io/devstatusdecos
+Project-URL: Github, https://github.com/MarkusHammer/devstatusdecos
+Project-URL: Issues, https://github.com/MarkusHammer/devstatusdecos/issues
+Project-URL: Pull Requests, https://github.com/MarkusHammer/devstatusdecos/pulls
+Project-URL: Git, https://github.com/MarkusHammer/devstatusdecos.git
+Keywords: api,decorators,deprecation,design,development,experimental,fixme,management,pending,qa,quality,runtime,simple,single,small,stability,todo,tools,utils,validation,warnings
+Classifier: Intended Audience :: Developers
+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
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Classifier: Natural Language :: English
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: typing_extensions; python_version < "3.13.3"
+Provides-Extra: dev
+Requires-Dist: setuptools>=64.0.0; extra == "dev"
+Requires-Dist: pipreqs; extra == "dev"
+Requires-Dist: validate-pyproject[all]; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: pdoc3; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Dynamic: license-file
+
+# `devstatusdecos`
+
+> Decorators, warnings, and exceptions for explicitly marking the development status of Python objects.
+
+[![CodeQL](https://github.com/MarkusHammer/devstatusdecos/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/MarkusHammer/devstatusdecos/actions/workflows/github-code-scanning/codeql) [![Ko-Fi](https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge&logo=ko-fi&logoColor=white)](https://ko-fi.com/markushammer)
+
+This module provides structured, runtime-enforced annotations for things like deprecation, experimental APIs, insecure code paths, and unfinished implementations.
+
+[Documentation](https://MarkusHammer.github.io/devstatusdecos)
+
+## Features
+
+- Imports (and requires access to) the `deprecated` decorator from either `typing_extensions` or `warnings`. `typing_extensions` is requires for python < 3.13.3.
+- `pending_deprecation`, which raises the builtin `PendingDeprecationWarning` with optional the option of automatic escalation to `deprecated` status based on python version.
+- `experimental`, analogous to `deprecated`, raises a `ExperimentalWarning` warning when called.
+- `todo`, analogous to `deprecated`, raises a `ExperimentalWarning` warning when called, optionally raising a `TodoError` in a wrapped callable.
+- `insecure`, which always raises a `InsecureError` or `FatallyInsecureError`, optionally exiting.
+
+## Installation
+
+   `pip install devstatusdecos`
+
+## Example
+
+   ``` python
+   from devstatusdecos import experimental, todo, insecure
+
+   @experimental("API may change")
+   def new_feature():
+      ...
+
+   @todo("Implement edge case handling")
+   class Incomplete():
+      def __init__(self):
+         ...
+
+   @insecure("Uses unsafe cryptography", fatal=True)
+   def bad_idea():
+      ...
+   ```
+
+# Security Policy
+
+While the python source code will be actively maintained, any binary files (if at all provided) are in no way supported.
+These are provided as a courtesy and are not intended to be the main usage of this software.
+Please keep this in mind when choosing how you wish to use this software.
+
+## Supported Versions
+
+| Version     | Supported |
+| ----------- | --------- |
+| 0.0.0.0 <   | ❌        |
+
+## Reporting a Vulnerability
+
+Please report any issues to the email 107761433+MarkusHammer{THEN THE @ SYMBOL HERE}users.noreply.github.com
+
+Copyright © 2026 Markus Hammer
+
+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.

devstatusdecos-0.0.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+devstatusdecos/__init__.py,sha256=VSXGqq4Ocs8cpS8hfJH3NZSQI2cC2NJipBd75TfCNf8,620
+devstatusdecos/_type_imports.py,sha256=FU9MDRZvut4QJ2jPCZg4vIaYSSX8dFkaqEJKOLJy-vA,2771
+devstatusdecos/devstatusdecos.py,sha256=SOJu-FrYvJo_i7O3WW0aouso2q5seNWX1ITVkJlmyzc,8667
+devstatusdecos/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+devstatusdecos-0.0.0.0.dist-info/licenses/LICENCE,sha256=Mr_EX1s02EQAObw8hZ0USOnPx37-NzxGMpHmIezld8Y,1064
+devstatusdecos-0.0.0.0.dist-info/METADATA,sha256=W02ftgljBnFYiE_ZWxMFvzMP-Td2tAZX0N7oiLnSInc,6800
+devstatusdecos-0.0.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+devstatusdecos-0.0.0.0.dist-info/top_level.txt,sha256=iIHJAOL6jqt2GGL_YeX2WLxXkNAC4wbY1LRzUiWR_B4,15
+devstatusdecos-0.0.0.0.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+devstatusdecos-0.0.0.0.dist-info/RECORD,,

devstatusdecos-0.0.0.0.dist-info/WHEEL

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

devstatusdecos-0.0.0.0.dist-info/licenses/LICENCE

@@ -0,0 +1,7 @@
+Copyright © 2026 Markus Hammer
+
+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.

devstatusdecos-0.0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+devstatusdecos

devstatusdecos-0.0.0.0.dist-info/zip-safe

@@ -0,0 +1 @@
+