Configuration¶

The command line tool includes most but not all available options. The most advanced settings can be enabled through a project configuration file.

Create or Update¶

You can create a default one with the command:

```console exec="1" source="console" $ pyxsdata init-config --help

**Output:** `.pyxsdata.xml `

```python exec="true" result="xml"
from io import StringIO
from pyxsdata.models.config import GeneratorConfig

config = GeneratorConfig.create()
output = StringIO()
config.write(output, config)
print(output.getvalue())

Usage

$ pyxsdata generate --config project/.pyxsdata.xml

Output Settings¶

Configuration settings related to output generation.

maxLineLength¶

The maximum line length of the generated code.

Default Value: 79

CLI Option: -mll, --max-line-length INTEGER

genericCollections¶

Use collections.abc.Iterable and collections.abc.Mapping instead of List|Tuple and Dict

Default Value: False

CLI Option: --generic-collections / --no-generic-collections

Package¶

The output package for the generated code, e.g. code.models

Default Value: generated

CLI Option: -p, --package TEXT

Format¶

The output format for the generated code, e.g. code.models

Default Value: dataclasses

CLI Option: -o, --output TEXT

Attributes

The [dataclass][dataclasses.dataclass] parameters.

• repr: Generate the [repr][object.repr] method.
• eq: Generate the [eq][object.eq] method.
• order: Generates the [lt][object.lt], [le][object.le], [gt][object.gt], [ge][object.ge] methods.
• frozen: This emulates read-only frozen instances.
• unsafeHash: Generates a [hash][object.hash] method according to how eq and frozen are set.
• slots: Generates the class [slots][object.slots] attribute. python >= 3.10

Structure¶

The file structure style to create.

Default Value: filenames

CLI Option: -ss, --structure-style [filenames|namespaces|clusters|single-package|namespace-clusters]

DocstringStyle¶

The style of docstrings to create.

Default Value: reStructuredText

CLI Option: -ds, --docstring-style [reStructuredText|NumPy|Google|Accessible|Blank]

RelativeImports¶

Generate relative instead of absolute imports.

Default Value: False

CLI Option: --relative-imports / --no-relative-imports

CompoundFields¶

pyxsdata relies on the field ordering for serialization. This process fails for repeating choice or complex sequence elements. When you enable compound fields, these elements are grouped into a single field.

    <xsd:element name="root">
        <xsd:complexType>
            <xsd:choice maxOccurs="unbounded">
                <xsd:element ref="alpha"/>
                <xsd:element ref="bravo"/>
                <xsd:element name="charlie" type="charlie"/>
            </xsd:choice>
        </xsd:complexType>
    </xsd:element>

Default Value: False

CLI Option: --compound-fields / --no-compound-fields

Sub Settings

• defaultName: The default compound field name, default: choice
• forceDefaultName: Force the default name in all compound fields, default: False
• useSubstitutionGroups: When all elements are part of a substitution, use the group name as the field name, default: False
• maxNameParts: The maximum length of elements names allowed before using the default name, default: 3

Examples:

# Force default name or max name parts > 3
choice: list[str | int | float | bool] = field(...)

# max name parts <= 3
hat_or_bat_cat: list[str | int | float] = field(...)

# All types belong to the same substitution group `product`
product: list[Shoe | Shirt | Hat] = field(...)

WrapperFields¶

Generate wrapper fields whenever possible for single or collections of simple and complex elements.

The wrapper and wrapped elements can't be optional. If the wrapped value is a list it must have minimum occurs >= 1.

    <xsd:element name="wrapper">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element ref="xd:alphas"/>
                <xsd:element ref="xd:bravos"/>
                <xsd:element ref="xd:charlies"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element name="alphas">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="alpha" type="xsd:string"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>

Default Value: False

CLI Option: --wrapper-fields / --no-wrapper-fields

Examples:

