Entity Database

The EntityDB is a simple key/value database to store DXFEntity objects by it’s handle, every Drawing has its own EntityDB, stored in the Drawing attribute entitydb.

Every DXF entity/object, except tables and sections, are represented as DXFEntity or inherited types, this entities are stored in the EntityDB, database-key is the dxf.handle as plain hex string.

All iterators like keys(), values(), items() and __iter__() do not yield destroyed entities.


The get() method and the index operator [], return destroyed entities and entities from the trashcan.

class ezdxf.entitydb.EntityDB
__getitem__(handle: str) DXFEntity

Get entity by handle, does not filter destroyed entities nor entities in the trashcan.

__setitem__(handle: str, entity: DXFEntity) None

Set entity for handle.

__delitem__(handle: str) None

Delete entity by handle. Removes entity only from database, does not destroy the entity.

__contains__(item: str | DXFEntity) bool

True if database contains handle.

__len__() int

Count of database items.

__iter__() Iterator[str]

Iterable of all handles, does filter destroyed entities but not entities in the trashcan.

get(handle: str) DXFEntity | None

Returns entity for handle or None if no entry exist, does not filter destroyed entities.

next_handle() str

Returns next unique handle.

keys() Iterable[str]

Iterable of all handles, does filter destroyed entities.

values() Iterable[DXFEntity]

Iterable of all entities, does filter destroyed entities.

items() Iterable[Tuple[str, DXFEntity]]

Iterable of all (handle, entities) pairs, does filter destroyed entities.

add(entity: DXFEntity) None

Add entity to database, assigns a new handle to the entity if entity.dxf.handle is None. Adding the same entity multiple times is possible and creates only a single database entry.

new_trashcan() Trashcan

Returns a new trashcan, empty trashcan manually by: : func:Trashcan.clear().

trashcan() Trashcan

Returns a new trashcan in context manager mode, trashcan will be emptied when leaving context.

purge() None

Remove all destroyed entities from database, but does not empty the trashcan.

query(query: str = '*') EntityQuery

Entity query over all entities in the DXF document.


query – query string

Entity Space

class ezdxf.entitydb.EntitySpace(entities: Iterable[DXFEntity] | None = None)

An EntitySpace is a collection of DXFEntity objects, that stores only references to DXFEntity objects.

The Modelspace, any Paperspace layout and BlockLayout objects have an EntitySpace container to store their entities.

__iter__() Iterable[DXFEntity]

Iterable of all entities, filters destroyed entities.

__getitem__(index) DXFEntity

Get entity at index item

EntitySpace has a standard Python list like interface, therefore index can be any valid list indexing or slicing term, like a single index layout[-1] to get the last entity, or an index slice layout[:10] to get the first 10 or fewer entities as list[DXFEntity]. Does not filter destroyed entities.

__len__() int

Count of entities including destroyed entities.

has_handle(handle: str) bool

True if handle is present, does filter destroyed entities.


Remove all destroyed entities from entity space.

add(entity: DXFEntity) None

Add entity.

extend(entities: Iterable[DXFEntity]) None

Add multiple entities.

remove(entity: DXFEntity) None

Remove entity.

clear() None

Remove all entities.