preheat_open.query.Query

class preheat_open.query.Query(exclude=None)

Bases: object

Represents a query for filtering objects based on specified attributes.

A Query object defines criteria for filtering objects by their attributes. It supports exact matching, list-based filtering, and exclusion patterns. Queries can be combined and used to filter collections of objects.

Variables:: _class – The class type that the query is designed to filter
Parameters:: exclude (Query, optional) – A nested Query object for exclusion criteria

Note

This is an abstract base class. Concrete query classes should inherit from this class and define their specific filtering attributes. When inheriting, ensure that the eq=False parameter is set in the dataclass decorator to prevent default equality checks based on object identity.

Example:

>>> # Create a simple query subclass for demonstration
>>> from dataclasses import field
>>> @dataclass(eq=False)
... class SimpleQuery(Query):
...     name: list[str] = field(default_factory=list)
...     _class = object  # Normally would be a specific class
>>>
>>> query = SimpleQuery(name="test")
>>> query.name
['test']

__init__(exclude=None)

Methods

`__init__`([exclude])
`convert_attr`(value, name)	Convert an attribute value to the appropriate type.
`from_kwargs`([query])	Create a Query object from keyword arguments.
`is_type`(obj)	Check if an object is of the type this query is designed to filter.
`isin`(iterable)	Check if this query matches any element in an iterable.

Attributes

exclude

classmethod convert_attr(value, name)

Convert an attribute value to the appropriate type.

This method applies type conversion based on class-defined type hints or special type attributes. It supports both direct instantiation and dictionary-based construction.

Parameters:

value (Any) – The value to convert
name (str) – The attribute name for type lookup

Returns:

The converted value

Return type:

Any

Example:

>>> from dataclasses import field
>>> @dataclass(eq=False)
... class TestQuery(Query):
...     _type_age = int
...     _class = object
>>>
>>> converted = TestQuery.convert_attr("25", "age")
>>> converted
25
>>> isinstance(converted, int)
True

classmethod from_kwargs(query=None, **kwargs)

Create a Query object from keyword arguments.

This factory method creates a new Query instance from keyword arguments, with optional base query for inheritance. It validates that all provided keys are valid attributes for the query class.

Parameters:

query (Query, optional) – An existing Query object to use as a base
kwargs – Additional keyword arguments for query attributes

Returns:

A new Query object of the same type as the class

Return type:

QueryT

Raises:

TypeError – If unknown keys are provided in kwargs

Example:

>>> from dataclasses import field
>>> @dataclass(eq=False)
... class PersonQuery(Query):
...     name: list[str] = field(default_factory=list)
...     age: list[int] = field(default_factory=list)
...     _class = object
>>>
>>> query = PersonQuery.from_kwargs(name="Alice", age=30)
>>> type(query).__name__
'PersonQuery'
>>> query.name
['Alice']
>>> query.age
[30]

classmethod is_type(obj)

Check if an object is of the type this query is designed to filter.

This method uses a naming convention where the query class name ends with “Query” and the target class name is the prefix.

Parameters:: obj (object) – The object to check
Returns:: True if the object matches the expected type
Return type:: bool

Example:

>>> from dataclasses import field
>>> @dataclass(eq=False)
... class PersonQuery(Query):
...     _class = object
>>>
>>> class Person:
...     pass
>>>
>>> person = Person()
>>> PersonQuery.is_type(person)
True

isin(iterable)

Check if this query matches any element in an iterable.

This method iterates through the provided iterable and returns True if any element matches this query’s criteria.

Parameters:: iterable (Iterable) – The iterable to search through
Returns:: True if any element matches the query
Return type:: bool

Example:

>>> from dataclasses import field
>>> @dataclass
... class Person:
...     name: str
>>>
>>> @dataclass(eq=False)
... class PersonQuery(Query):
...     name: list[str] = field(default_factory=list)
...     _class = Person
>>>
>>> people = [Person("Alice"), Person("Bob"), Person("Charlie")]
>>> query = PersonQuery(name="Bob")
>>> query.isin(people)
True
>>>
>>> query2 = PersonQuery(name="David")
>>> query2.isin(people)
False