diff --git a/datalad_next/archive_operations/__init__.py b/datalad_next/archive_operations/__init__.py index a9dc25e7..cd0fc613 100644 --- a/datalad_next/archive_operations/__init__.py +++ b/datalad_next/archive_operations/__init__.py @@ -1,4 +1,15 @@ -"""Archive operation handlers""" +"""Handler for operations on various archive types + +All handlers implements the API defined by :class:`ArchiveOperations`. + +Available handlers: + +.. currentmodule:: datalad_next.archive_operations +.. autosummary:: + :toctree: generated + + tarfile +""" # allow for |-type UnionType declarations from __future__ import annotations @@ -25,7 +36,23 @@ class ArchiveOperations(ABC): - """ + """Base class of all archives handlers + + Any handler can be used as a context manager to adequately acquire and + release any resources necessary to access an archive. Alternatively, + the :func:`~ArchiveOperations.close()` method can be called, when archive + access is no longer needed. + + In addition to the :func:`~ArchiveOperations.open()` method for accessing + archive item content, each handler implements the standard + ``__contains__()``, and ``__iter__()``. + + ``__contains__()`` reports whether the archive contains an items of a given + identifier. + + ``__iter__()`` provides an iterator that yields + :class:`~datalad_next.iter_collections.utils.FileSystemItem` instances with + information on each archive item. """ def __init__(self, location: Any, *, cfg: ConfigManager | None = None): """ @@ -46,27 +73,39 @@ def __str__(self) -> str: @property def cfg(self) -> ConfigManager: + """ConfigManager given to the constructor, or the session default""" if self._cfg is None: self._cfg = datalad.cfg return self._cfg def __enter__(self): + """Default implementation that does nothing in particular""" return self def __exit__(self, exc_type, exc_value, traceback): + """Default implementation that only calls ``.close()``""" self.close() - # we have no desired to suppress exception, indicate standard + # we have no desire to suppress exception, indicate standard # handling by not returning True return @contextmanager @abstractmethod def open(self, item: Any) -> IO: - """ + """Get a file-like for an archive item + + Parameters + ---------- + item: + Any identifier for an archive item supported by a particular handler """ raise NotImplementedError def close(self) -> None: + """Default implementation for closing a archive handler + + This default implementation does nothing. + """ pass @abstractmethod diff --git a/datalad_next/commands/__init__.py b/datalad_next/commands/__init__.py index e21e6c8a..1138be55 100644 --- a/datalad_next/commands/__init__.py +++ b/datalad_next/commands/__init__.py @@ -1,4 +1,13 @@ -"""Components for basic functions of commands and their results""" +"""Essential tooling for implementing DataLad commands + +This module provides the advanced command base class +:class:`ValidatedInterface`, for implementing commands with uniform argument +validation and structured error reporting. + +Beyond that, any further components necessary to implement command are imported +in this module to offer a one-stop-shop experience. This includes +``build_doc``, ``datasetmethod``, and ``eval_results``, among others. +""" from __future__ import annotations from typing import Dict diff --git a/datalad_next/config/__init__.py b/datalad_next/config/__init__.py index cd5bc534..aa17805c 100644 --- a/datalad_next/config/__init__.py +++ b/datalad_next/config/__init__.py @@ -1 +1,6 @@ +"""Configuration query and manipulation + +This modules imports the central ``ConfigManager`` class from DataLad core. +""" + from datalad.config import ConfigManager diff --git a/datalad_next/credman/__init__.py b/datalad_next/credman/__init__.py index 5cb9ce89..a338f679 100644 --- a/datalad_next/credman/__init__.py +++ b/datalad_next/credman/__init__.py @@ -1 +1,9 @@ +"""Credential management + +.. currentmodule:: datalad_next.credman +.. autosummary:: + :toctree: generated + + manager +""" from .manager import CredentialManager diff --git a/datalad_next/exceptions/__init__.py b/datalad_next/exceptions/__init__.py index 6ad3479b..28fa8a5b 100644 --- a/datalad_next/exceptions/__init__.py +++ b/datalad_next/exceptions/__init__.py @@ -1,5 +1,7 @@ """All custom exceptions used in datalad-next""" +# TODO rethink the purpose of this module and possibly +# make it about *external* custom exceptions from datalad_next.runners import CommandError from datalad.support.exceptions import ( CapturedException, diff --git a/datalad_next/runners/__init__.py b/datalad_next/runners/__init__.py index b65b1fa7..ce3fa932 100644 --- a/datalad_next/runners/__init__.py +++ b/datalad_next/runners/__init__.py @@ -1,3 +1,8 @@ +"""Execution of subprocesses + +This module import all relevant components for subprocess execution. +""" + # runners from datalad.runner import ( GitRunner, diff --git a/datalad_next/tests/fixtures.py b/datalad_next/tests/fixtures.py index 0bf8711b..8995faf2 100644 --- a/datalad_next/tests/fixtures.py +++ b/datalad_next/tests/fixtures.py @@ -1,3 +1,5 @@ +"""Collection of fixtures for facilitation test implementations +""" import logging import os from pathlib import Path diff --git a/datalad_next/types/__init__.py b/datalad_next/types/__init__.py index e69de29b..75c360d0 100644 --- a/datalad_next/types/__init__.py +++ b/datalad_next/types/__init__.py @@ -0,0 +1,10 @@ +"""Custom types and dataclasses + +.. currentmodule:: datalad_next.types +.. autosummary:: + :toctree: generated + + annexkey + archivist + enums +""" diff --git a/datalad_next/uis/__init__.py b/datalad_next/uis/__init__.py index 44922d55..a0ea9574 100644 --- a/datalad_next/uis/__init__.py +++ b/datalad_next/uis/__init__.py @@ -1,3 +1,8 @@ +"""UI abstractions for user communication + +This module imports all necessary components. +""" + # make more obvious that this is a frontend that behaves # differently depending on many conditions from datalad.ui import ui as ui_switcher diff --git a/datalad_next/url_operations/__init__.py b/datalad_next/url_operations/__init__.py index d4c218e6..931ab2a8 100644 --- a/datalad_next/url_operations/__init__.py +++ b/datalad_next/url_operations/__init__.py @@ -1,5 +1,16 @@ -"""Abstract base class for URL operation handlers""" +"""Handlers for operations on various URL types and protocols +Available handlers: + +.. currentmodule:: datalad_next.url_operations +.. autosummary:: + :toctree: generated + + any + file + http + ssh +""" # allow for |-type UnionType declarations from __future__ import annotations diff --git a/docs/source/index.rst b/docs/source/index.rst index c5bbe209..86db9be4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -49,13 +49,16 @@ Command line reference cmd.rst -Python utilities ----------------- +Python tooling +-------------- + +``datalad-next`` comprises a number of more-or-less self-contained +mini-packages providing particular functionality. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - pyutils.rst + Infrastructure classes and utilities Git remote helpers diff --git a/docs/source/pyutils.rst b/docs/source/pyutils.rst index 729cb5fd..b97a248d 100644 --- a/docs/source/pyutils.rst +++ b/docs/source/pyutils.rst @@ -1,29 +1,31 @@ .. _pyutils: -Python utilities -**************** +Python tooling +************** + +``datalad-next`` comprises a number of more-or-less self-contained +mini-packages providing particular functionality. These implementations +are candidates for a migration into the DataLad core package, and are +provided here for immediate use. If and when components are migrated, +transition modules will be kept to prevent API breakage in dependent +packages. + .. currentmodule:: datalad_next .. autosummary:: :toctree: generated - commands.ValidatedInterface - config.ConfigManager + archive_operations + commands + config constraints - credman.manager + credman datasets exceptions iter_collections + runners + tests.fixtures + types + uis url_operations - url_operations.any - url_operations.file - url_operations.http - url_operations.ssh utils - utils.http_helpers - utils.multihash - utils.requests_auth - tests.fixtures - types.annexkey - types.archivist - types.enums