Groups¶

A group is just a bunch of DXF entities tied together. All entities of a group has to be in the same layout (modelspace or any paperspace layout but not block). Groups can be named or unnamed, but in reality an unnamed groups has just a special name like “*Annnn”. The name of a group has to be unique in the drawing. Groups are organized in the group table, which is stored as attribute groups in the Drawing object.

Important

Group entities have to reside in the modelspace or an paperspace layout but not in a block definition!

DXFGroup¶

class ezdxf.entities.dxfgroups.DXFGroup¶

The group name is not stored in the GROUP entity, it is stored in the GroupCollection object.

dxf.description¶: group description (string)

dxf.unnamed¶: 1 for unnamed, 0 for named group (int)

dxf.selectable¶: 1 for selectable, 0 for not selectable group (int)

__iter__() → Iterator[DXFEntity]¶: Iterate over all DXF entities in DXFGroup as instances of DXFGraphic or inherited (LINE, CIRCLE, …).

__len__() → int¶: Returns the count of DXF entities in DXFGroup.

__getitem__(item)¶: Returns entities by standard Python indexing and slicing.

__contains__(item: str | DXFEntity) → bool¶: Returns True if item is in DXFGroup. item has to be a handle string or an object of type DXFEntity or inherited.

handles() → Iterable[str]¶: Iterable of handles of all DXF entities in DXFGroup.

edit_data() → list[DXFEntity]¶

Context manager which yields all the group entities as standard Python list:

with group.edit_data() as data:
   # add new entities to a group
   data.append(modelspace.add_line((0, 0), (3, 0)))
   # remove last entity from a group
   data.pop()

set_data(entities: Iterable[DXFEntity]) → None¶: Set entities as new group content, entities should be an iterable DXFGraphic or inherited (LINE, CIRCLE, …). Raises DXFValueError if not all entities be on the same layout (modelspace or any paperspace layout but not block)

extend(entities: Iterable[DXFEntity]) → None¶

Add entities to DXFGroup without immediate verification!

Validation at DXF export may raise a DXFStructureError!

clear() → None¶: Remove all entities from DXFGroup, does not delete any drawing entities referenced by this group.

audit(auditor: Auditor) → None¶

Remove invalid entities from DXFGroup.

Invalid entities are:

deleted entities
all entities which do not reside in model- or paper space
all entities if they do not reside in the same layout

GroupCollection¶

Each Drawing has one group table, which is accessible by the attribute groups.

class ezdxf.entities.dxfgroups.GroupCollection¶

Manages all DXFGroup objects of a Drawing.

__len__()¶: Returns the count of DXF groups.

__iter__()¶: Iterate over all existing groups as (name, group) tuples. name is the name of the group as string and group is an DXFGroup object.

__contains__()¶: Returns True if a group name exist.

get(name: str) → DXFGroup¶: Returns the group name. Raises DXFKeyError if group name does not exist.

groups() → Iterator[DXFGroup]¶: Iterable of all existing groups.

new(name: str | None = None, description: str = '', selectable: bool = True) → DXFGroup¶

Creates a new group. If name is None an unnamed group is created, which has an automatically generated name like “*Annnn”. Group names are case-insensitive.

Parameters:

name – group name as string
description – group description as string
selectable – group is selectable if True

delete(group: DXFGroup | str) → None¶: Delete group, group can be an object of type DXFGroup or a group name as string.

clear()¶: Delete all groups.

audit(auditor: Auditor) → None¶: Removes empty groups and invalid handles from all groups.