Legacy API Reference

Backwards compatibility

fargv.fargv is the original fargv parser, present since the first release. It is exposed at the package top level so that existing scripts continue to work unchanged:

from fargv import fargv          # legacy entry point
p, help_str = fargv({"lr": 0.01, "epochs": 10, "verbose": False})

The legacy API uses single-dash (-name=value) syntax and is frozen — it receives no new features, only bug fixes. New scripts should use fargv.parse instead, which offers four definition styles, richer types, env-var overrides, config files, and standard double-dash (--name=value) syntax.

fargv.fargv (legacy)

fargv.parse (current)

CLI syntax

-name=value

--name=value

Short aliases

auto

auto

Config file

❌

✅ JSON / YAML / TOML / INI

Env-var overrides

✅ (bare PARAMNAME)

✅ (APPNAME_PARAMNAME)

Rich types

❌

✅ Fargv* classes

Mandatory params

❌

✅ fargv.REQUIRED

GUI backends

❌

✅ --user_interface=tk/qt

New features

❌ frozen

✅ actively developed

Main function

fargv.fargv_legacy.fargv(default_switches, argv: List[str] | None = None, use_enviromental_variables: bool = True, return_type: Literal['SimpleNamespace', 'dict', 'namedtuple'] = 'SimpleNamespace', return_named_tuple=None, spaces_are_equals: bool = True, description: str | None = None)[source]

Parse the argument list and create a dictionary with all parameters.

Parameter types are inferred from the default value:

  • str — string; supports {key} interpolation across parameters

  • int — integer

  • float — floating point

  • bool — flag; bare -name sets to True

  • tuple — choice; first element is the default

  • set — positional list; collected as a list of strings

Parameters:

  • default_switches – Dictionary mapping parameter names to defaults. A two-element value (default, "description string") attaches help text.

  • argv – Argument list to parse. Defaults to sys.argv. Mutated in-place: consumed switches are removed, positionals remain.

  • use_enviromental_variables – When True (default), environment variables with matching names override the defaults before argv parsing.

  • return_type – Output format — "SimpleNamespace" (default), "dict", or "namedtuple".

  • return_named_tuple – Deprecated. Use return_type instead.

  • spaces_are_equals – When True (default), -key value is equivalent to -key=value.

  • description – Script description shown in help. Defaults to the calling file’s module docstring if present.

Returns:

Tuple of (params, help_str) where params is the parsed namespace in the requested return type.

Helper functions

fargv.fargv_legacy.fargv2dict(args: SimpleNamespace | dict | tuple) → dict[source]

Converts any valid type of parsed arguments to dictionaries

Parameters:

args – Either a dictionary, a named tuple, or a SimpleNamespace

Returns:

a dictionary. In case args was a dictionary, it returns a copy of it.

fargv.fargv_legacy.can_override(standard_args: dict, new_args: dict) → bool[source]

Checks weather a given dictionary contains valid values for overriding defined arguments.

Parameters:

  • standard_args – the dictionary to be overiden

  • new_args – the dictionary conatining the overidden argumenst

Returns:

bool

fargv.fargv_legacy.override(standard_args: dict, new_args: dict) → dict[source]

Override standard_args entries with values from new_args.

Calls can_override() first; raises ValueError when the validation fails (unknown keys or type mismatches).

Parameters:

  • standard_args – The base dictionary to update.

  • new_args – Key/value pairs to apply on top.

Returns:

A new dict with the merged values.

Raises:

ValueError – If new_args contains keys or types not in standard_args.

fargv.fargv_legacy.generate_bash_autocomplete(default_switches, full_filename=None)[source]

Creates bash code for autocomplete

Parameters:

  • default_switches – a dictionary with the switches definitions

  • full_filename – The filename of the current program. If None, sys.argv[0] is used.

Returns:

A string with bash commands that enable autocomplete