# khard.query

Queries to match against contacts

## Attributes

`FIELD_PHONE_NUMBERS` |

## Classes

`Query` | A query to match against strings, lists of strings and Contacts
`NullQuery` | The null-query, it matches nothing.
`AnyQuery` | The match-anything-query, it always matches.
`TermQuery` | A query to match an object against a fixed string.
`FieldQuery` | A query to match against a certain field in a contact object.
`AndQuery` | A query to combine multiple queries with "and".
`OrQuery` | A query to combine multiple queries with "or".
`NameQuery` | special query to match any kind of name field of a vCard
`PhoneNumberQuery` | A special query to match against phone numbers.

## Functions

`parse`(→ Union[TermQuery, FieldQuery]) | Parse a string into a query object

## Module Contents

khard.query.FIELD_PHONE_NUMBERS = 'phone_numbers'

class khard.query.Query

  A query to match against strings, lists of strings and Contacts

  abstractmethod match(thing: str | khard.contacts.Contact) → bool

    Match the self query against the given thing

  abstractmethod get_term() → str | None

    Extract the search terms from a query.

  __and__(other: Query) → Query

    Combine two queries with AND

  __or__(other: Query) → Query

    Combine two queries with OR

  __eq__(other: object) → bool

    A generic equality for all query types without parameters

  __hash__() → int

    A generic hashing implementation for all queries without parameters

class khard.query.NullQuery

  Bases: `Query`

  The null-query, it matches nothing.

  match(thing: str | khard.contacts.Contact) → bool

    Match the self query against the given thing

  get_term() → None

    Extract the search terms from a query.

  __str__() → str

class khard.query.AnyQuery

  Bases: `Query`

  The match-anything-query, it always matches.

  match(thing: str | khard.contacts.Contact) → bool

    Match the self query against the given thing

  get_term() → str

    Extract the search terms from a query.

  __hash__() → int

    A generic hashing implementation for all queries without parameters

  __str__() → str

class khard.query.TermQuery(term: str)

  Bases: `Query`

  A query to match an object against a fixed string.

  _term
  match(thing: str | khard.contacts.Contact) → bool

    Match the self query against the given thing

  get_term() → str

    Extract the search terms from a query.

  __eq__(other: object) → bool

    A generic equality for all query types without parameters

  __hash__() → int

    A generic hashing implementation for all queries without parameters

  __str__() → str

class khard.query.FieldQuery(field: str, value: str)

  Bases: `TermQuery`

  A query to match against a certain field in a contact object.

  _field
  match(thing: str | khard.contacts.Contact) → bool

    Match the self query against the given thing

  _match_union(value: str | datetime.datetime | list | dict[str, Any]) → bool
  __eq__(other: object) → bool

    A generic equality for all query types without parameters

  __hash__() → int

    A generic hashing implementation for all queries without parameters

  __str__() → str

class khard.query.AndQuery(first: Query, second: Query, *queries: Query)

  Bases: `Query`

  A query to combine multiple queries with “and”.

  _queries
  match(thing: str | khard.contacts.Contact) → bool

    Match the self query against the given thing

  get_term() → str | None

    Extract the search terms from a query.

  __eq__(other: object) → bool

    A generic equality for all query types without parameters

  __hash__() → int

    A generic hashing implementation for all queries without parameters

  static reduce(queries: list[Query], start: Query | None = None) → Query
  __str__() → str

class khard.query.OrQuery(first: Query, second: Query, *queries: Query)

  Bases: `Query`

  A query to combine multiple queries with “or”.

  _queries
  match(thing: str | khard.contacts.Contact) → bool

    Match the self query against the given thing

  get_term() → str | None

    Extract the search terms from a query.

  __eq__(other: object) → bool

    A generic equality for all query types without parameters

  __hash__() → int

    A generic hashing implementation for all queries without parameters

  static reduce(queries: list[Query], start: Query | None = None) → Query
  __str__() → str

class khard.query.NameQuery(term: str)

  Bases: `TermQuery`

  special query to match any kind of name field of a vCard

  _props_query
  match(thing: str | khard.contacts.Contact) → bool

    Match the self query against the given thing

  __eq__(other: object) → bool

    A generic equality for all query types without parameters

  __hash__() → int

    A generic hashing implementation for all queries without parameters

  __str__() → str

class khard.query.PhoneNumberQuery(value: str)

  Bases: `FieldQuery`

  A special query to match against phone numbers.

  static _strip_phone_number(number: str) → str
  _term_only_digits
  match(thing: str | khard.contacts.Contact) → bool

    Match the self query against the given thing

  _match_union(value: str | datetime.datetime | list | dict[str, Any]) → bool
  _match_phone_number(number: str) → bool
  __eq__(other: object) → bool

    A generic equality for all query types without parameters

  __hash__() → int

    A generic hashing implementation for all queries without parameters

  __str__() → str

khard.query.parse(string: str) → TermQuery | FieldQuery

  Parse a string into a query object

  The input string interpreted as a `FieldQuery` if it starts with a valid property name of the `Contact` class, followed by a colon and an arbitrary search term. Otherwise it is interpreted as a `TermQuery`.

  Parameters:

    string – a string to parse into a query

  Returns:

    a FieldQuery if the string contains a valid field specifier, a TermQuery otherwise