API reference

The public entry points. The metaprogramming core (generated classes, descriptors) is intentionally dynamic; type[SchemaBase] and the XMLNode XMLNode protocol are the stable seams.

class pyxsd.PyXSD(xmlFileInput, xsdFile=None, xmlFileOutput=False, transformOutputName=None, transforms=None, classFile=None, verbose=False, quiet=False, mode=BindingPolicy(invalid_value='drop', unresolved_type='error', undeclared_content='error', whitespace='xsd', namespaces='legacy'), namespace_schemas=None)

Main class of the program that is in charge of data flow.

Has command line support when it is called as a script.

Parameters:

• xmlFileInput (Path | IO[str])

• xsdFile (str | Path | PathLike[str] | None)

• xmlFileOutput (str | Path | bool)

• transformOutputName (str | None)

• transforms (list[str] | None)

• classFile (str | Path | PathLike[str] | None)

• verbose (bool)

• quiet (bool)

• mode (BindingPolicy)

• namespace_schemas (dict[str, str | Path] | None)

xmlFileInput: Path | IO[str]

xmlPath: Path

xmlFileInputName: str | None

xmlFileOutput: str | Path | bool

xsdFile: str | Path | PathLike[str] | None

schemaRootInstance: Any

executeAndWriteTransforms(rootInstance)

Runs each transform in order and writes the transformed tree to the transform output, if one was requested.

Parameters:

rootInstance (Any)

Return type:

None

parseXSD()

Reads the given xsd file and creates a set of classes that correspond to the complex and simple type definitions.

Return type:

None

parseXML()

Reads the given xml file in the context of the xsd file.

Produces instances of the above classes. Does validation. Returns a schema instance object.

Return type:

Any

generateCorrectSchemaTags()

Generates the proper schema information and namespace information for a tag.

ElementTree leaves the schema information in a form that is not valid XML on its own.

Return type:

None

writeParsedXMLFile(rootInstance)

Writes the parsed (pre-transform) xml file, if requested.

Parameters:

rootInstance (Any)

Return type:

Any

writeXML(rootInstance, output)

Sends a pythonic instance tree to the tree writer.

• rootInstance: the root instance of a tree. Must be formatted in the program’s tree structure.

• output: the file object (or path) to write the tree to. Paths are opened and closed here; file objects passed by the caller are flushed but left open.

Parameters:

• rootInstance (Any)

• output (str | Path | PathLike[str] | IO[str])

Return type:

None

getClasses()

Returns the dictionary of classes created by ElementRepresentative for each type specified in the schema.

Return type:

dict[str, type[SchemaBase]]

loadClassFromFile(classFile)

Loads a file with overlay classes into the class dictionary.

Overlay classes add to and override the schema type classes to allow for a user to create their own types without changing the schema file itself.

Consider this functionality experimental.

• classFile: a string that specifies the location of a user-created overlay class file

Parameters:

classFile (str | Path | PathLike[str])

Return type:

None

getXmlTree()

Sends the xml file into the ElementTree library’s parser.

Allows for the program to get the schemaLocation before parsing the xml against the schema.

Return type:

Any

getXmlOutputFileName()

Creates a default name for the xml file that is parsed without any transforms. Uses the name from the input xml file.

Return type:

Path

getTransformModuleAndLoad(className)

Loads a transform class from its class name.

The module it is located in must share the class name, either in camelCase with a lowercase first letter (the historical convention) or in snake_case. The transform is looked up in the installed pyxsd.transforms package, then in the directory the program was called from, and then in the directory where the xml file is. If no exact module-name candidate matches, an underscore-insensitive fallback matches the class name against the available modules, so acronym spellings (SendTreeToPyXSD -> send_tree_to_pyxsd) still resolve.

• className: a string of the transform class name being called

Parameters:

className (str)

Return type:

ModuleType

transform(transforms, root)

Calls the transforms specified by the user.

Each transform is loaded into memory by getTransformModuleAndLoad(). The transform class is passed the instance of the root element when it is initialized. The transform object is called with the specified arguments and the new root instance is set to whatever the transform returns, which is usually the root, but it is not required. Any user who uses a transform that does not return the root tree instance should be aware that any transform that uses the root instance will fail to work and raise a fatal error.

• transforms: a list containing the transform calls in the order that they should be called. Each call looks like TransformClass(arg1, arg2, key=value).

• root: the root instance of a tree. Must be formatted in the program’s tree structure.

Parameters:

• transforms (list[str])

• root (Any)

Return type:

Any

getTransformsFileName()

Creates a default name for the xml file that is written after all of the transforms. Uses the name from the input xml file.

Return type:

Path

getSchemaInfo(nameOrLocation)

Extracts information from the schemaLocation tag or the noNamespaceSchemaLocation tag.

Depending on the value of the parameter nameOrLocation, the function outputs the namespace, the schema location, or the tag type. This function is meant for use with other functions to easily grab bits of data that are used in various locations in the program.

• nameOrLocation: a one letter string that is either ‘l’, ‘n’, or ‘t’. If the variable is ‘l’, the location of the schema is returned. If it is ‘n’, the namespace is returned, if there is one. ‘t’ returns the tag name to indicate if the xml uses schemaLocation or noNamespaceSchemaLocation.

Parameters:

nameOrLocation (str | None)

Return type:

str | None

getSchemaLocationPairs()

Returns every (namespace, location) hint in the instance.

xsi:schemaLocation may carry multiple namespace/location pairs; xsi:noNamespaceSchemaLocation yields a single pair with None for the namespace.

Return type:

list[tuple[str | None, str]]

makeFullName(ns, text)

Makes a string that looks similar to some of the names in ElementTree when it contains namespace information.

• ns: a string of the namespace used. For this function, this variable is usually set to a url.

• text: a string of the name of the tag that the full name is being created for.

Parameters:

• ns (str | None)

• text (str)

Return type:

str

class pyxsd.exceptions.PyXSDError

Raised when parsing cannot proceed.

class pyxsd.exceptions.PyXSDWarning

Warning category for recoverable, non-fatal conditions.

class pyxsd.nodes.XMLNode(*args, **kwargs)

Structural type of one node in a parsed instance tree.

Both the generated schema classes and the synthetic nodes built by Transform.makeElemObj satisfy this protocol:

• _name_: the element’s tag name.

• _attribs_: attribute names mapped to their lexical values.

• _children_: child nodes in document order (a child may be None when an optional element is absent).

• _value_: the element’s text split on line boundaries, or None when it has none.

The ValidationReport/ValidationIssue classes are documented in Validation (detailed reference) rather than duplicated here.

Transforms

See The Transform class for the Transform/Displayer class reference, iter_tree, and the built-ins.