:py:mod:`khard.query`
=====================

.. py:module:: khard.query

.. autoapi-nested-parse::

   Queries to match against contacts



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   khard.query.Query
   khard.query.NullQuery
   khard.query.AnyQuery
   khard.query.TermQuery
   khard.query.FieldQuery
   khard.query.AndQuery
   khard.query.OrQuery
   khard.query.NameQuery
   khard.query.PhoneNumberQuery



Functions
~~~~~~~~~

.. autoapisummary::

   khard.query.parse



Attributes
~~~~~~~~~~

.. autoapisummary::

   khard.query.FIELD_PHONE_NUMBERS


.. py:data:: FIELD_PHONE_NUMBERS
   :annotation: = phone_numbers

   

.. py:class:: Query

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

   .. py:method:: match(thing: Union[str, khard.carddav_object.CarddavObject]) -> bool
      :abstractmethod:

      Match the self query against the given thing


   .. py:method:: get_term() -> Optional[str]
      :abstractmethod:

      Extract the search terms from a query.


   .. py:method:: __and__(other: Query) -> Query

      Combine two queries with AND


   .. py:method:: __or__(other: Query) -> Query

      Combine two queries with OR


   .. py:method:: __eq__(other: object) -> bool

      A generic equality for all query types without parameters


   .. py:method:: __hash__() -> int

      A generic hashing implementation for all queries without parameters



.. py:class:: NullQuery

   Bases: :py:obj:`Query`

   The null-query, it matches nothing.

   .. py:method:: match(thing: Union[str, khard.carddav_object.CarddavObject]) -> bool

      Match the self query against the given thing


   .. py:method:: get_term() -> None

      Extract the search terms from a query.


   .. py:method:: __str__() -> str

      Return str(self).



.. py:class:: AnyQuery

   Bases: :py:obj:`Query`

   The match-anything-query, it always matches.

   .. py:method:: match(thing: Union[str, khard.carddav_object.CarddavObject]) -> bool

      Match the self query against the given thing


   .. py:method:: get_term() -> str

      Extract the search terms from a query.


   .. py:method:: __hash__() -> int

      A generic hashing implementation for all queries without parameters


   .. py:method:: __str__() -> str

      Return str(self).



.. py:class:: TermQuery(term: str)

   Bases: :py:obj:`Query`

   A query to match an object against a fixed string.

   .. py:method:: match(thing: Union[str, khard.carddav_object.CarddavObject]) -> bool

      Match the self query against the given thing


   .. py:method:: get_term() -> str

      Extract the search terms from a query.


   .. py:method:: __eq__(other: object) -> bool

      A generic equality for all query types without parameters


   .. py:method:: __hash__() -> int

      A generic hashing implementation for all queries without parameters


   .. py:method:: __str__() -> str

      Return str(self).



.. py:class:: FieldQuery(field: str, value: str)

   Bases: :py:obj:`TermQuery`

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

   .. py:method:: match(thing: Union[str, khard.carddav_object.CarddavObject]) -> bool

      Match the self query against the given thing


   .. py:method:: _match_union(value: Union[str, datetime.datetime, List, Dict[str, Any]]) -> bool


   .. py:method:: __eq__(other: object) -> bool

      A generic equality for all query types without parameters


   .. py:method:: __hash__() -> int

      A generic hashing implementation for all queries without parameters


   .. py:method:: __str__() -> str

      Return str(self).



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

   Bases: :py:obj:`Query`

   A query to combine multible queries with "and".

   .. py:method:: match(thing: Union[str, khard.carddav_object.CarddavObject]) -> bool

      Match the self query against the given thing


   .. py:method:: get_term() -> Optional[str]

      Extract the search terms from a query.


   .. py:method:: __eq__(other: object) -> bool

      A generic equality for all query types without parameters


   .. py:method:: __hash__() -> int

      A generic hashing implementation for all queries without parameters


   .. py:method:: reduce(queries: List[Query], start: Optional[Query] = None) -> Query
      :staticmethod:


   .. py:method:: __str__() -> str

      Return str(self).



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

   Bases: :py:obj:`Query`

   A query to combine multible queries with "or".

   .. py:method:: match(thing: Union[str, khard.carddav_object.CarddavObject]) -> bool

      Match the self query against the given thing


   .. py:method:: get_term() -> Optional[str]

      Extract the search terms from a query.


   .. py:method:: __eq__(other: object) -> bool

      A generic equality for all query types without parameters


   .. py:method:: __hash__() -> int

      A generic hashing implementation for all queries without parameters


   .. py:method:: reduce(queries: List[Query], start: Optional[Query] = None) -> Query
      :staticmethod:


   .. py:method:: __str__() -> str

      Return str(self).



.. py:class:: NameQuery(term: str)

   Bases: :py:obj:`TermQuery`

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

   .. py:method:: match(thing: Union[str, khard.carddav_object.CarddavObject]) -> bool

      Match the self query against the given thing


   .. py:method:: __eq__(other: object) -> bool

      A generic equality for all query types without parameters


   .. py:method:: __hash__() -> int

      A generic hashing implementation for all queries without parameters


   .. py:method:: __str__() -> str

      Return str(self).



.. py:class:: PhoneNumberQuery(value: str)

   Bases: :py:obj:`FieldQuery`

   A special query to match against phone numbers.

   .. py:method:: _strip_phone_number(number: str) -> str
      :staticmethod:


   .. py:method:: match(thing: Union[str, khard.carddav_object.CarddavObject]) -> bool

      Match the self query against the given thing


   .. py:method:: _match_union(value: Union[str, datetime.datetime, List, Dict[str, Any]]) -> bool


   .. py:method:: _match_phone_number(number: str) -> bool


   .. py:method:: __eq__(other: object) -> bool

      A generic equality for all query types without parameters


   .. py:method:: __hash__() -> int

      A generic hashing implementation for all queries without parameters


   .. py:method:: __str__() -> str

      Return str(self).



.. py:function:: parse(string: str) -> Union[TermQuery, FieldQuery]

   Parse a string into a query object

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

   :param string: a string to parse into a query
   :returns: a FieldQuery if the string contains a valid field specifier, a
       TermQuery otherwise


