jetpytools 2.1.1__tar.gz → 2.2.1__tar.gz

jetpytools-2.2.1/.gitignore

@@ -0,0 +1,233 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+.cache/
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# versioningit
+jetpytools/_version.py
+
+# DEVELOPERS:
+# Before adding a file directory to this .gitignore,
+# check if it should maybe go in your local .gitignore
+# (.git/info/exclude), or your own user-wide .gitignore
+# (https://sebastiandedeyne.com/setting-up-a-global-gitignore-file/)
+# instead.
+# Repository-specific files (Python cache files, build artifacts,
+# coverage reports, etc.) should go in here, user-specific files
+# (IDE folders, video index files, etc.) shouldn't.
+
+# JET files
+.vsjet/

{jetpytools-2.1.1 → jetpytools-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetpytools
-Version: 2.1.1
+Version: 2.2.1
 Summary: Collection of stuff that's useful in general python programming
 Project-URL: Source Code, https://github.com/Jaded-Encoding-Thaumaturgy/jetpytools
 Project-URL: Contact, https://discord.gg/XTpc6Fa9eB
@@ -16,23 +16,19 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: typing-extensions>=4.15.0
+Requires-Dist: typing-extensions>=4.15.0; python_version < '3.13'
 Description-Content-Type: text/markdown
 
 # jetpytools
 
-Collection of stuff that's useful in general python programming
+[![PyPI Version](https://img.shields.io/pypi/v/jetpytools)](https://pypi.org/project/jetpytools/)
+
+A collection of utilities useful for general Python programming.
 
 ## How to install
 
-Install `jetpytools` with the following command:
+`jetpytools` is distributed via **PyPI**, and the latest stable release can be installed using:
 
 ```sh
 pip install jetpytools
 ```
-
-Or if you want the latest git version, install it with this command:
-
-```sh
-pip install git+https://github.com/Jaded-Encoding-Thaumaturgy/jetpytools.git
-```

jetpytools-2.2.1/README.md

@@ -0,0 +1,13 @@
+# jetpytools
+
+[![PyPI Version](https://img.shields.io/pypi/v/jetpytools)](https://pypi.org/project/jetpytools/)
+
+A collection of utilities useful for general Python programming.
+
+## How to install
+
+`jetpytools` is distributed via **PyPI**, and the latest stable release can be installed using:
+
+```sh
+pip install jetpytools
+```

jetpytools-2.2.1/jetpytools/__init__.py

@@ -0,0 +1,16 @@
+"""A collection of utilities useful for general Python programming."""
+
+from .enums import *
+from .exceptions import *
+from .functions import *
+from .types import *
+from .utils import *
+
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+
+try:
+    from ._version import __version__, __version_tuple__
+except ImportError:
+    __version__ = "0.0.0+unknown"
+    __version_tuple__ = (0, 0, 0, "+unknown")

jetpytools-2.2.1/jetpytools/_version.py

@@ -0,0 +1,2 @@
+__version__ = "2.2.1"
+__version_tuple__ = (2, 2, 1)

{jetpytools-2.1.1 → jetpytools-2.2.1}/jetpytools/enums/base.py

@@ -42,12 +42,15 @@ class CustomEnum(Enum):
         """
         Return the enum value from a parameter.
 
-        :param value:               Value to instantiate the enum class.
-        :param func_except:         Exception function.
+        Args:
+            value: Value to instantiate the enum class.
+            func_except: Exception function.
 
-        :return:                    Enum value.
+        Returns:
+            Enum value.
 
-        :raises NotFoundEnumValue:   Variable not found in the given enum.
+        Raises:
+            NotFoundEnumValue: Variable not found in the given enum.
         """
         func_except = func_except or cls.from_param
 
@@ -78,6 +81,7 @@ class CustomIntEnum(int, CustomEnum, ReprEnum):
 
     if TYPE_CHECKING:
         _value_: int
+        _value2member_map_: dict[int, Enum]
 
         @enum_property
         def value(self) -> int: ...
@@ -88,6 +92,7 @@ class CustomStrEnum(str, CustomEnum, ReprEnum):
 
     if TYPE_CHECKING:
         _value_: str
+        _value2member_map_: dict[str, Enum]
 
         @enum_property
         def value(self) -> str: ...

{jetpytools-2.1.1 → jetpytools-2.2.1}/jetpytools/enums/other.py

@@ -9,7 +9,8 @@ class Coordinate:
     """
     Positive set of (x, y) coordinates.
 
-    :raises ValueError:     Negative values were passed.
+    Raises:
+        ValueError: Negative values were passed.
     """
 
     x: int

{jetpytools-2.1.1 → jetpytools-2.2.1}/jetpytools/exceptions/base.py

@@ -2,11 +2,8 @@ from __future__ import annotations
 
 import sys
 from contextlib import AbstractContextManager
-from copy import deepcopy
 from types import TracebackType
-from typing import TYPE_CHECKING, Any
-
-from typing_extensions import Self
+from typing import Any, Self
 
 from ..types import MISSING, FuncExcept, MissingT, SupportsString
 
@@ -23,59 +20,26 @@ __all__ = [
 ]
 
 
-if TYPE_CHECKING:
-
-    class ExceptionError(Exception):
-        __name__: str
-        __qualname__: str
-else:
-    ExceptionError = Exception
-
-
 class CustomErrorMeta(type):
     """Custom base exception meta class."""
 
-    def __new__[MetaSelf: CustomErrorMeta](cls: type[MetaSelf], *args: Any) -> MetaSelf:
-        return CustomErrorMeta.setup_exception(super().__new__(cls, *args))
-
-    @staticmethod
-    def setup_exception[MetaSelf: CustomErrorMeta](
-        exception: MetaSelf, override: str | ExceptionError | None = None
+    def __new__[MetaSelf: CustomErrorMeta](
+        mcls: type[MetaSelf], name: str, bases: tuple[type, ...], namespace: dict[str, Any], /, **kwds: Any
     ) -> MetaSelf:
-        """
-        Setup an exception for later use in CustomError.
-
-        :param exception:   Exception to update.
-        :param override:    Optional name or exception from which get the override values.
-
-        :return:            Set up exception.
-        """
-
-        if override:
-            if isinstance(override, str):
-                over_name = over_qual = override
-            else:
-                over_name, over_qual = override.__name__, override.__qualname__
-
-            if over_name.startswith("Custom"):
-                exception.__name__ = over_name
-            else:
-                exception.__name__ = f"Custom{over_name}"
-
-            exception.__qualname__ = over_qual
+        cls = super().__new__(mcls, name, bases, namespace, **kwds)
 
-        if exception.__qualname__.startswith("Custom"):
-            exception.__qualname__ = exception.__qualname__[6:]
+        if cls.__qualname__.startswith("Custom"):
+            cls.__qualname__ = cls.__qualname__[6:]
 
         if sys.stdout and sys.stdout.isatty():
-            exception.__qualname__ = f"\033[0;31;1m{exception.__qualname__}\033[0m"
+            cls.__qualname__ = f"\033[0;31;1m{cls.__qualname__}\033[0m"
 
-        exception.__module__ = Exception.__module__
+        cls.__module__ = Exception.__module__
 
-        return exception
+        return cls
 
 
-class CustomError(ExceptionError, metaclass=CustomErrorMeta):
+class CustomError(Exception, metaclass=CustomErrorMeta):
     """Custom base exception class."""
 
     def __init__(
@@ -84,9 +48,10 @@ class CustomError(ExceptionError, metaclass=CustomErrorMeta):
         """
         Instantiate a new exception with pretty printing and more.
 
-        :param message: Message of the error.
-        :param func:    Function this exception was raised from.
-        :param reason:  Reason of the exception. For example, an optional parameter.
+        Args:
+            message: Message of the error.
+            func: Function this exception was raised from.
+            reason: Reason of the exception. For example, an optional parameter.
         """
 
         self.message = message
@@ -106,10 +71,12 @@ class CustomError(ExceptionError, metaclass=CustomErrorMeta):
         """
         Copy an existing exception with defaults and instantiate a new one.
 
-        :param message: Message of the error.
-        :param func:    Function this exception was raised from.
-        :param reason:  Reason of the exception. For example, an optional parameter.
+        Args:
+            message: Message of the error.
+            func: Function this exception was raised from.
+            reason: Reason of the exception. For example, an optional parameter.
         """
+        from copy import deepcopy
 
         err = deepcopy(self)
 

{jetpytools-2.1.1 → jetpytools-2.2.1}/jetpytools/exceptions/file.py

@@ -1,7 +1,14 @@
 from __future__ import annotations
 
+import sys
+
 from .base import CustomError, CustomPermissionError
 
+if sys.version_info < (3, 13):
+    from typing_extensions import deprecated
+else:
+    from warnings import deprecated
+
 __all__ = [
     "FileIsADirectoryError",
     "FileNotExistsError",
@@ -24,6 +31,7 @@ class FilePermissionError(CustomPermissionError):
     """Raised when you try to access a file but haven't got permissions to do so"""
 
 
+@deprecated("FileTypeMismatchError is deprecated and will be removed in a future version.", category=DeprecationWarning)
 class FileTypeMismatchError(CustomError, OSError):
     """Raised when you try to access a file with a FileType != AUTO and it's another file type"""
 

{jetpytools-2.1.1 → jetpytools-2.2.1}/jetpytools/exceptions/module.py

@@ -19,9 +19,10 @@ class CustomImportError(CustomError, ImportError):
         **kwargs: Any,
     ) -> None:
         """
-        :param func:        Function this error was raised from.
-        :param package:     Either the raised error or the name of the missing package.
-        :param message:     Custom error message.
+        Args:
+            func: Function this error was raised from.
+            package: Either the raised error or the name of the missing package.
+            message: Custom error message.
         """
 
         super().__init__(message, func, package=package if isinstance(package, str) else package.name, **kwargs)

{jetpytools-2.1.1 → jetpytools-2.2.1}/jetpytools/functions/funcs.py

@@ -1,10 +1,9 @@
 from __future__ import annotations
 
-from inspect import signature
 from typing import Any, Callable, Concatenate, overload
 
 from ..exceptions import CustomRuntimeError, CustomValueError
-from ..types import MISSING, KwargsT, MissingT
+from ..types import KwargsT
 
 __all__ = ["fallback", "filter_kwargs", "iterate", "kwargs_fallback"]
 
@@ -18,19 +17,21 @@ def iterate[T, **P, R](
     Different from regular iteration functions is that you do not need to pass a partial object.
     This function accepts *args and **kwargs. These will be passed on to the given function.
 
-    Examples:
-
-    >>> iterate(5, lambda x: x * 2, 2)
+    - Example:
+        ```python
+        >>> iterate(5, lambda x: x * 2, 2)
         20
+        ```
 
-    :param base:        Base value, etc. to iterate over.
-    :param function:    Function to iterate over the base.
-    :param count:       Number of times to execute function.
-    :param *args:       Positional arguments to pass to the given function.
-    :param **kwargs:    Keyword arguments to pass to the given function.
+    Args:
+        base: Base value, etc. to iterate over.
+        function: Function to iterate over the base.
+        count: Number of times to execute function.
+        *args: Positional arguments to pass to the given function.
+        **kwargs: Keyword arguments to pass to the given function.
 
-    :return:            Value, etc. with the given function run over it
-                        *n* amount of times based on the given count.
+    Returns:
+        Value, etc. with the given function run over it *n* amount of times based on the given count.
     """
 
     if count <= 0:
@@ -44,90 +45,49 @@ def iterate[T, **P, R](
     return result
 
 
-fallback_missing = object()
-
-
-@overload
-def fallback[T](value: T | None, fallback: T, /) -> T: ...
-
-
-@overload
-def fallback[T](value: T | None, fallback0: T | None, default: T, /) -> T: ...
-
-
-@overload
-def fallback[T](value: T | None, fallback0: T | None, fallback1: T | None, default: T, /) -> T: ...
+_fallback_missing = object()
 
 
 @overload
-def fallback[T](value: T | None, *fallbacks: T | None) -> T | MissingT: ...
-
-
+def fallback[T](value: T | None, *fallbacks: T | None) -> T: ...
 @overload
 def fallback[T](value: T | None, *fallbacks: T | None, default: T) -> T: ...
-
-
-def fallback[T](value: T | None, *fallbacks: T | None, default: Any | T = fallback_missing) -> T | MissingT:
+def fallback[T](value: T | None, *fallbacks: T | None, default: Any = _fallback_missing) -> T:
     """
     Utility function that returns a value or a fallback if the value is None.
 
-    Example:
-
-    .. code-block:: python
-
+    - Example:
+        ```python
         >>> fallback(5, 6)
         5
         >>> fallback(None, 6)
         6
+        ```
 
-    :param value:               Input value to evaluate. Can be None.
-    :param fallback_value:      Value to return if the input value is None.
+    Args:
+        value: Input value to evaluate. Can be None.
+        *fallbacks: Value to return if the input value is None.
 
-    :return:                    Input value or fallback value if input value is None.
+    Returns:
+        Input value or fallback value if input value is None.
     """
+    for v in (value, *fallbacks):
+        if v is not None:
+            return v
 
-    if value is not None:
-        return value
-
-    for fallback in fallbacks:
-        if fallback is not None:
-            return fallback
-
-    if default is not fallback_missing:
+    if default is not _fallback_missing:
         return default
-    elif len(fallbacks) > 3:
-        return MISSING
 
     raise CustomRuntimeError("You need to specify a default/fallback value!")
 
 
 @overload
-def kwargs_fallback[T](input_value: T | None, kwargs: tuple[KwargsT, str], fallback: T, /) -> T: ...
-
-
-@overload
-def kwargs_fallback[T](input_value: T | None, kwargs: tuple[KwargsT, str], fallback0: T | None, default: T, /) -> T: ...
-
-
+def kwargs_fallback[T](value: T | None, kwargs: tuple[KwargsT, str], *fallbacks: T | None) -> T: ...
 @overload
+def kwargs_fallback[T](value: T | None, kwargs: tuple[KwargsT, str], *fallbacks: T | None, default: T) -> T: ...
 def kwargs_fallback[T](
-    input_value: T | None, kwargs: tuple[KwargsT, str], fallback0: T | None, fallback1: T | None, default: T, /
-) -> T: ...
-
-
-@overload
-def kwargs_fallback[T](input_value: T | None, kwargs: tuple[KwargsT, str], /, *fallbacks: T | None) -> T | MissingT: ...
-
-
-@overload
-def kwargs_fallback[T](
-    input_value: T | None, kwargs: tuple[KwargsT, str], /, *fallbacks: T | None, default: T
-) -> T: ...
-
-
-def kwargs_fallback[T](
-    value: T | None, kwargs: tuple[KwargsT, str], *fallbacks: T | None, default: Any | T = fallback_missing
-) -> T | MissingT:
+    value: T | None, kwargs: tuple[KwargsT, str], *fallbacks: T | None, default: Any = _fallback_missing
+) -> T:
     """Utility function to return a fallback value from kwargs if value was not found or is None."""
 
     return fallback(value, kwargs[0].get(kwargs[1], None), *fallbacks, default=default)
@@ -145,25 +105,30 @@ def filter_kwargs(func: Callable[..., Any], kwargs: dict[str, Any] | None = None
     """
     Filter kwargs to only include parameters that match the callable's signature, ignoring **kwargs.
 
-    Examples:
-
+    - Examples:
+        ```python
         >>> def my_func(a: int, b: str, c: bool = True):
         ...     return a, b, c
         >>> filter_kwargs(my_func, a=1, b="hello", c=False, d="extra")
         {'a': 1, 'b': 'hello', 'c': False}
         >>> filter_kwargs(my_func, {"a": 1, "b": "hello", "c": False, "d": "extra"})
         {'a': 1, 'b': 'hello', 'c': False}
+        ```
 
-    :param func:        The callable to filter kwargs for.
-    :param kwargs:      Dictionary of keyword arguments to filter.
-    :param **kw:        Keyword arguments to filter (used when kwargs is None).
+    Args:
+        func: The callable to filter kwargs for.
+        kwargs: Dictionary of keyword arguments to filter.
+        **kw: Keyword arguments to filter (used when kwargs is None).
 
-    :return:            A dictionary containing only the kwargs that match the callable's parameters.
+    Returns:
+        A dictionary containing only the kwargs that match the callable's parameters.
     """
 
     if not (filtered_kwargs := fallback(kwargs, kw)):
         return {}
 
+    from inspect import signature
+
     try:
         sig = signature(func)
     except Exception as e: