bagofholding 0.0.2__tar.gz → 0.0.3__tar.gz

bagofholding-0.0.3/.gitignore

@@ -0,0 +1,13 @@
+*.pyc
+.DS_Store
+.coverage
+nohup.out
+pyiron.log
+.idea/
+inspectionProfiles/
+_build/
+apidoc/
+.ipynb_checkpoints/
+test_times.dat
+core.*
+bagofholding/_version.py

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

@@ -1,7 +1,10 @@
 Metadata-Version: 2.4
 Name: bagofholding
-Version: 0.0.2
+Version: 0.0.3
 Summary: bagofholding - browsable, partially-reloadable serialization for pickleable python objects.
+Project-URL: Homepage, https://pyiron.org/
+Project-URL: Documentation, https://bagofholding.readthedocs.io
+Project-URL: Repository, https://github.com/pyiron/bagofholding
 Author-email: Liam Huber <liamhuber@greyhavensolutions.com>
 License: BSD 3-Clause License
         
@@ -31,31 +34,26 @@ License: BSD 3-Clause License
         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-        
-Project-URL: Homepage, https://pyiron.org/
-Project-URL: Documentation, https://bagofholding.readthedocs.io
-Project-URL: Repository, https://github.com/pyiron/bagofholding
+License-File: LICENSE
 Keywords: pyiron
 Classifier: Development Status :: 3 - Alpha
-Classifier: Topic :: Scientific/Engineering
-Classifier: License :: OSI Approved :: BSD License
 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
-Description-Content-Type: text/markdown
-License-File: LICENSE
 Requires-Dist: bidict==0.23.1
 Requires-Dist: h5py<3.15.0,>=3.14.0
 Requires-Dist: mpi4py<4.1.0,>=4.0.1
 Requires-Dist: numpy<2.4.0,>=2.3.0
 Requires-Dist: pygtrie<2.6.0,>=2.5.0
-Requires-Dist: pyiron_snippets==0.2.0
+Requires-Dist: pyiron-snippets==0.2.0
 Provides-Extra: widget
-Requires-Dist: ipytree==0.2.2; extra == "widget"
-Requires-Dist: traitlets==5.14.3; extra == "widget"
-Dynamic: license-file
+Requires-Dist: ipytree==0.2.2; extra == 'widget'
+Requires-Dist: traitlets==5.14.3; extra == 'widget'
+Description-Content-Type: text/markdown
 
 # bagofholding
 

{bagofholding-0.0.2 → bagofholding-0.0.3}/bagofholding/__init__.py

@@ -1,6 +1,11 @@
-from . import _version
+import importlib.metadata
 
-__version__ = _version.get_versions()["version"]
+try:
+    # Installed package will find its version
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    # Repository clones will register an unknown version
+    __version__ = "0.0.0+unknown"
 
 from bagofholding.exceptions import BagMismatchError as BagMismatchError
 from bagofholding.exceptions import BagOfHoldingError as BagOfHoldingError

bagofholding-0.0.3/bagofholding/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.0.3'
+__version_tuple__ = version_tuple = (0, 0, 3)

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

@@ -0,0 +1,25 @@
+import importlib.metadata
+
+try:
+    # Installed package will find its version
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    # Repository clones will register an unknown version
+    __version__ = "0.0.0+unknown"
+
+from bagofholding.exceptions import BagMismatchError as BagMismatchError
+from bagofholding.exceptions import BagOfHoldingError as BagOfHoldingError
+from bagofholding.exceptions import EnvironmentMismatchError as EnvironmentMismatchError
+from bagofholding.exceptions import FileAlreadyOpenError as FileAlreadyOpenError
+from bagofholding.exceptions import FileNotOpenError as FileNotOpenError
+from bagofholding.exceptions import FilepathError as FilepathError
+from bagofholding.exceptions import InvalidMetadataError as InvalidMetadataError
+from bagofholding.exceptions import ModuleForbiddenError as ModuleForbiddenError
+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,
+)
+from bagofholding.h5.bag import H5Bag as H5Bag
+from bagofholding.h5.triebag import TrieH5Bag as TrieH5Bag

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

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.0.3'
+__version_tuple__ = version_tuple = (0, 0, 3)

bagofholding-0.0.3/cached-miniforge/my-env/lib/python3.1/site-packages/bagofholding/bag.py

