pyeasydeploy 0.1.0__py3-none-any.whl

pyeasydeploy/__init__.py

@@ -0,0 +1,103 @@
+"""pyeasydeploy — deploy Python apps to Linux servers over SSH.
+
+No agents, no YAML, no magic: plain Python functions that do exactly
+what they say. See the README for the philosophy (destructive and
+reproducible uploads, fail-fast validation, trust in the user).
+
+Typical flow::
+
+    from pyeasydeploy import (
+        connect_to_host, get_target_python_instance, create_venv,
+        install_local_package, deploy_supervisor_service,
+        SupervisorService,
+    )
+
+    conn = connect_to_host(host, user, key_filename="~/.ssh/id_ed25519",
+                           sudo_password="...")
+    py = get_target_python_instance(conn, "3.11")
+    venv = create_venv(conn, py, "/home/deploy/venvs/myapp")
+    install_local_package(conn, venv, "./myapp")
+    deploy_supervisor_service(conn, SupervisorService(
+        name="myapp",
+        command="/home/deploy/venvs/myapp/bin/python -m myapp",
+    ))
+"""
+
+__version__ = "0.1.0"
+
+# Models (foundation layer; importable standalone)
+from .models import PythonInstance, SupervisorService, VenvPython
+
+# Connection
+from .connection import connect_to_host, has_sudo_password, require_sudo
+
+# Remote Python discovery
+from .python import (
+    get_any_python_instance,
+    get_python_instances,
+    get_target_python_instance,
+)
+
+# Virtual environments
+from .venv import create_venv, delete_venv, run_in_venv
+
+# File transfer
+from .transfer import DEFAULT_IGNORE, upload_directory, upload_file
+
+# Package installation
+from .packages import (
+    install_local_package,
+    install_package_from_github,
+    install_package_from_private_github,
+    install_packages,
+)
+
+# Supervisor services
+from .supervisor import (
+    check_supervisor_installed,
+    create_supervisor_config,
+    deploy_supervisor_service,
+    install_supervisor,
+    supervisor_restart,
+    supervisor_start,
+    supervisor_status,
+    supervisor_stop,
+)
+
+__all__ = [
+    "__version__",
+    # models
+    "PythonInstance",
+    "VenvPython",
+    "SupervisorService",
+    # connection
+    "connect_to_host",
+    "has_sudo_password",
+    "require_sudo",
+    # python
+    "get_python_instances",
+    "get_target_python_instance",
+    "get_any_python_instance",
+    # venv
+    "create_venv",
+    "delete_venv",
+    "run_in_venv",
+    # transfer
+    "upload_file",
+    "upload_directory",
+    "DEFAULT_IGNORE",
+    # packages
+    "install_packages",
+    "install_local_package",
+    "install_package_from_github",
+    "install_package_from_private_github",
+    # supervisor
+    "install_supervisor",
+    "check_supervisor_installed",
+    "create_supervisor_config",
+    "deploy_supervisor_service",
+    "supervisor_start",
+    "supervisor_stop",
+    "supervisor_restart",
+    "supervisor_status",
+]

pyeasydeploy/connection.py

