class_docstr: Abstract base class for DataLad command implementations
  
  Any DataLad command implementation must be derived from this class. The
  code snippet below shows a complete sketch of a Python class with such an
  implementation.
  
  Importantly, no instances of command classes will created. Instead the main
  entry point is a static ``__call__()`` method, which must be implemented
  for any command. It is incorporated as a function in :mod:`datalad.api`, by
  default under the name of the file the implementation resides (e.g.,
  ``command`` for a ``command.py`` file).  Therefore the file should have a
  name that is a syntax-compliant function name. The default naming rule can
  be overwritten with an explicit alternative name (see
  :func:`datalad.interface.base.get_api_name`).
  
  For commands implementing functionality that is operating on DataLad
  datasets, a command can be also be bound to the
  :class:`~datalad.distribution.dataset.Dataset` class as a method using
  the ``@datasetmethod`` decorator, under the specified name.
  
  Any ``__call__()`` implementation should be decorated with
  :func:`datalad.interface.utils.eval_results`. This adds support for
  standard result processing, and a range of common command parameters that
  do not need to be manually added to the signature of ``__call__()``. Any
  implementation decorated in this way should be implemented as a generator,
  and ``yield`` :ref:`result records <chap_design_result_records>`.
  
  Any argument or keyword argument that appears in the signature of
  ``__call__()`` must have a matching item in :attr:`Interface._params_`.
  The dictionary maps argument names to
  :class:`datalad.support.param.Parameter` specifications. The specification
  contain CLI argument declarations, value constraint and data type
  conversation specifications, documentation, and optional
  ``argparse``-specific arguments for CLI parser construction.
  
  The class decorator :func:`datalad.interface.base.build_doc` inspects an
  :class:`Interface` implementation, and builds a standard docstring from
  various sources of structured information within the class (also see
  below). The documentation is automatically tuned differently, depending on
  the target API (Python vs CLI).
  
  .. code:: python
  
      @build_doc
      class ExampleCommand(Interface):
          """SHORT DESCRIPTION
  
          LONG DESCRIPTION
          ...
          """
  
          # COMMAND PARAMETER DEFINITIONS
          _params_ = dict(
              example=Parameter(
                  args=("--example",),
                  doc="""Parameter description....""",
                  constraints=...),
              ...
              )
          )
  
          # RESULT PARAMETER OVERRIDES
          return_type= 'list'
          ...
  
          # USAGE EXAMPLES
          _examples_ = [
              dict(text="Example description...",
                   code_py="Example Python code...",
                   code_cmd="Example shell code ..."),
              ...
          ]
  
          @staticmethod
          @datasetmethod(name='example_command')
          @eval_results
          def __call__(example=None, ...):
              ...
  
              yield dict(...)
  
  The basic implementation setup described above can be customized for
  individual commands in various way that alter the behavior and
  presentation of a specific command. The following overview uses
  the code comment markers in the above snippet to illustrate where
  in the class implementation these adjustments can be made.
  
  (SHORT/LONG) DESCRIPTION
  
  ``Interface.short_description`` can be defined to provide an
  explicit short description to be used in documentation and help output,
  replacing the auto-generated extract from the first line of the full
  description.
  
  COMMAND PARAMETER DEFINITIONS
  
  When a parameter specification declares ``Parameter(args=tuple(), ...)``,
  i.e. no arguments specified, it will be ignored by the CLI. Likewise, any
  ``Parameter`` specification for which :func:`is_api_arg` returns ``False``
  will also be ignored by the CLI. Additionally, any such parameter will
  not be added to the parameter description list in the Python docstring.
  
  RESULT PARAMETER OVERRIDES
  
  The :func:`datalad.interface.utils.eval_results` decorator automatically
  add a range of additional arguments to a command, which are defined in
  :py:data:`datalad.interface.common_opts.eval_params`. For any such
  parameter an Interface implementation can define an interface-specific
  default value, by declaring a class member with the respective parameter
  name and the desired default as its assigned value. This feature can be
  used to tune the default command behavior, for example, with respect to the
  default result rendering style, or its error behavior.
  
  In addition to the common parameters of the Python API, an additional
  ``Interface.result_renderer_cmdline`` can be defined, in order to
  instruct the CLI to prefer the specified alternative result renderer
  over an ``Interface.result_renderer`` specification.
  
  USAGE EXAMPLES
  
  Any number of usage examples can be described in an ``_examples_`` list
  class attribute. Such an example contains a description, and code examples
  for Python and CLI.
