pyeasydeploy 0.1.0__tar.gz

pyeasydeploy-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: pyeasydeploy
+Version: 0.1.0
+Summary: Simple and replicable Python server deployment toolkit
+Author: Beltrán Offerrall
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/offerrall/pyeasydeploy
+Project-URL: Repository, https://github.com/offerrall/pyeasydeploy
+Project-URL: Issues, https://github.com/offerrall/pyeasydeploy/issues
+Keywords: deployment,devops,automation,ssh,fabric,supervisor
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Installation/Setup
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fabric>=3.0.0
+
+# pyeasydeploy 0.1.0
+
+A small library for deploying Python applications to Linux servers over SSH. Plain Python functions on top of [Fabric](https://www.fabfile.org/): no agents on the server, no YAML, no DSL to learn. Your deploy script reads top to bottom.
+
+It doesn't try to compete with Ansible or Docker. If you have a few servers, you write Python, and you want your deploy to be just another `deploy.py` in your project, it might be for you.
+
+## A complete deploy
+
+```python
+from pyeasydeploy import (
+    SupervisorService, connect_to_host, create_venv,
+    deploy_supervisor_service, get_target_python_instance,
+    install_local_package,
+)
+
+APP = "myapp"
+USER = "deploy"
+
+conn = connect_to_host(
+    host="203.0.113.10",
+    user=USER,
+    key_filename="~/.ssh/id_ed25519",
+    sudo_password="...",   # better: os.environ["SUDO_PASSWORD"]
+)
+
+py = get_target_python_instance(conn, "3.11")
+venv = create_venv(conn, py, f"/home/{USER}/venvs/{APP}")
+install_local_package(conn, venv, f"./{APP}")
+
+deploy_supervisor_service(conn, SupervisorService(
+    name=APP,
+    command=f"{venv.venv_path}/bin/python -m {APP}",
+    directory=f"/home/{USER}",
+    user=USER,
+))
+```
+
+Connect, pick an interpreter, create the venv, install your package with its dependencies, and leave it running as a supervised service that survives reboots. The `venv` object returned by `create_venv` carries its own path: the service command is built from it, no paths repeated by hand.
+
+## The ideas behind it
+
+**Destructive and reproducible.** Uploads remove the destination and copy from scratch, every time. After each deploy, the server has exactly what you have locally — no leftovers from previous versions. This is not configurable; it's the contract. (The one safety net: paths like `/`, `/home` or `/etc` are rejected as destinations.)
+
+**Fail early, fail clearly.** Models validate on construction: a relative path or a service name that would corrupt the INI file blows up on your laptop with a useful message, before touching the server. Functions that need sudo check for it upfront — an immediate error with instructions, instead of the classic hang waiting for a password that will never come.
+
+**Trust the user.** The library validates *form* (types, absolute paths, dangerous characters), not your *facts*: if you hand-build a `PythonInstance` pointing at an exotic interpreter, it's accepted. You know what's on your server.
+
+## Installation
+
+```bash
+pip install pyeasydeploy
+```
+
+Python ≥ 3.10 on your machine. On the server: SSH and some `python3` (tested on Debian/Ubuntu).
+
+## Quick guide
+
+### Connecting
+
+```python
+conn = connect_to_host(host, user, password="...")                    # password (reused for sudo)
+conn = connect_to_host(host, user, key_filename="~/.ssh/id_ed25519")  # SSH key
+```
+
+With key auth and sudo operations, add `sudo_password=`. The connection is lazy: a wrong password shows up on the first command, not at connect time.
+
+### Remote Python
+
+```python
+py = get_any_python_instance(conn)             # newest on the server
+py = get_target_python_instance(conn, "3.11")  # a specific one
+```
+
+Only real interpreters are matched (`python3.X-config` and friends are filtered out), and version matching is component-wise: `"3.1"` means 3.1, not 3.11. For non-standard locations, build the model yourself:
+
+```python
+py = PythonInstance(version="3.12", executable="/opt/py312/bin/python3.12")
+```
+
+### Venvs and packages
+
+```python
+venv = create_venv(conn, py, "/home/deploy/venvs/myapp")  # idempotent
+
+install_packages(conn, venv, ["fastapi", "uvicorn[standard]"])
+install_local_package(conn, venv, "./myapp")
+install_package_from_private_github(conn, venv, "git@github.com:org/private.git")
+
+run_in_venv(conn, venv, "python -m myapp --check")
+```
+
+Installs use `uv` inside the venv (fast; `use_uv=False` for classic pip). Private repos are cloned **on your machine** with your own credentials, then the source is uploaded: the server never needs access to your GitHub.
+
+### Files
+
+```python
+upload_directory(conn, "./data", "/home/deploy/data")
+upload_file(conn, "config.toml", "/home/deploy/myapp/config.toml")
+```
+
+⚠️ Destructive: the destination is removed before copying. `.git`, `__pycache__`, venvs and similar are excluded by default (`DEFAULT_IGNORE`); pass `ignore=[]` to upload everything.
+
+### Services
+
+```python
+install_supervisor(conn)   # once per server
+
+deploy_supervisor_service(conn, SupervisorService(
+    name="myapp",
+    command=f"{venv.venv_path}/bin/python -m myapp",
+    extra={
+        "stdout_logfile_maxbytes": "10MB",   # any supervisord option,
+        "stdout_logfile_backups": 5,         # passed through verbatim
+        "stopsignal": "INT",
+    },
+))
+
+supervisor_status(conn)
+supervisor_restart(conn, "myapp")
+```
+
+Named fields cover the common cases; the `extra` dict accepts any supervisord option with no restrictions — the library only blocks what would corrupt the generated file.
+
+## What it is not
+
+- **Not Ansible/Terraform.** No inventories, no state, no declarative idempotency. Imperative on purpose.
+- **Not provisioning.** It installs supervisor because services are its job, and that's where it stops: nginx, databases and the rest of your server are up to you.
+- **No secret management.** The passwords you pass in are your environment's responsibility.
+- **No fleet orchestration.** One connection, one server. For several, write a loop.
+- **Linux targets only.** The source machine can be Windows, macOS or Linux.
+
+For many of those cases, bigger tools will do it better. This one exists for when you don't need them.
+
+## License
+
+MIT

pyeasydeploy-0.1.0/README.md

@@ -0,0 +1,136 @@
+# pyeasydeploy 0.1.0
+
+A small library for deploying Python applications to Linux servers over SSH. Plain Python functions on top of [Fabric](https://www.fabfile.org/): no agents on the server, no YAML, no DSL to learn. Your deploy script reads top to bottom.
+
+It doesn't try to compete with Ansible or Docker. If you have a few servers, you write Python, and you want your deploy to be just another `deploy.py` in your project, it might be for you.
+
+## A complete deploy
+
+```python
+from pyeasydeploy import (
+    SupervisorService, connect_to_host, create_venv,
+    deploy_supervisor_service, get_target_python_instance,
+    install_local_package,
+)
+
+APP = "myapp"
+USER = "deploy"
+
+conn = connect_to_host(
+    host="203.0.113.10",
+    user=USER,
+    key_filename="~/.ssh/id_ed25519",
+    sudo_password="...",   # better: os.environ["SUDO_PASSWORD"]
+)
+
+py = get_target_python_instance(conn, "3.11")
+venv = create_venv(conn, py, f"/home/{USER}/venvs/{APP}")
+install_local_package(conn, venv, f"./{APP}")
+
+deploy_supervisor_service(conn, SupervisorService(
+    name=APP,
+    command=f"{venv.venv_path}/bin/python -m {APP}",
+    directory=f"/home/{USER}",
+    user=USER,
+))
+```
+
+Connect, pick an interpreter, create the venv, install your package with its dependencies, and leave it running as a supervised service that survives reboots. The `venv` object returned by `create_venv` carries its own path: the service command is built from it, no paths repeated by hand.
+
+## The ideas behind it
+
+**Destructive and reproducible.** Uploads remove the destination and copy from scratch, every time. After each deploy, the server has exactly what you have locally — no leftovers from previous versions. This is not configurable; it's the contract. (The one safety net: paths like `/`, `/home` or `/etc` are rejected as destinations.)
+
+**Fail early, fail clearly.** Models validate on construction: a relative path or a service name that would corrupt the INI file blows up on your laptop with a useful message, before touching the server. Functions that need sudo check for it upfront — an immediate error with instructions, instead of the classic hang waiting for a password that will never come.
+
+**Trust the user.** The library validates *form* (types, absolute paths, dangerous characters), not your *facts*: if you hand-build a `PythonInstance` pointing at an exotic interpreter, it's accepted. You know what's on your server.
+
+## Installation
+
+```bash
+pip install pyeasydeploy
+```
+
+Python ≥ 3.10 on your machine. On the server: SSH and some `python3` (tested on Debian/Ubuntu).
+
+## Quick guide
+
+### Connecting
+
+```python
+conn = connect_to_host(host, user, password="...")                    # password (reused for sudo)
+conn = connect_to_host(host, user, key_filename="~/.ssh/id_ed25519")  # SSH key
+```
+
+With key auth and sudo operations, add `sudo_password=`. The connection is lazy: a wrong password shows up on the first command, not at connect time.
+
+### Remote Python
+
+```python
+py = get_any_python_instance(conn)             # newest on the server
+py = get_target_python_instance(conn, "3.11")  # a specific one
+```
+
+Only real interpreters are matched (`python3.X-config` and friends are filtered out), and version matching is component-wise: `"3.1"` means 3.1, not 3.11. For non-standard locations, build the model yourself:
+
+```python
+py = PythonInstance(version="3.12", executable="/opt/py312/bin/python3.12")
+```
+
+### Venvs and packages
+
+```python
+venv = create_venv(conn, py, "/home/deploy/venvs/myapp")  # idempotent
+
+install_packages(conn, venv, ["fastapi", "uvicorn[standard]"])
+install_local_package(conn, venv, "./myapp")
+install_package_from_private_github(conn, venv, "git@github.com:org/private.git")
+
+run_in_venv(conn, venv, "python -m myapp --check")
+```
+
+Installs use `uv` inside the venv (fast; `use_uv=False` for classic pip). Private repos are cloned **on your machine** with your own credentials, then the source is uploaded: the server never needs access to your GitHub.
+
+### Files
+
+```python
+upload_directory(conn, "./data", "/home/deploy/data")
+upload_file(conn, "config.toml", "/home/deploy/myapp/config.toml")
+```
+
+⚠️ Destructive: the destination is removed before copying. `.git`, `__pycache__`, venvs and similar are excluded by default (`DEFAULT_IGNORE`); pass `ignore=[]` to upload everything.
+
+### Services
+
+```python
+install_supervisor(conn)   # once per server
+
+deploy_supervisor_service(conn, SupervisorService(
+    name="myapp",
+    command=f"{venv.venv_path}/bin/python -m myapp",
+    extra={
+        "stdout_logfile_maxbytes": "10MB",   # any supervisord option,
+        "stdout_logfile_backups": 5,         # passed through verbatim
+        "stopsignal": "INT",
+    },
+))
+
+supervisor_status(conn)
+supervisor_restart(conn, "myapp")
+```
+
+Named fields cover the common cases; the `extra` dict accepts any supervisord option with no restrictions — the library only blocks what would corrupt the generated file.
+
+## What it is not
+
+- **Not Ansible/Terraform.** No inventories, no state, no declarative idempotency. Imperative on purpose.
+- **Not provisioning.** It installs supervisor because services are its job, and that's where it stops: nginx, databases and the rest of your server are up to you.
+- **No secret management.** The passwords you pass in are your environment's responsibility.
+- **No fleet orchestration.** One connection, one server. For several, write a loop.
+- **Linux targets only.** The source machine can be Windows, macOS or Linux.
+
+For many of those cases, bigger tools will do it better. This one exists for when you don't need them.
+
+## License
+
+MIT

pyeasydeploy-0.1.0/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-0.1.0/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."
+    )