| 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. |