Debian Codegraph @

docs/source/customization.rst

raw
1 .. -*- mode: rst -*-
2 .. vi: set ft=rst sts=4 ts=4 sw=4 et tw=79:
3
4 .. _chap_customization:
5
6 ********************************************
7 Customization and extension of functionality
8 ********************************************
9
10 DataLad provides numerous commands that cover many use cases. However, there
11 will always be a demand for further customization or extensions of built-in
12 functionality at a particular site, or for an individual user. DataLad
13 addresses this need with a mechanism for extending particular DataLad
14 functionality, such as metadata extractor, or providing entire command suites
15 for a specialized purpose.
16
17 As the name suggests, a :term:`DataLad extension` package is a proper Python package.
18 Consequently, there is a significant amount of boilerplate code involved in the
19 creation of a new DataLad extension. However, this overhead enables a number of
20 useful features for extension developers:
21
22 - extensions can provide any number of additional commands that can be grouped into
23 labeled command suites, and are automatically exposed via the standard DataLad commandline
24 and Python API
25 - extensions can define `entry_points` for any number of additional metadata extractors
26 that become automatically available to DataLad
27 - extensions can define `entry_points` for their test suites, such that the standard `datalad create`
28 command will automatically run these tests in addition to the tests shipped with DataLad core
29 - extensions can ship additional dataset procedures by installing them into a
30 directory ``resources/procedures`` underneath the extension module directory
31
32
33 Using an extension
34 ==================
35
36 A :term:`DataLad extension` is a standard Python package. Beyond installation of the package there is
37 no additional setup required.
38
39
40 Writing your own extensions
41 ===========================
42
43 A good starting point for implementing a new extension is the "helloworld" demo extension
44 available at https://github.com/datalad/datalad-extension-template. This repository can be cloned
45 and adjusted to suit one's needs. It includes:
46
47 - a basic Python package setup
48 - simple demo command implementation
49 - Travis test setup
50
51 A more complex extension setup can be seen in the DataLad Neuroimaging
52 extension: https://github.com/datalad/datalad-neuroimaging, including additional metadata extractors,
53 test suite registration, and a sphinx-based documentation setup for a DataLad extension.
54
55 As a DataLad extension is a standard Python package, an extension should declare
56 dependencies on an appropriate DataLad version, and possibly other extensions
57 via the standard mechanisms.