python3-cyberfusion-nextcloud-support 1.1.1.2.2__py3-none-any.whl

cyberfusion/NextCloudSupport/__init__.py

@@ -0,0 +1 @@
+"""Empty file to turn this into a package."""

cyberfusion/NextCloudSupport/_occ.py

@@ -0,0 +1,37 @@
+"""Functions to run `occ` commands."""
+
+import subprocess
+from typing import List
+
+from cyberfusion.Common import find_executable
+from cyberfusion.NextCloudSupport.exceptions import CommandFailedError
+
+PHP_BIN = find_executable("php")
+
+
+def run_command(command: List[str], cwd: str) -> str:
+    """Run command and get output."""
+    command = [
+        PHP_BIN,
+        "-d",
+        "memory_limit=512M",
+        "occ",
+        "--no-interaction",
+    ] + command
+
+    try:
+        return subprocess.run(
+            command,
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            cwd=cwd,
+        ).stdout.rstrip()
+    except subprocess.CalledProcessError as e:
+        raise CommandFailedError(
+            return_code=e.returncode,
+            stdout=e.stdout,
+            stderr=e.stderr,
+            command=command,
+        )

cyberfusion/NextCloudSupport/app.py

@@ -0,0 +1,143 @@
+"""App."""
+
+import os
+import re
+import tarfile
+from typing import TYPE_CHECKING, Optional, Tuple
+
+from cyberfusion.Common import download_from_url
+from cyberfusion.NextCloudSupport._occ import run_command
+from cyberfusion.NextCloudSupport.exceptions import AppNotInstalledError
+
+if TYPE_CHECKING:  # pragma: no cover
+    from cyberfusion.NextCloudSupport.instance import Instance
+
+
+class App:
+    """Represents app."""
+
+    def __init__(
+        self,
+        instance: "Instance",
+        name: str,
+    ) -> None:
+        """Set attributes."""
+        self.instance = instance
+        self.name = name
+
+    @staticmethod
+    def install(
+        instance: "Instance",
+        name: Optional[str] = None,
+        url: Optional[str] = None,
+    ) -> None:
+        """Install app by name or URL.
+
+        For custom versions: NextCloud does not natively support installing
+        specific versions of apps (default is latest). To work around this,
+        install the app by URL, pointing to the archive containing the
+        needed version.
+
+        Note that installing apps from a specific URL is not officially
+        supported, and the way we do it is undocumented, and therefore
+        a hack.
+        """
+        if name and url:
+            raise ValueError("Specify either name or URL")
+
+        if name:
+            run_command(["app:install", name], instance.path)
+
+            return
+
+        with tarfile.open(download_from_url(url)) as f:
+            name = os.path.commonpath(f.getnames())
+
+            f.extractall(path=os.path.join(instance.path, "apps"))
+
+        run_command(
+            ["app:enable", name],
+            instance.path,
+        )
+
+    @property
+    def is_enabled(self) -> bool:
+        """Get if app is enabled."""
+        return self.name in self.instance.raw_app_list["enabled"]
+
+    def enable(self) -> None:
+        """Enable app."""
+        run_command(
+            ["app:enable", self.name],
+            self.instance.path,
+        )
+
+        self.instance.refresh_raw_app_list()
+
+    def disable(self) -> None:
+        """Disable app."""
+        run_command(
+            ["app:disable", self.name],
+            self.instance.path,
+        )
+
+        self.instance.refresh_raw_app_list()
+
+    @property
+    def version(self) -> str:
+        """Get version."""
+        for app_name, version in (
+            self.instance.raw_app_list["enabled"]
+            | self.instance.raw_app_list["disabled"]
+        ).items():
+            if app_name != self.name:
+                continue
+
+            # Sometimes, NextCloud suffixes the version by another version number.
+            # It's unclear why or when, but we don't want it.
+            # Code: https://github.com/nextcloud/server/blob/72b6db40435ce0407d0aafa626945d4f2380460f/core/Command/App/ListApps.php#L91
+
+            return version.split(" ")[0]
+
+        raise AppNotInstalledError
+
+    def remove(self) -> None:
+        """Remove app."""
+        run_command(
+            ["app:remove", self.name],
+            self.instance.path,
+        )
+
+        self.instance.refresh_raw_app_list()
+
+    def update(self) -> Tuple[str, str]:
+        """Update app."""
+        old_version = self.version
+
+        run_command(
+            ["app:update", self.name],
+            self.instance.path,
+        )
+
+        self.instance.refresh_raw_app_list()
+        self.instance.refresh_raw_app_update_list()
+
+        new_version = self.version
+
+        return old_version, new_version
+
+    @property
+    def available_version(self) -> Optional[str]:
+        """Get version that app can be updated to."""
+        for line in self.instance.raw_app_update_list:
+            match = re.fullmatch("^(.*) new version available: (.*)$", line)
+
+            if not match:
+                continue
+
+            if match.group(1) != self.name:
+                continue
+
+            return match.group(2)
+
+        return None

