charmlibs-systemd 1.0.0__py3-none-any.whl

charmlibs/systemd/__init__.py

@@ -0,0 +1,65 @@
+# Copyright 2025 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Abstractions for stopping, starting and managing system services via systemd.
+
+For the most part, we transparently provide an interface to a commonly used selection of
+systemd commands, with a few shortcuts baked in. For example, :func:`service_pause` and
+:func:`service_resume` will run the mask/unmask and enable/disable invocations.
+
+Example usage
+-------------
+
+.. code-block:: python
+
+    from charmlibs import systemd
+
+    # Start a service
+    if not systemd.service_running("mysql"):
+        success = systemd.service_start("mysql")
+
+    # Attempt to reload a service, restarting if necessary
+    success = systemd.service_reload("nginx", restart_on_failure=True)
+"""
+
+from ._systemd import (
+    SystemdError,
+    daemon_reload,
+    service_disable,
+    service_enable,
+    service_failed,
+    service_pause,
+    service_reload,
+    service_restart,
+    service_resume,
+    service_running,
+    service_start,
+    service_stop,
+)
+from ._version import __version__ as __version__
+
+__all__ = [
+    'SystemdError',
+    'daemon_reload',
+    'service_disable',
+    'service_enable',
+    'service_failed',
+    'service_pause',
+    'service_reload',
+    'service_restart',
+    'service_resume',
+    'service_running',
+    'service_start',
+    'service_stop',
+]

charmlibs/systemd/_systemd.py

@@ -0,0 +1,241 @@
+# Copyright 2025 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Manage services controlled by systemd."""
+
+import logging
+import subprocess
+
+_logger = logging.getLogger(__name__)
+
+
+class SystemdError(Exception):
+    """Custom exception for systemd related errors."""
+
+
+def _systemctl(*args: str, check: bool = False) -> int:
+    """Call a `systemctl` command with logging enabled.
+
+    Args:
+        args: Arguments to pass to the `systemctl` command.
+        check: If set to `True`, raise an error if the command exits with a non-zero exit code.
+
+    Returns:
+        Returncode of `systemctl` command execution.
+
+    Raises:
+        SystemdError:
+            Raised if the called command fails and check is set to `True`.
+    """
+    cmd = ['systemctl', *args]
+    _logger.debug('running command %s', cmd)
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=check)
+    except subprocess.CalledProcessError as e:
+        raise SystemdError(
+            f'Command {cmd} failed with returncode {e.returncode}. systemctl output:\n'
+            + f'stdout: {e.stdout}\n'
+            + f'stderr: {e.stderr}'
+        ) from None
+
+    _logger.debug(
+        "command '%s' completed with:\nexit code: %s\nstdout: %s\nstderr: %s",
+        ' '.join(cmd),
+        result.returncode,
+        result.stdout,
+        result.stderr,
+    )
+    return result.returncode
+
+
+def service_running(service_name: str) -> bool:
+    """Report whether a system service is running.
+
+    Args:
+        service_name: The name of the service to check.
+
+    Returns:
+        True if service is running/active; False if not.
+    """
+    # If returncode is 0, this means that is service is active.
+    return _systemctl('--quiet', 'is-active', service_name) == 0
+
+
+def service_failed(service_name: str) -> bool:
+    """Report whether a system service has failed.
+
+    Args:
+        service_name: The name of the service to check.
+
+    Returns:
+        True if service is marked as failed; False if not.
+    """
+    # If returncode is 0, this means that the service has failed.
+    return _systemctl('--quiet', 'is-failed', service_name) == 0
+
+
+def service_start(*args: str) -> bool:
+    """Start a system service.
+
+    Args:
+        *args: Arguments to pass to `systemctl start` (normally the service name).
+
+    Returns:
+        On success, this function returns True for historical reasons.
+
+    Raises:
+        SystemdError: Raised if `systemctl start ...` returns a non-zero returncode.
+    """
+    return _systemctl('start', *args, check=True) == 0
+
+
+def service_stop(*args: str) -> bool:
+    """Stop a system service.
+
+    Args:
+        *args: Arguments to pass to `systemctl stop` (normally the service name).
+
+    Returns:
+        On success, this function returns True for historical reasons.
+
+    Raises:
+        SystemdError: Raised if `systemctl stop ...` returns a non-zero returncode.
+    """
+    return _systemctl('stop', *args, check=True) == 0
+
+
+def service_restart(*args: str) -> bool:
+    """Restart a system service.
+
+    Args:
+        *args: Arguments to pass to `systemctl restart` (normally the service name).
+
+    Returns:
+        On success, this function returns True for historical reasons.
+
+    Raises:
+        SystemdError: Raised if `systemctl restart ...` returns a non-zero returncode.
+    """
+    return _systemctl('restart', *args, check=True) == 0
+
+
+def service_enable(*args: str) -> bool:
+    """Enable a system service.
+
+    Args:
+        *args: Arguments to pass to `systemctl enable` (normally the service name).
+
+    Returns:
+        On success, this function returns True for historical reasons.
+
+    Raises:
+        SystemdError: Raised if `systemctl enable ...` returns a non-zero returncode.
+    """
+    return _systemctl('enable', *args, check=True) == 0
+
+
+def service_disable(*args: str) -> bool:
+    """Disable a system service.
+
+    Args:
+        *args: Arguments to pass to `systemctl disable` (normally the service name).
+
+    Returns:
+        On success, this function returns True for historical reasons.
+
+    Raises:
+        SystemdError: Raised if `systemctl disable ...` returns a non-zero returncode.
+    """
+    return _systemctl('disable', *args, check=True) == 0
+
+
+def service_reload(service_name: str, restart_on_failure: bool = False) -> bool:
+    """Reload a system service, optionally falling back to restart if reload fails.
+
+    Args:
+        service_name: The name of the service to reload.
+        restart_on_failure:
+            Boolean indicating whether to fall back to a restart if the reload fails.
+
+    Returns:
+        On success, this function returns True for historical reasons.
+
+    Raises:
+        SystemdError: Raised if `systemctl reload|restart ...` returns a non-zero returncode.
+    """
+    try:
+        return _systemctl('reload', service_name, check=True) == 0
+    except SystemdError:
+        if restart_on_failure:
+            return service_restart(service_name)
+        else:
+            raise
+
+
+def service_pause(service_name: str) -> bool:
+    """Pause a system service.
+
+    Stops the service and prevents the service from starting again at boot.
+
+    Args:
+        service_name: The name of the service to pause.
+
+    Returns:
+        On success, this function returns True for historical reasons.
+
+    Raises:
+        SystemdError: Raised if service is still running after being paused by systemctl.
+    """
+    _systemctl('disable', '--now', service_name)
+    _systemctl('mask', service_name)
+
+    if service_running(service_name):
+        raise SystemdError(f'Attempted to pause {service_name!r}, but it is still running.')
+
+    return True
+
+
+def service_resume(service_name: str) -> bool:
+    """Resume a system service.
+
+    Re-enable starting the service again at boot. Start the service.
+
+    Args:
+        service_name: The name of the service to resume.
+
+    Returns:
+        On success, this function returns True for historical reasons.
+
+    Raises:
+        SystemdError: Raised if service is not running after being resumed by systemctl.
+    """
+    _systemctl('unmask', service_name)
+    _systemctl('enable', '--now', service_name)
+
+    if not service_running(service_name):
+        raise SystemdError(f'Attempted to resume {service_name!r}, but it is not running.')
+
+    return True
+
+
+def daemon_reload() -> bool:
+    """Reload systemd manager configuration.
+
+    Returns:
+        On success, this function returns True for historical reasons.
+
+    Raises:
+        SystemdError: Raised if `systemctl daemon-reload` returns a non-zero returncode.
+    """
+    return _systemctl('daemon-reload', check=True) == 0

