class weldx.WeldxFile(filename_or_file_like=None, mode='r', asdffile_kwargs=None, write_kwargs=None, tree=None, sync=True, custom_schema=None, software_history_entry=None, compression='input', copy_arrays=True, array_inline_threshold=10)#

Expose an ASDF file as a dictionary like object and handle underlying files.

The WeldxFile class makes it easy to work with ASDF files. Creating, validating, and updating data is handled by just treating the WeldxFile object as a dictionary. Every piece of data is accessible via a key, while the keys should be strings, the data can be any Python object.

Creation is being done by just creating a WeldxFile with or without a filename. Operation without filenames is of course non-persitant, meaning that your changes will be lost upon the end of your Python session.

You can decide, whether you want to open your file with read-only (default) or read and write mode. This is mainly a safety precaution, in order not to overwrite or manipulate existing data by accident.

For a brief introduction into the features of this class, please have a look at the tutorial or the examples given here.

  • filename_or_file_like – A path to a weldx file or file handle like to read/write data from. If None is passed, an in-memory file will be created.

  • mode – Reading or reading/writing mode: “r” or “rw”.

  • asdffile_kwargs – Keyword arguments to pass to asdf.open. See asdf.open for reference.

  • write_kwargs – Keyword arguments to pass to asdf.AsdfFile.write_to. See asdf.AsdfFile.open for reference.

  • tree – An optional dictionary to write to the file.

  • sync – If True, the changes to file will be written upon closing this. This is only relevant, if the file has been opened in write mode.

  • custom_schema

    Either a path-like object to a custom schema which validates the tree or a tuple of these objects. This tuple is allowed of lengths two and the first element will be used to validate the file contents upon reading, the second upon writing. For example:

    (None, “A”)

    will not run validation upon reading, but for writing will use “A”. Likewise

    (“A”, “B”)

    will use schema “A” to validate after reading, and “B” for writing again.

    Note that all schemas provided by weldx can be given by name as well.

  • software_history_entry – An optional dictionary which will be used to add history entries upon modification of the file. It has to provide the following keys: “name”, “author”, “homepage”, “version” These should be set to string typed values. The homepage should be a URL.

  • compression

    If provided, set the compression type on all binary blocks in the file. Must be one of:

    • '' or None: No compression.

    • zlib: Use zlib compression.

    • bzp2: Use bzip2 compression.

    • lz4: Use lz4 compression.

    • input: Use the same compression as in the file read. If there is no prior file, acts as None.

  • copy_arrays – When False, when reading files, attempt to memory map (memmap) underlying data arrays when possible. This avoids blowing the memory when working with very large datasets.

  • array_inline_threshold – arrays below this threshold will be serialized as string, if larger as binary block. Note that this does not affect arrays, which are being shared across several objects in the same file.


We define a simple data set and store it in a WeldxFile.

>>> data = {"name": "CXCOMP", "value": 42}
>>> wx = WeldxFile(tree=data, mode="rw")

If we want to persist the WeldxFile to a file on hard drive we invoke:

>>> wx2 = WeldxFile("output.wx", tree=data, mode="rw")

Or we can store the previously created file to disk:

>>> wx.write_to("output2.wx")

If we omit the filename, we receive an in-memory file. This is useful to create quick copies without the need for physical files.

>>> wx.write_to()  
<_io.BytesIO object at 0x...>

We can also read a data set from disk and manipulate it in a dictionary like manner.

>>> with WeldxFile("output.wx", mode="rw") as wx:
...    wx["name"] = "changed"

If a file name is omitted, we operate only in memory.

We can have a look at the serialized data by looking at the asdf header

>>> wx2.header()  
#ASDF 1.0.0
%YAML 1.1
%TAG ! tag:stsci.edu:asdf/
--- !core/asdf-1.1.0
asdf_library: !core/software-1.0.0 {...
  name: asdf, version: ...}
  - !core/extension_metadata-1.0.0
    extension_class: asdf.extension.BuiltinExtension
    software: !core/software-1.0.0 {name: asdf, version: ...}
name: CXCOMP
value: 42



Add an history_entry to the file.


Return the Weldx dictionary as an attributed object.


Clear all data except the protected keys.


Close this file and sync it, if mode is read/write.


Take a copy of this file.


Create a new file with keys from iterable and values set to value.


Get data attached to given key from file.


Show the header of the ASDF serialization.


Print the content to the stdout.


Return a set-like object providing a view on this file's items.


Return a set of keys/attributes stored in this file.


Get and remove the given key from the file.


Remove the item that was last inserted into the file.


Set a default for given key.



Update the file on disk in place.


Update this file from mapping or iterable mapping and kwargs.


Return a view list like object of the file content.


Write current contents to given file name or file type.



Get version information about the ASDF library lastly modifying this file.


Return schema used to validate the structure and types of the tree.


Return the underlying file handle, use with CARE.


Return a list of all history entries in this file.


Is the underlying file an in-memory buffer.


File operation mode.


History entries will use this software.