Make safe input handling effortless.
VCoder is a zero-dependency Python library for validated input prompts, composable validators, and honest security helpers. It does not claim to magically sanitize all input or to "prevent injection". Instead, it makes the safe path the easy path.
from vcoder import vc
name = vc.text("Name: ")
age = vc.int("Age: ", min=0, max=120)
email = vc.email("Email: ")
password = vc.password("Password: ", min_length=12)
choice = vc.choice("Language: ", ["Python", "Rust", "Go"])
numbers = vc.list("Numbers: ", parser=int)Every prompt validates, reprompts on failure, supports defaults and optional input, accepts custom validators and custom error messages — so you never write a validation loop by hand.
- Pythonic & discoverable. One import (
vc) surfaces everything. - Strongly typed. Fully annotated; passes
mypy --strictandpyright. - Zero dependencies. Standard library only.
- Composable validators.
Validator(MinLength(8), Regex(...), NoControlCharacters()). - Honest security helpers. For paths, filenames, shell, SQL, HTML and passwords — with documented limitations, never misleading guarantees.
pip install vcoderFrom source (development):
git clone https://github.com/bitilia/vcoder
cd vcoder
pip install -e ".[dev]"Requires Python 3.9+.
from vcoder import vc
vc.text("Name: ", min_length=1)
vc.int("Age: ", min=0, max=120)
vc.float("Ratio: ", min=0.0, max=1.0)
vc.decimal("Price: ") # exact, for money
vc.bool("Continue? ") # yes/no
vc.choice("Pick: ", ["a", "b", "c"])
vc.list("CSV: ", parser=int)
vc.json("Payload: ")
vc.date("When: ") # ISO 8601 by default
vc.uuid("Id: ")
vc.email("Email: ")
vc.url("Site: ") # http/https only by default
vc.ip("Addr: ")
vc.port("Port: ")
vc.password("Password: ", min_length=12) # never echoed, never logged
vc.filename("File: ") # rejects reserved/illegal names
vc.path("Path: ", within="/srv/uploads") # blocks traversalAll 26 input types accept the same keyword contract:
default, optional, retries, error_message, validators, reader.
The
reader=keyword lets you inject input (used throughout the tests and in the doctests). In real use you omit it and VCoder reads from the terminal.
from vcoder import Validator, MinLength, Regex, NoControlCharacters, ValidationError
username = Validator(
MinLength(3),
Regex(r"[a-z0-9_]+"),
NoControlCharacters(),
)
username.validate("ada_lovelace") # ok
username.is_valid("x") # False
# Extending is just subclassing:
class EvenNumber(Validator):
def validate(self, value):
if value % 2:
raise ValidationError("must be even", value=value)Use any validator with any prompt via validators=[...].
from vcoder import vc
# Paths — anchored to a root, traversal-aware (raw, %2e-encoded, unicode).
vc.safe_join("/srv/uploads", user_supplied) # -> Path or UnsafePathError
vc.contains_traversal("../../etc/passwd") # True
# Subprocess — argument lists only, never a shell.
vc.run(["git", "status"])
vc.run_capture(["echo", user_supplied]) # metacharacters are inert
# SQL — parameterized by construction.
query, params = vc.sql.build_select("users", where={"id": 1})
vc.sql.execute(cursor, query, params)
# HTML — context-aware escaping.
vc.html.escape(user_supplied) # for text nodes
vc.html.escape_attribute(user_supplied) # for quoted attributes
# Passwords — configurable strength, optional HIBP check.
vc.validate_password(pw) # PasswordTooWeak on failurefrom vcoder import vc
vc.configure(retries=5, strip=True, lowercase=False, logging=True)See SECURITY.md for the full, honest breakdown. In short:
- It reduces the risk of path traversal, shell injection, accidental SQL string-building, XSS from untrusted text, and weak passwords.
- It cannot guarantee the absence of any of these. Validation is context-dependent, symlinks and TOCTOU races exist, and the program you invoke may still mishandle its arguments. Use least privilege and defense in depth.
pip install -e ".[dev]"
pytest # tests + doctests, 95%+ coverage
mypy # strict type checking
ruff check . # linting
black --check . # formattingMIT © 2026 VCoder contributors.