Settings¶

How the command line and scripts find their FAIG_* settings. The command line guide shows pyfortiaigate config, which writes and shows them.

settings ¶

Settings for the command line and for scripts: FAIG_* variables and a settings file, resolved the way most command-line tools resolve them.

Precedence, highest first:

a command-line flag (--url, --ws, --key, --insecure);
a FAIG_* environment variable, even an empty one;
the settings file;
the built-in default.

The settings file is the one --env-file names, else FAIG_ENV_FILE, else $XDG_CONFIG_HOME/pyfortiaigate/.env (~/.config/pyfortiaigate/.env) when it exists. A .env in the current directory is never read, so a stray one cannot point your credentials at another server.

The file uses the python-dotenv format: NAME=value lines, an optional export in front, # comments (also at the end of an unquoted value), single quotes for a literal value and double quotes for one with \n, \t, \" or \\ escapes. A value is one line, and ${VAR} is not expanded. An empty value (FAIG_WS=) is the same as leaving the line out. Only FAIG_* names are used; any other line is ignored.

Reading settings never changes os.environ::

from pyfortiaigate import FortiAIGate
from pyfortiaigate.settings import load_settings

with FortiAIGate.from_env(load_settings()) as faig:
    ...

PREFIX `module-attribute` ¶

PREFIX

KNOWN `module-attribute` ¶

KNOWN: tuple[Setting, ...]

Setting `dataclass` ¶

One documented setting: its name, what it is for, whether it is a secret.

name `instance-attribute` ¶

name: str

help `instance-attribute` ¶

help: str

secret `class-attribute` `instance-attribute` ¶

secret: bool

Settings ¶

Bases: Mapping[str, str]

Resolved FAIG_* settings, and where each one came from: flag, environment, or the settings file's path. A read-only mapping, so it can be passed straight to FortiAIGate.from_env.

file `instance-attribute` ¶

file

The settings file that was read, or None.

source ¶

source(name: str) -> str | None

flag, environment, the settings file's path, or None (unset).

with_flags ¶

with_flags(flags: Mapping[str, str | None]) -> Settings

A copy with command-line values on top (None means the flag was not given).

masked ¶

masked(name: str) -> str

The value for display: a password shows nothing, a key or token only its last four characters, so you can tell two apart.

parse_env ¶

parse_env(text: str) -> dict[str, str]

NAME=value pairs from settings-file text (python-dotenv format, one line per value). Lines that are not a pair are skipped.

read_env_file ¶

read_env_file(path: str | PathLike[str]) -> dict[str, str]

Every pair in a settings file. Raises FileNotFoundError when it is missing.

default_settings_file ¶

default_settings_file(environ: Mapping[str, str] | None = None) -> Path

FAIG_ENV_FILE, else $XDG_CONFIG_HOME/pyfortiaigate/.env (~/.config/pyfortiaigate/.env). The file need not exist.

settings_file ¶

settings_file(env_file: str | PathLike[str] | None = None, environ: Mapping[str, str] | None = None) -> Path | None

The file to read: a named one (env_file, FAIG_ENV_FILE) even when it is missing, so reading it reports the mistake; the default one only when it exists; else None.

load_settings ¶

load_settings(env_file: str | PathLike[str] | None = None, environ: Mapping[str, str] | None = None, *, missing_ok: bool = False) -> Settings

FAIG_* settings from the environment, filled in from the settings file (see the module docstring for which file and the order). A named file that is missing raises FileNotFoundError, unless missing_ok (for a command that is about to create it).

write_settings ¶

write_settings(path: str | PathLike[str], updates: Mapping[str, str | None]) -> Path

Set (or, for None, remove) NAME=value lines in a settings file, keeping every other line and comment. Creates the file and its folder as needed; the file is written atomically and readable only by you (mode 600).