cyberfusion/NextCloudSupport/exceptions.py

@@ -0,0 +1,31 @@
+"""Exceptions."""
+
+from dataclasses import dataclass
+from typing import List
+
+
+class DirectoryNotEmptyError(Exception):
+    """Directory is not empty."""
+
+    pass
+
+
+class AppNotInstalledError(Exception):
+    """App should be installed, but is not."""
+
+    pass
+
+
+@dataclass
+class CommandFailedError(Exception):
+    """Command failed."""
+
+    command: List[str]
+    return_code: int
+    stdout: str
+    stderr: str
+
+    @property
+    def streams(self) -> str:
+        """Combine output streams."""
+        return f"Stdout:\n\n{self.stdout}\n\nStderr:\n\n{self.stderr}"

cyberfusion/NextCloudSupport/instance.py

@@ -0,0 +1,392 @@
+"""Instance."""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import zipfile
+from enum import StrEnum
+from functools import cached_property
+from typing import List, Optional, Tuple, Union
+
+from cyberfusion.Common import download_from_url
+from cyberfusion.NextCloudSupport._occ import PHP_BIN, run_command
+from cyberfusion.NextCloudSupport.app import App
+from cyberfusion.NextCloudSupport.exceptions import (
+    AppNotInstalledError,
+    CommandFailedError,
+    DirectoryNotEmptyError,
+)
+from cyberfusion.NextCloudSupport.user import User
+
+URL_ZIP_NEXTCLOUD = "https://download.nextcloud.com/server/releases/latest.zip"
+
+
+class SSLMode(StrEnum):
+    """SSL modes."""
+
+    NONE = "none"
+    SSL = "ssl"
+    TLS = "tls"
+
+
+class MailAccountAuthMethod(StrEnum):
+    """Auth methods for mail accounts."""
+
+    PASSWORD = "password"
+    XOAUTH2 = "xoauth2"
+
+
+class DatabaseType(StrEnum):
+    """Database types."""
+
+    SQLITE = "sqlite"
+    MYSQL = "mysql"
+    PGSQL = "pgsql"
+    OCI = "oci"
+
+
+class Instance:
+    """Represents NextCloud instance."""
+
+    def __init__(self, path: str) -> None:
+        """Set attributes."""
+        self.path = path
+
+    @staticmethod
+    def download(destination_path: str, zip_path: Optional[str] = None) -> None:
+        """Download NextCloud to path.
+
+        If zip_path is not set, NextCloud is downloaded from their website.
+        """
+        if os.listdir(destination_path):
+            raise DirectoryNotEmptyError
+
+        # Downlaod ZIP from NextCloud if not specified
+
+        if zip_path is None:
+            zip_path = download_from_url(
+                URL_ZIP_NEXTCLOUD,
+                root_directory=destination_path,
+            )
+
+        # Extract ZIP
+
+        with zipfile.ZipFile(zip_path, "r") as z:
+            z.extractall(destination_path)
+
+        # Move files from nextcloud/ to destination directory
+
+        temp_directory = os.path.join(
+            destination_path,
+            "nextcloud",
+        )
+
+        for file_ in os.listdir(temp_directory):
+            shutil.move(os.path.join(temp_directory, file_), destination_path)
+
+        os.rmdir(temp_directory)
+
+    @staticmethod
+    def install(
+        path: str,
+        *,
+        database_host: str,
+        database_name: str,
+        database_username: str,
+        database_password: str,
+        admin_user: str,
+        admin_password: str,
+        database_type: DatabaseType = DatabaseType.MYSQL,
+    ) -> None:
+        """Install downloaded NextCloud instance.
+
+        NextCloud must be downloaded before calling this method.
+        """
+        run_command(
+            [
+                "maintenance:install",
+                "--database",
+                database_type,
+                "--database-host",
+                database_host,
+                "--database-name",
+                database_name,
+                "--database-user",
+                database_username,
+                "--database-pass",
+                database_password,
+                "--admin-user",
+                admin_user,
+                "--admin-pass",
+                admin_password,
+                "--data-dir",
+                os.path.join(path, "data"),
+            ],
+            path,
+        )
+
+    def get_app(self, name: str) -> App:
+        """Get installed app by name."""
+        for app in self.installed_apps:
+            if name != app.name:
+                continue
+
+            return app
+
+        raise AppNotInstalledError
+
+    def get_system_config(
+        self, name: str
+    ) -> Union[
+        str,
+        int,
+        float,
+        bool,
+    ]:
+        """Get system config value by name."""
+        output = run_command(
+            [
+                "config:system:get",
+                name,
+            ],
+            self.path,
+        )
+
+        if output.isdigit():
+            return int(output)
+
+        if output == "true":
+            return True
+
+        if output == "false":
+            return False
+
+        try:
+            return float(output)
+        except ValueError:
+            pass
+
+        return output
+
+    def set_system_config(
+        self,
+        name: str,
+        value: Union[str, int, float, bool],
+        index: Optional[int] = None,
+    ) -> None:
+        """Set system config value.
+
+        Index must be set when manipulating arrays, as it corresponds to the
+        array item.
+        """
+
+        # Set type
+
+        type_ = "string"
+
+        if isinstance(value, int):
+            type_ = "integer"
+
+        if isinstance(value, float):
+            type_ = "float"
+
+        if isinstance(value, bool):
+            type_ = "boolean"
+
+        # Set value
+
+        _value = str(value)
+
+        if isinstance(value, bool):
+            _value = _value.lower()
+
+        # Set command
+
+        command = [
+            "config:system:set",
+            name,
+        ]
+
+        if index is not None:
+            command.append(str(index))
+
+        command.extend(["--value", _value, "--type", type_])
+
+        # Run command
+
+        run_command(command, self.path)
+
+    def update(self) -> Tuple[str, str]:
+        """Update NextCloud."""
+        old_version = self.version
+
+        command = [PHP_BIN, "updater/updater.phar", "--no-interaction"]
+
+        try:
+            subprocess.run(
+                command,
+                check=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                cwd=self.path,
+            )
+        except subprocess.CalledProcessError as e:
+            raise CommandFailedError(
+                return_code=e.returncode,
+                stdout=e.stdout,
+                stderr=e.stderr,
+                command=command,
+            )
+
+        new_version = self.version
+
+        return old_version, new_version
+
+    @property
+    def available_version(self) -> Optional[str]:
+        """Get version that instance can be updated to."""
+        lines = run_command(
+            [
+                "update:check",
+            ],
+            self.path,
+        ).splitlines()
+
+        for line in lines:
+            match = re.fullmatch(
+                "^Nextcloud (.*) is available. Get more information on how to update at (.*).$",
+                line,
+            )
+
+            if not match:
+                continue
+
+            return match.group(1)
+
+        return None
+
+    @property
+    def version(self) -> str:
+        """Get version."""
+        return self.get_system_config("version")  # type: ignore[return-value]
+
+    def create_mail_account(
+        self,
+        *,
+        user_id: str,
+        name: str,
+        email_address: str,
+        imap_hostname: str,
+        imap_port: int,
+        imap_ssl_mode: SSLMode,
+        imap_username: str,
+        imap_password: str,
+        smtp_host: str,
+        smtp_port: int,
+        smtp_ssl_mode: SSLMode,
+        smtp_username: str,
+        smtp_password: str,
+        auth_method: MailAccountAuthMethod,
+    ) -> None:
+        """Create mail account."""
+        run_command(
+            [
+                "mail:account:create",
+                user_id,
+                name,
+                email_address,
+                imap_hostname,
+                str(imap_port),
+                imap_ssl_mode,
+                imap_username,
+                imap_password,
+                smtp_host,
+                str(smtp_port),
+                smtp_ssl_mode,
+                smtp_username,
+                smtp_password,
+                auth_method,
+            ],
+            self.path,
+        )
+
+    @property
+    def users(self) -> List[User]:
+        """Get users."""
+        result = []
+
+        output = json.loads(
+            run_command(
+                [
+                    "user:list",
+                    "--output",
+                    "json",
+                ],
+                self.path,
+            )
+        )
+
+        for id_, name in output.items():
+            user = User(self, id_, name)
+
+            result.append(user)
+
+        return result
+
+    def refresh_raw_app_list(self) -> None:
+        """Clear the raw app list cache."""
+        try:
+            del self.raw_app_list
+        except AttributeError:
+            pass
+
+    def refresh_raw_app_update_list(self) -> None:
+        """Clear the raw app list cache."""
+        try:
+            del self.raw_app_update_list
+        except AttributeError:
+            pass
+
+    @cached_property
+    def raw_app_update_list(self) -> List[str]:
+        """Get raw app list output."""
+        return run_command(
+            [
+                "app:update",
+                "--showonly",
+            ],
+            self.path,
+        ).splitlines()
+
+    @cached_property
+    def raw_app_list(self) -> dict:
+        """Get raw app list output."""
+        return json.loads(
+            run_command(
+                [
+                    "app:list",
+                    "--output",
+                    "json",
+                ],
+                self.path,
+            )
+        )
+
+    @property
+    def installed_apps(self) -> List[App]:
+        """Get installed apps."""
+        result = []
+
+        for name, _ in (
+            self.raw_app_list["enabled"] | self.raw_app_list["disabled"]
+        ).items():
+            app = App(
+                self,
+                name,
+            )
+
+            result.append(app)
+
+        return result

