pelutils 4.2.1__cp315-cp315-win_amd64.whl

pelutils/__init__.py

@@ -0,0 +1,3 @@
+from .__version__ import __version__
+
+__all__ = ("__version__",)

pelutils/__version__.py

@@ -0,0 +1,2 @@
+# Do not put anything else in this file
+__version__ = "4.2.1"

pelutils/_c/__init__.py

@@ -0,0 +1,29 @@
+"""Utilities for pelutils C api, including a helpful way of passing numpy arrays and torch tensors to C."""
+
+from __future__ import annotations
+
+import numpy as np
+import numpy.typing as npt
+
+from pelutils.misc._conditional_import import import_torch
+from pelutils.types import AnyArray as AnyArray
+
+torch = import_torch()
+
+
+# Data pointer, num dims, dimensions pointer, strides pointer
+class ArrayArgs:
+    def __init__(self, arr: npt.ArrayLike):
+        if torch is not None and isinstance(arr, torch.Tensor):
+            arr = arr.numpy()
+        if not isinstance(arr, np.ndarray):
+            raise TypeError(f"Array cannot be of type {type(arr)}")
+        # Store attributes on self to prevent garbage collector cleaning them up until the object no longer exists
+        self._arr = arr
+        self._dims = np.array(self._arr.shape, dtype=np.uint64)
+        self._strides = np.array(self._arr.strides, dtype=np.uint64)
+
+        self.array_ptr = self._arr.ctypes.data
+        self.ndim = len(self._dims)
+        self.dims_ptr = self._dims.ctypes.data
+        self.strides_ptr = self._strides.ctypes.data

pelutils/_entry_points/linecounter.py

