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