| 1 |
.. _cedar-extenspec: |
| 2 |
|
| 3 |
Extension Architecture Interface |
| 4 |
================================ |
| 5 |
|
| 6 |
The Cedar Backup Extension Architecture Interface is the application |
| 7 |
programming interface used by third-party developers to write Cedar |
| 8 |
Backup extensions. This appendix briefly specifies the interface in |
| 9 |
enough detail for someone to succesfully implement an extension. |
| 10 |
|
| 11 |
Backup extensions are third-party pieces of code which extend Cedar Backup's |
| 12 |
functionality. Extensions can be invoked from the Cedar Backup command line and |
| 13 |
are allowed to place their configuration in Cedar Backup's configuration file. |
| 14 |
|
| 15 |
There is a one-to-one mapping between a command-line extended action and |
| 16 |
an extension function. The mapping is configured in the Cedar Backup |
| 17 |
configuration file using a section something like this: |
| 18 |
|
| 19 |
:: |
| 20 |
|
| 21 |
<extensions> |
| 22 |
<action> |
| 23 |
<name>database</name> |
| 24 |
<module>foo</module> |
| 25 |
<function>bar</function> |
| 26 |
<index>101</index> |
| 27 |
</action> |
| 28 |
</extensions> |
| 29 |
|
| 30 |
|
| 31 |
In this case, the action “database” has been mapped to the extension |
| 32 |
function ``foo.bar()``. |
| 33 |
|
| 34 |
Extension functions can take any actions they would like to once they |
| 35 |
have been invoked, but must abide by these rules: |
| 36 |
|
| 37 |
1. Extensions must not write to ``stdout`` or ``stderr`` using functions |
| 38 |
such as ``print`` or ``sys.write``. |
| 39 |
|
| 40 |
2. All logging must take place using the Python logging facility. |
| 41 |
Flow-of-control logging should happen on the ``CedarBackup3.log`` |
| 42 |
topic. Authors can assume that ERROR will always go to the terminal, |
| 43 |
that INFO and WARN will always be logged, and that DEBUG will be |
| 44 |
ignored unless debugging is enabled. |
| 45 |
|
| 46 |
3. Any time an extension invokes a command-line utility, it must be done |
| 47 |
through the ``CedarBackup3.util.executeCommand`` function. This will |
| 48 |
help keep Cedar Backup safer from format-string attacks, and will |
| 49 |
make it easier to consistently log command-line process output. |
| 50 |
|
| 51 |
4. Extensions may not return any value. |
| 52 |
|
| 53 |
5. Extensions must throw a Python exception containing a descriptive |
| 54 |
message if processing fails. Extension authors can use their |
| 55 |
judgement as to what constitutes failure; however, any problems |
| 56 |
during execution should result in either a thrown exception or a |
| 57 |
logged message. |
| 58 |
|
| 59 |
6. Extensions may rely only on Cedar Backup functionality that is |
| 60 |
advertised as being part of the public interface. This means that |
| 61 |
extensions must not directly make use of methods, functions or values |
| 62 |
starting with with the ``_`` character. Furthermore, extensions |
| 63 |
should only rely on parts of the public interface that are documented |
| 64 |
in the online interface documentation. |
| 65 |
|
| 66 |
7. Extension authors are encouraged to extend the Cedar Backup public |
| 67 |
interface through normal methods of inheritence. However, no |
| 68 |
extension is allowed to directly change Cedar Backup code in a way |
| 69 |
that would affect how Cedar Backup itself executes when the extension |
| 70 |
has not been invoked. For instance, extensions would not be allowed |
| 71 |
to add new command-line options or new writer types. |
| 72 |
|
| 73 |
8. Extensions must be written to assume an empty locale set (no |
| 74 |
``$LC_*`` settings) and ``$LANG=C``. For the typical open-source |
| 75 |
software project, this would imply writing output-parsing code |
| 76 |
against the English localization (if any). The ``executeCommand`` |
| 77 |
function does sanitize the environment to enforce this configuration. |
| 78 |
|
| 79 |
Extension functions take three arguments: the path to configuration on |
| 80 |
disk, a ``CedarBackup3.cli.Options`` object representing the |
| 81 |
command-line options in effect, and a ``CedarBackup3.config.Config`` |
| 82 |
object representing parsed standard configuration. |
| 83 |
|
| 84 |
:: |
| 85 |
|
| 86 |
def function(configPath, options, config): |
| 87 |
"""Sample extension function.""" |
| 88 |
pass |
| 89 |
|
| 90 |
|
| 91 |
This interface is structured so that simple extensions can use standard |
| 92 |
configuration without having to parse it for themselves, but more |
| 93 |
complicated extensions can get at the configuration file on disk and |
| 94 |
parse it again as needed. |
| 95 |
|
| 96 |
The interface to the ``CedarBackup3.cli.Options`` and |
| 97 |
``CedarBackup3.config.Config`` classes has been thoroughly documented |
| 98 |
in the online interface documentation. The interface is guaranteed to change |
| 99 |
only in backwards-compatible ways unless the Cedar Backup major version number |
| 100 |
is bumped (i.e. from 3 to 4). |
| 101 |
|
| 102 |
If an extension needs to add its own configuration information to the |
| 103 |
Cedar Backup configuration file, this extra configuration must be added |
| 104 |
in a new configuration section using a name that does not conflict with |
| 105 |
standard configuration or other known extensions. |
| 106 |
|
| 107 |
For instance, our hypothetical database extension might require |
| 108 |
configuration indicating the path to some repositories to back up. This |
| 109 |
information might go into a section something like this: |
| 110 |
|
| 111 |
:: |
| 112 |
|
| 113 |
<database> |
| 114 |
<repository>/path/to/repo1</repository> |
| 115 |
<repository>/path/to/repo2</repository> |
| 116 |
</database> |
| 117 |
|
| 118 |
|
| 119 |
In order to read this new configuration, the extension code can either |
| 120 |
inherit from the ``Config`` object and create a subclass that knows how |
| 121 |
to parse the new ``database`` config section, or can write its own code |
| 122 |
to parse whatever it needs out of the file. Either way, the resulting |
| 123 |
code is completely independent of the standard Cedar Backup |
| 124 |
functionality. |
| 125 |
|
| 126 |
---------- |
| 127 |
|
| 128 |
*Previous*: :doc:`extensions` • *Next*: :doc:`depends` |
| 129 |
|
| 130 |
.. |note| image:: images/note.png |
| 131 |
.. |tip| image:: images/tip.png |
| 132 |
.. |warning| image:: images/warning.png |