@@ -0,0 +1,266 @@
+"""
+The core user-facing object.
+
+Full implementations of bags should guarantee the key features promised by the package:
+- Storage and retrieval of arbitrary pickleable python objects
+- Metadata preservation
+- Versioning verification
+- Browsing without loading
+- Partial reloading
+"""
+
+from __future__ import annotations
+
+import abc
+import dataclasses
+import os.path
+import pathlib
+import pickle
+from collections.abc import Iterator, Mapping
+from typing import (
+    Any,
+    ClassVar,
+    Self,
+    SupportsIndex,
+)
+
+import bidict
+from pyiron_snippets import import_alarm
+
+from bagofholding.content import BespokeItem, Packer, pack, unpack
+from bagofholding.exceptions import BagMismatchError, InvalidMetadataError
+from bagofholding.metadata import (
+    HasFieldIterator,
+    HasVersionInfo,
+    Metadata,
+    VersionScrapingMap,
+    VersionValidatorType,
+    get_version,
+)
+
+try:
+    from bagofholding.widget import BagTree
+
+    alarm = import_alarm.ImportAlarm()
+except (ImportError, ModuleNotFoundError):
+    alarm = import_alarm.ImportAlarm(
+        "The browsing widget relies on ipytree and traitlets, but this was "
+        "unavailable. You can get a text-representation of all available paths with "
+        ":meth:`bagofholding.bag.Bag.list_paths`.",
+        _fail_on_warning=True,
+    )
+
+PATH_DELIMITER = "/"
+
+
+@dataclasses.dataclass(frozen=True)
+class BagInfo(HasVersionInfo, HasFieldIterator):
+    pass
+
+
+class Bag(Packer, Mapping[str, Metadata | None], abc.ABC):
+    """
+    Bags are the user-facing object.
+    """
+
+    bag_info: BagInfo
+    storage_root: ClassVar[str] = "object"
+    filepath: pathlib.Path
+
+    @classmethod
+    def get_bag_info(cls) -> BagInfo:
+        return BagInfo(
+            qualname=cls.__qualname__,
+            module=cls.__module__,
+            version=cls.get_version(),
+        )
+
+    @classmethod
+    def _bag_info_class(cls) -> type[BagInfo]:
+        return BagInfo
+
+    @classmethod
+    def save(
+        cls,
+        obj: Any,
+        filepath: str | pathlib.Path,
+        require_versions: bool = False,
+        forbidden_modules: list[str] | tuple[str, ...] = (),
+        version_scraping: VersionScrapingMap | None = None,
+        _pickle_protocol: SupportsIndex = pickle.DEFAULT_PROTOCOL,
+        overwrite_existing: bool = True,
+    ) -> None:
+        """
+        Save a python object to file.
+
+        Args:
+            obj (Any): The (pickleble) python object to be saved.
+            filepath (str|pathlib.Path): The path to save the object to.
+            require_versions (bool): Whether to require a metadata for reduced
+                and complex objects to contain a non-None version. (Default is False,
+                objects can be stored from non-versioned packages/modules.)
+            forbidden_modules (list[str] | tuple[str, ...] | None): Do not allow saving
+                objects whose root-most modules are listed here. (Default is an empty
+                tuple, i.e. don't disallow anything.) This is particularly useful to
+                disallow  `"__main__"` to improve the odds that objects will actually
+                be loadable in the future.
+            version_scraping (dict[str, Callable[[str], str]] | None): An optional
+                dictionary mapping module names to a callable that takes this name and
+                returns a version (or None). The default callable imports the module
+                string and looks for a `__version__` attribute.
+        """
+        if os.path.exists(filepath):
+            if overwrite_existing and os.path.isfile(filepath):
+                os.remove(filepath)
+            else:
+                raise FileExistsError(f"{filepath} already exists or is not a file.")
+        bag = cls(filepath)
+        bag._pack_bag_info()
+        pack(
+            obj,
+            bag,
+            bag.storage_root,
+            bidict.bidict(),
+            [],
+            require_versions,
+            forbidden_modules,
+            version_scraping,
+            _pickle_protocol=_pickle_protocol,
+        )
+        bag._write()
+
+    @classmethod
+    def get_version(cls) -> str:
+        return str(get_version(cls.__module__, {}))
+
+    def __init__(
+        self, filepath: str | pathlib.Path, *args: object, **kwargs: Any
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self.filepath = pathlib.Path(filepath)
+        if os.path.isfile(self.filepath):
+            self.bag_info = self._unpack_bag_info()
+            if not self.validate_bag_info(self.bag_info, self.get_bag_info()):
+                raise BagMismatchError(
+                    f"The bag class {self.__class__} does not match the bag saved at "
+                    f"{filepath}; class info is {self.get_bag_info()}, but the info saved "
+                    f"is {self.bag_info}"
+                )
+
+    @abc.abstractmethod
+    def _pack_field(self, path: str, key: str, value: str) -> None: ...
+
+    @abc.abstractmethod
+    def _unpack_field(self, path: str, key: str) -> str | None: ...
+
+    @staticmethod
+    def validate_bag_info(bag_info: BagInfo, reference: BagInfo) -> bool:
+        return bag_info == reference
+
+    def load(
+        self,
+        path: str = storage_root,
+        version_validator: VersionValidatorType = "exact",
+        version_scraping: VersionScrapingMap | None = None,
+    ) -> Any:
+        return unpack(
+            self,
+            path,
+            {},
+            version_validator=version_validator,
+            version_scraping=version_scraping,
+        )
+
+    def __getitem__(self, path: str) -> Metadata:
+        return self.unpack_metadata(path)
+
+    @abc.abstractmethod
+    def list_paths(self) -> list[str]:
+        """A list of all available content paths."""
+
+    @alarm
+    def widget(self):  # type: ignore[no-untyped-def]
+        return BagTree(self)
+
+    def browse(self):  # type: ignore[no-untyped-def]
+        try:
+            return self.widget()
+        except ImportError:
+            return self.list_paths()
+
+    def __len__(self) -> int:
+        return len(self.list_paths())
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.list_paths())
+
+    def join(self, *paths: str) -> str:
+        return PATH_DELIMITER.join(paths)
+
+    @staticmethod
+    def pickle_check(
+        obj: Any, raise_exceptions: bool = True, print_message: bool = False
+    ) -> str | None:
+        """
+        A simple helper to check if an object can be pickled and unpickled.
+        Useful if you run into trouble saving or loading and want to see whether the
+        underlying object is compliant with pickle-ability requirements to begin with.
+
+        Args:
+            obj: The object to test for pickling support.
+            raise_exceptions: If True, re-raise any exception encountered.
+            print_message: If True, print the exception message on failure.
+
+        Returns:
+            None if pickling is successful; otherwise, returns the exception message as a string.
+        """
+
+        try:
+            pickle.loads(pickle.dumps(obj))
+        except Exception as e:
+            if print_message:
+                print(e)
+            if raise_exceptions:
+                raise e
+            return str(e)
+        return None
+
+    def _pack_fields(self, dataclass: HasFieldIterator, path: str) -> None:
+        for k, v in dataclass.field_items():
+            if v is not None:
+                self._pack_field(path, k, v)
+
+    def _unpack_fields(
+        self, dataclass_type: type[HasFieldIterator], path: str
+    ) -> dict[str, str | None]:
+        field_values: dict[str, str | None] = {}
+        for k in dataclass_type.__dataclass_fields__:
+            field_values[k] = self._unpack_field(path, k)
+        return field_values
+
+    def _pack_bag_info(self) -> None:
+        self._pack_fields(self.get_bag_info(), PATH_DELIMITER)
+
+    def _unpack_bag_info(self) -> BagInfo:
+        return self._bag_info_class()(
+            **self._unpack_fields(self._bag_info_class(), PATH_DELIMITER)
+        )
+
+    def _write(self) -> None:
+        return
+
+    def pack_metadata(self, metadata: Metadata, path: str) -> None:
+        self._pack_fields(metadata, path)
+        return None
+
+    def unpack_metadata(self, path: str) -> Metadata:
+        metadata = self._unpack_fields(Metadata, path)
+        content_type = metadata.pop("content_type", None)
+        if content_type is None:
+            raise InvalidMetadataError(f"Metadata at {path} is missing a content type")
+        return Metadata(content_type, **metadata)
+
+    def get_bespoke_content_class(
+        self, obj: object
+    ) -> type[BespokeItem[Any, Self]] | None:
+        return None