weldx.WeldxFile

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.

Parameters:

• filename_or_file_like (types_path_like | types_file_like | None) – 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 (str) – Reading or reading/writing mode: “r” or “rw”.

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

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

• tree (Mapping) – An optional dictionary to write to the file.

• sync (bool) – 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 (None | (types_path_like, tuple[None, types_path_like])) –

  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 (Mapping) – 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 (str) –

  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 (bool) – 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 (int) – 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.

Examples

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")
'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
#ASDF_STANDARD 1.5.0
%YAML 1.1
%TAG ! tag:stsci.edu:asdf/
--- !core/asdf-1.1.0
asdf_library: !core/software-1.0.0 ...
history:
  extensions:
  ...
name: CXCOMP
value: 42

Methods

add_history_entry	Add an history_entry to the file.
as_attr	Return the Weldx dictionary as an attributed object.
clear	Clear all data except the protected keys.
close	Close this file and sync it, if mode is read/write.
copy	Take a copy of this file.
fromkeys	Create a new file with keys from iterable and values set to value.
get	Get data attached to given key from file.
header	Show the header of the ASDF serialization.
info	Print the content to the stdout.
items	Return a set-like object providing a view on this file's items.
keys	Return a set of keys/attributes stored in this file.
pop	Get and remove the given key from the file.
popitem	Remove the item that was last inserted into the file.
setdefault	Set a default for given key.
show_asdf_header
sync	Update the file on disk in place.
update	Update this file from mapping or iterable mapping and kwargs.
values	Return a view list like object of the file content.
write_to	Write current contents to given file name or file type.

Attributes

asdf_library	Get version information about the ASDF library lastly modifying this file.
custom_schema	Return schema used to validate the structure and types of the tree.
file_handle	Return the underlying file handle, use with CARE.
history	Return a list of all history entries in this file.
in_memory	Is the underlying file an in-memory buffer.
mode	File operation mode.
software_history_entry	History entries will use this software.