@@ -0,0 +1,149 @@
+import os
+from argparse import ArgumentParser
+
+import git
+import matplotlib.pyplot as plt
+import numpy as np
+from tqdm import tqdm
+
+from pelutils.misc import git_repo_info
+from pelutils.plots import Figure, get_dateticks
+from pelutils.types import FloatArray, IntArray
+
+_default_extensions = ", ".join((
+    ".py",
+    ".pyw",
+    ".c",
+    ".cpp",
+    ".cc",
+    ".h",
+    ".hpp",
+    ".tex",
+    ".html",
+    ".css",
+    ".js",
+    ".jsx",
+    ".ts",
+    ".java",
+    ".kt",
+    ".dart",
+    ".swift",
+    ".rs",
+    ".go",
+    ".r",
+    ".m",
+    ".sh",
+    ".zsh",
+    ".bash",
+))
+
+
+def _count(repo: git.Repo, branch: git.Head, exts: list[str]) -> tuple[FloatArray, dict[str, IntArray]]:
+    """Count lines of all files recursively in the current working directory.
+
+    Return an array of commit epoch times and a dict mapping file extensions to line counts
+    """
+    commits = list(reversed(list(repo.iter_commits())))  # List of commit from oldest to newest
+    times = np.array([c.committed_date for c in commits])
+    lines = {ext: np.zeros_like(times) for ext in exts}
+    try:
+        for i, commit in enumerate(tqdm(commits)):
+            try:
+                repo.git.checkout(str(commit))
+            except git.GitCommandError as e:
+                # This error happens if there is a file that has been moved in and out of .gitignore
+                # For safety, the commit is ignored
+                if "error: The following untracked working tree files would be overwritten by checkout:" in str(e):
+                    continue
+                raise
+            for path, __ in repo.index.entries:
+                try:
+                    ext = next(e for e in exts if path.endswith(e) and os.path.isfile(path))  # pyright: ignore[reportAttributeAccessIssue]
+                except StopIteration:
+                    continue
+                with open(path) as f:
+                    lines[ext][i] += len([line for line in f if line.strip()])
+    finally:
+        repo.git.checkout(branch)
+
+    return times, lines
+
+
+def _fuse_times(all_times: list[FloatArray]) -> FloatArray:
+    """Merge all time arrays together into a single array that is also sorted."""
+    n = sum(times.size for times in all_times)
+    times = np.empty(n, dtype=int)
+    idcs = [0] * len(all_times)
+    for i in range(n):
+        current_times = [time[idx] if idx < len(time) else float("inf") for time, idx in zip(all_times, idcs, strict=True)]
+        min_time = np.argmin(current_times)
+        times[i] = current_times[min_time]
+        idcs[min_time] += 1
+    return times
+
+
+def _last_initial_zero(values: IntArray) -> int:
+    if values[0] != 0:
+        return 0
+    return np.where(values != 0)[0][0] - 1
+
+
+def linecounter(repos: list[str], output: str, extensions: str, date_format: str, no_repo_name: bool):
+    file_extensions = [x.strip() for x in extensions.split(",")]
+    file_extensions = [x if x.startswith(".") else "." + x for x in file_extensions]
+    wd = os.getcwd()
+    repo_names, all_times, all_counts = list(), list(), list()
+    for possible_repo_path in repos:
+        repo_path, __ = git_repo_info(possible_repo_path)
+        if repo_path is None:
+            raise ValueError(f"{repo_path} is not a git repository")
+        os.chdir(repo_path)
+
+        repo = git.Repo()
+        branch = repo.active_branch
+        try:
+            times, lines = _count(repo, branch, file_extensions)
+        finally:
+            # Reset repo
+            repo.git.checkout(branch)
+
+        repo_names.append(os.path.split(repo_path)[-1])
+        all_times.append(times)
+        all_counts.append(lines)
+        os.chdir(wd)
+
+    with Figure(output):
+        repo_name: str | None = None
+        for _i, (repo_name, times, counts) in enumerate(zip(repo_names, all_times, all_counts, strict=True)):
+            for ext, line_counts in counts.items():
+                if not line_counts.any():
+                    continue
+                non_zero = line_counts != 0
+                non_zero[_last_initial_zero(line_counts)] = 1
+                lab = ext + (f" ({repo_name})" if len(repo_names) > 1 and not no_repo_name else "")
+                plt.plot(times[non_zero], line_counts[non_zero], marker=".", ms=8, lw=2, label=lab)
+
+        fused_times = _fuse_times(all_times)
+        plt.xticks(*get_dateticks(fused_times, date_format=date_format))
+        title = "Line count over time" + (f" ({repo_name})" if len(repo_names) == 1 and not no_repo_name else "")
+        plt.title(title)
+        plt.xlabel("Date of commit")
+        plt.ylabel("Number of non-empty lines")
+        plt.legend(loc=2)
+        plt.grid()
+
+
+def run():
+    parser = ArgumentParser()
+    parser.add_argument("repos", nargs="+")
+    parser.add_argument("-o", "--output", default="linecount.png", help="Path to produce output figure to.")
+    parser.add_argument("-e", "--extensions", default=_default_extensions, help="Comma separated list of file extensions to look for.")
+    parser.add_argument("-d", "--date-format", default="%y-%m-%d", help="How to format axis labels.")
+    parser.add_argument("-n", "--no-repo-name", action="store_true", help="Disable repository name from the produced figure.")
+    args = parser.parse_args()
+
+    linecounter(args.repos, args.output, args.extensions, args.date_format, args.no_repo_name)
+
+
+if __name__ == "__main__":
+    run()

pelutils/array/__init__.py

@@ -0,0 +1,48 @@
+"""Utilities and various algorithms for working with numpy arrays.
+
+The flagship is :func:`unique`, a drop-in for ``numpy.unique`` that runs in linear time
+(rather than sorting), making it dramatically faster on large arrays.
+
+Quick start
+-----------
+
+.. code-block:: python
+
+    import numpy as np
+    from pelutils.array import unique
+
+    x = np.random.randint(0, 100, size=10_000_000)
+    values = unique(x)
+    values, index, inverse, counts = unique(
+        x, return_index=True, return_inverse=True, return_counts=True,
+    )
+
+:class:`SparseGridBlobDetection` is used for detecting blobs in a sparse, N-dimensional grid.
+It also works for dense grids (effetively boolean numpy arrays), which can trivially be converted
+to sparse grids using ``np.where`` and ``np.column_stack``, as shown in the example.
+
+A blob is defined as an area of touching grid entries which are all ``True``. An obvious example
+is finding areas that are left in an image after thresholding on pixel values.
+
+.. code-block:: python
+
+    greyscale_image = ...  # Numpy array of shape height x width
+    thresholded = greyscale_image > 100
+    # Find the indices in the thresholded image which are True and stack them into an n x 2 array
+    coords_above_threshold = np.column_stack(np.where(thresholded))
+
+    blob_detector = SparseGridBlobDetection(coords_above_threshold)
+    blobs = blob_detector.find_all_blobs()
+
+    # The pixel coordinates in the first blob are fetched with
+    coords_above_threshold[blobs[0]]
+
+Both :func:`unique` and :class:`SparseGridBlobDetection` are implemented in C, making them
+blazingly fast compared to what you usually expect from Python.
+"""
+
+from ._blob import SparseGridBlobDetection
+from ._unique import unique
+from ._utils import array_bytes, array_ptr
+
+__all__ = ("SparseGridBlobDetection", "array_bytes", "array_ptr", "unique")

