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 – 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.

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 {...
  name: asdf, version: ...}
history:
  extensions:
  - !core/extension_metadata-1.0.0
    extension_class: asdf.extension.BuiltinExtension
    software: !core/software-1.0.0 {name: asdf, version: ...}
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.