# Reference

Every public name, importable from `pyeasydeploy`. Models take keyword arguments only, are deeply immutable, and raise `SchemaTypeError` or `SchemaValueError` (subclasses of `TypeError` and `ValueError`) naming the field when a value is invalid. Every function that talks to the server takes the connection first; most also take `verbose=True`, which prints each step.

## Models

| Name | Fields | Notes |
|---|---|---|
| `Host` | `address`, `user`, `auth`, `sudo_password=None`, `port=22` | A server. `auth` is a `Password` or a `Key`. sudo uses `sudo_password`, or the SSH password when `auth` is a `Password`. |
| `Password` | `value` | SSH password, not empty. |
| `Key` | `path` | An SSH private key file on your machine, e.g. `"~/.ssh/id_ed25519"`. |
| `PythonInstance` | `version`, `executable` | An interpreter on the server. `version` looks like `"3"` or `"3.11"`; `executable` is an absolute path. |
| `Venv` | `python`, `path` | A virtual environment on the server, bound to the `PythonInstance` that created it. `path` is absolute. |
| `SupervisorService` | `name`, `command`, `directory=None`, `user=None`, `autostart=True`, `autorestart=True`, `stdout_logfile`, `stderr_logfile`, `environment=None`, `extra=()` | A supervisord `[program:name]` entry. Fields set to `None` are left out of the file. The log files default to `/var/log/supervisor/%(program_name)s.log` and `%(program_name)s_err.log`. |
| `Option` | `key`, `value` | One supervisord option for `SupervisorService.extra`, written as `key=value`. `value` is a one-line `str`, an `int` or a `bool` (written `true`/`false`). |

## Connection

| Function | Does |
|---|---|
| `connect(host)` | An SSH connection (a Fabric `Connection`) to a `Host`. Lazy: a wrong password shows up on the first command. |
| `has_sudo_password(conn)` | Whether the connection has a sudo password. |
| `require_sudo(conn, what="this operation")` | Raises `PermissionError` at once if sudo would hang waiting for a password. |

## Remote Python

| Function | Does |
|---|---|
| `get_python_instances(conn)` | The `python3` interpreters in `/usr/bin`, newest first. `RuntimeError` if there is none. |
| `get_target_python_instance(conn, target_version)` | The newest interpreter matching `target_version` by components: `"3.1"` matches 3.1 only, `"3"` any 3.x. `RuntimeError` listing the available versions if none matches. |
| `get_any_python_instance(conn)` | The newest `python3` interpreter. |

## Venvs

| Function | Does |
|---|---|
| `create_venv(conn, python, path, recreate=True)` | Creates a `Venv` at `path` with `uv` installed in it and returns it. By default an existing venv there is removed first; `recreate=False` reuses it. |
| `delete_venv(conn, venv)` | Removes the venv's directory. |
| `run_in_venv(conn, venv, command, hide=False)` | Runs a shell command with the venv's `bin/` first in `PATH`. The command reaches the remote shell as is. Returns Fabric's result. |

## Packages

All four take `use_uv=True` (`False` installs with pip) and `force=False` (`True` passes `--force-reinstall`).

| Function | Does |
|---|---|
| `install_packages(conn, venv, packages)` | Installs requirement specifiers from PyPI, e.g. `["fastapi", "requests>=2.31"]`. |
| `install_local_package(conn, venv, local_package_dir)` | Uploads a local package (`pyproject.toml` or `setup.py` at its root) to a temporary directory and installs it with its dependencies. |
| `install_package_from_github(conn, venv, github_repo_url)` | Installs from a repository the server can clone itself. |
| `install_package_from_private_github(conn, venv, github_repo_url, branch=None)` | Clones on your machine with your git credentials, then uploads the source and installs it. |

## Files

Both remove the destination first, and refuse system roots such as `/`, `/etc`, `/home`, `/usr` or `/var` with `ValueError`.

| Name | Does |
|---|---|
| `upload_file(conn, local_file, remote_file, mode=None)` | Replaces `remote_file` with the local file, creating its parents. `mode` (e.g. `0o600`) sets its permissions. |
| `upload_directory(conn, local_dir, remote_dir, ignore=None, mode=None)` | Replaces `remote_dir` with a copy of `local_dir`. `ignore` holds name patterns; `None` means `DEFAULT_IGNORE`, `[]` uploads everything. `mode` applies to every file. |
| `DEFAULT_IGNORE` | The name patterns skipped by default: `.git`, `.venv`, `venv`, `__pycache__`, `.vscode`, `.idea`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `*.pyc`, `*.pyo`, `*.db`, `*.sqlite`, `*.sqlite3`, `.DS_Store`. |

## Services

All of these need sudo, except `check_supervisor_installed` and `create_supervisor_config`. Arch and Debian-based servers are supported, detected from `/etc/os-release`.

| Function | Does |
|---|---|
| `install_supervisor(conn)` | Installs, enables and starts supervisord. Safe to run again. |
| `check_supervisor_installed(conn)` | Whether `supervisorctl` is on the server. |
| `create_supervisor_config(service)` | The INI text for a `SupervisorService`: the named fields that are not `None`, then `extra` in order. Local, touches no server. |
| `deploy_supervisor_service(conn, service)` | Writes the service's configuration, replacing any with the same name, and reloads supervisord. It starts if `autostart` is set; a running service whose configuration changed is restarted. |
| `supervisor_start(conn, service_name)` | `supervisorctl start`. |
| `supervisor_stop(conn, service_name)` | `supervisorctl stop`. |
| `supervisor_restart(conn, service_name)` | `supervisorctl restart`. |
| `supervisor_status(conn, service_name=None)` | `supervisorctl status` of one service, or of all when `service_name` is `None`. |