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: Optional[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

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[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