: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



Functions
~~~~~~~~~

.. autoapisummary::

   khard.query.parse


.. py:class:: Query

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

   .. method:: match(self, thing: Union[str, 'carddav_object.CarddavObject'])
      :abstractmethod:


      Match the self query against the given thing


   .. method:: get_term(self)
      :abstractmethod:


      Extract the search terms from a query.


   .. method:: __and__(self, other: Query)


      Combine two queries with AND


   .. method:: __or__(self, other: Query)


      Combine two queries with OR


   .. method:: __eq__(self, other: object)


      A generic equality for all query types without parameters


   .. method:: __hash__(self)


      A generic hashing implementation for all queries without parameters



.. py:class:: NullQuery

   Bases: :class:`khard.query.Query`

   The null-query, it matches nothing.

   .. method:: match(self, thing: Union[str, 'carddav_object.CarddavObject'])


      Match the self query against the given thing


   .. method:: get_term(self)


      Extract the search terms from a query.


   .. method:: __str__(self)


      Return str(self).



.. py:class:: AnyQuery

   Bases: :class:`khard.query.Query`

   The match-anything-query, it always matches.

   .. method:: match(self, thing: Union[str, 'carddav_object.CarddavObject'])


      Match the self query against the given thing


   .. method:: get_term(self)


      Extract the search terms from a query.


   .. method:: __hash__(self)


      A generic hashing implementation for all queries without parameters


   .. method:: __str__(self)


      Return str(self).



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

   Bases: :class:`khard.query.Query`

   A query to match an object against a fixed string.

   .. method:: match(self, thing: Union[str, 'carddav_object.CarddavObject'])


      Match the self query against the given thing


   .. method:: get_term(self)


      Extract the search terms from a query.


   .. method:: __eq__(self, other: object)


      A generic equality for all query types without parameters


   .. method:: __hash__(self)


      A generic hashing implementation for all queries without parameters


   .. method:: __str__(self)


      Return str(self).



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

   Bases: :class:`khard.query.TermQuery`

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

   .. method:: match(self, thing: Union[str, 'carddav_object.CarddavObject'])


      Match the self query against the given thing


   .. method:: _match_union(self, value: Union[str, datetime, List, Dict[str, Any]])



   .. method:: __eq__(self, other: object)


      A generic equality for all query types without parameters


   .. method:: __hash__(self)


      A generic hashing implementation for all queries without parameters


   .. method:: __str__(self)


      Return str(self).



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

   Bases: :class:`khard.query.Query`

   A query to combine multible queries with "and".

   .. method:: match(self, thing: Union[str, 'carddav_object.CarddavObject'])


      Match the self query against the given thing


   .. method:: get_term(self)


      Extract the search terms from a query.


   .. method:: __eq__(self, other: object)


      A generic equality for all query types without parameters


   .. method:: __hash__(self)


      A generic hashing implementation for all queries without parameters


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



   .. method:: __str__(self)


      Return str(self).



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

   Bases: :class:`khard.query.Query`

   A query to combine multible queries with "or".

   .. method:: match(self, thing: Union[str, 'carddav_object.CarddavObject'])


      Match the self query against the given thing


   .. method:: get_term(self)


      Extract the search terms from a query.


   .. method:: __eq__(self, other: object)


      A generic equality for all query types without parameters


   .. method:: __hash__(self)


      A generic hashing implementation for all queries without parameters


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



   .. method:: __str__(self)


      Return str(self).



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

   Bases: :class:`khard.query.TermQuery`

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

   .. method:: match(self, thing: Union[str, 'carddav_object.CarddavObject'])


      Match the self query against the given thing


   .. method:: __eq__(self, other: object)


      A generic equality for all query types without parameters


   .. method:: __hash__(self)


      A generic hashing implementation for all queries without parameters


   .. method:: __str__(self)


      Return str(self).



.. 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