Command-line reference¶

pyxsd [options]

pyxsd is the console script installed by the package (equivalent to python -m pyxsd).

Flags¶

Flag	Long form(s)	Meaning
`--version`		Print the version and exit.
`-i FILE`	`--inputXml`	Filename of the XML document to read in. Reads from stdin by default.
`-s FILE`	`--inputXsd`, `--schema`	Filename of the XSD schema. By default pyxsd tries to determine the location from the instance document (schema hints).
`-p FILE`	`--parsedXml`, `--parsedOutput`	Filename for the parsed (pre-transform) output. Default: input filename + `Parsed`.
`-k`	`--ParsedFile`	Write the parsed tree even when transforms are given. Off by default.
`-o FILE`	`--transformOutput`	Output after parsing and transforming. stdout by default. `stdout` may also be given explicitly as the value.
`-d`	`--useDefaultFile`	Use the default filename for transformed output instead of stdout.
`-t CALLS`	`--transform`	Transform call(s): `Class(args...)`, chained with `>` when multiple.
`-T FILE`	`--transformFile`	File with transform calls, one per line. Mutually exclusive with `-t`.
`-c FILE`	`--overlayClassesFile`	Experimental. Overlay class file that extends/overrides generated classes.
`--mode`		Binding mode: `strict` (default) reports invalid values and drops them; `lax` binds best-effort values (raw strings, generic subtrees) so no data is lost. See Parse modes and binding.
`--namespaces`		Namespace handling: `legacy` (default) matches by local name and ignores namespace URIs; `strict` resolves QNames and matches by expanded name. See Parse modes and binding.
`--xsd-version VERSION`		XSD version to process: `1.1` (default) or `1.0`. In `1.0` mode the XSD 1.1-only vocabulary is rejected (`xsd11-construct`) and the 1.0/1.1 semantic differences are applied. See Supported features.
`--emit-stubs [PATH]`		Compile the schema and write a `.pyi` type stub for its generated classes to `PATH` — or to stdout when `PATH` is omitted — then exit without reading any XML input. Requires `-s`. See API reference.
`--stubs-compact`		Emit the compact, agent-oriented stub description instead of the full `.pyi` document. Requires `--emit-stubs`.
`-v`	`--verbose`	Verbose logging (DEBUG).
`-q`	`--quiet`	Quiet logging (CRITICAL). Validation issues are still printed. `-v` and `-q` are mutually exclusive.
`--strict`		Exit with status 1 if the validation report contains errors.

Exit codes¶

0 — run completed (validation issues are non-fatal).
1 — --strict and the report contains errors, or a fatal error occurred (missing schema, unreadable input, malformed schema).
2 — command-line usage error (argparse).

Schema location¶

When -s is omitted, pyxsd reads the instance document first and looks for schema hints — a xsi:noNamespaceSchemaLocation attribute or a xsi:schemaLocation pair — and resolves the schema path relative to the instance file. A malformed hint produces a warning (schema-hint code); no hint at all produces an error unless -s is given.

Type stubs¶

--emit-stubs compiles -s SCHEMA and writes the stub text Schema.stub() returns (see API reference): a full .pyi document by default, the compact agent-oriented description with --stubs-compact. It is a schema-only mode — no instance document is required or read, and no validation report is printed — and the process exits with status 0 right after writing the stub to PATH, or to stdout when PATH is omitted.

-s is required, because there is no instance document to carry a schema hint; leaving it out — or using --stubs-compact without --emit-stubs — is a usage error (exit 2). A schema that cannot be read or fails to compile, or an unwritable PATH, exits 1 with a pyxsd: error: line on stderr. A schema whose report carries non-fatal findings still emits, degrading the affected members to Any, exactly as Schema.stub() does. --strict has no effect in stub mode: no instance document is parsed, so there is no validation report for it to exit on.

The flag composes with every other compilation option — --mode, --namespaces, --xsd-version, and -c/--overlayClassesFile — because stub emission is a schema compile in every other respect. Loading an overlay with -c and regenerating the stub is the extension loop the feature is built around.

# Full .pyi for mypy and IDE use, written to a file
pyxsd --emit-stubs orders.pyi -s orders.xsd

# The same stub on stdout, without an output path
pyxsd --emit-stubs -s orders.xsd

# Compact agent view, including the members of an overlay module
pyxsd --emit-stubs --stubs-compact -s orders.xsd -c overlay.py

For the ORDERS schema of API reference, the full stub reads (abridged):

# Generated by pyxsd 1.2.1 from orders.xsd. Do not edit by hand.
...
from pyxsd.schema_base import SchemaBase
from pyxsd.xsd_data_types import Int, String

class SKU(String):
    ...
    # pattern: \d{3}-[A-Z]{2}

class Item(SchemaBase):
    sku: SKU
    quantity: Int
    note: String | None
    id: String

# bookkeeping name 'orders|complexType'; stub name synthesized
class Orders(SchemaBase):
    item: list[Item]

# Root elements:
orders: type[Orders]

Examples¶

# Round-trip: parse and write the parsed tree back out
pyxsd -i inventory.xml -k -o parsed.xml

# Validate against an explicit schema, strict mode (CI-friendly)
pyxsd -i inventory.xml -s inventory.xsd --strict

# Transform pipeline: both transforms run, final tree to stdout
pyxsd -i inventory.xml -t 'PrintData() > PrintData()'

# Transform calls from a file
pyxsd -i inventory.xml -T transforms.txt

# Validate an XSD 1.0 schema under the 1.0 processor
pyxsd -i inventory.xml -s inventory.xsd --xsd-version 1.0 --strict

# Export the bound tree as JSON (the ToDict transform; a dict result is
# written as JSON to the transform output)
pyxsd -i inventory.xml -t 'ToDict()'