getting_started.md

layout	default
title	Getting started
nav_order	2

Getting started

VCoder gives you validated input prompts and honest security helpers behind a single facade, vc.

from vcoder import vc

The prompt contract

Every input function shares the same keywords:

Keyword	Meaning
default	Value returned when the user submits an empty line. Omit for "required".
optional	If True and there is no default, empty input returns None.
retries	Maximum attempts before RetryLimitExceeded. Defaults to the global config (3).
error_message	Custom message shown to the user on any failure.
validators	Extra Validator objects or plain callables applied after conversion.
reader	A callable used to read input. Defaults to the terminal; injectable for tests.

On a validation failure the prompt prints Error: <message> to stderr and reprompts, until it succeeds or exhausts retries.

age = vc.int("Age: ", min=0, max=120)
# Age: -4
# Error: must be >= 0
# Age: 31
# -> 31

Defaults and optional input

vc.text("Name: ", default="anonymous")   # empty input -> "anonymous"
vc.text("Nickname: ", optional=True)     # empty input -> None

Testing prompts (the reader keyword)

Because prompts read from stdin, VCoder lets you inject a reader — a function that takes the prompt string and returns the "typed" line:

assert vc.int("Age: ", min=0, reader=lambda _: "30") == 30

A reader that raises StopIteration/EOFError simulates end-of-input. The test suite includes scripted_reader(...) to simulate a user who mistypes first.

Custom validators on any prompt

from vcoder import vc, Blacklist

vc.text("Username: ", validators=[Blacklist({"root", "admin"})])

Custom error messages

vc.int("Age: ", min=0, max=120, error_message="Enter an age between 0 and 120.")

Global configuration

vc.configure(
    retries=5,      # reprompt up to 5 times
    strip=True,     # strip whitespace from raw input (default True)
    lowercase=False,
    logging=True,   # emit info logs (never logs secrets)
)

Configuration is process-global but every default can be overridden per call, so nothing depends on hidden state. For a temporary change use the context manager:

from vcoder import config_scope

with config_scope(retries=1):
    ...

Next steps

• Validators guide — build and compose validators.
• Security guide — paths, subprocess, SQL, HTML, passwords.
• API reference — every public symbol.