pelutils/array/_blob.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import _pelutils_c as _c
+import numpy as np
+
+import pelutils._c as c_utils
+from pelutils.types import BoolArray, IntArray
+
+
+class SparseGridBlobDetection:
+    """Detect blobs (continuous regions) in a sparse grid, implemented in C for high performance.
+
+    The grids can have an arbitrary number of dimensions, but a common usecase might be in image analysis.
+    Imaging thresholding an image based on pixel values. This class offers blazingly fast detection of all
+    blobs in the resulting boolean image.
+
+    While images are a prime use case, this class works for any dimensionality of arrays.
+    It provides two methods: ``find_all_blobs`` and ``find_single_blob``. The first, as demonstrated above, detects,
+    for each blobs, all pixels belonging to that blob. The second finds only a single blob and optionally accepts a
+    starting pixel.
+
+    Adjacency is defined by a plus-shaped kernel (generalised to the dimensions of the array), not a solid square-shaped
+    kernel. To get the behaviour of a square-shaped kernel, run a dilation with a square kernel over the array first.
+
+    Note that this class is stateful, meaning that for each call to either of the afforementioned methods, trying to
+    detected an already detected blob will raise a ``RuntimeError``.
+
+    Parameters
+    ----------
+    grid_coords : IntArray
+        Coordinates in the grid that are part of any blob. For an ``d``-dimensional grid, it has shape ``n x d`` where
+        ``n`` is the number of nodes in the grid belonging to any blob. For a grid representated by a boolean numpy
+        array, the coordinates can be gotten with ``np.column_stack(np.where(grid))``.
+
+        Note that even though ``grid_coords`` commonly would represent axis coordinates in a numpy array,
+        negative coordinates are fully supported.
+
+    wrap_axes : dict[int, int] | None, optional
+        A dictionary mapping axis numbers to their corresponding axis lengths
+        in the grid. Values will be wrapped on that axis. Negative axis numbers are supported.
+
+        As an example, if ``wrap_axes = {2: 10}``, the third column in ``grid_coords`` will be wrapped to
+        the range (0, 9), and the coordinates 0 and 9 will be considered next to each other. This is
+        effectively the same as doing ``grid_coords[:, 2] %= 10``, and pretending the ends touch each other.
+    """
+
+    def __init__(self, grid_coords: IntArray, wrap_axes: dict[int, int] | None = None):
+        """Initialise the blob detection by building necessary data structures."""
+        self._validate_grid_coords(grid_coords)
+
+        # Ensure correct dtype and make a copy to prevent both inside and outside changes to the array unintentionally causing a ruckus
+        self._grid_coords = grid_coords.astype(np.int64).copy()
+        # Boolean array of visited nodes
+        # After each call to `find_blob`, the found indices are set to True
+        self._visited = np.zeros(self._grid_coords.shape[0], dtype=bool)
+        # Next row in _grid_coords from which to start a search
+        self._next_index = 0
+        # For each axes that should be wrapped, the size of the axis in the grid is stored
+        # For axes which should not be wrapped, 0 is used
+        self._wrap_axis_sizes = np.zeros(self._grid_coords.shape[1], dtype=np.uint64)
+        wrap_axes = wrap_axes or dict()
+        for axis, axis_size in wrap_axes.items():
+            self._wrap_axis_sizes[axis] = axis_size
+
+        # The pointers array is used to store pointers from objects allocated in the C code and pass them between calls
+        # This is very ugly and hacky but it works and is arguably simpler that using the Python C API correctly in this
+        # use case - at least I'm lazy enough to assume so
+        # This first element is the pointer to the coord-to-index hashmap
+        self._pointers = np.empty(1, dtype=np.uint64)
+
+        self._index_args = c_utils.ArrayArgs(self._grid_coords)
+        self._pointer_args = c_utils.ArrayArgs(self._pointers)
+        self._wrap_axis_sizes_args = c_utils.ArrayArgs(self._wrap_axis_sizes)
+        _c.build_lookup_table(
+            self._pointer_args.array_ptr,
+            self._wrap_axis_sizes_args.array_ptr,
+            self._index_args.array_ptr,
+            self._grid_coords.shape[0],
+            self._grid_coords.shape[1],
+        )
+
+    @property
+    def done(self) -> bool:
+        """True if all coordinates have been explored and there are no more blobs to discover."""
+        return self._next_index == len(self._grid_coords)
+
+    @property
+    def next_index(self) -> int:
+        """Return the index of the first unvisited coordinate.
+
+        This starts at ``0`` and advances as blobs are detected, whether by :meth:`find_single_blob` or :meth:`find_all_blobs`.
+        It reaches ``len(grid_coords)`` when all coordinates have been visited, and there are no more blobs to be found.
+        This is equivalent to :meth:`done` being ``True``.
+
+        When a blob is detected, if the current value is part of that blob, it will increase to the index of the first coordinate
+        which has not been visited.
+        """
+        return self._next_index
+
+    @property
+    def visited_coords(self) -> BoolArray:
+        """Return 1D boolean array of length ``len(grid_coords)`` indicating which grid coordinates have been visited."""
+        visited_coords = self._visited.view()
+        visited_coords.flags.writeable = False
+        return visited_coords
+
+    def _validate_grid_coords(self, grid_coords: IntArray):
+        """Raise an exception if given ``grid_coords`` are invalid."""
+        if not np.issubdtype(grid_coords.dtype, np.integer):
+            raise TypeError(f"`grid_coords` must have an integer dtype, not {grid_coords.dtype}")
+        if len(grid_coords.shape) != 2:
+            raise ValueError(f"`grid_coords` must have shape n x d but has {len(grid_coords.shape)} axes")
+        if grid_coords.shape[1] == 0:
+            raise ValueError("Coordinates cannot be 0-dimensional")
+
+    def _mark_visited(self, indices: IntArray):
+        self._visited[indices] = True
+        while self._next_index < len(self._visited) and self._visited[self._next_index]:
+            self._next_index += 1
+
+    def find_single_blob(self, init_index: int | None = None) -> IntArray:
+        """Detect one blob starting at ``grid_coords[init_index]``, or ``grid_coords[self.next_index]`` if ``init_index`` is not provided.
+
+        Return the index of each row in ``grid_coords`` which is part of the blob.
+        """
+        if init_index is None:
+            init_index = self.next_index
+        if init_index >= len(self._grid_coords):
+            raise IndexError(f"Cannot start blob search from index {init_index} as there are only {len(self._grid_coords)} coordinates")
+        if self._visited[init_index]:
+            raise RuntimeError(f"Blob at index {init_index} ({self._grid_coords[init_index]}) has already been visited")
+        blob_indices: list[int] = list()
+        _c.find_blob(
+            self._pointer_args.array_ptr,
+            self._wrap_axis_sizes_args.array_ptr,
+            self._index_args.array_ptr,
+            init_index,
+            self._grid_coords.shape[0],
+            self._grid_coords.shape[1],
+            blob_indices,
+        )
+
+        blob_indices_arr = np.array(blob_indices)
+        self._mark_visited(blob_indices_arr)
+        return blob_indices_arr
+
+    def find_all_blobs(self) -> list[IntArray]:
+        """Detect all blobs in ``grid_coords``.
+
+        For each detected blob, an array is returned containing the rows in ``grid_coords`` which are part of that blob.
+        """
+        if len(self._grid_coords) == 0:
+            return list()
+        if self.done:
+            raise RuntimeError("Blob detection has already been run")
+
+        indices = np.array([], dtype=np.int64)
+        blobs: list[IntArray] = list()
+        while not self.done:
+            indices = self.find_single_blob()
+            blobs.append(indices)
+            self._mark_visited(indices)
+
+        return blobs
+
+    def __del__(self):
+        """Free the lookup table when the instance is no longer referenced to prevent memory leak."""
+        try:
+            _c.free_lookup_table(self._pointer_args.array_ptr)
+        except AttributeError:
+            # If the error happens early in init (e.g. wrong call to __init__), _pointer_args has not yet been defined,
+            # and the hashmap has not been created
+            pass

