datahold 3.0.0.dev4__tar.gz → 3.0.0.dev40__tar.gz

{datahold-3.0.0.dev4 → datahold-3.0.0.dev40}/LICENSE.txt

@@ -18,4 +18,4 @@ 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.
+SOFTWARE.

datahold-3.0.0.dev40/MANIFEST.in

@@ -0,0 +1,4 @@
+include run_tests.py
+recursive-include docs *.rst
+recursive-include src *.toml
+recursive-include tests *.toml

datahold-3.0.0.dev40/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: datahold
+Version: 3.0.0.dev40
+Summary: This project wraps common mutable datastructures for inheritance with modification.
+Author-email: Johannes <johannes.programming@gmail.com>
+License-Expression: MIT
+Project-URL: Download, https://pypi.org/project/datahold/#files
+Project-URL: Index, https://pypi.org/project/datahold/
+Project-URL: Source, https://github.com/johannes-programming/datahold/
+Project-URL: Website, http://datahold.johannes-programming.online/
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+Requires-Dist: cmp3<2,>=1.1
+Requires-Dist: copyable<2,>=1.1
+Requires-Dist: frozendict<3,>=2.4.6
+Requires-Dist: iterprod<2,>=1.1
+Requires-Dist: setdoc<2,>=1.4
+Dynamic: license-file
+
+========
+datahold
+========
+
+Each minor version has its own documentation.
+These docs can be found as rst-files in the ``docs/`` directory of this project.
+They can also be viewed on the website `https://datahold.johannes-programming.online/ <https://datahold.johannes-programming.online/>`_.

datahold-3.0.0.dev40/README.rst

@@ -0,0 +1,7 @@
+========
+datahold
+========
+
+Each minor version has its own documentation.
+These docs can be found as rst-files in the ``docs/`` directory of this project.
+They can also be viewed on the website `https://datahold.johannes-programming.online/ <https://datahold.johannes-programming.online/>`_.

datahold-3.0.0.dev40/docs/v1.1.rst

