Debian Codegraph @

docs/source/design/pos_vs_kw_parameters.rst

raw
1 .. -*- mode: rst -*-
2 .. vi: set ft=rst sts=4 ts=4 sw=4 et tw=79:
3
4 .. _chap_pos_vs_kw_parameters:
5
6 ********************************
7 Positional vs Keyword parameters
8 ********************************
9
10 .. topic:: Specification scope and status
11
12 This specification is a proposal, subject to review and further discussion.
13 Technical preview was implemented in the `PR #6176 <https://github.com/datalad/datalad/pull/6176>`_.
14
15 Motivation
16 ==========
17
18 Python allows for keyword arguments (arguments with default values) to be specified positionally.
19 That complicates addition or removal of new keyword arguments since such changes must account for their possible
20 positional use.
21 Moreover, in case of our Interface's, it contributes to inhomogeneity since when used in :term:`CLI`, all keyword
22 arguments
23 must be specified via non-positional ``--<option>``'s, whenever Python interface allows for them to be used
24 positionally.
25
26 Python 3 added possibility to use a ``*`` separator in the function definition to mandate that all keyword arguments
27 *after* it must be be used only via keyword (``<option>=<value>``) specification.
28 It is encouraged to use ``*`` to explicitly separate out positional from keyword arguments in majority of the cases,
29 and below we outline two major types of constructs.
30
31 Interfaces
32 ==========
33
34 Subclasses of the :class:`~datalad.interface.base.Interface` provide specification and implementation for both
35 :term:`CLI` and Python API interfaces.
36 All new interfaces must separate all CLI ``--options`` from positional arguments using ``*`` in their ``__call__``
37 signature.
38
39 **Note:** that some positional arguments could still be optional (e.g., destination ``path`` for ``clone``),
40 and thus should be listed **before** ``*``, despite been defined as a keyword argument in the ``__call__`` signature.
41
42 A unit-test will be provided to guarantee such consistency between :term:`CLI` and Python interfaces.
43 Overall, exceptions to this rule could be only some old(er) interfaces.
44
45 Regular functions and methods
46 =============================
47
48 Use of ``*`` is encouraged for any function (or method) with keyword arguments.
49 Generally, ``*`` should come before the first keyword argument, but similarly to the Interfaces above, it is left to
50 the discretion of the developer to possibly allocate some (just few) arguments which could be used positionally if
51 specified.