API for command line tools¶

pynxtools provides a unified pynx entry point with subcommands for all CLI operations. This page documents the current API.

The legacy entry points (dataconverter, validate_nexus, read_nexus, generate_eln) are still installed as deprecated aliases — they continue to work but emit a deprecation warning.

Data conversion¶

pynx convert¶

Convert input files to a NeXus HDF5 file.

Usage:

pynx convert [OPTIONS] [FILES]...

Options:

Name	Type	Description	Default
`--input-file`	text	Deprecated: Please use the positional file arguments instead. The path to the input data file to read. Repeat for more than one file. default=[] This option is required if no '--params-file' is supplied.	`[]`
`--reader`	choice (`example` \| `json_map` \| `json_yml` \| `multi`)	The reader to use. Examples are json_map or readers from a pynxtools plugin. default='json_map' This option is required if no '--params-file' is supplied.	`json_map`
`--nxdl`	text	The name of the NeXus application definition file to use without the extension nxdl.xml. This option is required if no '--params-file' is supplied.	None
`--output`	text	The path to the output NeXus file to be generated. default='output.nxs'	`output.nxs`
`--params-file`	filename	Allows to pass a .yaml file with all the parameters the converter supports.	None
`--append`	boolean	Appends instance data to the given file if the file already exists.Will prevent an overwriting of existent data and adding of new NXentry instances.If True, will skip the validation whatever irrespective if --skip-verify is passed.	`False`
`--ignore-undocumented`	boolean	Ignore all undocumented concepts during validation.	`False`
`--fail`	boolean	Fail conversion and don't create an output file if the validation fails.	`False`
`--skip-verify`	boolean	Skips the verification routine during conversion. When --append is used the verification is always skipped irrespective if --skip-verify is used or not.	`False`
`--mapping`	text	Takes a .mapping.json file and converts data from given input files. Deprecated. Will be removed in a future release. The --config flag can be used instead.	`Sentinel.UNSET`
`-c`, `--config`	file	A json config file for the reader	None
`--help`	boolean	Show this message and exit.	`False`

Sub-commands¶

pynx convert¶

Convert data to NeXus.

Usage:

