From 2c1d42a0906d97fd6269fd3811c585591ee52354 Mon Sep 17 00:00:00 2001 From: Lin Zhihao <59785146+LinZhihao-723@users.noreply.github.com> Date: Wed, 12 Jun 2024 22:51:25 -0400 Subject: [PATCH] Docs: Clean-up docstrings for wildcard query methods and classes introduced in #62. (#63) Co-authored-by: Kirk Rodrigues <2454684+kirkrodrigues@users.noreply.github.com> --- clp_ffi_py/ir/query_builder.py | 9 ++-- clp_ffi_py/wildcard_query.py | 50 ++++++++++++-------- docs/src/api/clp_ffi_py.ir.query_builder.rst | 39 +++++++++++++-- 3 files changed, 69 insertions(+), 29 deletions(-) diff --git a/clp_ffi_py/ir/query_builder.py b/clp_ffi_py/ir/query_builder.py index 5b216bda..413b47da 100644 --- a/clp_ffi_py/ir/query_builder.py +++ b/clp_ffi_py/ir/query_builder.py @@ -9,9 +9,9 @@ from clp_ffi_py.ir.native import Query from clp_ffi_py.wildcard_query import FullStringWildcardQuery, WildcardQuery -_add_wildcard_query_deprecation_warning_message: str = "The wildcard query must be explicitly " -"created and passed as a parameter to this function. QueryBuilder should only accept instances of " -"`clp_ffi_py.wildcard_query.WildcardQuery`." +_add_wildcard_query_deprecation_warning_message: str = "Instead, use :meth:`add_wildcard_query`" +" with either a :class:`~clp_ffi_py.wildcard_query.FullStringWildcardQuery` or " +" :class:`~clp_ffi_py.wildcard_query.SubstringWildcardQuery`." class QueryBuilderException(Exception): @@ -115,9 +115,6 @@ class of :class:`~clp_ffi_py.wildcard_query.WildcardQuery`. def add_wildcard_query( self, wildcard_query: Union[str, WildcardQuery], case_sensitive: bool = False ) -> QueryBuilder: - """ - This method is the implementation of `add_wildcard_query`. - """ if isinstance(wildcard_query, WildcardQuery): self._wildcard_queries.append(wildcard_query) return self diff --git a/clp_ffi_py/wildcard_query.py b/clp_ffi_py/wildcard_query.py index f6737bce..64c34772 100644 --- a/clp_ffi_py/wildcard_query.py +++ b/clp_ffi_py/wildcard_query.py @@ -5,31 +5,32 @@ class WildcardQuery: """ - This class defines an abstract wildcard query. It includes a wildcard string - and a boolean value to indicate if the match is case-sensitive. + An abstract class defining a wildcard query. Users should instantiate a + wildcard query through :class:`SubstringWildcardQuery` or + :class:`FullStringWildcardQuery`. - A wildcard string may contain the following types of supported wildcards: + A wildcard string may contain the following types of wildcards: 1. '*': match 0 or more characters. 2. '?': match any single character. Each wildcard can be escaped using a preceding '\\\\' (a single backslash). - Other characters which are escaped are treated as normal characters. + Other characters that are escaped are treated as normal characters. """ @deprecated( version="0.0.12", - reason="`clp_ffi_py.wildcard_query.WildcardQuery` is supposed to be an abstract class and" - " should not be used directly. To create a wildcard query, please explicit instantiate" - " `clp_ffi_py.wildcard_query.SubstringWildcardQuery` or" - " `clp_ffi_py.wildcard_query.FullStringWildcardQuery`.", + reason=":class:`WildcardQuery` will soon be made abstract and should" + " not be used directly. To create a wildcard query, use" + " :class:`SubstringWildcardQuery` or :class:`FullStringWildcardQuery`" + " instead.", ) def __init__(self, wildcard_query: str, case_sensitive: bool = False): """ Initializes a wildcard query using the given parameters. :param wildcard_query: Wildcard query string. - :param case_sensitive: Case sensitive indicator. + :param case_sensitive: Whether to perform case-sensitive matching. """ self._wildcard_query: str = wildcard_query self._case_sensitive: bool = case_sensitive @@ -60,12 +61,12 @@ def case_sensitive(self) -> bool: class SubstringWildcardQuery(WildcardQuery): """ - This class defines a substring wildcard query. + A wildcard query that can match a substring in a log event's message, in + contrast with :class:`FullStringWildcardQuery` where the query needs to + match the entire message. - It is derived from - :class:`~clp_ffi_py.WildcardQuery`, adding both a prefix and a postfix - wildcard ("*") to the input wildcard string. This allows the query to match - any substring within a log message. + This class is derived from :class:`WildcardQuery` by adding both a prefix + and a postfix wildcard ("*") to the input wildcard string. """ def __init__(self, substring_wildcard_query: str, case_sensitive: bool = False): @@ -73,7 +74,7 @@ def __init__(self, substring_wildcard_query: str, case_sensitive: bool = False): Initializes a substring wildcard query using the given parameters. :param substring_wildcard_query: Wildcard query string. - :param case_sensitive: Case sensitive indicator. + :param case_sensitive: Whether to perform case-sensitive matching. """ substring_wildcard_query = "*" + substring_wildcard_query + "*" with warnings.catch_warnings(): @@ -83,15 +84,24 @@ def __init__(self, substring_wildcard_query: str, case_sensitive: bool = False): class FullStringWildcardQuery(WildcardQuery): """ - This class defines a full string wildcard query. + A wildcard query where the query must match the entirety of the log event's + message, in contrast with :class:`SubstringWildcardQuery` where the query + only needs to match a substring. - It is derived from - :class:`~clp_ffi_py.WildcardQuery`, and uses the input wildcard string - directly to create the query. This ensures that the query matches only the - entire log message. + This class is derived from :class:`WildcardQuery` as a more explicit + interface for full-string matches. + + Users can create a match that's anchored to only one end of the message by + adding a prefix OR postfix wildcard ("*"). """ def __init__(self, full_string_wildcard_query: str, case_sensitive: bool = False): + """ + Initializes a full-string wildcard query using the given parameters. + + :param full_string_wildcard_query: Wildcard query string. + :param case_sensitive: Whether to perform case-sensitive matching. + """ with warnings.catch_warnings(): warnings.simplefilter("ignore", DeprecationWarning) super().__init__(full_string_wildcard_query, case_sensitive) diff --git a/docs/src/api/clp_ffi_py.ir.query_builder.rst b/docs/src/api/clp_ffi_py.ir.query_builder.rst index b949a602..85ab2632 100644 --- a/docs/src/api/clp_ffi_py.ir.query_builder.rst +++ b/docs/src/api/clp_ffi_py.ir.query_builder.rst @@ -2,6 +2,39 @@ clp\_ffi\_py.ir.query\_builder module ===================================== .. automodule:: clp_ffi_py.ir.query_builder - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: + :exclude-members: QueryBuilder + + .. autoclass:: QueryBuilder + :members: + :undoc-members: + :show-inheritance: + :exclude-members: __init__, __new__, add_wildcard_query + + .. method:: add_wildcard_query(wildcard_query: WildcardQuery) -> QueryBuilder + + Adds the given wildcard query to the wildcard query list. + + :param WildcardQuery wildcard_query: The wildcard query object to add. + :returns: self. + :rtype: QueryBuilder + + .. method:: add_wildcard_query(wildcard_query: str, case_sensitive: bool = False) \ + -> QueryBuilder + :no-index: + + Constructs and adds a :class:`~clp_ffi_py.wildcard_query.WildcardQuery` to the wildcard + query list. + + .. deprecated:: 0.0.12 + Use :meth:`add_wildcard_query` with either a + :class:`~clp_ffi_py.wildcard_query.FullStringWildcardQuery` or + :class:`~clp_ffi_py.wildcard_query.SubstringWildcardQuery` + instead. + + :param str wildcard_query: The wildcard query string to add. + :param bool case_sensitive: Whether to perform case-sensitive matching. + :returns: self. + :rtype: QueryBuilder