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
- Tutorial: Storing Custom Data in DXF Files
- Example at github
- XDATA reference: Extended Data (XDATA)
- XDATA management class:
XData
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.-
__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 ifNone
. Changes of the content has to be committed at the end to be stored in the underlying xdata object.Parameters:
-
__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 newXData
instance.Parameters: - entity (DXFEntity) – target DXF entity for the XDATA
- name (str) – name of the user list
- appid (str) – application specific AppID
-
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 aXDataUserDict
can also be loaded asXDataUserList
. It is not possible to distinguish aXDataUserDict
from aXDataUserList
except by the name of the data structure.-
__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 ifNone
. Changes of the content has to be committed at the end to be stored in the underlying xdata object.Parameters:
-
__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 newXData
instance.Parameters: - entity (DXFEntity) – target DXF entity for the XDATA
- name (str) – name of the user list
- appid (str) – application specific AppID
-