Name Query String

A name query string is just a standard regular expression see: http://docs.python.org/3/library/re.html

A '$' will be appended to the query string.

For general usage of the query features see the tutorial: Tutorial for Getting Data from DXF Files

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, all other 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”

Query Result

The EntityQuery class is the return type of all query() methods. EntityQuery contains all DXF entities of the source collection, which matches one name of the entity query AND the whole attribute query. If a DXF entity does not have or support a required attribute, the corresponding attribute search term is false.

examples:

'LINE[text ? ".*"]' is always empty, because the LINE entity has no text attribute.

'LINE CIRCLE[layer=="construction"]' => all LINE and CIRCLE entities on layer "construction"
'*[!(layer=="construction" & color<7)]' => all entities except those on layer == "construction" and color < 7
'*[layer=="construction"]i' => (ignore case) all entities with layer == "construction" | "Construction" | "ConStruction" ...

EntityQuery Class

class EntityQuery(Sequence)

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 sequence methods and protocols. (Python Sequence Docs)

EntityQuery.first

Returns first entity or None.

EntityQuery.last

Returns last entity or None.

EntityQuery.__init__(entities, query='*')

Setup container with entities matching the initial query.

Parameters:
EntityQuery.extend(entities, query='*', unique=True)

Extent the query container by entities matching an additional query.

EntityQuery.remove(query='*')

Remove all entities from result container matching this additional query.

EntityQuery.query(query='*')

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

EntityQuery.groupby(dxfattrib='', key=None)

Returns a mapping of this result container, where entities are grouped by a dxfattrib or a key function.

Parameters:
  • dxfattrib (str) – grouping DXF attribute like ‘layer’
  • key (function) – 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

The new() Function

ezdxf.query.new(entities, query='*')

Start a new query based on a sequence entities. The sequence entities has to provide the Python iterator protocol and has to yield at least subclasses of GenericWrapper or better GraphicEntity. Returns an object of type EntityQuery.