Query Module

See also

The new() Function

ezdxf.query.new(entities: Iterable[DXFEntity] | None = None, query: str = '*') → EntityQuery

Start a new query based on sequence entities. The entities argument has to be an iterable of DXFEntity or inherited objects and returns an EntityQuery object.

Entity Query String

QueryString := EntityQuery ("[" AttribQuery "]" "i"?)*

The query string is the combination of two queries, first the required entity query and second the optional attribute query, enclosed in square brackets, append 'i' after the closing square bracket to ignore case for strings.

Entity Query

The entity query is a whitespace separated list of DXF entity names or the special name '*'. Where '*' means all DXF entities, exclude some entity types by appending their names with a preceding ! (e.g. all entities except LINE = '* !LINE'). All DXF names have to be uppercase.

Attribute Query

The optional attribute query is a boolean expression, supported operators are:

  • not (!): !term is true, if term is false

  • and (&): term & term is true, if both terms are true

  • or (|): term | term is true, if one term is true

  • and arbitrary nested round brackets

  • append (i) after the closing square bracket to ignore case for strings

Attribute selection is a term: “name comparator value”, where name is a DXF entity attribute in lowercase, value is a integer, float or double quoted string, valid comparators are:

  • == equal “value”

  • != not equal “value”

  • < lower than “value”

  • <= lower or equal than “value”

  • > greater than “value”

  • >= greater or equal than “value”

  • ? match regular expression “value”

  • !? does not match regular expression “value”

EntityQuery Class

class ezdxf.query.EntityQuery

The EntityQuery class is a result container, which is filled with DXF entities matching the query string. It is possible to add entities to the container (extend), remove entities from the container and to filter the container. Supports the standard Python Sequence methods and protocols. Does not remove automatically destroyed entities (entities deleted by calling method destroy()), the method purge() has to be called explicitly to remove the destroyed entities.

first

First entity or None.

last

Last entity or None.

__len__() → int

Returns count of DXF entities.

__getitem__(item)

Returns DXFEntity at index item, supports negative indices and slicing. Returns all entities which support a specific DXF attribute, if item is a DXF attribute name as string.

__setitem__(key, value)

Set the DXF attribute key for all supported DXF entities to value.

__delitem__(key)

Discard the DXF attribute key from all supported DXF entities.

__eq__(other)

Equal selector (self == other). Returns all entities where the selected DXF attribute is equal to other.

__ne__(other)

Not equal selector (self != other). Returns all entities where the selected DXF attribute is not equal to other.

__lt__(other)

Less than selector (self < other). Returns all entities where the selected DXF attribute is less than other.

Raises:

TypeError – for vector based attributes like center or insert

__le__(other)

Less equal selector (self <= other). Returns all entities where the selected DXF attribute is less or equal other.

Raises:

TypeError – for vector based attributes like center or insert

__gt__(other)

Greater than selector (self > other). Returns all entities where the selected DXF attribute is greater than other.

Raises:

TypeError – for vector based attributes like center or insert

__ge__(other)

Greater equal selector (self >= other). Returns all entities where the selected DXF attribute is greater or equal other.

Raises:

TypeError – for vector based attributes like center or insert

match(pattern: str) → EntityQuery

Returns all entities where the selected DXF attribute matches the regular expression pattern.

Raises:

TypeError – for non-string based attributes

__or__(other)

Union operator, see union().

__and__(other)

Intersection operator, see intersection().

__sub__(other)

Difference operator, see difference().

__xor__(other)

Symmetric difference operator, see symmetric_difference().

__iter__() → Iterator[DXFEntity]

Returns iterable of DXFEntity objects.

purge() → EntityQuery

Remove destroyed entities.

extend(entities: Iterable[DXFEntity], query: str = '*') → EntityQuery

Extent the EntityQuery container by entities matching an additional query.

remove(query: str = '*') → EntityQuery

Remove all entities from EntityQuery container matching this additional query.

query(query: str = '*') → EntityQuery

Returns a new EntityQuery container with all entities matching this additional query.

Raises:

pyparsing.ParseException – query string parsing error

groupby(dxfattrib: str = '', key: Callable[[DXFEntity], Hashable] | None = None) → dict[Hashable, list[DXFEntity]]

Returns a dict of entity lists, where entities are grouped by a DXF attribute or a key function.

Parameters:

  • dxfattrib – grouping DXF attribute as string like 'layer'

  • key – key function, which accepts a DXFEntity as argument, returns grouping key of this entity or None for ignore this object. Reason for ignoring: a queried DXF attribute is not supported by this entity

filter(func: Callable[[DXFEntity], bool]) → EntityQuery

Returns a new EntityQuery with all entities from this container for which the callable func returns True.

Build your own operator to filter by attributes which are not DXF attributes or to build complex queries:

result = msp.query().filter(
    lambda e: hasattr(e, "rgb") and e.rbg == (0, 0, 0)
)
union(other: EntityQuery) → EntityQuery

Returns a new EntityQuery with entities from self and other. All entities are unique - no duplicates.

intersection(other: EntityQuery) → EntityQuery

Returns a new EntityQuery with entities common to self and other.

difference(other: EntityQuery) → EntityQuery

Returns a new EntityQuery with all entities from self that are not in other.

symmetric_difference(other: EntityQuery) → EntityQuery

Returns a new EntityQuery with entities in either self or other but not both.