bagofholding 0.0.3__tar.gz → 0.1.0__tar.gz

{bagofholding-0.0.3 → bagofholding-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bagofholding
-Version: 0.0.3
+Version: 0.1.0
 Summary: bagofholding - browsable, partially-reloadable serialization for pickleable python objects.
 Project-URL: Homepage, https://pyiron.org/
 Project-URL: Documentation, https://bagofholding.readthedocs.io
@@ -36,14 +36,14 @@ License: BSD 3-Clause License
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 License-File: LICENSE
 Keywords: pyiron
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
-Requires-Python: <3.14,>=3.12
+Requires-Python: <3.14,>=3.11
 Requires-Dist: bidict==0.23.1
 Requires-Dist: h5py<3.15.0,>=3.14.0
 Requires-Dist: mpi4py<4.1.0,>=4.0.1
@@ -57,12 +57,24 @@ Description-Content-Type: text/markdown
 
 # bagofholding
 
-`bagofholding` is designed to be an easy stand-in for `pickle` serialization for python object that is transparent, flexible, and suitable for long-term storage.
+<img src="_static/bagofholding_logo.png" alt="Logo" width="190"/>  
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pyiron/bagofholding/HEAD)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Coverage](https://codecov.io/gh/pyiron/bagofholding/graph/badge.svg)](https://codecov.io/gh/pyiron/bagofholding)
+[![Documentation](https://readthedocs.org/projects/bagofholding/badge/?version=latest)](https://bagofholding.readthedocs.io/en/latest/?badge=latest)
+
+[![Anaconda](https://anaconda.org/conda-forge/bagofholding/badges/version.svg)](https://anaconda.org/conda-forge/bagofholding)
+[![Last Updated](https://anaconda.org/conda-forge/bagofholding/badges/latest_release_date.svg)](https://anaconda.org/conda-forge/bagofholding)
+[![Platform](https://anaconda.org/conda-forge/bagofholding/badges/platforms.svg)](https://anaconda.org/conda-forge/bagofholding)
+[![Downloads](https://anaconda.org/conda-forge/bagofholding/badges/downloads.svg)](https://anaconda.org/conda-forge/bagofholding)
+
+`bagofholding` is designed to be an easy stand-in for `pickle` serialization for python objects that is transparent, flexible, and suitable for long-term storage.
 
 ## Advantages
 ### Drop-in replacement
 
-`bagofholding` stores (almost) any `pickle`-able python object, and can be easily used as a drop-in replacement for `pickle` serialization:
+`bagofholding` stores `pickle`-able python objects, and can be easily used as a drop-in replacement for `pickle` serialization:
 
 ```python
 >>> import bagofholding as boh
@@ -76,7 +88,7 @@ Description-Content-Type: text/markdown
 
 ### Browseable
 
-The contents of stored objects can be browsed without actually re-instantiating any of the stored data.
+The contents of stored objects can be browsed without re-instantiating any of the stored data.
 In the example above, we saw that saving is a class-method, while loading is an instance method.
 We can grab the "bag" instance and use it to peek at what's inside!
 
@@ -130,53 +142,32 @@ With only `bagofholding` and `numpy` installed, the end user can browse through
 
 ### Version control
 
-In the examples above, we saw that version (and of course package) information is part of the stored metadata.
-This is useful post-facto for knowing what packages need to be installed to properly load your serialized data.
-You can also specify at load-time how strict or relaxed `bagofholding` should be in re-instantiating data if a stored version does not match the currently installed version, thus protecting you from flawed re-instantiations.
+In the examples above, we saw that version (and of course package) information is part of the automatically-scraped and stored metadata.
+This is useful post-facto for knowing what packages need to be installed to properly load your serialized data, and allows us to fail in clean and helpful ways if the loading environment does not match the saving environment.
+You can also specify at load-time how strict or relaxed `bagofholding` should be in re-instantiating data if a stored version does not match the currently installed version, giving flexible protection from flawed re-instantiations.
 
 `bagofholding` also provides tools to act on this data a-priori.
 To increase the likelihood that stored data will be accessible in the future, you can outlaw any (sub)objects coming from particular modules:
 
 ```python
-import bagofholding.exception
->> > try:
-    ...
-boh.H5Bag.save(something, "will_fail.h5", forbidden_modules=("__main__",))
-... except bagofholding.exception.ModuleForbiddenError as e:
-...
-print(e)
-Module
-'__main__' is forbidden as a
-source
-of
-stored
-objects.Change
-the
-`forbidden_modules` or move
-this
-object
-to
-an
-allowed
-module.
+import bagofholding as boh
+>>> try:
+...     boh.H5Bag.save(something, "will_fail.h5", forbidden_modules=("__main__",))
+... except boh.ModuleForbiddenError as e:
+...     print(e)
+Module '__main__' is forbidden as a source of stored objects. Change the `forbidden_modules` or move this object to an allowed module.
 
 ```
 
-And/or demand that all objects have an identifiable version that:
+And/or demand that all objects have an identifiable version:
 
 ```python
-import bagofholding.exception
->> > try:
-    ...
-boh.H5Bag.save(something, "will_fail.h5", require_versions=True)
-... except bagofholding.exception.NoVersionError as e:
-...
-print(e)
-Could
-not find
-a
-version
-for __main__.Either disable `require_versions`, use `version_scraping` to find an existing version for this package, or add versioning to the unversioned package.
+import bagofholding as boh
+>>> try:
+...     boh.H5Bag.save(something, "will_fail.h5", require_versions=True)
+... except boh.NoVersionError as e:
+...     print(e)
+Could not find a version for __main__. Either disable `require_versions`, use `version_scraping` to find an existing version for this package, or add versioning to the unversioned package.
 
 ```
 
@@ -195,8 +186,21 @@ H5Info(qualname='H5Bag', module='bagofholding.h5.bag', version='...', libver_str
 
 For a more in-depth look at the above features and to explore other aspects of `bagofholding`, check out [the tutorial notebook](../notebooks/tutorial.ipynb).
 
-Finally, `bagofholding` prioritizes transparency in what is stored and ease-of-use for both savers and loaders/browsers.
-As such, the current hdf5-based implementation is likely to be significantly less performant than raw pickling, due to the creation of many small datasets that allow the h5 file to directly replicate the underlying structure of the python objects being saved.
-For objects which contain large `numpy` arrays, this disadvantage is significantly alleviated as we benefit from the very efficient treatment of such arrays in hdf5 and `h5py`.
-For all other objects, the current `bagofholding.H5Bag` is still an appropriate choice when the robustness of long term storage is more pressing than optimizing storage space.
-Other bag types may be available in the future.
+
+## Object requirements
+
+Under-the-hood, we follow the same patterns as `pickle` by explicitly invoking many of the same method (`__reduce__`, `__setstate__`, etc).
+_Almost_ and object which can be pickled can be stored using `bagofholding`.
+Our requirements are that the object...
+
+- Must be pickleable
+  - You can use the `pickle_check` method on bag classes to quickly assess this
+- Must not depend on `pickle` protocol >4
+- Must have a valid boolean response to `hasattr` for each of the following, and they must conform to python and `abc.collections` norms if present:
+  - `__setstate__`
+  - `__setitem__`
+  - `append`
+  - `extend`
+- Must have a valid boolean response to `hasattr` for `__metadata__`, and this attribute must be castable to a string if present
+
+If your object satisfies these conditions and fails to "bag", please raise a bug report on the issues page!

{bagofholding-0.0.3/cached-miniforge/my-env/lib/python3.1/site-packages → bagofholding-0.1.0}/bagofholding/__init__.py

@@ -19,7 +19,7 @@ from bagofholding.exceptions import NotAGroupError as NotAGroupError
 from bagofholding.exceptions import NoVersionError as NoVersionError
 from bagofholding.exceptions import PickleProtocolError as PickleProtocolError
 from bagofholding.exceptions import (
-    StringReductionNotImportableError as StringReductionNotImportableError,
+    StringNotImportableError as StringNotImportableError,
 )
 from bagofholding.h5.bag import H5Bag as H5Bag
 from bagofholding.h5.triebag import TrieH5Bag as TrieH5Bag

{bagofholding-0.0.3 → bagofholding-0.1.0}/bagofholding/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.0.3'
-__version_tuple__ = version_tuple = (0, 0, 3)
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)

{bagofholding-0.0.3 → bagofholding-0.1.0}/bagofholding/content.py

@@ -35,6 +35,7 @@ from bagofholding.exceptions import (
     ModuleForbiddenError,
     NoVersionError,
     PickleProtocolError,
+    StringNotImportableError,
 )
 from bagofholding.metadata import (
     Metadata,
@@ -237,6 +238,15 @@ class Global(Item[GlobalType, Any, Packer]):
             value = "builtins." + obj if "." not in obj else obj
         else:
             value = obj.__module__ + "." + obj.__qualname__
+
+        if "<lambda>" in value:
+            raise StringNotImportableError(
+                f"Lambda functions are not re-importable, can't pack {obj}"
+            )
+        elif "<locals>" in value:
+            raise StringNotImportableError(
+                f"Local functions are not re-importable, can't pack {obj}"
+            )
         packer.pack_string(value, path)
 
     @classmethod

{bagofholding-0.0.3/cached-miniforge/my-env/lib/python3.1/site-packages → bagofholding-0.1.0}/bagofholding/exceptions.py

@@ -41,4 +41,4 @@ class NoVersionError(BagOfHoldingError, ValueError): ...
 class PickleProtocolError(BagOfHoldingError, ValueError): ...
 
 
-class StringReductionNotImportableError(BagOfHoldingError): ...
+class StringNotImportableError(BagOfHoldingError): ...

{bagofholding-0.0.3 → bagofholding-0.1.0}/bagofholding/retrieve.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 from importlib import import_module
 from typing import Any
 
-from bagofholding.exceptions import StringReductionNotImportableError
+from bagofholding.exceptions import StringNotImportableError
 
 
 def import_from_string(library_path: str) -> Any:
@@ -44,7 +44,7 @@ def get_importable_string_from_string_reduction(
         try:
             import_from_string(importable)
         except (ModuleNotFoundError, AttributeError) as e:
-            raise StringReductionNotImportableError(
+            raise StringNotImportableError(
                 f"Couldn't import {string_reduction} after scoping it as {importable}. "
                 f"Please contact the developers so we can figure out how to handle "
                 f"this edge case."

{bagofholding-0.0.3/cached-miniforge/my-env/lib/python3.1/site-packages → bagofholding-0.1.0}/bagofholding/trie.py

@@ -1,11 +1,14 @@
 import random
-from typing import cast
+from typing import TypeVar, cast
 
 import numpy as np
 import pygtrie
 
+ValueType = TypeVar("ValueType")  # python <3.12 compatibility
+# def not_allowed_to_have_inline[FunctionGenerics](in_python=3.12):
 
-def decompose_stringtrie[ValueType](
+
+def decompose_stringtrie(
     trie: pygtrie.StringTrie, null_value: ValueType
 ) -> tuple[list[str], list[int], list[ValueType]]:
     """
@@ -63,7 +66,7 @@ def decompose_stringtrie[ValueType](
     return segments, parents, values
 
 
-def reconstruct_stringtrie[ValueType](
+def reconstruct_stringtrie(
     segments: list[str],
     parents: list[int],
     values: list[ValueType],

{bagofholding-0.0.3 → bagofholding-0.1.0/cached-miniforge/my-env/lib/python3.1/site-packages}/bagofholding/__init__.py

@@ -19,7 +19,7 @@ from bagofholding.exceptions import NotAGroupError as NotAGroupError
 from bagofholding.exceptions import NoVersionError as NoVersionError
 from bagofholding.exceptions import PickleProtocolError as PickleProtocolError
 from bagofholding.exceptions import (
-    StringReductionNotImportableError as StringReductionNotImportableError,
+    StringNotImportableError as StringNotImportableError,
 )
 from bagofholding.h5.bag import H5Bag as H5Bag
 from bagofholding.h5.triebag import TrieH5Bag as TrieH5Bag

{bagofholding-0.0.3 → bagofholding-0.1.0}/cached-miniforge/my-env/lib/python3.1/site-packages/bagofholding/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.0.3'
-__version_tuple__ = version_tuple = (0, 0, 3)
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)

{bagofholding-0.0.3 → bagofholding-0.1.0}/cached-miniforge/my-env/lib/python3.1/site-packages/bagofholding/content.py

@@ -35,6 +35,7 @@ from bagofholding.exceptions import (
     ModuleForbiddenError,
     NoVersionError,
     PickleProtocolError,
+    StringNotImportableError,
 )
 from bagofholding.metadata import (
     Metadata,
@@ -237,6 +238,15 @@ class Global(Item[GlobalType, Any, Packer]):
             value = "builtins." + obj if "." not in obj else obj
         else:
             value = obj.__module__ + "." + obj.__qualname__
+
+        if "<lambda>" in value:
+            raise StringNotImportableError(
+                f"Lambda functions are not re-importable, can't pack {obj}"
+            )
+        elif "<locals>" in value:
+            raise StringNotImportableError(
+                f"Local functions are not re-importable, can't pack {obj}"
+            )
         packer.pack_string(value, path)
 
     @classmethod

{bagofholding-0.0.3 → bagofholding-0.1.0/cached-miniforge/my-env/lib/python3.1/site-packages}/bagofholding/exceptions.py

@@ -41,4 +41,4 @@ class NoVersionError(BagOfHoldingError, ValueError): ...
 class PickleProtocolError(BagOfHoldingError, ValueError): ...
 
 
-class StringReductionNotImportableError(BagOfHoldingError): ...
+class StringNotImportableError(BagOfHoldingError): ...

{bagofholding-0.0.3 → bagofholding-0.1.0}/cached-miniforge/my-env/lib/python3.1/site-packages/bagofholding/retrieve.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 from importlib import import_module
 from typing import Any
 
-from bagofholding.exceptions import StringReductionNotImportableError
+from bagofholding.exceptions import StringNotImportableError
 
 
 def import_from_string(library_path: str) -> Any:
@@ -44,7 +44,7 @@ def get_importable_string_from_string_reduction(
         try:
             import_from_string(importable)
         except (ModuleNotFoundError, AttributeError) as e:
-            raise StringReductionNotImportableError(
+            raise StringNotImportableError(
                 f"Couldn't import {string_reduction} after scoping it as {importable}. "
                 f"Please contact the developers so we can figure out how to handle "
                 f"this edge case."

{bagofholding-0.0.3 → bagofholding-0.1.0/cached-miniforge/my-env/lib/python3.1/site-packages}/bagofholding/trie.py

@@ -1,11 +1,14 @@
 import random
-from typing import cast
+from typing import TypeVar, cast
 
 import numpy as np
 import pygtrie
 
+ValueType = TypeVar("ValueType")  # python <3.12 compatibility
+# def not_allowed_to_have_inline[FunctionGenerics](in_python=3.12):
 
-def decompose_stringtrie[ValueType](
+
+def decompose_stringtrie(
     trie: pygtrie.StringTrie, null_value: ValueType
 ) -> tuple[list[str], list[int], list[ValueType]]:
     """
@@ -63,7 +66,7 @@ def decompose_stringtrie[ValueType](
     return segments, parents, values
 
 
-def reconstruct_stringtrie[ValueType](
+def reconstruct_stringtrie(
     segments: list[str],
     parents: list[int],
     values: list[ValueType],

{bagofholding-0.0.3 → bagofholding-0.1.0}/docs/README.md

@@ -1,11 +1,23 @@
 # bagofholding
 
-`bagofholding` is designed to be an easy stand-in for `pickle` serialization for python object that is transparent, flexible, and suitable for long-term storage.
+<img src="_static/bagofholding_logo.png" alt="Logo" width="190"/>  
+
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pyiron/bagofholding/HEAD)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Coverage](https://codecov.io/gh/pyiron/bagofholding/graph/badge.svg)](https://codecov.io/gh/pyiron/bagofholding)
+[![Documentation](https://readthedocs.org/projects/bagofholding/badge/?version=latest)](https://bagofholding.readthedocs.io/en/latest/?badge=latest)
+
+[![Anaconda](https://anaconda.org/conda-forge/bagofholding/badges/version.svg)](https://anaconda.org/conda-forge/bagofholding)
+[![Last Updated](https://anaconda.org/conda-forge/bagofholding/badges/latest_release_date.svg)](https://anaconda.org/conda-forge/bagofholding)
+[![Platform](https://anaconda.org/conda-forge/bagofholding/badges/platforms.svg)](https://anaconda.org/conda-forge/bagofholding)
+[![Downloads](https://anaconda.org/conda-forge/bagofholding/badges/downloads.svg)](https://anaconda.org/conda-forge/bagofholding)
+
+`bagofholding` is designed to be an easy stand-in for `pickle` serialization for python objects that is transparent, flexible, and suitable for long-term storage.
 
 ## Advantages
 ### Drop-in replacement
 
-`bagofholding` stores (almost) any `pickle`-able python object, and can be easily used as a drop-in replacement for `pickle` serialization:
+`bagofholding` stores `pickle`-able python objects, and can be easily used as a drop-in replacement for `pickle` serialization:
 
 ```python
 >>> import bagofholding as boh
@@ -19,7 +31,7 @@
 
 ### Browseable
 
-The contents of stored objects can be browsed without actually re-instantiating any of the stored data.
+The contents of stored objects can be browsed without re-instantiating any of the stored data.
 In the example above, we saw that saving is a class-method, while loading is an instance method.
 We can grab the "bag" instance and use it to peek at what's inside!
 
@@ -73,53 +85,32 @@ With only `bagofholding` and `numpy` installed, the end user can browse through
 
 ### Version control
 
-In the examples above, we saw that version (and of course package) information is part of the stored metadata.
-This is useful post-facto for knowing what packages need to be installed to properly load your serialized data.
-You can also specify at load-time how strict or relaxed `bagofholding` should be in re-instantiating data if a stored version does not match the currently installed version, thus protecting you from flawed re-instantiations.
+In the examples above, we saw that version (and of course package) information is part of the automatically-scraped and stored metadata.
+This is useful post-facto for knowing what packages need to be installed to properly load your serialized data, and allows us to fail in clean and helpful ways if the loading environment does not match the saving environment.
+You can also specify at load-time how strict or relaxed `bagofholding` should be in re-instantiating data if a stored version does not match the currently installed version, giving flexible protection from flawed re-instantiations.
 
 `bagofholding` also provides tools to act on this data a-priori.
 To increase the likelihood that stored data will be accessible in the future, you can outlaw any (sub)objects coming from particular modules:
 
 ```python
-import bagofholding.exception
->> > try:
-    ...
-boh.H5Bag.save(something, "will_fail.h5", forbidden_modules=("__main__",))
-... except bagofholding.exception.ModuleForbiddenError as e:
-...
-print(e)
-Module
-'__main__' is forbidden as a
-source
-of
-stored
-objects.Change
-the
-`forbidden_modules` or move
-this
-object
-to
-an
-allowed
-module.
+import bagofholding as boh
+>>> try:
+...     boh.H5Bag.save(something, "will_fail.h5", forbidden_modules=("__main__",))
+... except boh.ModuleForbiddenError as e:
+...     print(e)
+Module '__main__' is forbidden as a source of stored objects. Change the `forbidden_modules` or move this object to an allowed module.
 
 ```
 
-And/or demand that all objects have an identifiable version that:
+And/or demand that all objects have an identifiable version:
 
 ```python
-import bagofholding.exception
->> > try:
-    ...
-boh.H5Bag.save(something, "will_fail.h5", require_versions=True)
-... except bagofholding.exception.NoVersionError as e:
-...
-print(e)
-Could
-not find
-a
-version
-for __main__.Either disable `require_versions`, use `version_scraping` to find an existing version for this package, or add versioning to the unversioned package.
+import bagofholding as boh
+>>> try:
+...     boh.H5Bag.save(something, "will_fail.h5", require_versions=True)
+... except boh.NoVersionError as e:
+...     print(e)
+Could not find a version for __main__. Either disable `require_versions`, use `version_scraping` to find an existing version for this package, or add versioning to the unversioned package.
 
 ```
 
@@ -138,8 +129,21 @@ H5Info(qualname='H5Bag', module='bagofholding.h5.bag', version='...', libver_str
 
 For a more in-depth look at the above features and to explore other aspects of `bagofholding`, check out [the tutorial notebook](../notebooks/tutorial.ipynb).
 
-Finally, `bagofholding` prioritizes transparency in what is stored and ease-of-use for both savers and loaders/browsers.
-As such, the current hdf5-based implementation is likely to be significantly less performant than raw pickling, due to the creation of many small datasets that allow the h5 file to directly replicate the underlying structure of the python objects being saved.
-For objects which contain large `numpy` arrays, this disadvantage is significantly alleviated as we benefit from the very efficient treatment of such arrays in hdf5 and `h5py`.
-For all other objects, the current `bagofholding.H5Bag` is still an appropriate choice when the robustness of long term storage is more pressing than optimizing storage space.
-Other bag types may be available in the future.
+
+## Object requirements
+
+Under-the-hood, we follow the same patterns as `pickle` by explicitly invoking many of the same method (`__reduce__`, `__setstate__`, etc).
+_Almost_ and object which can be pickled can be stored using `bagofholding`.
+Our requirements are that the object...
+
+- Must be pickleable
+  - You can use the `pickle_check` method on bag classes to quickly assess this
+- Must not depend on `pickle` protocol >4
+- Must have a valid boolean response to `hasattr` for each of the following, and they must conform to python and `abc.collections` norms if present:
+  - `__setstate__`
+  - `__setitem__`
+  - `append`
+  - `extend`
+- Must have a valid boolean response to `hasattr` for `__metadata__`, and this attribute must be castable to a string if present
+
+If your object satisfies these conditions and fails to "bag", please raise a bug report on the issues page!

{bagofholding-0.0.3 → bagofholding-0.1.0}/pyproject.toml

@@ -7,8 +7,8 @@ name = "bagofholding"
 description = "bagofholding - browsable, partially-reloadable serialization for pickleable python objects."
 readme = "docs/README.md"
 keywords = [ "pyiron",]
-requires-python = ">=3.12, <3.14"
-classifiers = [ "Development Status :: 3 - Alpha", "Topic :: Scientific/Engineering", "License :: OSI Approved :: BSD License", "Intended Audience :: Science/Research", "Operating System :: OS Independent", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13",]
+requires-python = ">=3.11, <3.14"
+classifiers = [ "Development Status :: 4 - Beta", "Topic :: Scientific/Engineering", "License :: OSI Approved :: BSD License", "Intended Audience :: Science/Research", "Operating System :: OS Independent", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13",]
 dependencies = [ "bidict==0.23.1", "h5py>=3.14.0,<3.15.0", "mpi4py>=4.0.1,<4.1.0", "numpy>=2.3.0,<2.4.0", "pygtrie>=2.5.0,<2.6.0", "pyiron_snippets==0.2.0",]
 dynamic = [ "version",]
 [[project.authors]]