Custom XDATA

The classes XDataUserList and XDataUserDict manage custom user data stored in the XDATA section of a DXF entity. For more information about XDATA see reference section: Extended Data (XDATA)

These classes store only a limited set of data types with fixed group codes and the types are checked by isinstance() so a Vec3 object can not be replaced by a (x, y, z)-tuple:

Group Code

Data Type

1000

str, limited to 255 characters, line breaks "\n" and "\r" are not allowed

1010

Vec3

1040

float

1071

32-bit int, restricted by the DXF standard not by Python!

Strings are limited to 255 characters, line breaks "\n" and "\r" are not allowed.

This classes assume a certain XDATA structure and therefore can not manage arbitrary XDATA!

This classes do not create the required AppID table entry, only the default AppID “EZDXF” exist by default. Setup a new AppID in the AppID table: doc.appids.add("MYAPP").

For usage look at this example at github or go to the tutorial: Storing Custom Data in DXF Files.

See also

XDataUserList

class ezdxf.entities.xdata.XDataUserList

Manage user data as a named list-like object in XDATA. Multiple user lists with different names can be stored in a single XData instance for a single AppID.

Recommended usage by context manager entity():

with XDataUserList.entity(entity, name="MyList", appid="MYAPP") as ul:
    ul.append("The value of PI")  # str "\n" and "\r" are not allowed
    ul.append(3.141592)  # float
    ul.append(1) # int
    ul.append(Vec3(1, 2, 3)) # Vec3

    # invalid data type raises DXFTypeError
    ul.append((1, 2, 3))  # tuple instead of Vec3

    # retrieve a single value
    s = ul[0]

    # store whole content into a Python list
    data = list(ul)

Implements the MutableSequence interface.

xdata

The underlying XData instance.

__init__(xdata: XData | None = None, name='DefaultList', appid='EZDXF')

Setup a XDATA user list name for the given appid.

The data is stored in the given xdata object, or in a new created XData instance if None. Changes of the content has to be committed at the end to be stored in the underlying xdata object.

Parameters:

  • xdata (XData) – underlying XData instance, if None a new one will be created

  • name (str) – name of the user list

  • appid (str) – application specific AppID

__str__()

Return str(self).

__len__() → int

Returns len(self).

__getitem__(item)

Get self[item].

__setitem__(item, value)

Set self[item] to value.

__delitem__(item)

Delete self[item].

classmethod entity(entity: DXFEntity, name='DefaultList', appid='EZDXF') → Iterator[XDataUserList]

Context manager to manage a XDATA list name for a given DXF entity. Appends the user list to the existing XData instance or creates new XData instance.

Parameters:

  • entity (DXFEntity) – target DXF entity for the XDATA

  • name (str) – name of the user list

  • appid (str) – application specific AppID

commit() → None

Store all changes to the underlying XData instance. This call is not required if using the entity() context manager.

Raises:

XDataUserDict

class ezdxf.entities.xdata.XDataUserDict

Manage user data as a named dict-like object in XDATA. Multiple user dicts with different names can be stored in a single XData instance for a single AppID. The keys have to be strings.

Recommended usage by context manager entity():

with XDataUserDict.entity(entity, name="MyDict", appid="MYAPP") as ud:
    ud["comment"] = "The value of PI"  # str "\n" and "\r" are not allowed
    ud["pi"] = 3.141592  # float
    ud["number"] = 1 # int
    ud["vertex"] = Vec3(1, 2, 3) # Vec3

    # invalid data type raises DXFTypeError
    ud["vertex"] = (1, 2, 3)  # tuple instead of Vec3

    # retrieve single values
    s = ud["comment"]
    pi = ud.get("pi", 3.141592)

    # store whole content into a Python dict
    data = dict(ud)

Implements the MutableMapping interface.

The data is stored in XDATA like a XDataUserList by (key, value) pairs, therefore a XDataUserDict can also be loaded as XDataUserList. It is not possible to distinguish a XDataUserDict from a XDataUserList except by the name of the data structure.

xdata

The underlying XData instance.

__init__(xdata: XData | None = None, name='DefaultDict', appid='EZDXF')

Setup a XDATA user dict name for the given appid.

The data is stored in the given xdata object, or in a new created XData instance if None. Changes of the content has to be committed at the end to be stored in the underlying xdata object.

Parameters:

  • xdata (XData) – underlying XData instance, if None a new one will be created

  • name (str) – name of the user list

  • appid (str) – application specific AppID

__str__()

Return str(self).

__len__()

Returns len(self).

__getitem__(key)

Get self[key].

__setitem__(key, item)

Set self[key] to value, key has to be a string.

Raises:

DXFTypeError – key is not a string

__delitem__(key)

Delete self[key].

discard(key)

Delete self[key], without raising a KeyError if key does not exist.

__iter__()

Implement iter(self).

classmethod entity(entity: DXFEntity, name='DefaultDict', appid='EZDXF') → Iterator[XDataUserDict]

Context manager to manage a XDATA dict name for a given DXF entity. Appends the user dict to the existing XData instance or creates new XData instance.

Parameters:

  • entity (DXFEntity) – target DXF entity for the XDATA

  • name (str) – name of the user list

  • appid (str) – application specific AppID

commit() → None

Store all changes to the underlying XData instance. This call is not required if using the entity() context manager.

Raises: