From 0e86cc5ca4949c18847556169281840890992be5 Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 17:16:41 +0200 Subject: [PATCH] syntax.py : Doc and rtypes --- src/bootstraparse/modules/syntax.py | 32 ++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/src/bootstraparse/modules/syntax.py b/src/bootstraparse/modules/syntax.py index af7ba63..17e4842 100644 --- a/src/bootstraparse/modules/syntax.py +++ b/src/bootstraparse/modules/syntax.py @@ -29,6 +29,11 @@ class SemanticType: label = None def __init__(self, content): + """ + Initialises the token. + :param content: The content of the token. + :type content: list[pp.ParseResults] + """ self.content = content self.line_number = "Undefined" self.file_name = "Undefined" @@ -37,6 +42,8 @@ class SemanticType: def to_markup(self): """ Function used for testing and readability purposes. Replaces matched markup with html-like tags. + :return: The markup of the token. + :rtype: str """ if self.content: return_list = [] @@ -51,6 +58,8 @@ class SemanticType: def to_original(self): """ Return the original string of the token. + :return: The original string of the token. + :rtype: str """ return " ".join(self.content) @@ -79,6 +88,12 @@ class SemanticType: return not self.__eq__(other) def counterpart(self): # noqa # FUTURE: Check for static counterpart implementation + """ + Function called by the context manager to know how to deal with the encapsulation of the token. + Will return the counterpart of the token (the previous token to look for). + :return: The counterpart of the token. + :rtype: str | None + """ return None def to_container(self, filter_func=None): @@ -92,7 +107,7 @@ class SemanticType: Returns ------- - SemanticType + SemanticType | context_mngr.BaseContainer Self if containable, the expected replacement token if it can, raises an error otherwise. Raises ------ @@ -103,12 +118,18 @@ class SemanticType: class TokensToMatch(SemanticType): - """Class used for verification in the context manager. - Classes inheriting this should be added to matched_elements.""" + """ + Class used for verification in the context manager. + Classes inheriting this should be added to matched_elements. + """ pass class AddFirstElementToLabel(SemanticType): + """ + Class used for verification in the context manager. + Adds the first element of the content to the label (for matching purposes). + """ def __init__(self, content): super().__init__(content) self.label += ":" + content[0] @@ -330,7 +351,9 @@ def of_type(token_class): """ Function creating a custom function for generating the given Token type. :param token_class: SemanticType class + :type token_class: type :return: returns a function creating an instance of the given class + :rtype: function """ def _of_type(_, __, content): if len(content) == 0: # Drop Empty token @@ -344,7 +367,9 @@ def reparse(parse_element): """ Creates a function which reparses given match with specified parsing element. :param parse_element: pp object defining desired match + :type parse_element: pp.ParserElement :return: returns a function parsing given match with specified parsing element + :rtype: function """ def _reparse(__, _, tokens): return parse_element.parseString(tokens[0]) # Future: document this behaviour more in-depth @@ -392,6 +417,7 @@ def readable_markup(list_of_tokens): """ Function used for testing and readability purposes. Replaces matched markup with html-like tags. :param list_of_tokens: list of matched markup tokens in analysed text. + :type list_of_tokens: list :return: returns readable string. :rtype: string """