1. First script

In this first step, disk_watch.py displays the usage of the root filesystem. It is short, but it already is a complete Scrippy script.

The code

Create the file disk_watch.py:

#!/usr/bin/env python3
"""
--------------------------------------------------------------------------------
  @author         : Luiggi Vercotti
  @date           : 2026-10-08
  @version        : 0.1.0
  @description    : Monitor filesystem usage

--------------------------------------------------------------------------------
  Update:
  0.1.0  2026-10-08 - Luiggi Vercotti - cre: Script creation

--------------------------------------------------------------------------------
  Functioning:
  ---------------
    Displays the usage of the root filesystem.
"""
# ------------------------------------------------------------------------------
#  Initialization of the environment
# ------------------------------------------------------------------------------
import shutil
import scrippy_core
from scrippy_core import logger

# ------------------------------------------------------------------------------
#  Definition of functions and classes
# ------------------------------------------------------------------------------
def get_usage(mount_point):
  usage = shutil.disk_usage(mount_point)
  return round(usage.used * 100 / usage.total, 1)

# ------------------------------------------------------------------------------
#  Main processing
# ------------------------------------------------------------------------------
def main():
  with scrippy_core.ScriptContext() as _context:
    logger.info(f"[+] /: {get_usage('/')}% used")

# ------------------------------------------------------------------------------
#  Entry point
# ------------------------------------------------------------------------------
if __name__ == '__main__':
  main()

Make it executable and run it:

chmod +x disk_watch.py
./disk_watch.py
[20261008 19:05:05] [INFO    ] [+] Secrets registration (args)
[20261008 19:05:05] [INFO    ] [+] No configuration file /home/luiggi/.local/share/scrippy/conf/disk_watch.conf
[20261008 19:05:05] [INFO    ] [+] Configuration check
[20261008 19:05:05] [INFO    ] [+] Secrets registration (conf)
[20261008 19:05:05] [INFO    ] [+] Opening history (retention=50)
[20261008 19:05:05] [INFO    ] [+] Using workspace: /home/luiggi/.local/share/scrippy/tmp/disk_watch_1791446705.884451_27893
[20261008 19:05:05] [INFO    ] [+] /: 34.9% used
[20261008 19:05:05] [INFO    ] [+] Workspace deletion: /home/luiggi/.local/share/scrippy/tmp/disk_watch_1791446705.884451_27893
[20261008 19:05:05] [INFO    ] [+] End: 0

Only one line comes from your code (/: 34.9% used). All the other lines come from Scrippy, which did a lot of work for you. Let's see how.

Anatomy of a Scrippy script

The declarative header

The docstring at the top of the script is the declarative header. Scrippy reads it to know how the script must behave.

The four @author, @date, @version and @description declarations are mandatory: A script missing one of them exits immediately with an error such as Missing script version.

The Update and Functioning sections are not read by Scrippy. They are part of the Scrippy conventions and keep the changelog and the documentation of the script within the script itself.

The following steps of this tutorial will add other declarations to the header. They are all described in the header reference.

Note: The header must be the very first statement of the script (only comments, such as the shebang, may precede it), otherwise Python does not consider it as the docstring of the script.

The scrippy_core import

import scrippy_core
from scrippy_core import logger

Importing scrippy_core reads the Scrippy configuration, parses the header and the command line options. The header is always read from the script being executed (the Python __main__ module), so scrippy_core can not be imported from an interactive Python interpreter.

logger is the Scrippy logger, a standard Python logging.Logger with a few additions. It is the only way your script should display information: Never use print() in a Scrippy script.

The execution context

def main():
  with scrippy_core.ScriptContext() as _context:
    ...

scrippy_core.ScriptContext() is the execution context. When entering the with block, it:

  1. Loads and checks the configuration file of the script (No configuration file ..., Configuration check)
  2. Registers the secrets (Secrets registration)
  3. Checks the user is allowed to run the script and manages the concurrent executions
  4. Opens the log file and records the execution in the history (Opening history)
  5. Creates a temporary workspace (Using workspace)

When leaving the with block, whatever happened inside, it deletes the workspace (Workspace deletion), records the end of the execution in the history (End: 0) and handles errors.

The _context object gives access to the configuration, the options, the workspace and the environment of the script. You will use it in the next steps.

Note: By convention, the whole content of the main() function is enclosed in the execution context, and main() is only called from the Entry point section of the script.

What you get for free

An help, a version and the source code

The --help option is generated from the header:

./disk_watch.py --help
usage: disk_watch.py [-h] [--version] [--source-code]
                     [--hist [NB_EXECUTION (default:10)]]
                     [--log [SESSION (default: last)]] [--debug] [--no-stdout]
                     [--no-log-file]

Author: Luiggi Vercotti
Date: 2026-10-08
Version: 0.1.0
Description: Monitor filesystem usage

options:
  -h, --help            show this help message and exit
  --version             Show version and exit
  --source-code         Show source code
  --hist [NB_EXECUTION (default:10)]
                        Show execution history
  --log [SESSION (default: last)]
                        Show log content
  --debug               Force log level to DEBUG
  --no-stdout           Disable log output to standard output (error et critical are kept)
  --no-log-file         disable log file and history
./disk_watch.py --version
disk_watch.py 0.1.0

--source-code displays the source code of the script with syntax highlighting, which is handy when the script is installed on a server where no editor is available.

The other options are presented in the next steps of this tutorial.

Files

The execution created some files in the Scrippy directories:

File Purpose
log/disk_watch/disk_watch_1791446705.884451_27893.log The log file of this execution (see Logging)
hist/disk_watch.db The execution history of the script (see History)
tmp/disk_watch.pids and tmp/disk_watch.pids.lock The concurrent executions management files (see Concurrent executions)

The workspace tmp/disk_watch_1791446705.884451_27893 has already been deleted.

What's next

disk_watch.py only checks /. In the next step, it will check several mount points and use log levels to report their status.