khard.query
***********

Queries to match against contacts


Attributes
==========

+------------+--------------------------------------------------------------------------------------------+
| "FIELD_PH  |                                                                                            |
| ONE_NUMBE  |                                                                                            |
| RS"        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


Classes
=======

+------------+--------------------------------------------------------------------------------------------+
| "Query"    | A query to match against strings, lists of strings and Contacts                            |
+------------+--------------------------------------------------------------------------------------------+
| "NullQuer  | The null-query, it matches nothing.                                                        |
| y"         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "AnyQuery" | The match-anything-query, it always matches.                                               |
+------------+--------------------------------------------------------------------------------------------+
| "TermQuer  | A query to match an object against a fixed string.                                         |
| y"         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "FieldQue  | A query to match against a certain field in a contact object.                              |
| ry"        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "AndQuery" | A query to combine multiple queries with "and".                                            |
+------------+--------------------------------------------------------------------------------------------+
| "OrQuery"  | A query to combine multiple queries with "or".                                             |
+------------+--------------------------------------------------------------------------------------------+
| "NameQuer  | special query to match any kind of name field of a vCard                                   |
| y"         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "PhoneNum  | A special query to match against phone numbers.                                            |
| berQuery"  |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


Functions
=========

+------------+--------------------------------------------------------------------------------------------+
| "parse"(→  | Parse a string into a query object                                                         |
| Union[Ter  |                                                                                            |
| mQuery, F  |                                                                                            |
| ieldQuery  |                                                                                            |
| ])         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


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