pelutils/array/_unique.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import TypeVar
+
+import _pelutils_c as _c
+import numpy as np
+import numpy.typing as npt
+
+import pelutils._c as c_utils
+from pelutils.types import AnyArray
+
+_ArrayT = TypeVar("_ArrayT", bound=AnyArray)
+
+
+def unique(
+    array: npt.ArrayLike,
+    *,
+    return_index: bool = False,
+    return_inverse: bool = False,
+    return_counts: bool = False,
+    axis: int = 0,
+):
+    """Return unique elements in a given numpy array.
+
+    This function works very similar to ``np.unique``, but it runs in linear time, making it significantly faster
+    for large arrays. Unlike with ``np.unique``, the returned unique values are unsorted. Because of this, it can
+    also be used for detecting uniqueness along axes when ordering along the respective axes matters.
+    """
+    array = np.asarray(array)
+    if np.issubdtype(array.dtype, np.object_):
+        raise TypeError(f"Unsupported array dtype {array.dtype}")
+
+    if array.ndim == 0:
+        raise ValueError("unique does not work for shapeless arrays")
+
+    if axis:
+        axes = list(range(len(array.shape)))
+        axes[0] = axis
+        axes[axis] = 0
+        array = array.transpose(axes)
+    else:
+        axes = None
+    if not array.flags["C_CONTIGUOUS"]:
+        array = np.ascontiguousarray(array)
+
+    index = np.empty(len(array), dtype=np.int64)
+    inverse = np.empty(len(array), dtype=np.int64) if return_inverse else None
+    counts = np.empty(len(array), dtype=np.int64) if return_counts else None
+
+    array_args = c_utils.ArrayArgs(array)
+    c = _c.unique(
+        array_args.array_ptr,
+        array_args.ndim,
+        array_args.dims_ptr,
+        array_args.strides_ptr,
+        index.ctypes.data,
+        inverse.ctypes.data if inverse is not None else 0,
+        counts.ctypes.data if counts is not None else 0,
+    )
+
+    index = index[:c]
+    if axis:
+        array = array[index]
+        array = np.ascontiguousarray(array.transpose(axes))
+    else:
+        array = array[index]
+    ret = [array]
+    if return_index:
+        ret.append(index)
+    if return_inverse:
+        assert inverse is not None
+        ret.append(inverse)
+    if return_counts:
+        assert counts is not None
+        ret.append(counts[index])
+
+    return tuple(ret) if len(ret) > 1 else ret[0]