charmlibs/systemd/_version.py

@@ -0,0 +1,15 @@
+# Copyright 2025 Canonical Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+__version__ = '1.0.0'

charmlibs_systemd-1.0.0.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: charmlibs-systemd
+Version: 1.0.0
+Summary: The charmlibs.systemd package.
+Project-URL: Repository, https://github.com/canonical/charmlibs
+Project-URL: Issues, https://github.com/canonical/charmlibs/issues
+Project-URL: Documentation, https://documentation.ubuntu.com/charmlibs/reference/charmlibs/systemd/
+Project-URL: Changelog, https://github.com/canonical/charmlibs/blob/main/systemd/CHANGELOG.md
+Author: The Charm Tech team at Canonical
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# charmlibs.systemd
+
+The `systemd` library.
+
+To install, add `charmlibs-systemd` to your Python dependencies. Then in your Python code, import as:
+
+```py
+from charmlibs import systemd
+```
+
+See the [reference documentation](https://documentation.ubuntu.com/charmlibs/reference/charmlibs/systemd) for more.

charmlibs_systemd-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+charmlibs/systemd/__init__.py,sha256=LXElGX2wHg-fPeQDCWmgkZEFm7hZcLmpI5ntb1kI_UU,1841
+charmlibs/systemd/_systemd.py,sha256=2a56LTyaghQ8a8wxAu3Ec0OK-K0HLQkeKjjhhqFWMTw,7132
+charmlibs/systemd/_version.py,sha256=SOabh2HM3GM1fjRvHHGC-IV789Y2DPLYqgl_cRoScto,597
+charmlibs/systemd/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+charmlibs_systemd-1.0.0.dist-info/METADATA,sha256=I7OBxBRyChJJgmuPZrmYq1qHoNUTGsUjMUeJtnk5RJ0,1095
+charmlibs_systemd-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+charmlibs_systemd-1.0.0.dist-info/RECORD,,

charmlibs_systemd-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any