Debian Codegraph @

docs/source/design/miscpatterns.rst

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