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.

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: Optional[ezdxf.entities.xdata.XData] = 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:	`DXFValueError` – invalid chars `"\n"` or `"\r"` in a string `DXFTypeError` – invalid data type

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: Optional[ezdxf.entities.xdata.XData] = 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:	`DXFValueError` – invalid chars `"\n"` or `"\r"` in a string `DXFTypeError` – invalid data type