class_docstr_tok: ["Abstract","base","class","for","DataLad","command","implementations","Any","DataLad","command","implementation","must","be","derived","from","this","class",".","The","code","snippet","below","shows","a","complete","sketch","of","a","Python","class","with","such","an","implementation",".","Importantly",",","no","instances","of","command","classes","will","created",".","Instead","the","main","entry","point","is","a","static","``","__call__","(",")","``","method",",","which","must","be","implemented","for","any","command",".","It","is","incorporated","as","a","function","in",":","mod",":","`","datalad.api","`",",","by","default","under","the","name","of","the","file","the","implementation","resides","(","e.g.",",","``","command","``","for","a","``","command.py","``","file",")",".","Therefore","the","file","should","have","a","name","that","is","a","syntax-compliant","function","name",".","The","default","naming","rule","can","be","overwritten","with","an","explicit","alternative","name","(","see",":","func",":","`","datalad.interface.base.get_api_name","`",")",".","For","commands","implementing","functionality","that","is","operating","on","DataLad","datasets",",","a","command","can","be","also","be","bound","to","the",":","class",":","`","~datalad.distribution.dataset.Dataset","`","class","as","a","method","using","the","``","@","datasetmethod","``","decorator",",","under","the","specified","name",".","Any","``","__call__","(",")","``","implementation","should","be","decorated","with",":","func",":","`","datalad.interface.utils.eval_results","`",".","This","adds","support","for","standard","result","processing",",","and","a","range","of","common","command","parameters","that","do","not","need","to","be","manually","added","to","the","signature","of","``","__call__","(",")","``",".","Any","implementation","decorated","in","this","way","should","be","implemented","as","a","generator",",","and","``","yield","``",":","ref",":","`","result","records","<","chap_design_result_records",">","`",".","Any","argument","or","keyword","argument","that","appears","in","the","signature","of","``","__call__","(",")","``","must","have","a","matching","item","in",":","attr",":","`","Interface._params_","`",".","The","dictionary","maps","argument","names","to",":","class",":","`","datalad.support.param.Parameter","`","specifications",".","The","specification","contain","CLI","argument","declarations",",","value","constraint","and","data","type","conversation","specifications",",","documentation",",","and","optional","``","argparse","``","-specific","arguments","for","CLI","parser","construction",".","The","class","decorator",":","func",":","`","datalad.interface.base.build_doc","`","inspects","an",":","class",":","`","Interface","`","implementation",",","and","builds","a","standard","docstring","from","various","sources","of","structured","information","within","the","class","(","also","see","below",")",".","The","documentation","is","automatically","tuned","differently",",","depending","on","the","target","API","(","Python","vs","CLI",")",".","..","code",":",":","python","@","build_doc","class","ExampleCommand","(","Interface",")",":","``","''","''","SHORT","DESCRIPTION","LONG","DESCRIPTION","...","``","''","''","#","COMMAND","PARAMETER","DEFINITIONS","_params_","=","dict","(","example=Parameter","(","args=","(","``","--","example","''",",",")",",","doc=","''","''","''","Parameter","description","....","''","''","''",",","constraints=","...",")",",","...",")",")","#","RESULT","PARAMETER","OVERRIDES","return_type=","'list'","...","#","USAGE","EXAMPLES","_examples_","=","[","dict","(","text=","''","Example","description","...","''",",","code_py=","''","Example","Python","code","...","''",",","code_cmd=","''","Example","shell","code","...","''",")",",","...","]","@","staticmethod","@","datasetmethod","(","name='example_command","'",")","@","eval_results","def","__call__","(","example=None",",","...",")",":","...","yield","dict","(","...",")","The","basic","implementation","setup","described","above","can","be","customized","for","individual","commands","in","various","way","that","alter","the","behavior","and","presentation","of","a","specific","command",".","The","following","overview","uses","the","code","comment","markers","in","the","above","snippet","to","illustrate","where","in","the","class","implementation","these","adjustments","can","be","made",".","(","SHORT\/LONG",")","DESCRIPTION","``","Interface.short_description","``","can","be","defined","to","provide","an","explicit","short","description","to","be","used","in","documentation","and","help","output",",","replacing","the","auto-generated","extract","from","the","first","line","of","the","full","description",".","COMMAND","PARAMETER","DEFINITIONS","When","a","parameter","specification","declares","``","Parameter","(","args=tuple","(",")",",","...",")","``",",","i.e",".","no","arguments","specified",",","it","will","be","ignored","by","the","CLI",".","Likewise",",","any","``","Parameter","``","specification","for","which",":","func",":","`","is_api_arg","`","returns","``","False","``","will","also","be","ignored","by","the","CLI",".","Additionally",",","any","such","parameter","will","not","be","added","to","the","parameter","description","list","in","the","Python","docstring",".","RESULT","PARAMETER","OVERRIDES","The",":","func",":","`","datalad.interface.utils.eval_results","`","decorator","automatically","add","a","range","of","additional","arguments","to","a","command",",","which","are","defined","in",":","py",":","data",":","`","datalad.interface.common_opts.eval_params","`",".","For","any","such","parameter","an","Interface","implementation","can","define","an","interface-specific","default","value",",","by","declaring","a","class","member","with","the","respective","parameter","name","and","the","desired","default","as","its","assigned","value",".","This","feature","can","be","used","to","tune","the","default","command","behavior",",","for","example",",","with","respect","to","the","default","result","rendering","style",",","or","its","error","behavior",".","In","addition","to","the","common","parameters","of","the","Python","API",",","an","additional","``","Interface.result_renderer_cmdline","``","can","be","defined",",","in","order","to","instruct","the","CLI","to","prefer","the","specified","alternative","result","renderer","over","an","``","Interface.result_renderer","``","specification",".","USAGE","EXAMPLES","Any","number","of","usage","examples","can","be","described","in","an","``","_examples_","``","list","class","attribute",".","Such","an","example","contains","a","description",",","and","code","examples","for","Python","and","CLI","."]
docstr: Return a resolved reference dataset path from a `dataset` argument
  
  .. deprecated:: 0.16
     Use ``require_dataset()`` instead.
