immlib 1.0.0.dev1__tar.gz → 1.0.0.dev2__tar.gz

{immlib-1.0.0.dev1/src/immlib.egg-info → immlib-1.0.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: immlib
-Version: 1.0.0.dev1
+Version: 1.0.0.dev2
 Summary: A library of utilites for immutable scientific data.
 Author-email: "Noah C. Benson" <nben@uw.edu>
 License: MIT
@@ -16,6 +16,8 @@ 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: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -28,34 +30,47 @@ Classifier: Operating System :: MacOS
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pcollections>=0.2.7
+Requires-Dist: pcollections>=0.3.2
 Requires-Dist: numpy>=1.24.0
 Requires-Dist: scipy>=1.7.0
-Requires-Dist: pint>=0.18.0
+Requires-Dist: pint>=0.20.0
 Requires-Dist: docrep>=0.3.2
 Requires-Dist: joblib>=1.3.0
 Requires-Dist: cloudpathlib[azure,gs,s3]>=0.18.0
+Requires-Dist: pyyaml>=6.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"
+Provides-Extra: docs
+Requires-Dist: torch>=2.2.0; extra == "docs"
+Requires-Dist: jupyter-book>=1.0.0; extra == "docs"
+Requires-Dist: matplotlib>=3.4.0; extra == "docs"
+Dynamic: license-file
 
-# immlib
+![immlib](https://noahbenson.github.io/immlib/_static/logo.svg "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
+**License**: MIT  
+**[Documentation](https://noahbenson.github.io/immlib)**
 
 ---
 
+`immlib` is a lightweight Python library that simplifies the design of
+application programming interfaces (APIs) for scientific libraries. The name
+immlib comes from the library’s philosophy of using immutable data to simplify
+scientific workflows.
+
+`immlib` is heavily based on the library
+[`pimms`](https://github.com/noahbenson/pimms), which effectively served as a
+prototype for `immlib`. Both libraries were motivated by a number of observations
+about the design of scientific software and are an attempt to make some of these
+problems easier to manage.
+
+For more information, see the [documentation](https://noahbenson.github.io/immlib).

immlib-1.0.0.dev2/README.md

@@ -0,0 +1,26 @@
+![immlib](https://noahbenson.github.io/immlib/_static/logo.svg "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)
+
+---
+
+**Author**: Noah C. Benson <[nben@uw.edu](mailto:nben@uw.edu)>  
+**License**: MIT  
+**[Documentation](https://noahbenson.github.io/immlib)**
+
+---
+
+`immlib` is a lightweight Python library that simplifies the design of
+application programming interfaces (APIs) for scientific libraries. The name
+immlib comes from the library’s philosophy of using immutable data to simplify
+scientific workflows.
+
+`immlib` is heavily based on the library
+[`pimms`](https://github.com/noahbenson/pimms), which effectively served as a
+prototype for `immlib`. Both libraries were motivated by a number of observations
+about the design of scientific software and are an attempt to make some of these
+problems easier to manage.
+
+For more information, see the [documentation](https://noahbenson.github.io/immlib).

{immlib-1.0.0.dev1 → immlib-1.0.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "immlib"
-version = "1.0.0.dev1"
+version = "1.0.0.dev2"
 description = """A library of utilites for immutable scientific data."""
 authors = [{name="Noah C. Benson", email="nben@uw.edu"}]
 license = {"text"="MIT"}
@@ -16,6 +16,8 @@ classifiers = [
     'Programming Language :: Python :: 3.9',
     'Programming Language :: Python :: 3.10',
     'Programming Language :: Python :: 3.11',
+    'Programming Language :: Python :: 3.12',
+    'Programming Language :: Python :: 3.13',
     'Topic :: Software Development',
     'Topic :: Software Development :: Libraries',
     'Topic :: Software Development :: Libraries :: Python Modules',
@@ -26,17 +28,19 @@ classifiers = [
     'Operating System :: Unix',
     'Operating System :: MacOS']
 dependencies = [
-     'pcollections >= 0.2.7',
+     'pcollections >= 0.3.2',
      'numpy >= 1.24.0',
      'scipy >= 1.7.0',
-     'pint >= 0.18.0',
+     'pint >= 0.20.0',
      'docrep >= 0.3.2',
      'joblib >= 1.3.0',
-     'cloudpathlib[s3,gs,azure] >= 0.18.0']
+     'cloudpathlib[s3,gs,azure] >= 0.18.0',
+     'pyyaml >= 6.0']
 
 [project.optional-dependencies]
-dev = ["torch >= 2.2.0", "pyyaml"]
-test = ["torch >= 2.2.0", "pyyaml"]
+dev = ["torch >= 2.2.0"]
+test = ["torch >= 2.2.0"]
+docs = ["torch >= 2.2.0", "jupyter-book >= 1.0.0", "matplotlib >= 3.4.0"]
 
 [project.urls]
 homepage = "https://github.com/noahbenson/immlib"

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

@@ -0,0 +1,131 @@
+# -*- 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.
+
+Attributes
+----------
+units : pint.UnitRegistry
+    The registry for units tracked by ``immlib``. The ``immlib.units`` object
+    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): ...``.
+version : immlib.Version
+    A representation of the ``immlib`` version. The version string may be
+    obtained via ``immlib.version.string``; major, minor, and micro numbers
+    (when present) may be obtained via ``immlib.version.major``,
+    ``immlib.version.minor``, and ``immlib.version.micro`` (when not provided
+    the are set to ``None``), and a stage tag (a string), if given, can be
+    obtained via ``immlib.version.stage``.
+submodules : tuple of str
+    A tuple of strings, each of which is the name of one of the submodules in
+    ``immlib``. The modules are listed in load-order and all ``immlib``
+    submodules, including private submodules, are included.
+docproc: docrep.DocstringProcessor object
+    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__``.
+'''
+
+
+# Imports #####################################################################
+
+# We always load _init first.
+from ._init    import reclaim
+# Then the core library.
+from .doc      import *
+from .util     import *
+from .pathlib  import *
+from .iolib    import *
+from .workflow import *
+from .types    import *
+# 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
+# Do the same for the global DocstringProcessor (from the docrep library) from
+# the doc subpackage.
+from .doc._core import _initial_global_docproc as docproc
+# We want the version object from the ._version namespace; this is always last.
+from ._version import (version, Version)
+
+
+# Modules/Reloading ###########################################################
+
+submodules = (
+    'immlib._init',
+    '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.types._core',
+    'immlib.types',
+    'immlib._version')
+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.
+
+    .. Warning:: This function exists primarily for debugging purposes; its use
+        is not generally needed or advised by users of the library.
+
+    Returns
+    -------
+    module
+        The newly reloaded ``immlib`` module.
+
+    Examples
+    --------
+    >>> import immlib as il
+    >>> il.units = None  # This will break parts of the library.
+    >>> il = il.reload_immlib()  # But this resets it.
+    >>> il.units is not None
+    True
+    """
+    import sys, importlib
+    for mod in submodules:
+        importlib.reload(sys.modules[mod])
+    return importlib.reload(sys.modules[__name__])
+
+
+# Package Meta-Code ###########################################################
+
+__version__ = version.string
+__all__ = tuple(
+    [k for k in locals()
+     if k[0] != '_'
+     if k != 'submodules'
+     if k != 'version'
+     if ('immlib.' + k) not in submodules])
+# We want to mark our functions as being from the immlib module.
+reclaim(__name__, __all__, del_reclaim=True)

immlib-1.0.0.dev2/src/immlib/_init.py

@@ -0,0 +1,108 @@
+# -*- coding: utf-8 -*-
+###############################################################################
+# immlib/_init.py
+
+"""Utilities and global definitions needed by theoretically the entire rest of
+the `immlib` library during the import process.
+
+The `immlib._init` module is the first submodule of the `immlib` library that
+is loaded during the import process and is the firt that is reloaded when the
+`immlib.reload_immlib()` library is called. Accordingly, functions and
+variables that are needed by other modules can be put here. These functions and
+variables, if they are intended to be public, should be reclaimed by another
+module (see the `immlib._init.reclaim` / `immlib.util.reclaim` function).
+"""
+
+
+# Dependencies ################################################################
+
+import sys
+from types import ModuleType
+
+
+# Utility Functions ###########################################################
+
+def reclaim(modname, attributes=Ellipsis, *,
+            del_reclaim=False,
+            skip_externs=True,
+            skip_private=True,
+            skip_modules=True):
+    """Sets the ``__module__`` attributes of objects in the module whose name
+    is `modname` to be `modname`.
+
+    ``reclaim(__name__, __all__)``, when run at the end of an ``__init__.py``
+    file, will set the module names of all objects in that module's ``__all__``
+    list to be ``__name__``, effectively hiding any submodule ownership of
+    those objects.
+
+    ``reclaim(__name__)`` attempts to reclaim all attributes in the module, not
+    just those in the ``__all__`` list.
+
+    Parameters
+    ----------
+    modname : str
+        The name of the module to reclaim. Typically, ``reclaim`` is called
+        from an ``__init__.py`` file using the syntax ``reclaim(__name__)`` or
+        ``reclaim(__name__, __all__)``.
+    attributes : Ellipsis | iterable of str, optional
+        The attributes to reclaim. If this is explicitly given then it must be
+        an iterable of attribute names (strings). In this case, no additional
+        checks implied by the subsequent ``skip_`` and ``only_`` parameters are
+        performed. If `attributes` is not provided or is given the value of
+        ``Ellipsis`` (the default), then all attributes of the module are
+        considered, and the filters specified by the subsequent options are
+        applied.
+    del_reclaim : bool, optional
+        If the optional argument `del_reclaim` is set to ``True``, then the
+        ``reclaim`` attribute is deleted from the module as well. This can be
+        used to automatically sanitize a module.
+    skip_externs : bool, optional
+        The `skip_externs` option (default: ``True``) can be set to ``False``
+        to instruct the ``reclaim`` function to include attributes that are not
+        from a submodule of the module named by `modname`.
+
+        If this option is set to ``True``, then attributes of the module on
+        which ``reclaim`` is run are only reclaimed if they belong to a
+        submodule of of that module.
+
+        .. Warning:: If `skip_externs` is set to ``False``, attributes like
+            ``np`` from the import statement ``import numpy as np`` at the top
+            of an ``__init__.py`` file can result in the ``numpy`` module being
+            reclaimed (if ``skip_modules`` is also ``False``). Similarly, if
+            the line ``from immlib.util import reclaim`` appears in an
+            ``__init__.py`` file followed by ``reclaim(__name__,
+            skip_externs=False)`` then the ``reclaim`` function will be
+            reclaimed by the module.
+    skip_private : boolean, optional
+        The `skip_private` option may be set to ``False`` to instruct the
+        function to claim ownership over attributes whose names begin with the
+        underscore (``_``) charcter. If this is not provided or is ``True``,
+        then such attributes are skipped.
+    skip_modules : boolean, optional
+        The `skip_modules` option (default: ``True``) may be set to false to
+        instruct the ``reclaim`` function to attempt to reclaim modules as well
+        as functions and attributes.
+
+    Returns
+    -------
+    str
+        The module named by the given `modname` argument.
+    """
+    mod = sys.modules[modname]
+    for k in dir(mod):
+        if skip_private and k[0] == '_':
+            continue
+        obj = getattr(mod, k)
+        if skip_modules and isinstance(obj, ModuleType):
+            continue
+        if del_reclaim and obj is reclaim:
+            continue
+        objmodname = getattr(obj, '__module__', modname)
+        if objmodname == modname:
+            continue
+        if skip_externs and not objmodname.startswith(modname):
+            continue
+        obj.__module__ = modname
+    if del_reclaim and hasattr(mod, 'reclaim'):
+        delattr(mod, 'reclaim')
+    return mod

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

@@ -0,0 +1,235 @@
+# -*- coding: utf-8 -*-
+################################################################################
+# immlib/_version.py
+
+
+# Dependencies #################################################################
+
+from ast import literal_eval
+from collections import namedtuple
+from pathlib import Path
+from warnings import warn
+
+
+# Version Type #################################################################
+
+VersionTuple = namedtuple(
+    'VersionTuple',
+    ['string', 'tuple', 'major', 'minor', 'micro', 'stage'])
+class Version(VersionTuple):
+    """A type that represents a Python package version.
+
+    Python packages are represented simultaneously as version strings, version
+    tuples, and by the version components `major`, `minor`, `micro`, and
+    `stage`.
+
+    Parameters
+    ----------
+    string : str or None, optional
+        The version string to be represented. If this argument is not provided,
+        then one or both of the `package_name` and `pyproject_path` options must
+        be provided so that the version string can be obtained via the package
+        version or the `pyproject.toml` file.
+    package_name : str or None, optional
+        If the first argument (`string`) is provided, then this argument is
+        ignored; otherwise, the version string is first searched for by this
+        package name using the `importlib` or `importlib_metadata` packages. If
+        found, then this version string is represented in the `Version` object.
+    pyproject_path : path-like or None, optional
+        If the first argument (`string`) is not given and the `package_name` is
+        not given, then the version is searched for in the `pyproject.toml` file
+        given by this path. In order for such a file to be valid, it must
+        contain a line that, when stripped of whitespace, begins with the string
+        `'version='` followed by a string representation (e.g.,
+        `'version="1.12.5"'`). If such a line is found in the `[project]`
+        section of the TOM: file pointed to by this argument, then it is
+        represented as the version string in the `Version` object.
+    on_error : {'warn' | 'ignore' | 'raise'}, optional
+        How to handle failures to deduce or parse the version number. If
+        `'raise'` is given, then the errors are allowed to be raised. If
+        `'warn'`, then a warning is raised and a null version is returned. If
+        `'ignore'`, then errors are ignored and a null version is returned. The
+        default is `'raise'`.
+    tag_prefixes : tuple of str, optional
+        An optional tuple of strings that can appear as the prefixes of stage
+        tagss at the end of the version string. By default, this is `('rc', 'a',
+        'b')`, so version strings like `'1.1.12a6'` and `'1.1.12rc6'` are valid
+        but `'1.1.12c6'` is not.
+    
+    Attributes
+    ----------
+    string : str
+        The string representing the package version. For example `"1.2.15"` or
+        `"0.2.2.dev1"`.
+    tuple : tuple of int and str
+        The components of the version string, for example, `(1, 2, 15)` or
+        `(0, 2, 2, 'dev1')`. Any missing component is excluded.
+    major : int
+        The major version number, typically indicates major API version.
+    minor : int
+        The minor version number, typically indicates minor API version.
+    micro : int
+        The micro version number, typically indicates patch increment number.
+    stage : str
+        The development stage of the version. For example `'dev1'` or `'rc2'`.
+    """
+
+    # Static Methods -----------------------------------------------------------
+    def getstring(package_name=None, pyproject_path=None):
+        """Returns the current version string for the given package name.
+        
+        `Version.getstring(package_name)` returns the version string of the
+        package with the given package name.
+        
+        `Version.getstring(pyproject_path=path)` returns the version string
+        found in the pyproject.toml file found at the given `path`.
+        
+        `Version.getstring(package_name, path)` returns
+        `Version.getstring(package_name)` if the given `package_name` is found,
+        otherwise returns `Version.getstring(pyproject_path=path)`.
+        """
+        if package_name is None and pyproject_path is None:
+            raise ValueError("Version.getstring() requires 1 or 2 arguments")
+        if package_name is not None:
+            try:
+                from importlib.metadata import version
+                from importlib.metadata import PackageNotFoundError
+            except ModuleNotFoundError:
+                from importlib_metadata import version
+                from importlib_metadata import PackageNotFoundError
+            if pyproject_path is None:
+                return version(package_name)
+            # Try to deduce the version string but don't raise if this fails.
+            try:
+                return version(package_name)
+            except PackageNotFoundError:
+                pass
+        # Either a package name wasn't given or the package wasn't found; check
+        # the pyproject.toml if possible.
+        path = Path(pyproject_path)
+        with path.open('rt') as fl:
+            toml_lines = fl.read().split('\n')
+        in_project_section = False
+        for ln in toml_lines:
+            ln = ln.strip()
+            if ln == '[project]':
+                in_project_section = True
+            elif ln[0] == '[' and ln[-1] == ']':
+                in_project_section = False
+            elif in_project_section and '=' in ln:
+                parts = ln.split('=')
+                if parts[0].strip() == 'version':
+                    v = '='.join(parts[1:]).strip()
+                    return literal_eval(v)
+        # If we reach this point, we didn't fine a version line.
+        if package_name is not None:
+            raise RuntimeError(
+                f"Version.getstring() found no package named '{package_name}'"
+                f" and no 'version = ...' line in file {path}")
+        else:
+            raise RuntimeError(
+                f"Version.getstring() found no 'version = ...' line in file"
+                f" {path}")
+
+    # Construction -------------------------------------------------------------
+    __slots__ = ()
+    null = None
+    def __new__(cls, string=None, /, *,
+                package_name=None,
+                pyproject_path=None,
+                on_error='warn',
+                tag_prefixes=('rc', 'a', 'b')):
+        if on_error not in ('raise', 'warn', 'ignore'):
+            raise ValueError(
+                "invalid value for on_error; must be one of 'raise', 'warn',"
+                " or 'ignore'")
+        if string is None:
+            # Try to deduce the version string.
+            if on_error == 'raise':
+                string = Version.getstring(package_name, pyproject_path)
+            else:
+                try:
+                    string = Version.getstring(package_name, pyproject_path)
+                except Exception as e:
+                    if on_error == 'warn':
+                        warn(
+                            f"Version: could not deduce version string for"
+                            f" package_name={repr(package_name)} and"
+                            f" pyproject_path={repr(pyproject_path)}")
+                        return Version.null
+                    else:
+                        return Version.null
+        ss = string.split('.')
+        nss = len(ss)
+        if nss == 4:
+            (major, minor, micro, stage) = ss
+        else:
+            if nss == 3:
+                (major, minor, micro) = ss
+                last = micro
+            elif nss == 2:
+                (major, minor) = ss
+                micro = '0'
+                last = minor
+            elif nss == 1:
+                major = ss
+                (minor, micro) = ('0', '0')
+                last = major
+            else:
+                raise ValueError(
+                    f"invalid version string: '{string}' contains {nss}"
+                    f" components")
+            stage = None
+            for tag in tag_prefixes:
+                if tag in last:
+                    (num, stage) = last.split(tag)
+                    stage = tag + stage
+                    if last is micro:
+                        micro = num
+                    elif last is minor:
+                        minor = num
+                    else:
+                        major = num
+                    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(Version, cls).__new__(
+            cls,
+            string=string,
+            tuple=tup,
+            major=major,
+            minor=minor,
+            micro=micro,
+            stage=stage)
+    def __str__(self):
+        return self.string
+    def __repr__(self):
+        return f"Version({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
+Version.null = VersionTuple.__new__(
+    Version,
+    string='',
+    tuple=(),
+    major=None,
+    minor=None,
+    micro=None,
+    stage=None)
+
+
+# Variables ####################################################################
+
+# The path of immlib's pyproject.toml file.
+pyproject_path = Path(__file__).parent.parent.parent / 'pyproject.toml'
+
+# Declare the version object; this will automatically detect the version.
+version = Version(package_name=__package__, pyproject_path=pyproject_path)

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

@@ -0,0 +1,38 @@
+# -*- 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.
+
+Attributes
+----------
+docproc: docrep.DocstringProcessor
+    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__``.
+"""
+
+from ._core import (
+    docwrap, make_docproc, default_docproc,
+    detect_indentation, reindent)
+
+# make_docproc lives in this subpackage (the others live in the immlib package
+# and will be reclaimed there).
+make_docproc.__module__ = __name__
+
+__all__ = ("docwrap", "default_docproc")
+
+from .._init import reclaim
+reclaim(__name__, del_reclaim=True)