immlib 1.0.0.dev1__tar.gz

immlib-1.0.0.dev1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Noah C. Benson
+
+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.

immlib-1.0.0.dev1/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.1
+Name: immlib
+Version: 1.0.0.dev1
+Summary: A library of utilites for immutable scientific data.
+Author-email: "Noah C. Benson" <nben@uw.edu>
+License: MIT
+Project-URL: homepage, https://github.com/noahbenson/immlib
+Project-URL: documentation, https://github.com/noahbenson/immlib
+Project-URL: repository, https://github.com/noahbenson/immlib
+Keywords: persistent,immutable,functional,scientific,workflow
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pcollections>=0.2.7
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: pint>=0.18.0
+Requires-Dist: docrep>=0.3.2
+Requires-Dist: joblib>=1.3.0
+Requires-Dist: cloudpathlib[azure,gs,s3]>=0.18.0
+Provides-Extra: dev
+Requires-Dist: torch>=2.2.0; extra == "dev"
+Requires-Dist: pyyaml; extra == "dev"
+Provides-Extra: test
+Requires-Dist: torch>=2.2.0; extra == "test"
+Requires-Dist: pyyaml; extra == "test"
+
+# immlib
+
+![Build Status](https://github.com/noahbenson/immlib/actions/workflows/tests.yml/badge.svg)
+[![codecov](https://codecov.io/gh/noahbenson/immlib/graph/badge.svg?token=8KO3K6DUX4)](https://codecov.io/gh/noahbenson/immlib)
+[![PyPI version](https://badge.fury.io/py/immlib.svg)](https://badge.fury.io/py/immlib)
+
+`immlib` is a library of utilities for managing and manipulating immutable
+scientific data with a focus on lazy calculations and workflows. It is based on
+a prototype library [`pimms`](https://github.com/noahbenson/pimms).
+
+---
+
+**Author**: Noah C. Benson &lt;[nben@uw.edu](mailto:nben@uw.edu)&gt;  
+**License**: MIT
+
+---
+

immlib-1.0.0.dev1/README.md

@@ -0,0 +1,17 @@
+# immlib
+
+![Build Status](https://github.com/noahbenson/immlib/actions/workflows/tests.yml/badge.svg)
+[![codecov](https://codecov.io/gh/noahbenson/immlib/graph/badge.svg?token=8KO3K6DUX4)](https://codecov.io/gh/noahbenson/immlib)
+[![PyPI version](https://badge.fury.io/py/immlib.svg)](https://badge.fury.io/py/immlib)
+
+`immlib` is a library of utilities for managing and manipulating immutable
+scientific data with a focus on lazy calculations and workflows. It is based on
+a prototype library [`pimms`](https://github.com/noahbenson/pimms).
+
+---
+
+**Author**: Noah C. Benson <[nben@uw.edu](mailto:nben@uw.edu)>  
+**License**: MIT
+
+---
+

immlib-1.0.0.dev1/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "immlib"
+version = "1.0.0.dev1"
+description = """A library of utilites for immutable scientific data."""
+authors = [{name="Noah C. Benson", email="nben@uw.edu"}]
+license = {"text"="MIT"}
+readme = "README.md"
+requires-python = ">=3.8"
+keywords = ["persistent", "immutable", "functional", "scientific", "workflow"]
+classifiers = [
+    'Intended Audience :: Science/Research',
+    'Intended Audience :: Developers',
+    'License :: OSI Approved :: MIT License',
+    'Programming Language :: Python :: 3',
+    'Programming Language :: Python :: 3.8',
+    'Programming Language :: Python :: 3.9',
+    'Programming Language :: Python :: 3.10',
+    'Programming Language :: Python :: 3.11',
+    'Topic :: Software Development',
+    'Topic :: Software Development :: Libraries',
+    'Topic :: Software Development :: Libraries :: Python Modules',
+    'Topic :: Scientific/Engineering',
+    'Topic :: Scientific/Engineering :: Information Analysis',
+    'Operating System :: Microsoft :: Windows',
+    'Operating System :: POSIX',
+    'Operating System :: Unix',
+    'Operating System :: MacOS']
+dependencies = [
+     'pcollections >= 0.2.7',
+     'numpy >= 1.24.0',
+     'scipy >= 1.7.0',
+     'pint >= 0.18.0',
+     'docrep >= 0.3.2',
+     'joblib >= 1.3.0',
+     'cloudpathlib[s3,gs,azure] >= 0.18.0']
+
+[project.optional-dependencies]
+dev = ["torch >= 2.2.0", "pyyaml"]
+test = ["torch >= 2.2.0", "pyyaml"]
+
+[project.urls]
+homepage = "https://github.com/noahbenson/immlib"
+documentation = "https://github.com/noahbenson/immlib"
+repository = "https://github.com/noahbenson/immlib"

immlib-1.0.0.dev1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

immlib-1.0.0.dev1/src/immlib/__init__.py

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+################################################################################
+# immlib/__init__.py
+
+'''`immlib` is a library of tools for manipulating immutable scientific data.
+
+The `immlib` library is designed to enable immutable data structures and lazy
+computation in a scientific context, and it works primarily via a collection of
+utility functions and through the use of decorators, which are generally applied
+to classes and their members to declare how an immutable data-structure's
+members are related.  Taken together, these utilities form a DSL-like system for
+declaring workflows and immutable data-structures with full inheritance support.
+'''
+
+
+# Imports ######################################################################
+
+from .doc      import *
+from .util     import *
+from .pathlib  import *
+from .iolib    import *
+from .workflow import *
+# We want the version object from the ._version namespace.
+from ._version import version
+# Import the Global UnitRegistry object to the global immlib scope. This is the
+# value that gets updated when one runs `immlib.default_ureg()`, and this is the
+# UnitRegistry that is used as the default registry for all `immlib` functions.
+from .util._quantity import _initial_global_ureg as units
+"""UnitRegistry: the registry for units tracked by immlib.
+
+`immlib.units` is a global `pint`-module unit registry that can be used as a
+single global place for tracking units. Immlib functions that interact with
+units generally take an argument `ureg` that can be used to modify this
+registry.  Additionally, the default registry (this object, `immlib.units`) can
+be temporarily changed in a local block using `with immlib.default_ureg(ureg):
+...`.
+"""
+
+
+# Modules/Reloading ############################################################
+
+submodules = (
+    'immlib.doc._core',
+    'immlib.doc',
+    'immlib.util._core',
+    'immlib.util._numeric',
+    'immlib.util._quantity',
+    'immlib.util',
+    'immlib.pathlib._osf',
+    'immlib.pathlib._cache',
+    'immlib.pathlib._core',
+    'immlib.pathlib',
+    'immlib.iolib._core',
+    'immlib.iolib',
+    'immlib.workflow._core',
+    'immlib.workflow._plantype',
+    'immlib.workflow',
+    'immlib._version')
+"""tuple: a list of all immlib subpackage names in load-order.
+
+`immlib.submodules` is a tuple of strings, each of which is the name of one of
+the sub-submodules in `immlib`. The modules are listed in load-order and all
+`immlib` submodules are included.
+"""
+def reload_immlib():
+    """Reload and return the entire `immlib` package.
+
+    `immlib.reload_immlib()` reloads every submodule in the `immlib` package
+    then reloads `immlib` itself, and returns the reloaded package.
+
+    This function exists primarily for debugging purposes; its use is not
+    generally needed or advised.
+    """
+    import sys, importlib
+    for mod in submodules:
+        importlib.reload(sys.modules[mod])
+    return importlib.reload(sys.modules['immlib'])
+
+
+# Package Meta-Code ############################################################
+
+__version__ = version.string
+__all__ = tuple(
+    [k for k in locals()
+     if k[0] != '_'
+     if k != 'reload_immlib'
+     if k != 'submodules'
+     if ('immlib.' + k) not in submodules])

immlib-1.0.0.dev1/src/immlib/_version.py

@@ -0,0 +1,94 @@
+# -*- coding: utf-8 -*-
+################################################################################
+# immlib/_version.py
+#
+# Loads the version and splits it into meaningful pieces.
+
+
+import os, re
+from collections import namedtuple
+
+try:
+    from importlib.metadata import version as get_version
+    from importlib.metadata import PackageNotFoundError
+except ModuleNotFoundError:
+    try:
+        from importlib_metadata import version as get_version
+        from importlib_metadata import PackageNotFoundError
+    except ModuleNotFoundError:
+        pass
+
+
+# ImmLibVersion Type ###########################################################
+
+_ImmLibVersionBase = namedtuple(
+    '_ImmLibVersionBase',
+    ['string', 'major', 'minor', 'micro', 'stage', 'tuple'])
+class ImmLibVersion(_ImmLibVersionBase):
+    """The type that manages the version information for the immlib package."""
+    __slots__ = ()
+    def __new__(cls, string=None):
+        if string is None:
+            # Try to deduce the version string.
+            try:
+                string = get_version(__package__)
+            except PackageNotFoundError:
+                # Probably immlib isn't installed via pip or poetry so it
+                # doesn't show up as a registered module. As a backup, we can
+                # grab it from the pyproject.toml file.
+                base_path = os.path.join(os.path.split(__file__)[0], '..', '..')
+                pyproject_toml_path = os.path.join(base_path, 'pyproject.toml')
+                with open(pyproject_toml_path, 'r') as fl:
+                    pyproject_toml_lines = fl.read().split('\n')
+                for ln in pyproject_toml_lines:
+                    ln = ln.strip()
+                    if ln.startswith('version = '):
+                        string = ln.split('"')[1]
+                        break
+        if string is None:
+            from warnings import warn
+            warn("immlib could not detect its version number")
+            (major, minor, micro, stage) = (None, None, None, None)
+        else:
+            s = string
+            ss = s.split('.')
+            if len(ss) == 4:
+                (major, minor, micro, stage) = ss
+            else:
+                if len(ss) == 3:
+                    (major, minor, micro) = ss
+                elif len(ss) == 2:
+                    (major, minor) = ss
+                    micro = '0'
+                stage = None
+                for tag in ('rc', 'a', 'b'):
+                    if tag in micro:
+                        (micro, stage) = micro.split(tag)
+                        stage = tag + stage
+                        break
+            major = int(major)
+            minor = int(minor)
+            micro = int(micro)
+        tup = tuple(u for u in (major, minor, micro, stage) if u is not None)
+        return super(ImmLibVersion, cls).__new__(
+            cls, 
+            string=string,
+            major=major, minor=minor, micro=micro,
+            stage=stage,
+            tuple=tup)
+    def __str__(self):
+        return self.string
+    def __repr__(self):
+        return f"ImmLibVersion({repr(self.string)})"
+    def __iter__(self):
+        return iter(self.tuple)
+    def __reversed__(self):
+        return reversed(self.tuple)
+    def __contains__(self, k):
+        if isinstance(k, str):
+            return k in self.string
+        else:
+            return k in self.tuple
+
+# Declare the version object; this will automatically detect the version.
+version = ImmLibVersion()

immlib-1.0.0.dev1/src/immlib/doc/__init__.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+################################################################################
+# immlib/doc/__init__.py
+
+"""Documentation tools that operate via decorators.
+
+The module `immlib.doc` primarily contains a decorator, `docwrap`, which can be
+used to parse the inputs, outputs, parameters, and return values in a function's
+docstring and to save them in a global cache of all such docstring
+components. These components can then be referenced in the docstring of another
+function decorated with `@docwrap` such that the text needn't be repeated in
+every related function.
+"""
+
+from ._core import (docwrap, docproc, make_docproc)
+
+# For each of the above we transfer it to this (non-private) subpackage.
+docwrap.__module__ = __name__
+docproc.__module__ = __name__
+make_docproc.__module__ = __name__
+
+__all__ = ("docwrap", "docproc")

immlib-1.0.0.dev1/src/immlib/doc/_core.py

@@ -0,0 +1,103 @@
+# -*- coding: utf-8 -*-
+################################################################################
+# immlib/doc/_core.py
+
+
+# Dependencies #################################################################
+
+from re import compile as _re_compile
+from functools import wraps as _wraps
+from docrep import DocstringProcessor as _DocstringProcessor
+
+
+# The Document Processor #######################################################
+def make_docproc():
+    """Creates and returns a document preprocessor."""
+    docproc = _DocstringProcessor()
+    # We need to add a few features to the docproc's members so that we can
+    # process the Inputs and Outputs sections when present.
+    docproc.param_like_sections = \
+        docproc.param_like_sections + ['Inputs','Outputs']
+    docproc.patterns['Inputs'] = _re_compile(
+        docproc.patterns['Parameters'].pattern
+            .replace('Parameters', 'Inputs')
+            .replace('----------', '------'))
+    docproc.patterns['Outputs'] = _re_compile(
+        docproc.patterns['Parameters'].pattern
+            .replace('Parameters', 'Outputs')
+            .replace('----------', '-------'))
+    return docproc
+docproc = make_docproc()
+"""The `docrep.DocstringProcessor` object used by `immlib`.
+
+This object is used to process all of the doc-strings in the `immlib` library;
+it should be used only with the `immlib.docwrap` decorator, which can safely be
+applied anywhere in a sequence of decorators and which correctly applies the
+`wraps` decorator to its argument. Function documentation is always processed
+using the `sections=('Parameters', 'Returns', 'Raises', 'Examples', 'Inputs',
+'Outputs')` parameter and the `with_indent(4)` decorator. The base-name for the
+function `f` is `f.__module__ + '.' + f.__name__`.
+"""
+
+# The docwrap Decorator ########################################################
+def _docwrap_helper(f, fnname, indent=None, proc=docproc):
+    # If no ident number was provided, deduce it.
+    if indent is None:
+        if not hasattr(f, '__doc__') or f.__doc__ is None:
+            # Doesn't matter, no documentation.
+            indent = 0
+        else:
+            lines = f.__doc__.split('\n')
+            # We always skip the first line (the one that starts with """).
+            lines = lines[1:]
+            # Strip the lines.
+            striplines = [s.lstrip() for s in lines]
+            # Pick out the ones with text in them and calculate the indentation.
+            indents = [
+                len(ws_s) - len(s)
+                for (ws_s,s) in zip(lines, striplines)
+                if len(s) > 0]
+            # The minimum is the one we want.
+            indent = min(indents) if len(indents) > 0 else 0
+    ff = f
+    ff = proc.with_indent(indent)(ff)
+    fd = proc.get_sections(base=fnname, sections=proc.param_like_sections)
+    ff = fd(ff)
+    ff = _wraps(f)(ff)
+    # Post-process the documentation sections.
+    for section in ['parameters', 'other_parameters', 'inputs', 'outputs']:
+        k = fnname + '.' + section
+        v = proc.params.get(k, '')
+        if len(v) == 0: continue
+        for ln in v.split('\n'):
+            # Skip lines that start with whitespace.
+            if ln[0].strip() == '': continue
+            pname = ln.split(':')[0].strip()
+            proc.keep_params(k, pname)
+    return ff
+def docwrap(f=None, indent=None, proc=docproc):
+    """Applies standard doc-string processing to the decorated function.
+
+    The `immlib.docwrap` decorator applies a standard set of pre-processing to
+    the docstring of the function that follows it. This processing amounts to
+    using the `docrep` module's `DocstringProcessor` as a filter on the
+    documentation of the function. The function's documentation is always placed
+    in the base-name equal to its fully-qualified namespace name.
+
+    When called as `@docwrap(name)` for a string `name`, the documentation for
+    the decorated function is instead placed under the base-name `name`.
+    """
+    # If we've been given a string, then we've been called as @docwrap(name)
+    # instead of @docwrap.
+    if f is None:
+        return lambda fn: _docwrap_helper(
+            fn, fn.__module__ + '.' + fn.__name__,
+            indent=indent,
+            proc=proc)
+    if isinstance(f, str):
+        return lambda fn: _docwrap_helper(fn, f, indent=indent, proc=proc)
+    else:
+        return _docwrap_helper(
+            f, f.__module__ + '.' + f.__name__,
+            indent=indent,
+            proc=proc)

immlib-1.0.0.dev1/src/immlib/iolib/__init__.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+################################################################################
+# pimms/iolib/__init__.py
+
+"""Input/output tools managed by pimms; primarily the save and load functions.
+
+The `pimms.iolib` module contains tools for saving and loading data to/from
+paths or streams. This functionality is primarily supported via the `save` and
+`load` objects that behave as general (de)serializers to which formats can be
+registered.
+"""
+
+from ._core import (
+    Save,
+    save,
+    Load,
+    load,
+)
+
+__all__ = (
+    'Save',
+    'save',
+    'Load',
+    'load',
+)
+
+# Mark these as native to this module.
+Save.__module__ = __name__
+save.__module__ = __name__
+Load.__module__ = __name__
+load.__module__ = __name__