Declarative header

The declarative header is the docstring of the script. Scrippy reads its declarations to configure the behavior of the script.

Table of content

• General rules
• Script information
• Authorized users and groups
• Concurrent executions
• Configuration parameters
• Options and arguments
• Complete template

General rules

• The header is the docstring of the script: It must be the first statement of the script, enclosed in triple quotes. Only comments, such as the shebang, may precede it.
• A declaration is a line whose first non blank characters are @<name>, followed by : and its value. Indentation and spaces around : are ignored.
• Declarations can be placed anywhere in the header, in any order. The sections and separator lines of the Scrippy template are a convention, not a requirement.
• Any line that does not start with @ is ignored: To comment a declaration out, prefix it with any character, i.e: # @user:luiggi.
• For the single value declarations (@author, @date, @version, @description, @max_instance, @timeout, @exit_on_wait, @exit_on_timeout), only the first occurrence is used.
• Declarations are case sensitive: @User is not a declaration.

Script information

These declarations are displayed by the --help option, and @version by the --version option. Their format is free, but the Scrippy conventions recommend a YYYY-MM-DD date and a X.Y.Z version.

A missing declaration stops the script with one of the following errors: Missing script author, Missing script date, Missing script version, Missing script description.

@author         : Luiggi Vercotti
@date           : 2026-10-08
@version        : 1.0.0
@description    : Monitor filesystem usage

Authorized users and groups

• Without @user nor @group declarations, any user allowed by the file permissions can run the script.
• With @user declarations only, the effective user must be one of the listed users.
• With @group declarations only, the effective user must be a member of one of the listed groups.
• With both, both conditions must be met.

@user:luiggi
@user:harry
@group:ops

See the Access control step of the tutorial.

Concurrent executions

• Booleans: true, 1 and on (case insensitive) are true, any other value is false.
• An invalid integer stops the script with an error such as [ValueError] invalid literal for int() with base 10: 'two'.
• When the maximum is reached, the new executions wait for a slot and get it in the order they started.
• The availability of a slot is checked every 3 seconds: The actual waiting time is the largest multiple of 3 lower than @timeout.

See the Concurrent executions step of the tutorial.

Configuration parameters

@conf:<section>|<key>|<type>|<secret>

Declares a key that must be present in the configuration file of the script.

• All fields are mandatory and can not be empty.
• When entering the execution context, every declared key is checked: The section and the key must exist, and the value must be convertible to the declared type. Otherwise, the script stops before running any code of the main() function.
• Only the structure and the types are checked, not the values.
• Keys present in the configuration file but not declared are not checked and remain available.
• The [log] section and its level key are reserved and do not need to be declared.

Invalid declarations are all reported at once, with the reason:

Configuration check errors:

@conf:filesystems|mount_points|str|false
@conf:thresholds|warning|int|false
@conf:alerting|token|str|true

Options and arguments

@args:<name>|<type>|<help>|<number of arguments>|<default value>|<conflicts>|<implies>|<required>|<secret>

Declares a command line option --<name>.

The 9 fields are always present, optional fields being left empty.

Values

• Default values: With a fixed number of arguments greater than 1, the default value contains as many comma separated values (i.e: 1,1,2026 for 3 arguments). With +, any number of comma separated values. With 1 or ?, the default value is a single value that may contain commas.
• bool options: The default value is false when empty. A bool option whose default value is true is True when not used and False when used. A bool option can not be secret.
• choice options: The default value field holds the accepted values, so a choice option has no default value: It is None when not used.
• conflicts and implies can reference the declared options and the debug, no-stdout and no-log-file automatic options.

Validation

Invalid declarations are all reported at once with the reason, i.e:

Invalid @args declaration(s):
  - @args:warning|integer|Warning threshold|1||||false|false: unknown type 'integer' (expected: str, int, float, choice, bool)

A declaration is invalid when: A field is missing or extra, the name is empty, invalid or reserved, the help is empty, the type is unknown, the number of arguments is invalid, a default value does not match the type or the number of arguments, a choice option has no accepted values, required or secret is not a boolean, a bool option is secret, an option is declared twice, or conflicts or implies references an unknown option.

The reserved names are help, version, source-code, hist, log, debug, no-stdout and no-log-file (see Automatic options).

Usage errors

Usage errors are reported by the option parser, with the usage of the script, and the script exits with the status 2:

disk_watch.py: error: argument --warning: invalid int value: 'high'
disk_watch.py: error: Params --mount-point conflicts with --exclude. Please remove --mount-point or --exclude
disk_watch.py: error: Params --format implies --report. Please add --report

See the Options and arguments step of the tutorial.

Complete template

"""
--------------------------------------------------------------------------------
  @author         : <Author>
  @date           : <Date of current script version>
  @version        : <X.Y.Z>
  @description    : <Brief description (one line) of the utility of the script>

--------------------------------------------------------------------------------
  Update:
  <X.Y.Z>  <Date> - <Author> - <Reason>: <Description of update>

--------------------------------------------------------------------------------
  List of authorized users or group:
    @user:<username>
    @group:<group name>

--------------------------------------------------------------------------------
  Concurrent executions:
    @max_instance: <INT>
    @timeout: <INT>
    @exit_on_wait: <BOOL>
    @exit_on_timeout: <BOOL>

--------------------------------------------------------------------------------
  List of mandatory configuration parameters:
    @conf:<section>|<key>|<type>|<secret>

--------------------------------------------------------------------------------
  List of execution options and argument parameters:
    @args:<name>|<type>|<help>|<number of arguments>|<default value>|<conflicts>|<implies>|<required>|<secret>

--------------------------------------------------------------------------------
  Functioning:
  ---------------
    <Detailed description of the script>
"""