docstr_tok: ["Return","a","resolved","reference","dataset","path","from","a","`","dataset","`","argument","..","deprecated",":",":","0.16","Use","``","require_dataset","(",")","``","instead","."]
code: def get_refds_path(cls, dataset):
      """Return a resolved reference dataset path from a `dataset` argument
  
      .. deprecated:: 0.16
         Use ``require_dataset()`` instead.
      """
      # theoretically a dataset could come in as a relative path -> resolve
      if dataset is None:
          return dataset
      refds_path = (
          dataset.path
          if isinstance(dataset, Dataset)
          else Dataset(dataset).path
      )
      if refds_path:
          refds_path = str(resolve_path(refds_path))
      return refds_path
  
imports: import inspect
  import logging
  import os
  import re
  import textwrap
  import warnings
  from abc import ABC, abstractmethod
  from functools import wraps
  from importlib import import_module
  from typing import Callable, Dict, Generator, TypeVar, TYPE_CHECKING
  import datalad
  from datalad import cfg
  from datalad.core.local.resulthooks import get_jsonhooks_from_config, match_jsonhook2result, run_jsonhook
  from datalad.distribution.dataset import Dataset, resolve_path
  from datalad.interface.common_opts import eval_params
  from datalad.interface.results import known_result_xfms
  from datalad.interface.utils import get_result_filter, keep_result, render_action_summary, xfm_result, _process_results
  from datalad.support.exceptions import CapturedException, IncompleteResultsError
  from datalad.utils import get_wrapped_class
label_desc: Use image node_id 2 for calling the Interface obj's underlying member method code with example usage: obj.get_refds_path(cls, dataset) and returns: refds_path, dataset