diff --git a/doc/dev/reference/components/index.rst b/doc/dev/reference/components/index.rst index ec91f206c..7273e82ca 100644 --- a/doc/dev/reference/components/index.rst +++ b/doc/dev/reference/components/index.rst @@ -8,6 +8,7 @@ Components info menu + packages daemon firewall webserver diff --git a/doc/dev/reference/components/packages.rst b/doc/dev/reference/components/packages.rst new file mode 100644 index 000000000..6ae4f77fb --- /dev/null +++ b/doc/dev/reference/components/packages.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +Packages +^^^^^^^^ + +.. autoclass:: plinth.package.Packages + :members: diff --git a/doc/dev/tutorial/components.rst b/doc/dev/tutorial/components.rst index fde22cf41..9b2d801a1 100644 --- a/doc/dev/tutorial/components.rst +++ b/doc/dev/tutorial/components.rst @@ -112,6 +112,36 @@ the daemon. The final argument is the list of ports that this daemon listens on. This information is used to check if the daemon is listening on the expected ports when the user requests diagnostic tests on the app. +Package management +^^^^^^^^^^^^^^^^^^ + +Transmission server is installed through a set of packages fetched from Debian +package repositories. The packages required for this are passed on to a +:class:`~plinth.package.Packages` component which takes care of installing, +upgrading and uninstalling the Debian packages. An app might require one or more +Debian packages to be installed. + +.. code-block:: python3 + :caption: ``__init__.py`` + + from plinth.package import Packages + + managed_packages = ['transmission-daemon'] + + class TransmissionApp(app_module.App): + ... + + def __init__(self): + ... + + packages = Packages('packages-transmission', managed_packages) + self.add(packages) + +The first argument uniquely identifies this instance of the `Packages` +component. Choose an appropriate unique identifier if your app has multiple +`Packages` components. The second argument is a list of Debian packages that +this component is responsible for. + Managing web server configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/plinth/package.py b/plinth/package.py index c24f2ac1a..f2e1a1946 100644 --- a/plinth/package.py +++ b/plinth/package.py @@ -21,16 +21,28 @@ logger = logging.getLogger(__name__) class Packages(app.FollowerComponent): - """Component to manage the packages of an app.""" + """Component to manage the packages of an app. - def __init__(self, component_id, packages): - super(Packages, self).__init__(component_id) + This component is responsible for installation, upgrades and uninstallation + of packages required by an app. + """ + + def __init__(self, component_id: str, packages: list[str]): + """Initialize a new packages component. + + 'component_id' should be a unique ID across all components of an app + and across all components. + + 'packages' is the list of Debian packages managed by this component. + """ + super().__init__(component_id) self.component_id = component_id self._packages = packages @property - def packages(self): + def packages(self) -> list[str]: + """Return the list of packages managed by this component.""" return self._packages