Debian Codegraph @

docs/source/design/application_vs_library_mode.rst

raw
1 .. -*- mode: rst -*-
2 .. vi: set ft=rst sts=4 ts=4 sw=4 et tw=79:
3
4 .. _chap_design_application_vs_libary_mode:
5
6 ***************************************
7 Application-type vs. library-type usage
8 ***************************************
9
10 .. topic:: Specification scope and status
11
12 This specification describes the current implementation.
13
14 Historically, DataLad was implemented with the assumption of application-type
15 usage, i.e., a person using DataLad through any of its APIs. Consequently,
16 (error) messaging was primarily targeting humans, and usage advice focused on
17 interactive use. With the increasing utilization of DataLad as an
18 infrastructural component it was necessary to address use cases of library-type
19 or internal usage more explicitly.
20
21 DataLad continues to behave like a stand-alone application by default.
22
23 For internal use, Python and command-line APIs provide dedicated mode switches.
24
25 Library mode can be enabled by setting the boolean configuration setting
26 ``datalad.runtime.librarymode`` **before the start of the DataLad process**.
27 From the command line, this can be done with the option
28 ``-c datalad.runtime.librarymode=yes``, or any other means for setting
29 configuration. In an already running Python process, library mode can be
30 enabled by calling ``datalad.enable_libarymode()``. This should be done
31 immediately after importing the ``datalad`` package for maximum impact.
32
33 .. code-block:: python
34
35 >>> import datalad
36 >>> datalad.enable_libarymode()
37
38 In a Python session, library mode **cannot** be enabled reliably by just setting
39 the configuration flag **after** the ``datalad`` package was already imported.
40 The ``enable_librarymode()`` function must be used.
41
42 Moreover, with ``datalad.in_librarymode()`` a query utility is provided that
43 can be used throughout the code base for adjusting behavior according to the
44 usage scenario.
45
46 Switching back and forth between modes during the runtime of a process is not
47 supported.
48
49 A library mode setting is exported into the environment of the Python process.
50 By default, it will be inherited by all child-processes, such as dataset
51 procedure executions.
52
53
54 Library-mode implications
55 =========================
56
57 No Python API docs
58 Generation of comprehensive doc-strings for all API commands is skipped. This
59 speeds up ``import datalad.api`` by about 30%.