Merge pull request #671 from mih/docs

Update docs

datalad_next/commands/ls_file_collection.py

@@ -319,6 +319,10 @@ class LsFileCollection(ValidatedInterface):
       by this command (``return_type='generator``) and only until the next
       result is yielded. PY]
 
+    ``annexworktree``
+      Like ``gitworktree``, but amends the reported items with git-annex
+      information, such as ``annexkey``, ``annexsize``, and ``annnexobjpath``.
+
     ``tarfile``
       Reports on members of a TAR archive. The collection identifier is the
       path of the TAR file. Item identifiers are the relative paths
@@ -329,6 +333,9 @@ class LsFileCollection(ValidatedInterface):
       cases. This file handle is only open when items are yielded directly
       by this command (``return_type='generator``) and only until the next
       result is yielded. PY]
+
+    ``zipfile``
+      Like ``tarfile`` for reporting on ZIP archives.
     """
     _validator_ = LsFileCollectionParamValidator()
 
@@ -386,6 +393,13 @@ class LsFileCollection(ValidatedInterface):
          ' | jq \'. | select(.type == "file")\' \\\n'
          ' | jq --slurp . \\\n'
          " | datalad addurls --key 'et:MD5-s{size}--{hash-md5}' - 'https://example.com/{item}'"},
+        {'text': 'List annex keys of all files in the working tree of a dataset',
+         'code_py': "[r['annexkey'] \\\n"
+                    "for r in ls_file_collection('annexworktree', '.') \\\n"
+                    "if 'annexkey' in r]",
+         'code_cmd': "datalad -f json ls-file-collection annexworktree . \\\n"
+                     "| jq '. | select(.annexkey) | .annexkey'",
+        },
     ]
 
     @staticmethod

datalad_next/runners/__init__.py

@@ -1,11 +1,33 @@
 """Execution of subprocesses
 
-This module provides all relevant components for subprocess execution.
+This module provides all relevant components for subprocess execution.  The
+main work horse is :func:`~datalad_next.runners.iter_subproc`, a context
+manager that enables interaction with a subprocess in the form of an iterable
+for input/output processing. Execution errors are communicated with the
+:class:`~datalad_next.runners.CommandError` exception. In addition, a few
+convenience functions are provided to execute Git commands (including
+git-annex).
 
 .. currentmodule:: datalad_next.runners
+.. autosummary::
+   :toctree: generated
+
+   iter_subproc
+   call_git
+   call_git_lines
+   call_git_oneline
+   call_git_success
+   iter_git_subproc
+   CommandError
+
+
+Low-level tooling from datalad-core
+-----------------------------------
 
-Low-level tooling
------------------
+.. deprecated:: 1.4
+   The functionality described here has been deprecated, and the associated
+   imports from datalad-core are scheduled for removal with version 2.0.
+   Use the implementations listed above instead.
 
 Few process execution/management utilities are provided, for
 generic command execution, and for execution command in the context
@@ -16,8 +38,6 @@
 
    GitRunner
    Runner
-   iter_subproc
-   iter_git_subproc
 
 Additional information on the design of the subprocess execution tooling
 is available from https://docs.datalad.org/design/threaded_runner.html

datalad_next/runners/git.py

@@ -72,7 +72,7 @@ def call_git(
     cwd: Path | None = None,
     force_c_locale: bool = False,
 ) -> None:
-    """Call git with no output capture, raises on non-zero exit.
+    """Call Git with no output capture, raises on non-zero exit.
 
     If ``cwd`` is not None, the function changes the working directory to
     ``cwd`` before executing the command.
@@ -96,7 +96,7 @@ def call_git_success(
     cwd: Path | None = None,
     capture_output: bool = False,
 ) -> bool:
-    """Call Git for a single line of output.
+    """Call Git and report success or failure of the command
 
     ``args`` is a list of arguments for the Git command. This list must not
     contain the Git executable itself. It will be prepended (unconditionally)
@@ -128,7 +128,7 @@ def call_git_lines(
     input: str | None = None,
     force_c_locale: bool = False,
 ) -> list[str]:
-    """Call Git for any (small) number of lines of output.
+    """Call Git for any (small) number of lines of output
 
     ``args`` is a list of arguments for the Git command. This list must not
     contain the Git executable itself. It will be prepended (unconditionally)
@@ -168,7 +168,7 @@ def call_git_oneline(
     input: str | None = None,
     force_c_locale: bool = False,
 ) -> str:
-    """Call git for a single line of output.
+    """Call Git for a single line of output
 
     If ``cwd`` is not None, the function changes the working directory to
     ``cwd`` before executing the command.