The DICTIONARY entity is a general storage entity.

AutoCAD maintains items such as MLINE_STYLES and GROUP definitions as objects in dictionaries. Other applications are free to create and use their own dictionaries as they see fit. The prefix 'ACAD_' is reserved for use by AutoCAD applications.

Dictionary entries are (key, DXFEntity) pairs for fully loaded or new created DXF documents. The referenced entities are owned by the dictionary and cannot be graphical entities that always belong to the layout in which they are located.

Loading DXF files is done in two passes, because at the first loading stage not all referenced objects are already stored in the entity database. Therefore the entities are stored as handles strings at the first loading stage and have to be replaced by the real entity at the second loading stage. If the entity is still a handle string after the second loading stage, the entity does not exist.

Dictionary keys are handled case insensitive by AutoCAD, but not by ezdxf, in doubt use an uppercase key. AutoCAD stores all keys in uppercase.

Subclass of ezdxf.entities.DXFObject
Factory function ezdxf.sections.objects.ObjectsSection.add_dictionary()


Do not instantiate object classes by yourself - always use the provided factory functions!

class ezdxf.entities.Dictionary

If set to 1, indicates that elements of the dictionary are to be treated as hard-owned.


Duplicate record cloning flag (determines how to merge duplicate entries, ignored by ezdxf):

0 not applicable
1 keep existing
2 use clone
3 <xref>$0$<name>
4 $0$<name>
5 Unmangle name

Returns True if the dictionary is hard owner of entities. Hard owned entities will be destroyed by deleting the dictionary.

__len__() → int

Returns count of dictionary entries.

__contains__(key: str) → bool

Returns key in self.

__getitem__(key: str) → ezdxf.entities.dxfentity.DXFEntity

Return self[key].

The returned value can be a handle string if the entity does not exist.

Raises:DXFKeyErrorkey does not exist
__setitem__(key: str, entity: ezdxf.entities.dxfobj.DXFObject) → None

Set self[key] = entity.

Only DXF objects stored in the OBJECTS section are allowed as content of Dictionary objects. DXF entities stored in layouts are not allowed.

Raises:DXFTypeError – invalid DXF type
__delitem__(key: str) → None

Delete self[key].

Raises:DXFKeyErrorkey does not exist

Returns a KeysView of all dictionary keys.


Returns an ItemsView for all dictionary entries as (key, entity) pairs. An entity can be a handle string if the entity does not exist.

count() → int

Returns count of dictionary entries.

get(key: str, default: Optional[ezdxf.entities.dxfobj.DXFObject] = None) → Optional[ezdxf.entities.dxfobj.DXFObject]

Returns the DXFEntity for key, if key exist else default. An entity can be a handle string if the entity does not exist.

add(key: str, entity: ezdxf.entities.dxfobj.DXFObject) → None

Add entry (key, value).

If the DICTIONARY is hard owner of its entries, the add() does NOT take ownership of the entity automatically.

  • DXFValueError – invalid entity handle
  • DXFTypeError – invalid DXF type
remove(key: str) → None

Delete entry key. Raises DXFKeyError, if key does not exist. Destroys hard owned DXF entities.

discard(key: str) → None

Delete entry key if exists. Does not raise an exception if key doesn’t exist and does not destroy hard owned DXF entities.

clear() → None

Delete all entries from the dictionary and destroys hard owned DXF entities.

add_new_dict(key: str, hard_owned: bool = False) → ezdxf.entities.dictionary.Dictionary

Create a new sub-dictionary of type Dictionary.

  • key – name of the sub-dictionary
  • hard_owned – entries of the new dictionary are hard owned
get_required_dict(key: str, hard_owned=False) → ezdxf.entities.dictionary.Dictionary

Get entry key or create a new Dictionary, if Key not exist.

add_dict_var(key: str, value: str) → ezdxf.entities.dictionary.DictionaryVar

Add a new DictionaryVar.

  • key – entry name as string
  • value – entry value as string
add_xrecord(key: str) → XRecord

Add a new XRecord.

Parameters:key – entry name as string

Add obj and set owner of obj to this dictionary.

Graphical DXF entities have to reside in a layout and therefore can not be owned by a Dictionary.

Raises:DXFTypeErrorobj has invalid DXF type


Subclass of ezdxf.entities.Dictionary
Factory function ezdxf.sections.objects.ObjectsSection.add_dictionary_with_default()
class ezdxf.entities.DictionaryWithDefault

Handle to default entry as hex string like FF00.

get(key: str, default: Optional[ezdxf.entities.dxfobj.DXFObject] = None) → Optional[ezdxf.entities.dxfobj.DXFObject]

Returns DXFEntity for key or the predefined dictionary wide dxf.default entity if key does not exist or None if default value also not exist.

set_default(default: ezdxf.entities.dxfobj.DXFObject) → None

Set dictionary wide default entry.

Parameters:default – default entry as DXFEntity


Subclass of ezdxf.entities.DXFObject
Factory function ezdxf.entities.Dictionary.add_dict_var()
class ezdxf.entities.DictionaryVar

Object schema number (currently set to 0)


Value as string.