Conventions

Scrippy aims at standardizing scripts: Any script should look familiar to anyone who knows Scrippy. The conventions below are not enforced by Scrippy, but all Scrippy scripts should follow them.

Script template

#!/usr/bin/env python3
"""
--------------------------------------------------------------------------------
  @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>
"""
# ------------------------------------------------------------------------------
#  Initialization of the environment
# ------------------------------------------------------------------------------
import scrippy_core
from scrippy_core import logger

# ------------------------------------------------------------------------------
#  Definition of functions and classes
# ------------------------------------------------------------------------------
def <function>([<param>, ...]):
  [...]

# ------------------------------------------------------------------------------
#  Main processing
# ------------------------------------------------------------------------------
def main():
  with scrippy_core.ScriptContext() as _context:
    config = _context.config
    args = _context.args
    [...]

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

Remove the unused declarations: The placeholders above are not valid values (see the header reference).

The script is made of five parts:

Part Content
Header The declarative header, with its sections
Initialization of the environment The imports, scrippy_core first, and the constants
Definition of functions and classes The functions and classes of the script
Main processing The main() function, whose whole content is enclosed in the execution context
Entry point The call to main()

Header sections

Section Content
Script information @author, @date, @version, @description
Update The changelog of the script, one line per version (see Changelog)
List of authorized users or group @user and @group declarations
Concurrent executions @max_instance, @timeout, @exit_on_wait, @exit_on_timeout declarations
List of mandatory configuration parameters @conf declarations
List of execution options and argument parameters @args declarations
Functioning The detailed documentation of the script: What it does, how, its configuration, its exit status...

Versioning

The version of a script follows the X.Y.Z format (semantic versioning):

  • X, the major version: Incremented when a change breaks the backward compatibility (i.e: an option is removed or renamed, the configuration file format changes). Y and Z are reset to 0.
  • Y, the minor version: Incremented when a feature is added or the code is improved without breaking the backward compatibility. Z is reset to 0.
  • Z, the correction version: Incremented when a bug is fixed, or for a typographical correction.

The major version is 0 during the development: The script is considered unstable and should not be used in production nor called by other scripts. The first stable version is 1.0.0.

The @date declaration is the date of the current version, in the YYYY-MM-DD format.

Changelog

Each version of the script adds a line to the Update section:

<X.Y.Z>  <Date> - <Author> - <Reason>: <Description of update>
Reason Usage
cre Script creation
evo Evolution: New feature, code improvement...
bugfix Correction of an unexpected behavior
typo Typographical correction, comments, any change that does not modify the code 
  Update:
  1.0.0  2026-10-08 - Luiggi Vercotti - cre: Script creation
  1.1.0  2026-11-02 - Harry Fink - evo: CSV report
  1.1.1  2026-11-15 - Luiggi Vercotti - bugfix: Mount points with spaces

Good practices

  • A log is never too verbose: Each function should log what it does and, where possible, the parameters it receives.
  • Give priority to readability and maintainability over compactness and technicality.
  • Break down the code into small functions, and keep the main() function as simple as possible: It should read as a summary of the script.
  • No hard coded values: Move them to the configuration file or to options.
  • Avoid global variables at all costs: Pass values as function parameters.
  • Handle errors as finely and as close as possible to where they occur, and let the execution context handle the fatal ones (see Error handling).
  • Minimize information leaks: Declare sensitive values (passwords, tokens, logins, server names...) as secret, and prefer the configuration file to options for them (see Secrets).
  • Use the Scrippy directories (_context.env) and the workspace instead of hard coded paths.
  • Never use print(): Use the logger.
  • Return a meaningful exit status: 0 for success, a documented non-zero value otherwise.
  • Debug your scripts in a test environment, not in production.