@@ -0,0 +1,321 @@
+Overview
+--------
+
+This project wraps common mutable datastructures for inheritance with modification.
+
+.. container:: warning
+
+    **Warning:** The major version ``1`` of ``datahold`` has reached end-of-life.
+
+Links
+-----
+
+- Download: https://pypi.org/project/datahold/#files
+- Index: https://pypi.org/project/datahold/
+- Source: https://github.com/johannes-programming/datahold/
+- Website: https://datahold.johannes-programming.online/
+
+Installation
+------------
+
+To install ``datahold``, you can use ``pip``.
+Open your terminal and run:
+
+.. code-block:: shell
+
+    pip install datahold
+
+Features
+--------
+
+``class datahold.HoldABC(*args: Any, **kwargs: Any)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    class HoldABC(ABC):
+
+        __slots__ = ("_data",)
+
+        __hash__ = unhash
+
+        @abstractmethod
+        def __init__(self: Self, *args: Any, **kwargs: Any) -> None:
+            "This magic method initializes self."
+            ...
+
+        @classmethod
+        def __subclasshook__(cls: type, other: type, /) -> bool:
+            "This magic classmethod can be overwritten for a custom subclass check."
+            return NotImplemented
+
+        @property
+        @abstractmethod
+        def data(self: Self) -> Any: ...
+
+``class datahold.HoldDict(*args: Any, **kwargs: Any)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This class is a brute wrapper for ``dict``. It inherits from ``HoldABC`` and ``collections.abc.MutableMapping``. Its constructor passes all arguments to the constructor of ``dict`` and the result is saved within the ``data`` property.
+
+``__contains__(key: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the ``in`` operator. Internally its code is equivalent to the following:
+
+.. code-block:: python
+
+    def __contains__(self: Self, key: Any, /) -> Any:
+        "True if the dictionary has the specified key, else False."
+        data = self.data
+        ans = data.__contains__(*args, **kwargs)
+        self.data = data
+        return ans
+
+The imprecise annotations and docstring are due to it adhering to the underlying ``dict.__contains__`` as closely as possible.
+
+``__delitem__(key: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the deletion of items. Its inner workings are analogous to ``__contains__``.
+
+``__eq__(value: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the ``==`` operator. Its inner workings are analogous to ``__contains__``.
+
+``__format__(format_spec: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the inbuilt ``format`` function. Its inner workings are analogous to ``__contains__``.
+
+``__ge__(value: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the ``>=`` operator. Its inner workings are analogous to ``__contains__``.
+
+``__getitem__(key: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the returning of items. Its inner workings are analogous to ``__contains__``.
+
+``__gt__(value: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the ``>`` operator. Its inner workings are analogous to ``__contains__``.
+
+``__hash__() -> int``
+^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the inbuilt function ``hash``. Its function is ``unhash.unhash``. It always raises a ``TypeError``.
+
+``__ior__(value: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the ``|=`` operator. Its inner workings are analogous to ``__contains__``.
+
+``__iter__() -> Any``
+^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements iteration. Its inner workings are analogous to ``__contains__``.
+
+``__le__(value: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the ``<=`` operator. Its inner workings are analogous to ``__contains__``.
+
+``__len__() -> Any``
+^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the inbuilt ``len`` function. Its inner workings are analogous to ``__contains__``.
+
+``__lt__(value: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the ``<`` operator. Its inner workings are analogous to ``__contains__``.
+
+``__or__(value: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the ``|`` operator. Its inner workings are analogous to ``__contains__``.
+
+``__repr__() -> Any``
+^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements representation. Its inner workings are analogous to ``__contains__``.
+
+``__reversed__() -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the inbuilt ``reversed`` function. Its inner workings are analogous to ``__contains__``.
+
+``__ror__(value: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the ``|`` operator from the right side if the left operand does not have it implemented. Its inner workings are analogous to ``__contains__``.
+
+``__setitem__(key: Any, value: Any, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the setting of items. Its inner workings are analogous to ``__contains__``.
+
+``__str__() -> Any``
+^^^^^^^^^^^^^^^^^^^^
+
+This magic method implements the explicit conversion into a string. Its inner workings are analogous to ``__contains__``.
+
+``__subclasshook__(other: type, /) -> bool``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This classmethod is inherited directly from ``HoldABC``.
+
+``clear() -> Any``
+^^^^^^^^^^^^^^^^^^
+
+This method deletes of all ``items``. Its inner workings are analogous to ``__contains__``.
+
+``copy() -> Any``
+^^^^^^^^^^^^^^^^^
+
+This method implements dublication. Its inner workings are analogous to ``__contains__``. Remember that because of that a ``dict`` is returned.
+
+``data: dict``
+^^^^^^^^^^^^^^
+
+This property is implemented with the equivalent to the following code:
+
+.. code-block:: python
+
+    @property
+    def data(self: Self) -> dict:
+        return dict(self._data)
+
+    @data.setter
+    def data(self: Self, value: Any) -> None:
+        self._data = dict(value)
+
+    @data.deleter
+    def data(self: Self) -> None:
+        self._data = dict()
+
+``get(key: Any, default: Any = None, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This method implements getting an item with a ``default`` in case of its absence. Its inner workings are analogous to ``__contains__``.
+
+``items() -> Any``
+^^^^^^^^^^^^^^^^^^
+
+This method returns an iterator over the ``items``. Its inner workings are analogous to ``__contains__``.
+
+``keys() -> Any``
+^^^^^^^^^^^^^^^^^
+
+This method returns an iterator over the ``keys``. Its inner workings are analogous to ``__contains__``.
+
+``popitem() -> Any``
+^^^^^^^^^^^^^^^^^^^^
+
+This method deletes and returns the last item. Its inner workings are analogous to ``__contains__``.
+
+``setdefault(key: Any, default: Any = None, /) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This method ensures the presence of a ``key``. Its inner workings are analogous to ``__contains__``.
+
+``update(*args: Any, **kwargs: Any) -> Any``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This method updates the ``data``. Its inner workings are analogous to ``__contains__``.
+
+``values() -> Any``
+^^^^^^^^^^^^^^^^^^^
+
+This method returns an iterator over the ``values``. Its inner workings are analogous to ``__contains__``.
+
+``class datahold.HoldList(*args: Any, **kwargs: Any)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This class is analogous to ``HoldDict``. It implements the magic methods ``__add__``, ``__contains__``, ``__delitem__``, ``__eq__``, ``__format__``, ``__ge__``, ``__getitem__``, ``__gt__``, ``__iadd__``, ``__imul__``, ``__iter__``, ``__le__``, ``__len__``, ``__lt__``, ``__mul__``, ``__repr__``, ``__reversed__``, ``__rmul__``, ``__setitem__``, and ``__str__``. The other methods implemented are ``append``, ``clear``, ``copy``, ``count``, ``extend``, ``index``, ``insert``, ``pop``, ``remove``, ``reverse``, and ``sort``. It is a child of ``HoldABC`` and of ``collections.abc.MutableSequence``, thereby also inheriting their members.
+
+``class datahold.HoldSet(*args: Any, **kwargs: Any)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This class is analogous to ``HoldDict``. It implements the magic methods ``__and__``, ``__contains__``, ``__eq__``, ``__format__``, ``__ge__``, ``__gt__``, ``__iand__``, ``__ior__``, ``__isub__``, ``__iter__``, ``__le__``, ``__len__``, ``__lt__``, ``__or__``, ``__rand__``, ``__repr__``, ``__ror__``, ``__rsub__``, ``__rxor__``, ``__str__``, ``__sub__``, ``__rmul__``, ``__sub__``, and ``__xor__``. The other methods implemented are ``add``, ``clear``, ``copy``, ``difference``, ``difference_update``, ``discard``, ``intersection``, ``intersection_update``, ``isdisjoint``, ``issubset``, ``issuperset``, ``pop``, ``remove``, ``symmetric_difference``, ``symmetric_difference_update``, ``union``, and ``update``. It is a child of ``HoldABC`` and of ``collections.abc.MutableSet``, thereby also inheriting their members.
+
+``class datahold.OkayABC(*args: Any, **kwargs: Any)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A common ABC for ``OkayList``, ``OkayDict``, and ``OkaySet``. Child of ``Scaevola`` and ``HoldABC``. It implements common-sense overwrites for some methods. For example:
+
+- All methods that cannot actually change the underlying object are now bound to ``_data`` instead of ``data``.
+- ``__bool__`` is implemented as ``bool(self._data)`` because neither ``list``, ``dict``, nor ``set`` have a ``__bool__`` method defined.
+- The comparison operations are overwritten:
+
+    - ``__eq__`` returns ``self._data == type(self._data)(other)``.
+    - ``__ne__`` negates ``__eq__``.
+    - ``__ge__`` returns ``type(self)(other) <= self`` (inherited from ``scaevola.Scaevola``).
+    - ``__gt__`` returns ``not (self == other) and (self >= other)``.
+    - ``__lt__`` returns ``not (self == other) and (self <= other)``.
+    - ``__le__`` returns ``self._data <= type(self)(other)._data``.
+
+- Modify ``__eq__`` or ``__le__`` as needed to change the behavior of the other comparison methods.
+
+``class datahold.OkayDict(data: Iterable = (), /, **kwargs: Any)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A subclass of ``HoldDict`` with common-sense implementations for further inheritance, just like ``OkayList`` for ``HoldList``.
+
+``class datahold.OkayList(data: Iterable = ())``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This class inherits from ``HoldList`` and ``OkayABC``. It implements a ``data`` property that binds a variable ``_data``.
+
+.. code-block:: python
+
+    @property
+    def data(self, /):
+        return list(self._data)
+
+    @data.setter
+    def data(self, values, /):
+        self._data = list(values)
+
+    @data.deleter
+    def data(self, /):
+        self._data = list()
+
+Based on this, it implements common-sense methods. For example:
+
+- All methods that returned a ``list`` before now return ``OkayList`` (type adapts to further inheritance).
+- ``__init__`` allows setting data immediately.
+
+``class datahold.OkaySet(data: Iterable = ())``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A subclass of ``HoldSet`` with common-sense implementations for further inheritance, just like ``OkayList`` for ``HoldList``.
+
+``datahold.test() -> unittest.TextTestResult``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This project can be tested through its ``test`` function.
+
+.. code-block:: python
+
+    import datahold
+    datahold.test()
+
+License
+-------
+
+This project is licensed under the MIT License.
+
+Impressum
+---------
+
+**Johannes Programming**
+
+- Name: Johannes
+- Email: johannes.programming@gmail.com
+- Homepage: https://www.johannes-programming.online/
+- Gravatar: https://www.johannes-programming.fyi/