From 53fbaf27f22457aa5f4528350f849553a726814e Mon Sep 17 00:00:00 2001 From: Joseph Nuthalapati Date: Fri, 5 Nov 2021 16:05:11 +0530 Subject: [PATCH] components: Add docstrings & tutorial for Packages Signed-off-by: Joseph Nuthalapati [sunil: Include the new component reference in the components index] [sunil: Minor changes to component doc string] Signed-off-by: Sunil Mohan Adapa Reviewed-by: Sunil Mohan Adapa --- doc/dev/reference/components/index.rst | 1 + doc/dev/reference/components/packages.rst | 7 ++++++ doc/dev/tutorial/components.rst | 30 +++++++++++++++++++++++ plinth/package.py | 20 ++++++++++++--- 4 files changed, 54 insertions(+), 4 deletions(-) create mode 100644 doc/dev/reference/components/packages.rst 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