pynx convert [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

Subcommands

generate-template: Print a conversion template for a NeXus application definition.
get-readers: List all installed readers.
reader-info: Show supported NXDLs and file extensions for a reader.
run: Convert input files to a NeXus HDF5 file.

pynx convert generate-template¶

Print a conversion template for a NeXus application definition.

NXDL: application definition name, e.g. NXmpes

Usage:

pynx convert generate-template [OPTIONS] NXDL

Options:

Name	Type	Description	Default
`--required`	boolean	Include only required fields.	`False`
`--pythonic`	boolean	Print a Python dict instead of JSON.	`False`
`--output`	path	Write output to this file instead of stdout.	`Sentinel.UNSET`
`--help`	boolean	Show this message and exit.	`False`

pynx convert get-readers¶

List all installed readers.

Usage:

pynx convert get-readers [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

pynx convert reader-info¶

Show supported NXDLs and file extensions for a reader.

READER: name of the reader to inspect, e.g. json_map

Usage:

pynx convert reader-info [OPTIONS] {example|json_map|json_yml|multi}

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

pynx convert run¶

Convert input files to a NeXus HDF5 file.

Usage:

pynx convert run [OPTIONS] [FILES]...

Options:

Name	Type	Description	Default
`--input-file`	text	Deprecated: Please use the positional file arguments instead. The path to the input data file to read. Repeat for more than one file. default=[] This option is required if no '--params-file' is supplied.	`[]`
`--reader`	choice (`example` \| `json_map` \| `json_yml` \| `multi`)	The reader to use. Examples are json_map or readers from a pynxtools plugin. default='json_map' This option is required if no '--params-file' is supplied.	`json_map`
`--nxdl`	text	The name of the NeXus application definition file to use without the extension nxdl.xml. This option is required if no '--params-file' is supplied.	None
`--output`	text	The path to the output NeXus file to be generated. default='output.nxs'	`output.nxs`
`--params-file`	filename	Allows to pass a .yaml file with all the parameters the converter supports.	None
`--append`	boolean	Appends instance data to the given file if the file already exists.Will prevent an overwriting of existent data and adding of new NXentry instances.If True, will skip the validation whatever irrespective if --skip-verify is passed.	`False`
`--ignore-undocumented`	boolean	Ignore all undocumented concepts during validation.	`False`
`--fail`	boolean	Fail conversion and don't create an output file if the validation fails.	`False`
`--skip-verify`	boolean	Skips the verification routine during conversion. When --append is used the verification is always skipped irrespective if --skip-verify is used or not.	`False`
`--mapping`	text	Takes a .mapping.json file and converts data from given input files. Deprecated. Will be removed in a future release. The --config flag can be used instead.	`Sentinel.UNSET`
`-c`, `--config`	file	A json config file for the reader	None
`--help`	boolean	Show this message and exit.	`False`

Info

Note that simply calling pynx convert defaults to pynx convert run.

NeXus file validation¶

pynx validate¶

Validate a NeXus HDF5 file against its application definition.

Usage:

pynx validate [OPTIONS] FILE

Options:

Name	Type	Description	Default
`--ignore-undocumented`	boolean	Ignore all undocumented concepts during validation.	`False`
`--help`	boolean	Show this message and exit.	`False`

NeXus annotator¶

pynx read¶

Annotate each group, field, and attribute in a NeXus/HDF5 file with the matching NXDL concept path, optionality, and documentation string.

Without options, the full annotation log for the file is printed. Use -d to restrict output to a single HDF5 path, or -c to find all instances in the file that correspond to a given NXDL concept path.

Usage:

pynx read [OPTIONS] NEXUS_FILE

Options:

Name	Type	Description	Default
`-d`, `--documentation`	text	Definition path in nexus output (.nxs) file. Returns debug log relevant with that definition path. Example input: /entry/data/delays	None
`-c`, `--concept`	text	Concept path from application definition file (.nxdl.xml). Finds out all the available concept definition (IS-A relation) for a given concept path. Example input: /NXarpes/ENTRY/INSTRUMENT/analyser	None
`--help`	boolean	Show this message and exit.	`False`

ELN generation¶

pynx generate-eln¶

Generate an ELN YAML scaffold for a NeXus application definition.

NXDL: application definition name, e.g. NXmpes

Usage:

pynx generate-eln [OPTIONS] NXDL

Options:

Name	Type	Description	Default
`--skip-top-levels`	integer	To skip the level of parent hierarchy level. For example, by default the part Entry[ENTRY] from /Entry[ENTRY]/Instrument[INSTRUMENT]/... will be skipped.	`0`
`--output-file`	text	Name of file that is needed to generated output file.	None
`--eln-type`	choice (`reader` \| `schema`)	Choose a type of ELN output (reader or schema).	`eln`
`--optionality`	choice (`required` \| `recommended` \| `optional`)	Level of requiredness to generate. If any of ('required', 'recommended', 'optional', only those concepts matching this requiredness level are created.	`required`
`--filter-file`	text	JSON configuration file to filter NeXus concepts (based on the presence of the '@eln' keyword). This is a positive filter, i.e., all concepts in the filter file will be included in the ELN.	None
`--help`	boolean	Show this message and exit.	`False`

Application definition inspector¶

pynx inspect-appdef¶

List the concept paths defined in a NeXus application definition.

Prints all paths at or above the requested optionality level (required, recommended, or optional). Useful for understanding what data must be provided before converting with pynx convert, or as a lightweight alternative to pynx convert generate-template when you only need the field names rather than a fillable JSON skeleton.

NXDL: application definition name, e.g. NXmpes

Usage:

pynx inspect-appdef [OPTIONS] NXDL

Options:

Name	Type	Description	Default
`--level`	choice (`required` \| `recommended` \| `optional`)	Minimum optionality level to include.	`required`
`--help`	boolean	Show this message and exit.	`False`