cyberfusion/NextCloudSupport/user.py

@@ -0,0 +1,16 @@
+"""User."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from cyberfusion.NextCloudSupport.instance import Instance
+
+
+class User:
+    """Represents user."""
+
+    def __init__(self, instance: "Instance", id_: str, name: str) -> None:
+        """Set attributes."""
+        self.instance = instance
+        self.id = id_
+        self.name = name

python3_cyberfusion_nextcloud_support-1.1.1.2.2.dist-info/METADATA

@@ -0,0 +1,39 @@
+Metadata-Version: 2.1
+Name: python3-cyberfusion-nextcloud-support
+Version: 1.1.1.2.2
+Summary: Library for NextCloud.
+Author-email: Cyberfusion <support@cyberfusion.io>
+Project-URL: Source, https://github.com/CyberfusionIO/python3-cyberfusion-nextcloud-support
+Description-Content-Type: text/markdown
+Requires-Dist: python3-cyberfusion-common ~=2.10
+
+# python3-cyberfusion-nextcloud-support
+
+Library for NextCloud.
+
+# Install
+
+## PyPI
+
+Run the following command to install the package from PyPI:
+
+    pip3 install python3-cyberfusion-nextcloud-support
+
+Next, install the following software:
+
+* PHP (see https://docs.nextcloud.com/server/latest/admin_manual/installation/php_configuration.html)
+
+## Debian
+
+Run the following commands to build a Debian package:
+
+    mk-build-deps -i -t 'apt -o Debug::pkgProblemResolver=yes --no-install-recommends -y'
+    dpkg-buildpackage -us -uc
+
+# Configure
+
+No configuration is supported.
+
+# Usage
+
+See code.

python3_cyberfusion_nextcloud_support-1.1.1.2.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+cyberfusion/NextCloudSupport/__init__.py,sha256=8JByOElHmHLFiNx9xTHIU6dy5AjPQQmpPLFq5IR4bpM,46
+cyberfusion/NextCloudSupport/_occ.py,sha256=46gDht7KKwNlDJ46YUrDdm4PQxYV0JtlzLyOTYx_ZGE,908
+cyberfusion/NextCloudSupport/app.py,sha256=IIH7N9F8i-vFnajXxw3BJO_5i9U5VxQ7rOqtcWqo-Q0,3901
+cyberfusion/NextCloudSupport/exceptions.py,sha256=--rrdtxwwCUmuukRV7sNIIughMxRHv9dD3s_p2lTtNY,569
+cyberfusion/NextCloudSupport/instance.py,sha256=oCuoyvKEJ7pbOV5oQE1ad5aK1kOSKCptwaydVW67L-s,9351
+cyberfusion/NextCloudSupport/user.py,sha256=CSSBzONswPu6IfCtl3vQ3dsLxpeF97bLvBcyeqTuCPw,375
+python3_cyberfusion_nextcloud_support-1.1.1.2.2.dist-info/METADATA,sha256=cX4nwx6ifGTtemnx3FLlK4R5BkuL3jOzgezB_SzJhT0,945
+python3_cyberfusion_nextcloud_support-1.1.1.2.2.dist-info/WHEEL,sha256=Mdi9PDNwEZptOjTlUcAth7XJDFtKrHYaQMPulZeBCiQ,91
+python3_cyberfusion_nextcloud_support-1.1.1.2.2.dist-info/top_level.txt,sha256=ss011q9S6SL_KIIyq7iujFmIYa0grSjlnInO7cDkeag,12
+python3_cyberfusion_nextcloud_support-1.1.1.2.2.dist-info/RECORD,,

python3_cyberfusion_nextcloud_support-1.1.1.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (73.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python3_cyberfusion_nextcloud_support-1.1.1.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+cyberfusion