pelutils/array/_unique.pyi

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Literal, overload
+
+import numpy.typing as npt
+
+from pelutils.types import AnyArray, IntArray
+
+@overload
+def unique(
+    array: npt.ArrayLike,
+    *,
+    return_index: Literal[False] = False,
+    return_inverse: Literal[False] = False,
+    return_counts: Literal[False] = False,
+    axis: int = 0,
+) -> AnyArray: ...
+@overload
+def unique(
+    array: npt.ArrayLike,
+    *,
+    return_index: Literal[True],
+    return_inverse: Literal[False] = False,
+    return_counts: Literal[False] = False,
+    axis: int = 0,
+) -> tuple[AnyArray, IntArray]: ...
+@overload
+def unique(
+    array: npt.ArrayLike,
+    *,
+    return_index: Literal[False] = False,
+    return_inverse: Literal[True],
+    return_counts: Literal[False] = False,
+    axis: int = 0,
+) -> tuple[AnyArray, IntArray]: ...
+@overload
+def unique(
+    array: npt.ArrayLike,
+    *,
+    return_index: Literal[True],
+    return_inverse: Literal[True],
+    return_counts: Literal[False] = False,
+    axis: int = 0,
+) -> tuple[AnyArray, IntArray, IntArray]: ...
+@overload
+def unique(
+    array: npt.ArrayLike,
+    *,
+    return_index: Literal[False] = False,
+    return_inverse: Literal[False] = False,
+    return_counts: Literal[True],
+    axis: int = 0,
+) -> tuple[AnyArray, IntArray]: ...
+@overload
+def unique(
+    array: npt.ArrayLike,
+    *,
+    return_index: Literal[True],
+    return_inverse: Literal[False] = False,
+    return_counts: Literal[True],
+    axis: int = 0,
+) -> tuple[AnyArray, IntArray, IntArray]: ...
+@overload
+def unique(
+    array: npt.ArrayLike,
+    *,
+    return_index: Literal[False] = False,
+    return_inverse: Literal[True],
+    return_counts: Literal[True],
+    axis: int = 0,
+) -> tuple[AnyArray, IntArray, IntArray]: ...
+@overload
+def unique(
+    array: npt.ArrayLike,
+    *,
+    return_index: Literal[True],
+    return_inverse: Literal[True],
+    return_counts: Literal[True],
+    axis: int = 0,
+) -> tuple[AnyArray, IntArray, IntArray, IntArray]: ...

