Parameter Types

This page maps Python literal types to their fargv equivalents, and lists fargv parameter types that have no Python literal counterpart.

Mapping table

Python literal	Example	Fargv* class	Legacy dict default	OO CLI syntax	Notes
bool	False	FargvBool	False	--verbose (bare toggles default)	Must be checked before int — bool subclasses int in Python
int	42	FargvInt	42	--count=3 or --count 3	Set is_count_switch=True for -vvvv style
float	3.14	FargvFloat	3.14	--lr=0.001	Accepts scientific notation (1e-3)
str	"hello"	FargvStr	"hello"	--name=Alice	Supports {key} cross-parameter interpolation
tuple (3+ items)	("a","b","c")	FargvChoice	("a","b","c")	--mode=b	First element is the default; 2-item tuple is (default, description)
list	[]	FargvPositional	set()	file1.txt file2.txt	Collects unmatched tokens; no -- prefix on CLI
set	set()	FargvPositional	set()	file1.txt file2.txt	Same as list; legacy API uses set for positionals
dict (all vals dicts)	{"train":{...}}	FargvSubcommand	—	prog train --lr=0.1	Git-style subcommand; flag style --cmd=train also works
(none)	—	FargvInputStream	—	--data=corpus.txt	Defaults to sys.stdin; accepts file paths or stdin
(none)	—	FargvOutputStream	—	--out=results.txt	Defaults to sys.stdout; accepts file paths, stdout, or stderr
(none)	—	FargvStream	—	--log=out.txt	Base class; use FargvInputStream / FargvOutputStream directly
(none)	—	FargvPath	—	--model=/weights/best.pt	Returns pathlib.Path; optional existence/non-existence validation
(none)	—	FargvExistingFile	—	--model=/weights/best.pt	FargvPath(must_exist=True)
(none)	—	FargvNonExistingFile	—	--out=/tmp/new.pt	FargvPath(must_not_exist=True)
(none)	—	FargvFile	—	--out=/data/run/pred.txt	FargvPath(parent_must_exist=True)
Tuple[int,int] annotation	(function param)	FargvTuple	—	--size=(640,480)	Parsed via ast.literal_eval; single-element shorthand "640" → (640,)
(none)	—	FargvCountSwitch	—	-vvvv	FargvInt(is_count_switch=True); counts repeated short flags

Notes

Two-element tuple (default, "description")

When a tuple has exactly two elements and the second is a str, fargv interprets it as (default_value, "help text") — not as a choice. Use three or more elements for a choice parameter:

# WRONG — treated as (default="fast", description="slow"):
{"mode": ("fast", "slow")}

# CORRECT — three-element choice:
{"mode": ("fast", "slow", "medium")}

# Attaching help text to a non-choice:
{"lr": (0.001, "Learning rate")}

FargvStr — cross-parameter interpolation

String parameters support {key} references to other string parameters. Resolution is lazy (evaluated when .value is read) and recursive:

from fargv import parse
p, _ = parse({"base": "/tmp/run", "out": "{base}/predictions"})
# --base=/data  →  p.out == "/data/predictions"

FargvChoice

The first element of the list / tuple is the default. All elements must be strings. Passing a value not in the list raises FargvError.

from fargv.parameters import FargvChoice
FargvChoice(["adam", "sgd", "rmsprop"], name="opt")
# --opt=sgd  →  "sgd"
# --opt=lion  →  FargvError

FargvPositional

At most one positional parameter is supported per parser. All tokens that do not start with the long or short prefix are routed to it.

from fargv import parse
p, _ = parse({"files": [], "count": 0})
# prog --count=2 a.txt b.txt  →  p.files == ["a.txt", "b.txt"]

FargvSubcommand — nested sub-parsers

Mirrors git-style subcommands. The value is always a dict: {"name": "<subcommand>", "result": {<sub-namespace>}}.

With subcommand_return_type="flat" (default), the result is merged into the top-level namespace and the subcommand key holds the selected name:

from fargv import parse
p, _ = parse(
    {"cmd": {"train": {"lr": 0.01}, "eval": {"dataset": "val"}}},
    given_parameters=["prog", "train", "--lr=0.5"],
)
# p.cmd == "train",  p.lr == 0.5

FargvStream — text I/O streams

Accepts a file path, or the keywords stdin / stdout / stderr. The stream mode (r / w / a) is determined by the default value: sys.stdin → r, sys.stdout/sys.stderr → w.

from fargv.parameters import FargvOutputStream
out = FargvOutputStream(name="out")
# --out=results.txt  →  open("results.txt", "w")
# --out=stdout       →  sys.stdout

FargvPath hierarchy

FargvPath                       (pathlib.Path, no validation)
├── FargvExistingFile           (must_exist=True)
├── FargvNonExistingFile        (must_not_exist=True)
└── FargvFile                   (parent_must_exist=True)

FargvTuple — typed fixed-length tuples

Parsed from a single string using ast.literal_eval. Single-element shorthand: "224" → (224,) for element_types=(int,). Optional tuples: "()" → None when optional=True.

from fargv.parameters import FargvTuple
p = FargvTuple((int, int), name="size")
p.ingest_value_strings("(640, 480)")
# p.value == (640, 480)

Type annotations in function signatures are also supported:

from typing import Tuple, Optional
from fargv import parse

def train(lr: float = 0.01, size: Tuple[int, int] = (224, 224)):
    ...

p, _ = parse(train)

FargvInt as a count switch

Set is_count_switch=True to count repeated short flags:

from fargv.parameters import FargvInt
v = FargvInt(0, name="verbosity", short_name="v", is_count_switch=True)
# -vvvv          →  4
# --verbosity=3  →  3