alpha: str = field(
    metadata={
        "wrapper": "alphas",
        "type": "Element",
    },
)
bravo: List[int] = field(
    default_factory=list,
    metadata={
        "wrapper": "bravos",
        "type": "Element",
    },
)
charlie: List[Charlie] = field(
    default_factory=list,
    metadata={
        "wrapper": "charlies",
        "type": "Element",
    },
)

UnnestClasses¶

The generator creates inner classes for xs:complexContent. This option allows to unnest all inner classes.

Default Value: False

CLI Option: --unnest-classes / --no-unnest-classes

IgnorePatterns¶

The generator will create a field metadata property for xs:pattern elements. This property is not used during parsing, it's only informative for the developer, if you want to reduce the noise in the generated code you can enable this option.

Default Value: False

CLI Option: --ignore-patterns / --no-ignore-patterns

IncludeHeader¶

The generator will add a module docstring in all the output files.

Example

"""This file was generated by pyxsdata, v0.0.0, on 2026-03-01 10:20:25

Generator: DataclassGenerator
See: https://nth-bailey.github.io/pyxsdata/
"""

Default Value: False

CLI Option: --include-header / --no-include-header

StrEnums¶

Generate StrEnum instead of standard Enum for string-based enumerations (Python >= 3.11).

Default Value: False

CLI Option: --str-enums / --no-str-enums

Convention Settings¶

Apply different naming convention per identifier.

Attributes

• case: The naming class to apply
• safePrefix: A prefix to add when the output name is reserved

Cases

Substitution Settings¶

A list of search and replace patterns for identifier names, the substitutions run before and after the naming conventions.

Attributes

• type: The identifier type [class|field|module|package]
• search: Search Pattern
• replace: Replace Pattern

Defaults

<Substitutions>
    <Substitution type="package" search="http://www.w3.org/2001/XMLSchema" replace="xs"/>
    <Substitution type="package" search="http://www.w3.org/XML/1998/namespace" replace="xml"/>
    <Substitution type="package" search="http://www.w3.org/2001/XMLSchema-instance" replace="xsi"/>
    <Substitution type="package" search="http://www.w3.org/1998/Math/MathML" replace="mathml3"/>
    <Substitution type="package" search="http://www.w3.org/1999/xlink" replace="xlink"/>
    <Substitution type="package" search="http://www.w3.org/1999/xhtml" replace="xhtml"/>
    <Substitution type="package" search="http://schemas.xmlsoap.org/wsdl/soap/" replace="soap"/>
    <Substitution type="package" search="http://schemas.xmlsoap.org/wsdl/soap12/" replace="soap12"/>
    <Substitution type="package" search="http://schemas.xmlsoap.org/soap/envelope/" replace="soapenv"/>
    <Substitution type="class" search="(.*)Class$" replace="\1Type"/>
</Substitutions>

Extension Settings¶

Though extensions you can add base classes, mixins or decorators to the generated classes. This way you can enhance the models functionality and add any custom business logic.

The following configuration will add a base class and a decorator to all the generated classes.

Attributes

• type: The extension type [class|decorator]
• class: The class name search pattern
• import: The absolute import of the base class or decorator object
• prepend Specify if you want the base class or decorator to added before all other
• apply_if_derived Specify if you want to add the extension if the class already extends another class.
• module Optional pattern to match against the fully-qualified parent element's name

Example:

<Extensions>
    <Extension type="class" class=".*" import="dataclasses_jsonschema.JsonSchemaMixin" prepend="false" applyIfDerived="false"/>
    <Extension type="decorator" class=".*" module="Ancestor\..*\.Papa$" import="typed_dataclass.typed_dataclass" prepend="false" applyIfDerived="false"/>
</Extensions>

from dataclasses import dataclass
from dataclasses_jsonschema import JsonSchemaMixin
from typed_dataclass import typed_dataclass

@dataclass
@typed_dataclass
class Cores(JsonSchemaMixin):
    ...