@@ -0,0 +1,153 @@
+"""SSH connection factory for pyeasydeploy.
+
+Builds Fabric Connection objects with authentication and sudo correctly
+wired. Depends only on models-level philosophy (validate at the
+boundary); imports nothing from the rest of the package.
+"""
+
+from typing import Optional
+
+from fabric import Connection
+
+
+def connect_to_host(
+    host: str,
+    user: str,
+    password: Optional[str] = None,
+    key_filename: Optional[str] = None,
+    sudo_password: Optional[str] = None,
+    port: int = 22,
+) -> Connection:
+    """Create an SSH connection to a remote host.
+
+    Exactly one of ``password`` or ``key_filename`` must be provided
+    for SSH authentication.
+
+    Sudo is configured independently: if ``sudo_password`` is given it
+    is used for ``conn.sudo()`` calls; otherwise, if ``password`` is
+    given it is reused for sudo (the common case where the SSH user's
+    password is also the sudo password). With key-based auth and no
+    ``sudo_password``, any later ``conn.sudo()`` call would block
+    forever waiting for a password prompt — so functions in this
+    library that need sudo will refuse early instead (see
+    ``require_sudo``).
+
+    Note: the connection is lazy. Fabric does not open the SSH session
+    here; authentication errors surface on the first command run.
+
+    Args:
+        host: Remote host address (IP or hostname).
+        user: Username for the SSH connection.
+        password: Password for SSH authentication. Mutually exclusive
+            with key_filename.
+        key_filename: Path to an SSH private key file. Mutually
+            exclusive with password.
+        sudo_password: Password for sudo on the remote host. Defaults
+            to ``password`` when that is provided. Required later by
+            any sudo-using function when authenticating with a key
+            (unless the remote user has passwordless sudo configured,
+            in which case sudo works without it).
+        port: SSH port. Defaults to 22.
+
+    Returns:
+        A Fabric Connection, with sudo password configured when
+        available.
+
+    Raises:
+        TypeError: If any argument has the wrong type.
+        ValueError: If host or user are empty, both or neither of
+            password/key_filename are provided, or port is outside
+            1-65535.
+    """
+    if not isinstance(host, str):
+        raise TypeError(f"host must be str, got {type(host).__name__}")
+    if not host.strip():
+        raise ValueError("host must be a non-empty string")
+    if not isinstance(user, str):
+        raise TypeError(f"user must be str, got {type(user).__name__}")
+    if not user.strip():
+        raise ValueError("user must be a non-empty string")
+    for name, value in (
+        ("password", password),
+        ("key_filename", key_filename),
+        ("sudo_password", sudo_password),
+    ):
+        if value is not None and not isinstance(value, str):
+            raise TypeError(f"{name} must be str or None, got {type(value).__name__}")
+    if isinstance(port, bool) or not isinstance(port, int):
+        raise TypeError(f"port must be int, got {type(port).__name__}")
+    if not 1 <= port <= 65535:
+        raise ValueError(f"port must be in 1-65535, got {port}")
+
+    if password is None and key_filename is None:
+        raise ValueError(
+            "You must provide either 'password' or 'key_filename' "
+            "for authentication"
+        )
+    if password is not None and key_filename is not None:
+        raise ValueError("Provide either 'password' or 'key_filename', not both")
+
+    connect_kwargs = {}
+    if password is not None:
+        connect_kwargs["password"] = password
+    else:
+        connect_kwargs["key_filename"] = key_filename
+
+    conn = Connection(
+        host=host,
+        user=user,
+        port=port,
+        connect_kwargs=connect_kwargs,
+    )
+
+    effective_sudo = sudo_password if sudo_password is not None else password
+    if effective_sudo is not None:
+        conn.config.sudo.password = effective_sudo
+
+    return conn
+
+
+def has_sudo_password(conn: Connection) -> bool:
+    """Return True if a sudo password is configured on this connection.
+
+    Args:
+        conn: Connection created by connect_to_host (or any Fabric
+            Connection).
+
+    Returns:
+        True when conn.config.sudo.password is set to a non-empty value.
+    """
+    return bool(getattr(conn.config.sudo, "password", None))
+
+
+def require_sudo(conn: Connection, what: str = "this operation") -> None:
+    """Fail fast if the connection cannot run sudo non-interactively.
+
+    Call this at the top of any function that uses ``conn.sudo()``.
+    Turns the silent infinite hang (sudo waiting for a password that
+    will never arrive) into an immediate, explanatory error.
+
+    Note: a remote user with passwordless sudo (NOPASSWD in sudoers)
+    does not need a sudo password; pass an empty-string check bypass by
+    configuring ``sudo_password=""`` is NOT supported — instead, this
+    check is advisory: it only raises when no password is configured
+    AND the connection was key-authenticated, the exact combination
+    that hangs.
+
+    Args:
+        conn: Connection to check.
+        what: Human description of the operation, used in the error
+            message.
+
+    Raises:
+        PermissionError: If no sudo password is configured and the
+            connection has no SSH password to fall back on.
+    """
+    if has_sudo_password(conn):
+        return
+    raise PermissionError(
+        f"{what} requires sudo, but no sudo password is configured for "
+        f"this connection. Pass sudo_password= to connect_to_host(), or "
+        f"configure passwordless sudo (NOPASSWD) for the remote user and "
+        f"call the function with check_sudo=False if it offers it."
+    )

