settings Module

Environment Configuration and Variable Management.

This module provides utility functions and configuration classes for handling environment variables used by the GONet Wizard system, in particular for its entry points and various command-line tools. It includes validation tools that either require or gently warn about missing variables, as well as data classes that organize related environment values for dashboard and camera-side operations.

Functions

require_env_var() : Prompt for required environment variables if missing.
warn_env_var_missing() : Prompt optionally for missing environment variables.

Classes

EnvVar : Represents an environment variable with an optional default value.
GONetConfig : Environment settings for interacting with a remote GONet device.
DashboardConfig : Environment settings for dashboard data and image access.

Constants

GONet variables

GONET_USEREnvVar: Environment variable for the GONet user (default name: GONET_USER; default value: "pi").
GONET_PASSWORDEnvVar: Environment variable for the GONet password (default name: GONET_PASSWORD).
GONET4_PATHEnvVar: Environment variable for the path of the gonet4.py script in a GONet camera (default name: GONET4_PATH; default value: "/home/pi/Tools/Camera/gonet4.py").
GONET_CONFIG_FOLDEREnvVar: Environment variable for the path of the folder containing ‘.config’ files in a GONet camera (default name: GONET_CONFIG_FOLDER; default value: "/home/pi/Tools/Camera/").
GONET_IMAGES_FOLDEREnvVar: Environment variable for the path of the folder containing the images acquired in a GONet camera (default name: GONET_IMAGES_FOLDER; default value: "/home/pi/images/").
LOCAL_OUTPUT_FOLDEREnvVar: Environment variable for the local path of where to download new GONet images (default name: LOCAL_OUTPUT_FOLDER; default value: "./downloaded_files/").

Dashboard variables

GONET_ROOTEnvVar: Environment variable for the folder containing the json data of extracted GONet data.
GONET_ROOT_IMGEnvVar: Environment variable for the folder containing the GONet images to visualize.

Functions

GONet_Wizard.settings.require_env_var(envvar, prompt=None)[source]

Retrieve a required environment variable, or prompt the user to input it.

This function ensures that a required environment variable is defined. If not found, the user is prompted to provide a value.

Parameters:

name (EnvVar) – The name of the required environment variable.
prompt (str, optional) – A custom prompt message shown to the user if the variable is not set.

Returns:

The retrieved or user-provided value for the environment variable.

Return type:

str

GONet_Wizard.settings.warn_env_var_missing(envvar, prompt=None)[source]

Warn the user if an optional environment variable is not set.

This function checks whether a given environment variable is defined. If it’s missing, the user is prompted to define it interactively.

To avoid duplicate prompts when running a Dash app in debug mode, the function only executes its logic in the reloader child process (i.e., when the environment variable WERKZEUG_RUN_MAIN is set to ‘true’).

Parameters:

name (EnvVar) – The name of the environment variable to check.
prompt (str, optional) – A custom input prompt if the user agrees to define the variable.

Returns:

The value of the environment variable if already set or newly defined, or None if the user chooses not to define it.

Return type:

str or None

Notes

When app.run_server(debug=True) is used in Dash, the server restarts itself in a child process for hot reloading. To avoid running this prompt logic multiple times, we check for the environment variable ‘WERKZEUG_RUN_MAIN’ which is only ‘true’ in the child process.

Classes

class GONet_Wizard.settings.EnvVar(name, default=None)[source]

Bases: object

Represents an environment variable with an optional default value.

This class provides a structured way to define environment variable names and their default values, and offers methods to retrieve them from the environment safely. Useful for centralizing and managing environment configuration in a DRY and maintainable way.

name

The name of the environment variable.

Type:: str

default

The default value to use if the environment variable is not set. Defaults to None.

Type:: Optional[str], optional

get()[source]

Returns the environment variable’s value or its default.

Return type:: str

class GONet_Wizard.settings.GONetConfig(gonet_user=None, gonet4_path=None, gonet_config_folder=None, gonet_images_folder=None, local_output_folder=None)[source]

Bases: object

Environment-based configuration for interacting with a remote GONet device.

This class retrieves configuration settings from environment variables, including SSH credentials, paths to scripts and image directories, and local output locations. Environment variables are loaded dynamically at runtime to ensure flexibility and testability.

⚠️ Implementation Note:

Environment variables are not read as default values at class definition time. Instead, they are loaded dynamically in the __post_init__ method.

Why?

If fields were defined like: gonet_user: str = GONET_USER.get() the environment lookup would occur at parse time, not instantiation time. This means:

Tests using tools like monkeypatch.setenv() would not affect behavior.
It becomes difficult to override variables dynamically.
Test isolation and runtime flexibility are compromised.

Solution:

All environment lookups are deferred to __post_init__() to ensure they reflect the current state of os.environ when the object is created.

gonet_user

Username for SSH connection to the GONet device, from GONET_USER.

Type:: str

gonet4_path

Remote path to gonet4.py, from GONET4_PATH.

Type:: str

gonet_config_folder

Remote folder containing camera config files, from GONET_CONFIG_FOLDER.

Type:: str

gonet_images_folder

Remote folder where images are stored, from GONET_IMAGES_FOLDER.

Type:: str

local_output_folder

Local folder where downloaded files should be saved, from LOCAL_OUTPUT_FOLDER.

Type:: str

gonet_password

SSH password for the GONet device, from GONET_PASSWORD, or prompted interactively.

Type:: str

get_gonet_password()[source]

SSH password for the GONet device.

Retrieved from the GONET_PASSWORD environment variable, or entered interactively if not set.

Returns:: The SSH password.
Return type:: str

class GONet_Wizard.settings.DashboardConfig[source]

Bases: object

Environment-based configuration for the GONet dashboard.

This class centralizes the retrieval of environment-based paths required for the GONet dashboard to function properly. It ensures that environment variables are not read until runtime, allowing for dynamic configuration and interactive prompting or fallback handling if variables are missing.

dashboard_data_path

Absolute path to the root directory where dashboard data is stored. Retrieved from the environment variable GONET_ROOT. Set during object initialization.

Type:: pathlib.Path

gonet_images_path

Optional absolute path to the directory containing image files for the dashboard. Retrieved from the environment variable GONET_ROOT_IMG, or set to None if the variable is not defined or skipped by the user.

Type:: pathlib.Path or None

get_dashboard_data_path()[source]

Path to the dashboard data directory.

Retrieves the value of the GONET_ROOT environment variable and converts it to a Path object. If the variable is not set, the user is prompted to enter a path interactively.

Returns:: The absolute path defined by the GONET_ROOT environment variable.
Return type:: pathlib.Path

get_gonet_images_path()[source]

Optional path to the image directory for the dashboard.

Retrieves the value of the GONET_ROOT_IMG environment variable and converts it to a Path object. If the variable is not set or skipped, returns None.

Returns:: The path defined by the GONET_ROOT_IMG environment variable, or None if the variable is missing.
Return type:: pathlib.Path or None