| 1 |
.. -*- mode: rst -*- |
| 2 |
.. vi: set ft=rst sts=4 ts=4 sw=4 et tw=79: |
| 3 |
|
| 4 |
.. _chap_designpatterns: |
| 5 |
|
| 6 |
********************** |
| 7 |
Miscellaneous patterns |
| 8 |
********************** |
| 9 |
|
| 10 |
DataLad is the result of a distributed and collaborative development effort |
| 11 |
over many years. During this time the scope of the project has changed |
| 12 |
multiple times. As a consequence, the API and employed technologies have been |
| 13 |
adjusted repeatedly. Depending on the age of a piece of code, a clear software |
| 14 |
design is not always immediately visible. This section documents a few design |
| 15 |
patterns that the project strives to adopt at present. Changes to existing code |
| 16 |
and new contributions should follow these guidelines. |
| 17 |
|
| 18 |
|
| 19 |
Generator methods in `Repo` classes |
| 20 |
=================================== |
| 21 |
|
| 22 |
Substantial parts of DataLad are implemented to behave like Python generators |
| 23 |
in order to be maximally responsive when processing long-running tasks. This |
| 24 |
included methods of the core API classes |
| 25 |
:class:`~datalad.support.gitrepo.GitRepo` and |
| 26 |
:class:`~datalad.support.annexrepo.AnnexRepo`. By convention, such methods |
| 27 |
carry a trailing `_` in their name. In some cases, sibling methods with the |
| 28 |
same name, but without the trailing underscore are provided. These behave like |
| 29 |
their generator-equivalent, but eventually return an iterable once processing |
| 30 |
is fully completed. |
| 31 |
|
| 32 |
|
| 33 |
Calls to Git commands |
| 34 |
===================== |
| 35 |
|
| 36 |
DataLad is built on Git, so calls to Git commands are a key element of the code |
| 37 |
base. All such calls should be made through methods of the |
| 38 |
:class:`~datalad.support.gitrepo.GitRepo` class. This is necessary, as only |
| 39 |
there it is made sure that Git operates under the desired conditions |
| 40 |
(environment configuration, etc.). |
| 41 |
|
| 42 |
For some functionality, for example querying and manipulating `gitattributes`, |
| 43 |
dedicated methods are provided. However, in many cases simple one-off calls to |
| 44 |
get specific information from Git, or trigger certain operations are needed. |
| 45 |
For these purposes the :class:`~datalad.support.gitrepo.GitRepo` class provides |
| 46 |
a set of convenience methods aiming to cover use cases requiring particular |
| 47 |
return values: |
| 48 |
|
| 49 |
- test success of a command: |
| 50 |
:meth:`~datalad.support.gitrepo.GitRepo.call_git_success` |
| 51 |
- obtain `stdout` of a command: |
| 52 |
:meth:`~datalad.support.gitrepo.GitRepo.call_git` |
| 53 |
- obtain a single output line: |
| 54 |
:meth:`~datalad.support.gitrepo.GitRepo.call_git_oneline` |
| 55 |
- obtain items from output split by a separator: |
| 56 |
:meth:`~datalad.support.gitrepo.GitRepo.call_git_items_` |
| 57 |
|
| 58 |
All these methods take care of raising appropriate exceptions when expected |
| 59 |
conditions are not met. Whenever desired functionality can be achieved |
| 60 |
using simple custom calls to Git via these methods, their use is preferred |
| 61 |
over the implementation of additional, dedicated wrapper methods. |
| 62 |
|
| 63 |
Command examples |
| 64 |
================ |
| 65 |
|
| 66 |
Examples of Python and commandline invocations of DataLad's user-oriented |
| 67 |
commands are defined in the class of the respective command as dictionaries |
| 68 |
within `_examples_`: |
| 69 |
|
| 70 |
.. code-block:: python |
| 71 |
|
| 72 |
_examples_ = [ |
| 73 |
dict(text="""Create a dataset 'mydataset' in the current directory""", |
| 74 |
code_py="create(path='mydataset')", |
| 75 |
code_cmd="datalad create mydataset", |
| 76 |
dict(text="""Apply the text2git procedure upon creation of a dataset""", |
| 77 |
code_py="create(path='mydataset', cfg_proc='text2git')", |
| 78 |
code_cmd="datalad create -c text2git mydataset") |
| 79 |
] |
| 80 |
|
| 81 |
The formatting of code lines is preserved. Changes to existing examples and |
| 82 |
new contributions should provide examples for Python and commandline API, as |
| 83 |
well as a concise description. |