Metadata-Version: 2.4
Name: scrippy
Version: 2.0.0
Summary: Scrippy framework install helper
Home-page: https://codeberg.org/scrippy/scrippy
Author: Michael Costa, Florent Chevalier
Author-email: michael.costa@mcos.nc, florent.chevalier.nc@gmail.com
License: MIT
Project-URL: Bug Tracker, https://codeberg.org/scrippy/scrippy/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Environment :: Console
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: coloredlogs>=10.0
Requires-Dist: PyYAML>=6.0.3
Provides-Extra: dev
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: wheel>=0.37.0; extra == "dev"
Requires-Dist: flake8>=4.0.1; extra == "dev"
Requires-Dist: flake8-breakpoint>=1.1.0; extra == "dev"
Requires-Dist: flake8-builtins>=1.5.3; extra == "dev"
Requires-Dist: flake8-print>=4.0.0; extra == "dev"
Requires-Dist: flake8-return>=1.1.3; extra == "dev"
Requires-Dist: pep8-naming>=0.8.2; extra == "dev"
Requires-Dist: bump2version>=1.0.1; extra == "dev"
Requires-Dist: setuptools>=60.9.2; extra == "dev"
Requires-Dist: pypirc-chappers>=1.0.8; extra == "dev"
Requires-Dist: pylint>=2.12.2; extra == "dev"
Dynamic: license-file

![Version](https://img.shields.io/static/v1?label=version&color=informational&message=2.0.0)
![License](https://img.shields.io/static/v1?label=license&color=orange&message=MIT) ![Language](https://img.shields.io/static/v1?label=language&color=informational&message=Python)

# Scrippy installer

This is the [**Scrippy**](https://codeberg.org/scrippy) framework installer.

The `scrippy` command creates the Scrippy directories, writes the Scrippy main configuration file and installs the [*Scrippy scripting framework*](https://codeberg.org/scrippy/) packages with `pip`. It also uninstalls them.

## Requirements

- Python >= 3.11
- Linux, BSD or macOS

## Install the Scrippy installer

- In a dedicated virtual environment (recommended, mandatory on *externally managed* Python environments, see [PEP 668](#externally-managed-python-environments-pep-668))

  ```shell
  python3 -m venv ~/.local/share/scrippy/venv
  ~/.local/share/scrippy/venv/bin/pip install scrippy
  ```

  Scrippy packages are installed in the same virtual environment as the installer: Run the `scrippy` command with `~/.local/share/scrippy/venv/bin/scrippy` and Scrippy scripts with `~/.local/share/scrippy/venv/bin/python`.

- In the user Python environment

  ```shell
  export PATH=${HOME}/.local/bin:${PATH}
  pip install scrippy
  ```

## Configure and install [*the Scrippy scripting framework*](https://codeberg.org/scrippy/) with default values

- With configuration confirmation

  ```shell
  scrippy install
  ```

- Without configuration confirmation

  ```shell
  scrippy install -y
  ```

Default values:

| | User | `root` (system wide installation) |
|---|---|---|
| Main configuration file | `~/.config/scrippy/scrippy.yml` | `/etc/scrippy/scrippy.yml` |
| Scrippy directories | `~/.local/share/scrippy/{conf,data,hist,log,reports,templates,tmp}` | `/etc/scrippy/{conf,data,hist,log,reports,templates,tmp}` |
| Packages | `scrippy-core`, `scrippy-remote`, `scrippy-api`, `scrippy-db`, `scrippy-mail`, `scrippy-git`, `scrippy-template`, `scrippy-snmp` (latest versions) | same |

Any preexisting main configuration file is overwritten. Packages are installed with `pip install --upgrade` (automatic upgrade/downgrade).

## Configure and install [*the Scrippy scripting framework*](https://codeberg.org/scrippy/) interactively

```shell
scrippy install -i
```

Each directory and package version is prompted for, with the default value between brackets (press `Enter` to keep it).

## Configure and install [*the Scrippy scripting framework*](https://codeberg.org/scrippy/) from custom configuration file

```shell
scrippy install -c /path/to/config.yml
```

`-i` and `-c` are mutually exclusive. Both can be combined with `-y`.

### Configuration file example

```yaml
env:
  confdir: ~/.local/share/scrippy/conf
  datadir: ~/.local/share/scrippy/data
  histdir: ~/.local/share/scrippy/hist
  logdir: ~/.local/share/scrippy/log
  reportdir: ~/.local/share/scrippy/reports
  templatedir: ~/.local/share/scrippy/templates
  tmpdir: ~/.local/share/scrippy/tmp
packages:
  scrippy-core: latest
  scrippy-remote: latest
  scrippy-api: latest
  scrippy-db: latest
  scrippy-mail: latest
  scrippy-git: latest
  scrippy-template: latest
  scrippy-snmp: latest
```

- Both sections are optional.
- Directories missing from the `env` section keep their default value.
- Paths may be relative or use `~`, they are converted to absolute paths (this also applies to paths entered interactively).
- When defined, the `packages` section replaces the default package list: only the listed packages are installed.
- Package value is either `latest` (or empty) or a version number (e.g. `1.10`).
- The resulting configuration (including the package list) is saved in the main configuration file and used by `scrippy uninstall`.

## Uninstall [*the Scrippy scripting framework*](https://codeberg.org/scrippy/)

```shell
scrippy uninstall
```

The packages listed in the main configuration file are uninstalled, then the main configuration file is deleted. Scrippy directories are kept.

When run as `root`, a confirmation is asked before uninstalling the system wide installation.

## Uninstall [*the Scrippy scripting framework*](https://codeberg.org/scrippy/) and delete all Scrippy directories

```shell
scrippy uninstall --prune
```

A confirmation is asked before deleting the Scrippy directories (`confdir`, `datadir`, `histdir`, `logdir`, `reportdir`, `templatedir`, `tmpdir`) and all their content.

`scrippy uninstall` does not uninstall the Scrippy installer itself (`pip uninstall scrippy`) nor delete its virtual environment.

## Externally managed Python environments (PEP 668)

On recent operating systems (Debian 12+, Ubuntu 23.04+, ...), the system Python environment is *externally managed* and `pip` refuses to install or uninstall packages into it. In such an environment, `scrippy install` and `scrippy uninstall` fail with a message explaining the available solutions:

- Recommended: Install Scrippy in a dedicated virtual environment (see [Install the Scrippy installer](#install-the-scrippy-installer)) and run Scrippy scripts with its Python interpreter. For a system wide installation (`root`):

  ```shell
  python3 -m venv /opt/scrippy/venv
  /opt/scrippy/venv/bin/pip install scrippy
  /opt/scrippy/venv/bin/scrippy install
  ```

- Or force the installation into the system Python environment (**may break Python tools provided by the operating system**)

  ```shell
  pip install --break-system-packages scrippy
  scrippy install --break-system-packages
  scrippy uninstall --break-system-packages
  ```

  The `--break-system-packages` option only has an effect when the Python environment is externally managed.

## Command reference

```text
scrippy install [-i | -c CONFIG] [-y] [--break-system-packages]
scrippy uninstall [-p] [--break-system-packages]
```

| Command | Option | Description |
|---|---|---|
| `install` | `-i`, `--interactive` | Prompt for configuration values |
| `install` | `-c CONFIG`, `--config CONFIG` | Configure Scrippy according to the specified YAML file |
| `install` | `-y`, `--yes` | Answer `yes` to all questions |
| `install`, `uninstall` | `--break-system-packages` | Allow `pip` to modify an externally managed Python environment (PEP 668) |
| `uninstall` | `-p`, `--prune` | Remove all Scrippy directories and their content |