pelutils/array/_utils.py

@@ -0,0 +1,31 @@
+import ctypes
+
+import numpy as np
+import numpy.typing as npt
+
+from pelutils.misc._conditional_import import import_torch
+
+torch = import_torch()
+
+
+def array_ptr(arr: npt.ArrayLike) -> ctypes.c_void_p:
+    """Return a pointer to a numpy array or torch tensor which can be used to interact with it in low-level languages like C/C++/Rust.
+
+    This function is mostly useful when not using Python's C api and instead interfacing with .so files directly with ctypes.
+    """
+    if torch is not None and isinstance(arr, torch.Tensor):
+        return ctypes.c_void_p(arr.data_ptr())
+    if not isinstance(arr, np.ndarray):
+        raise TypeError(f"Array should be of type np.ndarray or torch.Tensor, not {type(arr)}")
+    if not arr.flags.c_contiguous:
+        raise ValueError("Array must be C-contiguous")
+    return ctypes.c_void_p(arr.ctypes.data)
+
+
+def array_bytes(x: npt.ArrayLike) -> int:
+    """Calculate the size of a numpy array or torch tensor in bytes."""
+    if torch is not None and isinstance(x, torch.Tensor):
+        x = x.numpy()
+    if isinstance(x, np.ndarray):
+        return x.nbytes
+    raise TypeError(f"`x` of type {type(x)} is not a numpy array or torch tensor")

pelutils/job_parser/__init__.py

@@ -0,0 +1,61 @@
+"""Typed argument and configuration parsing that treats a run as a *job*.
+
+``argparse`` handles command-line flags but knows nothing about config files, so the
+moment you want to save a run's settings, reproduce it later, or launch a sweep of
+several runs, you end up hand-rolling a config file parser, merging it with the CLI args by
+hand, and writing your own record of what was actually run. :class:`JobParser` does all
+of that: you declare your arguments once with a type, and it resolves values from the
+command line *and* an INI config file into one or more :class:`JobDescription` objects —
+CLI values overriding config values, which override declared defaults. A single config
+file can describe many named jobs, and every resolved job can write out an exact,
+human-readable record of how it was invoked.
+
+Quick start
+-----------
+
+.. code-block:: python
+
+    from pathlib import Path
+    from pelutils.job_parser import Flag, JobParser, OptionalArg, RequiredArg
+
+    parser = JobParser(
+        RequiredArg("data-path", help="Training data directory"),
+        OptionalArg("learning-rate", default=1e-4, type=float, help="Optimizer learning rate"),
+        Flag("fp16", help="Use mixed precision"),
+        multiple_jobs=True,
+    )
+
+    for job in parser.parse_jobs():
+        # Names are --kebab-case on the CLI and snake_case attributes on the job
+        print(job.name, job.data_path, job.learning_rate, job.fp16)
+        job.write_documentation(Path("runs") / job.name / "arguments.ini")
+        ...  # Run your application with the resolved job values
+
+Declare :class:`RequiredArg` for values every job must supply, :class:`OptionalArg` for
+values with a default, and :class:`Flag` for booleans. Point the parser at a config file
+with ``--config-file config.ini``; a file may contain a shared ``[DEFAULT]`` section plus
+named sections that each become a job. Target a single section directly with
+``--config-file config.ini:section-name``. A config file for the parser above might look
+like:
+
+.. code-block:: ini
+
+    [DEFAULT]
+    data-path = /data/train    # Shared by every job below
+
+    [baseline]
+    # Inherits the default learning rate; fp16 as a bare key means True
+    fp16
+
+    [high-lr]
+    learning-rate = 5e-4
+
+For the common single-job case, drop ``multiple_jobs=True`` and call :meth:`JobParser.parse_job`
+to get one :class:`JobDescription` back. See :class:`JobParser` for the full API and
+:meth:`JobDescription.write_documentation` for auto-documenting a run.
+"""
+
+from ._job_parser import JobParser
+from ._structs import ArgumentTypes, ConfigError, Flag, JobDescription, JobParserError, OptionalArg, RequiredArg
+
+__all__ = ("ArgumentTypes", "ConfigError", "Flag", "JobDescription", "JobParser", "JobParserError", "OptionalArg", "RequiredArg")