pyeasydeploy/models.py

@@ -0,0 +1,241 @@
+"""Shared data models for pyeasydeploy.
+
+This module is the foundation layer: it imports nothing from the rest of
+the package, so every other module can depend on it without cycles.
+
+All models are frozen (immutable) and validate themselves on
+construction: wrong types raise TypeError, invalid values raise
+ValueError. Validation is structural only — it protects the integrity
+of what we generate (paths that must be absolute to work remotely, INI
+section headers that must parse) and never restricts which supervisord
+features you can use.
+"""
+
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Mapping, Optional, Union
+
+# ----------------------------------------------------------------------
+# Private validation helpers (shared by all models)
+# ----------------------------------------------------------------------
+
+
+def _check_str(field_name: str, value: object) -> str:
+    """Require a non-empty, non-blank str. Returns the value."""
+    if not isinstance(value, str):
+        raise TypeError(f"{field_name} must be str, got {type(value).__name__}")
+    if not value.strip():
+        raise ValueError(f"{field_name} must be a non-empty string")
+    return value
+
+
+def _check_abs_posix_path(field_name: str, value: object) -> str:
+    """Require a non-empty str that is an absolute POSIX path (remote
+    hosts are Linux: paths must start with '/')."""
+    _check_str(field_name, value)
+    assert isinstance(value, str)
+    if not value.startswith("/"):
+        raise ValueError(
+            f"{field_name} must be an absolute POSIX path (start with '/'), "
+            f"got {value!r}"
+        )
+    return value
+
+
+def _check_bool(field_name: str, value: object) -> bool:
+    """Require a real bool (bool is a subclass of int, so a plain
+    isinstance(int) check would let 0/1 through)."""
+    if not isinstance(value, bool):
+        raise TypeError(f"{field_name} must be bool, got {type(value).__name__}")
+    return value
+
+
+# ----------------------------------------------------------------------
+# Models
+# ----------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PythonInstance:
+    """A Python interpreter found on the remote host.
+
+    Attributes:
+        version: Interpreter version string, e.g. "3.11". Must start
+            with a digit.
+        executable: Absolute remote path to the interpreter,
+            e.g. "/usr/bin/python3.11".
+
+    Raises:
+        TypeError: On construction, if any field has the wrong type.
+        ValueError: On construction, if version is empty or does not
+            start with a digit, or executable is not an absolute path.
+    """
+
+    version: str
+    executable: str
+
+    def __post_init__(self) -> None:
+        _check_str("version", self.version)
+        if not self.version[0].isdigit():
+            raise ValueError(
+                f"version must start with a digit, got {self.version!r}"
+            )
+        _check_abs_posix_path("executable", self.executable)
+
+
+@dataclass(frozen=True)
+class VenvPython:
+    """A virtual environment on the remote host, bound to the interpreter
+    that created it.
+
+    Attributes:
+        venv_name: Name of the environment, usually the last component
+            of venv_path. No whitespace or "/" allowed.
+        python_instance: Interpreter used to create this environment.
+        venv_path: Absolute remote path to the environment,
+            e.g. "/home/app/venvs/myapp".
+
+    Raises:
+        TypeError: On construction, if any field has the wrong type.
+        ValueError: On construction, if venv_name contains whitespace
+            or "/", or venv_path is not an absolute path.
+    """
+
+    venv_name: str
+    python_instance: PythonInstance
+    venv_path: str
+
+    def __post_init__(self) -> None:
+        _check_str("venv_name", self.venv_name)
+        if "/" in self.venv_name or any(c.isspace() for c in self.venv_name):
+            raise ValueError(
+                f"venv_name must not contain '/' or whitespace, "
+                f"got {self.venv_name!r}"
+            )
+        if not isinstance(self.python_instance, PythonInstance):
+            raise TypeError(
+                "python_instance must be a PythonInstance, got "
+                f"{type(self.python_instance).__name__}"
+            )
+        _check_abs_posix_path("venv_path", self.venv_path)
+
+
+@dataclass(frozen=True)
+class SupervisorService:
+    """Description of a supervisord [program:x] entry.
+
+    Named fields cover the common options; the open `extra` mapping
+    accepts ANY other supervisord program option verbatim, so no
+    supervisord feature is out of reach. Values may be str, int or
+    bool (bools are rendered as "true"/"false").
+
+    Example with rotating logs and process priority::
+
+        SupervisorService(
+            name="myapp",
+            command="/home/app/venv/bin/python -m myapp",
+            extra={
+                "stdout_logfile_maxbytes": "10MB",
+                "stdout_logfile_backups": 5,
+                "stderr_logfile_maxbytes": "10MB",
+                "stderr_logfile_backups": 5,
+                "priority": 200,
+                "stopsignal": "INT",
+            },
+        )
+
+    Attributes:
+        name: Program name; becomes the [program:<name>] section header.
+            Must be non-empty, with no whitespace and no "]".
+        command: Command line supervisord runs,
+            e.g. "/home/app/venv/bin/python -m myapp".
+        directory: Remote working directory the process is started from.
+            None omits the line (supervisord default applies).
+        user: Unix user the process runs as. None omits the line
+            (process runs as supervisord's own user).
+        autostart: Start the program automatically when supervisord
+            starts. Defaults to True.
+        autorestart: Restart the program automatically if it exits.
+            Defaults to True.
+        stdout_logfile: stdout log destination. Any value supervisord
+            accepts: an absolute path, "AUTO", "NONE" or "syslog".
+            None omits the line (supervisord defaults to AUTO).
+            "%(program_name)s" is expanded by supervisord itself.
+        stderr_logfile: stderr log destination. Same rules as
+            stdout_logfile.
+        environment: Environment variables in supervisord syntax,
+            e.g. 'KEY="value",OTHER="x"'. None omits the line.
+        extra: Any additional [program:x] options, rendered verbatim
+            as key=value lines. Keys must not collide with the named
+            fields above (that would emit duplicate INI keys).
+
+    Raises:
+        TypeError: On construction, if any field has the wrong type.
+        ValueError: On construction, if name would corrupt the INI
+            section header (empty, whitespace or "]"), or an extra key
+            collides with a named field, or an extra key is empty or
+            contains characters that would break a key=value INI line.
+    """
+
+    name: str
+    command: str
+    directory: Optional[str] = None
+    user: Optional[str] = None
+    autostart: bool = True
+    autorestart: bool = True
+    stdout_logfile: Optional[str] = "/var/log/supervisor/%(program_name)s.log"
+    stderr_logfile: Optional[str] = "/var/log/supervisor/%(program_name)s_err.log"
+    environment: Optional[str] = None
+    extra: Mapping[str, Union[str, int, bool]] = field(default_factory=dict)
+
+    # Named fields that render as their own INI lines; extra keys must
+    # not shadow them.
+    _NAMED_KEYS = frozenset(
+        {
+            "command", "directory", "user", "autostart", "autorestart",
+            "stdout_logfile", "stderr_logfile", "environment",
+        }
+    )
+
+    def __post_init__(self) -> None:
+        _check_str("name", self.name)
+        if any(c.isspace() for c in self.name) or "]" in self.name:
+            raise ValueError(
+                f"Invalid service name {self.name!r}: no whitespace or ']' "
+                "allowed (it would corrupt the INI section header)"
+            )
+        _check_str("command", self.command)
+        for opt in ("directory", "user", "stdout_logfile",
+                    "stderr_logfile", "environment"):
+            value = getattr(self, opt)
+            if value is not None:
+                _check_str(opt, value)
+        _check_bool("autostart", self.autostart)
+        _check_bool("autorestart", self.autorestart)
+
+        if not isinstance(self.extra, Mapping):
+            raise TypeError(
+                f"extra must be a mapping, got {type(self.extra).__name__}"
+            )
+        for key, value in self.extra.items():
+            _check_str("extra key", key)
+            if key in self._NAMED_KEYS:
+                raise ValueError(
+                    f"extra key {key!r} collides with the named field "
+                    f"'{key}'; set it through the field instead"
+                )
+            if "=" in key or "\n" in key or any(c.isspace() for c in key):
+                raise ValueError(
+                    f"extra key {key!r} would break the key=value INI line"
+                )
+            if not isinstance(value, (str, int, bool)):
+                raise TypeError(
+                    f"extra[{key!r}] must be str, int or bool, "
+                    f"got {type(value).__name__}"
+                )
+            if isinstance(value, str) and "\n" in value:
+                raise ValueError(
+                    f"extra[{key!r}] must not contain newlines"
+                )
+        # Freeze the mapping so the dataclass is deeply immutable.
+        object.__setattr__(self, "extra", MappingProxyType(dict(self.extra)))

