Debian Codegraph @

docs/manual/extenspec.rst

raw
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