Dictionary

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

DXF type

'DICTIONARY'

Factory function

ezdxf.sections.objects.ObjectsSection.add_dictionary()

Warning

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

class ezdxf.entities.Dictionary
dxf.hard_owned

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

dxf.cloning

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
is_hard_owner

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) → DXFEntity

Return self[key].

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

Raises:

DXFKeyError – key does not exist

__setitem__(key: str, entity: 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:

DXFKeyError – key does not exist

keys()

Returns a KeysView of all dictionary keys.

items()

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: DXFObject | None = None) → DXFObject | None

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: 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.

Raises:
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) → Dictionary

Create a new sub-dictionary of type Dictionary.

Parameters:

  • key – name of the sub-dictionary

  • hard_owned – entries of the new dictionary are hard owned

get_required_dict(key: str, hard_owned=False) → Dictionary

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

add_dict_var(key: str, value: str) → DictionaryVar

Add a new DictionaryVar.

Parameters:

  • 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:

DXFTypeError – obj has invalid DXF type

DictionaryWithDefault

Subclass of

ezdxf.entities.Dictionary

DXF type

'ACDBDICTIONARYWDFLT'

Factory function

ezdxf.sections.objects.ObjectsSection.add_dictionary_with_default()
class ezdxf.entities.DictionaryWithDefault
dxf.default

Handle to default entry as hex string like FF00.

get(key: str, default: DXFObject | None = None) → DXFObject | None

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: DXFObject) → None

Set dictionary wide default entry.

Parameters:

default – default entry as DXFEntity

DictionaryVar

Subclass of

ezdxf.entities.DXFObject

DXF type

'DICTIONARYVAR'

Factory function

ezdxf.entities.Dictionary.add_dict_var()
class ezdxf.entities.DictionaryVar
dxf.schema

Object schema number (currently set to 0)

dxf.value

Value as string.

property value: str

Get/set the value of the DictionaryVar as string.