pyeasydeploy/packages.py

@@ -0,0 +1,187 @@
+"""Package installation into remote virtual environments.
+
+All installs run inside the venv (see run_in_venv) and use 'uv pip'
+by default for speed, falling back to plain pip on request.
+
+The private-GitHub flow clones LOCALLY with your own git credentials
+and uploads the result: the server never needs access to your GitHub.
+"""
+
+import shlex
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import List
+
+from fabric import Connection
+
+from .models import VenvPython
+from .transfer import upload_directory
+from .venv import run_in_venv
+
+
+def _pip(use_uv: bool) -> str:
+    return "uv pip" if use_uv else "python -m pip"
+
+
+def _make_remote_tempdir(conn: Connection) -> str:
+    """Create a unique temporary directory on the remote host.
+
+    Unique per call: concurrent deploys of the same package to the
+    same host can never collide.
+    """
+    result = conn.run("mktemp -d /tmp/pyeasydeploy.XXXXXX", hide=True)
+    return result.stdout.strip()
+
+
+def install_packages(
+    conn: Connection,
+    venv: VenvPython,
+    packages: List[str],
+    use_uv: bool = True,
+    verbose: bool = True,
+) -> None:
+    """Install packages from PyPI into the remote venv.
+
+    Args:
+        conn: Connection to the remote host.
+        venv: Target virtual environment.
+        packages: Requirement specifiers, e.g. ["fastapi",
+            "uvicorn[standard]", "requests>=2.31"].
+        use_uv: Install with 'uv pip' (fast, default) instead of pip.
+        verbose: Print progress to stdout.
+
+    Raises:
+        TypeError: If packages is not a list of str.
+        ValueError: If packages is empty or contains blank entries.
+    """
+    if not isinstance(packages, list) or not all(
+        isinstance(pkg, str) for pkg in packages
+    ):
+        raise TypeError("packages must be a list of str")
+    if not packages or not all(pkg.strip() for pkg in packages):
+        raise ValueError("packages must be a non-empty list of non-blank specifiers")
+
+    quoted = " ".join(shlex.quote(pkg) for pkg in packages)
+    if verbose:
+        print(f"Installing packages in venv: {', '.join(packages)}")
+    run_in_venv(conn, venv, f"{_pip(use_uv)} install {quoted}",
+                verbose=False, hide=True)
+
+
+def install_local_package(
+    conn: Connection,
+    venv: VenvPython,
+    local_package_dir: str,
+    use_uv: bool = True,
+    verbose: bool = True,
+) -> None:
+    """Upload a local package directory and install it into the venv.
+
+    The directory must be an installable package (pyproject.toml or
+    setup.py at its root): its declared dependencies are installed
+    automatically. It is uploaded to a unique remote temp directory,
+    installed, and the temp directory is removed even if the install
+    fails.
+
+    Args:
+        conn: Connection to the remote host.
+        venv: Target virtual environment.
+        local_package_dir: Path to the local package root.
+        use_uv: Install with 'uv pip' (fast, default) instead of pip.
+        verbose: Print progress to stdout.
+
+    Raises:
+        FileNotFoundError: If local_package_dir does not exist (from
+            upload_directory).
+    """
+    remote_temp = _make_remote_tempdir(conn)
+    try:
+        upload_directory(conn, local_package_dir, remote_temp, verbose=verbose)
+        if verbose:
+            print(f"Installing package from {remote_temp}")
+        run_in_venv(conn, venv,
+                    f"{_pip(use_uv)} install {shlex.quote(remote_temp)}",
+                    verbose=False, hide=True)
+    finally:
+        if verbose:
+            print(f"Cleaning up {remote_temp}")
+        conn.run(f"rm -rf {shlex.quote(remote_temp)}", hide=True, warn=True)
+
+
+def install_package_from_github(
+    conn: Connection,
+    venv: VenvPython,
+    github_repo_url: str,
+    use_uv: bool = True,
+    verbose: bool = True,
+) -> None:
+    """Install a package from a public GitHub repository.
+
+    The REMOTE host clones the repo (it must be public, or reachable
+    from the server). For private repos, use
+    install_package_from_private_github instead.
+
+    Args:
+        conn: Connection to the remote host.
+        venv: Target virtual environment.
+        github_repo_url: Repository URL, e.g.
+            "https://github.com/user/repo".
+        use_uv: Install with 'uv pip' (fast, default) instead of pip.
+        verbose: Print progress to stdout.
+    """
+    if verbose:
+        print(f"Installing package from GitHub repo: {github_repo_url}")
+    run_in_venv(conn, venv,
+                f"{_pip(use_uv)} install {shlex.quote('git+' + github_repo_url)}",
+                verbose=False, hide=True)
+
+
+def install_package_from_private_github(
+    conn: Connection,
+    venv: VenvPython,
+    github_repo_url: str,
+    branch: str = None,
+    use_uv: bool = True,
+    verbose: bool = True,
+) -> None:
+    """Install a package from a private GitHub repository.
+
+    Clones LOCALLY (with your machine's git credentials), strips the
+    .git directory, uploads the source and installs it. The server
+    never needs GitHub access, deploy keys or tokens.
+
+    Args:
+        conn: Connection to the remote host.
+        venv: Target virtual environment.
+        github_repo_url: Repository URL, SSH or HTTPS form.
+        branch: Branch or tag to clone. None uses the default branch.
+        use_uv: Install with 'uv pip' (fast, default) instead of pip.
+        verbose: Print progress to stdout.
+
+    Raises:
+        RuntimeError: If the local 'git clone' fails (bad URL, no
+            access, branch not found...).
+    """
+    with tempfile.TemporaryDirectory() as tmpdir:
+        repo_name = github_repo_url.rstrip("/").split("/")[-1].removesuffix(".git")
+        local_clone = Path(tmpdir) / repo_name
+
+        clone_cmd = ["git", "clone", "--depth", "1"]
+        if branch:
+            clone_cmd += ["--branch", branch]
+        clone_cmd += [github_repo_url, str(local_clone)]
+
+        if verbose:
+            print(f"Cloning {github_repo_url} locally...")
+        result = subprocess.run(clone_cmd, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise RuntimeError(f"git clone failed: {result.stderr.strip()}")
+
+        # The .git directory is history + credentials-adjacent metadata:
+        # the server needs neither.
+        shutil.rmtree(local_clone / ".git", ignore_errors=True)
+
+        install_local_package(conn, venv, str(local_clone),
+                              use_uv=use_uv, verbose=verbose)