khard.query
===========

.. py:module:: khard.query

.. autoapi-nested-parse::

   Queries to match against contacts



Attributes
----------

.. autoapisummary::

   khard.query.FIELD_PHONE_NUMBERS


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


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

.. py:data:: FIELD_PHONE_NUMBERS
   :value: 'phone_numbers'


.. py:class:: Query

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


   .. py:method:: match(thing: Union[str, khard.contacts.Contact]) -> 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.contacts.Contact]) -> 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


.. py:class:: AnyQuery

   Bases: :py:obj:`Query`


   The match-anything-query, it always matches.


   .. py:method:: match(thing: Union[str, khard.contacts.Contact]) -> 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


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

   Bases: :py:obj:`Query`


   A query to match an object against a fixed string.


   .. py:attribute:: _term


   .. py:method:: match(thing: Union[str, khard.contacts.Contact]) -> 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


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

   Bases: :py:obj:`TermQuery`


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


   .. py:attribute:: _field


   .. py:method:: match(thing: Union[str, khard.contacts.Contact]) -> 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


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

   Bases: :py:obj:`Query`


   A query to combine multiple queries with "and".


   .. py:attribute:: _queries


   .. py:method:: match(thing: Union[str, khard.contacts.Contact]) -> 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


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

   Bases: :py:obj:`Query`


   A query to combine multiple queries with "or".


   .. py:attribute:: _queries


   .. py:method:: match(thing: Union[str, khard.contacts.Contact]) -> 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


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

   Bases: :py:obj:`TermQuery`


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


   .. py:attribute:: _props_query


   .. py:method:: match(thing: Union[str, khard.contacts.Contact]) -> 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


.. 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:attribute:: _term_only_digits


   .. py:method:: match(thing: Union[str, khard.contacts.Contact]) -> 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


.. 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.contacts.Contact` 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


