Block Reference Management¶

The package ezdxf is not designed as a CAD library and does not automatically monitor all internal changes. This enables faster entity processing at the cost of an unknown state of the DXF document.

In order to carry out precise BLOCK reference management, i.e. to handle dependencies or to delete unused BLOCK definition, the block reference status (counter) must be acquired explicitly by the package user. All block reference management structures must be explicitly recreated each time the document content is changed. This is not very efficient, but it is safe.

Warning

The DXF reference does not document all uses of blocks. The INSERT entity is just one explicit use case, but there are also many indirect block references and the customizability of DXF allows you to store block names and handles in many places.

There are some rules for storing names and handles and this module checks all of these known rules, but there is no guarantee that everyone follows these rules.

Therefore, it is still possible to destroy a DXF document by deleting an absolutely necessary block definition.

Always remember that ezdxf is not intended or suitable as a basis for a CAD application!

class ezdxf.blkrefs.BlockDefinitionIndex(doc: Drawing)¶

Index of all BlockRecord entities representing real BLOCK definitions, excluding all BlockRecord entities defining model space or paper space layouts. External references (XREF) and XREF overlays are included.

property block_records: Iterator[BlockRecord]¶: Returns an iterator of all BlockRecord entities representing BLOCK definitions.

rebuild()¶: Rebuild index from scratch.

has_handle(handle: str) → bool¶: Returns True if a BlockRecord for the given block record handle exist.

by_handle(handle: str) → BlockRecord | None¶: Returns the BlockRecord for the given block record handle or None.

has_name(name: str) → bool¶: Returns True if a BlockRecord for the given block name exist.

by_name(name: str) → BlockRecord | None¶: Returns BlockRecord for the given block name or None.

class ezdxf.blkrefs.BlockReferenceCounter(doc: Drawing, index: BlockDefinitionIndex | None = None)¶

Counts all block references in a DXF document.

Check if a block is referenced by any entity or any resource (DIMSYTLE, MLEADERSTYLE) in a DXF document:

import ezdxf
from ezdxf.blkrefs import BlockReferenceCounter

doc = ezdxf.readfile("your.dxf")
counter = BlockReferenceCounter(doc)
count = counter.by_name("XYZ")
print(f"Block 'XYZ' if referenced {count} times.")

by_handle(handle: str) → int¶: Returns the block reference count for a given BlockRecord handle.

by_name(block_name: str) → int¶: Returns the block reference count for a given block name.

ezdxf.blkrefs.find_unreferenced_blocks(doc: Drawing) → set[str]¶: Returns the names of all block definitions without references.

Warning

The DXF reference does not document all uses of blocks. The INSERT entity is just one explicit use case, but there are also many indirect block references and the customizability of DXF allows you to store block names and handles in many places.

There are some rules for storing names and handles and this module checks all of these known rules, but there is no guarantee that everyone follows these rules.

Therefore, it is still possible to destroy a DXF document by deleting an absolutely necessary block definition.

Added in version 1.3.5.