From df2e0941c80ffa6cd62fb86a7fba28f50d65725b Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 15:21:24 +0200 Subject: [PATCH 01/12] environment.py : rtype and function doc (part) --- src/bootstraparse/modules/environment.py | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/src/bootstraparse/modules/environment.py b/src/bootstraparse/modules/environment.py index dae7f84..fad2769 100644 --- a/src/bootstraparse/modules/environment.py +++ b/src/bootstraparse/modules/environment.py @@ -26,6 +26,10 @@ class Environment: """ def __init__(self): + """ + Initialises the environment, all parameters are set to None. + Set _wasInitialised to False for all parameters. + """ # mandatoryParameters self._mParams = { 'config': None, @@ -60,8 +64,10 @@ class Environment: def __getattr__(self, attribute): """ - Getter for all parameters. + Getter for all parameters, looks for super if the parameter is prefaced with an underscore. + Looks for mandatory parameters first, then secondary parameters. :param attribute: The name of the parameter to get. + :type attribute: str :return: The value of the parameter. """ if attribute[0] == "_": @@ -80,8 +86,9 @@ class Environment: def __setattr__(self, attribute, value): """ - Setter for all parameters. + Setter for all parameters, looks for super if the parameter is prefaced with an underscore. :param attribute: The name of the parameter to set. + :type attribute: str """ if attribute[0] == "_": super().__setattr__(attribute, value) From e64c6d7f41745e507b2c85e2ee9faf77d2dc433c Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 15:21:46 +0200 Subject: [PATCH 02/12] error_mngr.py : rtype and function doc (part) --- src/bootstraparse/modules/error_mngr.py | 57 +++++++++++++++++++------ 1 file changed, 44 insertions(+), 13 deletions(-) diff --git a/src/bootstraparse/modules/error_mngr.py b/src/bootstraparse/modules/error_mngr.py index 83eed01..0e95ae7 100644 --- a/src/bootstraparse/modules/error_mngr.py +++ b/src/bootstraparse/modules/error_mngr.py @@ -21,11 +21,14 @@ __all__ = _ERRORS+[] def init_logging(filename=None, loglevel="ERROR", filemode='w', handler=None): """ Initializes logging - :param filename: The name of the log file - :param loglevel: The level of logging - :type loglevel: str - :param filemode: The mode of the log file + :param filename: The path for the log file + :param loglevel: The level of logging: "ERROR", "INFO", "WARNING", "DEBUG", "CRITICAL" + :param filemode: The mode of the log file: "w", "a" :param handler: The handler to use + :type filename: str + :type loglevel: str + :type filemode: str + :type handler: logging.Handler :return: None """ loglevel = loglevel.upper() @@ -50,6 +53,7 @@ def log_message(message, level="ERROR"): :param message: The message to log :param level: The level of the message :type level: str + :type message: str :return: None """ level = level.lower() @@ -85,9 +89,11 @@ def log_exception(exception, level="ERROR"): def dict_check(dic, *args): """ - Helper function to test existence within a dictionary. + Helper function to test existence of a list of succesive keys within a nested dictionary. :param dic: The dictionary of dictionaries to check :param args: Any number of keys to check the dictionaries for + :type dic: dict | config.ConfigLoader + :type args: str :return: A table of Booleans for every key checked. """ output = [False for _ in args] @@ -102,33 +108,45 @@ def dict_check(dic, *args): def str_dict_check(dic, *args): """ - Helper function to test existence within a dictionary and return a string of the values. + Helper function to test existence within a dictionary and return a string of the values of the keys checked + and wether they exist. 'arg[0]' : True or False - + :param dic: The nested dictionary to check + :param args: Any number of keys to check successively + :type dic: dict + :type args: str + :return: A string of the values of the keys checked and wether they exist. + :rtype: str """ out = dict_check(dic, *args) return "\n".join([f"{args[i]}: {out[i]}" for i in range(len(out))]) class BootstraparseError(Exception): + """ + Base class for all Bootstraparse errors + """ pass class ParsingError(Exception): """ Exception class for parsing errors - :param message: The message to display - :type message: str - :param line: The line number of the error - :param column: The column number of the error - :param file: The name of the file - :return: None """ def __init__(self, message=None, line=None, column=None, file=None): """ Initializes the ParsingError class with the filename and a line and column number based on the current position in the file (if available) + :param message: The message to display + :type message: str + :param line: The line number of the error + :type line: int + :param column: The column number of the error + :type column: int + :param file: The name of the file + :type file: str + :return: None """ super().__init__(message) self.line = line @@ -154,6 +172,11 @@ class MismatchedContainerError(BootstraparseError): The token is not final and cannot be contained. Indicative of a mismatched token. """ def __init__(self, token): + """ + Initializes the MismatchedContainerError class with the token that was not final + :param token: The token that is not final + :type token: syntax.SemanticType + """ self.token = token if token: self.line = token.line_number @@ -171,6 +194,14 @@ class LonelyOptionalError(BootstraparseError): Optional token could not be matched with last element in pile (not a container). """ def __init__(self, token, last_in_pile): + """ + Initializes the LonelyOptionalError class with the token found and the last element in the pile + Used when a token is found that is optional and cannot be matched with the last element in the pile (not a container) + :param token: The token that is not final + :type token: syntax.SemanticType + :param last_in_pile: The last element in the pile + :type last_in_pile: syntax.SemanticType + """ self.token = token if token: self.line = token.line_number From 43db9f7a09acc23ea45b0c05f1c8fc9e38915f7b Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 15:21:56 +0200 Subject: [PATCH 03/12] export.py : rtype and function doc (part) --- src/bootstraparse/modules/export.py | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/src/bootstraparse/modules/export.py b/src/bootstraparse/modules/export.py index d17de30..f5e18c2 100644 --- a/src/bootstraparse/modules/export.py +++ b/src/bootstraparse/modules/export.py @@ -5,7 +5,6 @@ # rsp = ExportResponse("start_string", "end_string") # em = ExportManager(config_file, template_file) # em(ExportRequest()) -> ExportResponse() -# import rich import rich from io import StringIO @@ -47,7 +46,14 @@ class ExportManager: """ Transforms ExportRequest tuples to ExportResponse tuples with the config-provided appropriate markup. """ - def __init__(self, cnoifg, templates): # noqa + def __init__(self, cnoifg, templates): + """ + Initialization function for the ExportManager. + :param cnoifg: Config file + :type cnoifg: config.ConfigLoader + :param templates: Templates file + :type templates: config.ConfigLoader + """ self.config = cnoifg self.templates = templates self.advanced_export = { @@ -61,6 +67,12 @@ class ExportManager: } def __call__(self, export_request): + """ + Callable function for ExportManager, transforming ExportRequest tuples into ExportResponse tuples. + :param export_request: ExportRequest tuples + :type export_request: ExportRequest + :return: ExportResponse tuples + """ return self.transform(export_request) def transform(self, export_request): @@ -151,6 +163,7 @@ class ExportManager: """ Specific template for display. :type export_request: ExportRequest + :rtype: ExportResponse """ start, end, optionals = self._get_template(export_request) start = start.format(optionals=optionals, display_level=export_request.others["display_level"]) @@ -160,6 +173,7 @@ class ExportManager: """ Specific template for link. :type export_request: ExportRequest + :rtype: ExportResponse """ start, end, _ = self._get_template(export_request) start = start.format(url=export_request.others["url"]) @@ -169,6 +183,7 @@ class ExportManager: """ Specific template for table content. :type export_request: ExportRequest + :rtype: ExportResponse """ start, end, _ = self._get_template(export_request) start = start.format(col_span=export_request.others["col_span"]) @@ -178,6 +193,7 @@ class ExportManager: """ Specific template for images. :type export_request: ExportRequest + :rtype: ExportResponse """ start, end, optionals = self._get_template(export_request) end = end.format(optionals=optionals) @@ -197,6 +213,8 @@ class ContextConverter: pile output from the context manager. exporter : ExportManager Our ExportManager + destination : str + Destination of the output file. """ self.io_output = StringIO() self.pile = pile @@ -206,7 +224,8 @@ class ContextConverter: def process_pile(self): """ - Main method processing the given pile. + Processes the pile and writes the output to the io_output object. + :rtype: StringIO """ for container in self.pile: self.io_output.write(container.export(self.exporter)) @@ -224,6 +243,7 @@ class ContextConverter: def readlines(self): """ Yields the converted pile line after line + :rtype: list[str] """ return self.io_output.readlines() @@ -232,6 +252,9 @@ class ContextConverter: f"Status: {'initialized' if self.io_initialized else 'uninitialized'}" def print_all(self): + """ + Prints the entirety of the converted pile + """ print(self) def __eq__(self, other): From c4ee5f1e43a66ba55872549156ed83a2e2e35377 Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 15:22:09 +0200 Subject: [PATCH 04/12] pathresolver.py : rtype and function doc (part) --- src/bootstraparse/modules/pathresolver.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/bootstraparse/modules/pathresolver.py b/src/bootstraparse/modules/pathresolver.py index 51c166a..4ab0914 100644 --- a/src/bootstraparse/modules/pathresolver.py +++ b/src/bootstraparse/modules/pathresolver.py @@ -12,16 +12,21 @@ import os class PathResolver: """ Initialised with a relative path and returns the translated absolute path - :param base_path: Relative path to be resolved """ def __init__(self, base_path): + """ + Initialises the PathResolver with the base path + :param base_path: Base path + :type base_path: str + """ self.base_path = os.path.normpath(os.path.join(os.getcwd(), os.path.dirname(base_path))) def __call__(self, relative_path='.'): """ Returns the absolute path of the relative path :param relative_path: Relative path to be resolved + :type relative_path: str :return: Absolute path """ return self.give_absolute(relative_path) @@ -30,6 +35,7 @@ class PathResolver: """ Returns the absolute path of the relative path :param relative_path: Relative path to be resolved + :type relative_path: str :return: Absolute path """ return os.path.normpath(os.path.join(self.base_path, relative_path)) From 1fa28a41a756264aabc0ed6acf287a2e9a7d4835 Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 16:35:04 +0200 Subject: [PATCH 05/12] Added __init__.py --- src/bootstraparse/__init__.py | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 src/bootstraparse/__init__.py diff --git a/src/bootstraparse/__init__.py b/src/bootstraparse/__init__.py new file mode 100644 index 0000000..e69de29 From c52b7c959fa823ef92358daf230f9473e0c489ea Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 16:35:26 +0200 Subject: [PATCH 06/12] Typos --- src/bootstraparse/modules/context_mngr.py | 4 ++-- src/bootstraparse/modules/error_mngr.py | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/src/bootstraparse/modules/context_mngr.py b/src/bootstraparse/modules/context_mngr.py index 2cd6d5b..4a0e29b 100644 --- a/src/bootstraparse/modules/context_mngr.py +++ b/src/bootstraparse/modules/context_mngr.py @@ -130,7 +130,7 @@ class BaseContainer: def __iter__(self): """ - :rtype : iter[syntax.SemanticType] + :ytype : iter[syntax.SemanticType] """ for content in self.content: yield content @@ -617,7 +617,7 @@ class ContextManager: def __iter__(self): """ Iterator over the pile. - :rtype: BaseContainer + :ytype: BaseContainer """ for e in self.pile: if e: diff --git a/src/bootstraparse/modules/error_mngr.py b/src/bootstraparse/modules/error_mngr.py index 0e95ae7..837b99b 100644 --- a/src/bootstraparse/modules/error_mngr.py +++ b/src/bootstraparse/modules/error_mngr.py @@ -15,7 +15,6 @@ from bootstraparse.modules.tools import __GLk # __GFi, __GFu, __GL # Define the error codes _ERRORS = ["ParsingError", "MismatchedContainerError"] -__all__ = _ERRORS+[] def init_logging(filename=None, loglevel="ERROR", filemode='w', handler=None): From d1f4eaa6f259eb3353ad1de4596be51ba8652d11 Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 16:36:16 +0200 Subject: [PATCH 07/12] preparser.py : Doc and rtypes --- src/bootstraparse/modules/preparser.py | 61 ++++++++++++++++++++------ 1 file changed, 47 insertions(+), 14 deletions(-) diff --git a/src/bootstraparse/modules/preparser.py b/src/bootstraparse/modules/preparser.py index 47392ec..22ba02c 100644 --- a/src/bootstraparse/modules/preparser.py +++ b/src/bootstraparse/modules/preparser.py @@ -15,7 +15,7 @@ from io import StringIO from bootstraparse.modules import pathresolver as pr from bootstraparse.modules import environment from bootstraparse.modules import syntax -from bootstraparse.modules import error_mngr # noqa # pylint: disable=unused-import +from bootstraparse.modules import error_mngr from bootstraparse.modules import export import rich @@ -37,6 +37,10 @@ class PreParser: :param _env: the environment object :param list_of_paths: the list of files that have been imported in this branch of the import tree :param dict_of_imports: Dictionary of all imports made to avoid duplicate file opening / pre-parsing + :type file_path: str + :type _env: environment.Environment + :type list_of_paths: list[str] + :type dict_of_imports: dict[str, PreParser] """ if list_of_paths is None: list_of_paths = [] @@ -75,7 +79,6 @@ class PreParser: def make_temporary_files(self): """ Creates temporary files for the import list and the replacement. - :return: None """ self.file_with_all_imports = StringIO() self.file_with_all_replacements = StringIO() @@ -86,13 +89,14 @@ class PreParser: """ Make new temporary files, if the old one are not referenced, the garbage collector will delete them. - :return: None """ self.make_temporary_files() def do_imports(self): """ Execute all actions needed to do the imports and setup for the next step + :return: The file descriptor of the file with all imports + :rtype: StringIO """ self.parse_import_list() self.make_import_list() @@ -103,6 +107,8 @@ class PreParser: def do_replacements(self): """ Execute all actions needed to do the replacements. + :return: The file descriptor of the file with all replacements + :rtype: StringIO """ self.do_imports() self.parse_shortcuts_and_images() @@ -112,7 +118,8 @@ class PreParser: def readlines(self): """ Reads the original file and returns a list of lines. - :return: A list of lines + :return: a list of lines + :rtype: list[str] """ with open(self.relative_path_resolver(self.name), 'r') as f: return f.readlines() @@ -121,6 +128,7 @@ class PreParser: """ Get the lines from the file on the step you are in :return: A list of lines + :rtype: list[str] """ if self.current_origin_for_read is None: return self.readlines() @@ -133,6 +141,7 @@ class PreParser: Makes sure that the files are not already imported through a previous import statement. Recursively build a list of PreParser object for each file to be imported. :return: the dictionary of all files to be imported (key: file name, value: PreParser object) + :rtype: dict[str, PreParser] """ import_list = self.parse_import_list() if self.is_global_dict_of_imports_initialized: @@ -162,7 +171,8 @@ class PreParser: def parse_import_list(self): """ Parses the import list of the file. - :return: a list of files to be imported + :return: a list of files to be imported, and the line number of the import statement + :rtype: list[(str, int)] """ if self.saved_import_list: return self.saved_import_list @@ -183,6 +193,7 @@ class PreParser: """ Return the file object with all file imports done :return: a filelike object with all file imports done + :rtype: StringIO """ self.make_import_list() @@ -217,7 +228,8 @@ class PreParser: """ Parses through the output files from export_with_imports and replaces shortcuts and images calls with appropriate html - :return: a table of occurrences and their lines + :return: The file descriptor of the file with all replacements + :rtype: StringIO """ temp_file = self.file_with_all_imports temp_text = '' @@ -238,7 +250,10 @@ class PreParser: def get_element_from_config(self, *list_keys): """ - Fetches an element from the config + Fetches an element from the config (a nested dictionary) going through the list of keys + Raises an error if the element is not found + :param list_keys: the list of keys to go through the config + :type list_keys: str """ sub_dict = self._env.config.loaded_conf validated_elements = [] @@ -258,6 +273,12 @@ class PreParser: def make_replacements(message, *var_list, **var_dict): """ Tries to format the message or give an error message and return the original message + :param message: the message to format + :type message: str + :param var_list: the list of variables to replace in the message + :type var_list: str + :keyword var_dict: the dictionary of variables to replace in the message + :type var_dict: dict[str, str] """ try: return message.format(*var_list, **var_dict) @@ -271,10 +292,13 @@ class PreParser: def get_alias_from_config(self, shortcut, optionals): """ - Fetches shortcut paths from aliases.yaml - :return: the html to insert as a string + Returns the alias from the config and makes the replacements with the options provided :param shortcut: id of the shortcut to fetch + :type shortcut: str :param optionals: optional parameters along with alias + :type optionals: syntax.Optional + :return: the html to insert as a string + :rtype: str """ output = self.get_element_from_config('aliases', 'shortcuts', shortcut) _, _, var_list, var_dict = syntax.split_optionals(optionals) @@ -283,10 +307,12 @@ class PreParser: def get_image_from_config(self, shortcut, optionals): """ - Fetches image paths from aliases.yaml - :return: html to insert as a string - :param shortcut: the id of the picture to fetch + Returns the image from the config and makes the replacements with the options provided + :param shortcut: id of the image to fetch + :type shortcut: str :param optionals: optional parameters along with image + :type optionals: syntax.Optional + :return: the html to insert as a string """ shortcut_s = self.get_element_from_config('aliases', 'images', shortcut) @@ -299,7 +325,6 @@ class PreParser: def __repr__(self): """ Returns a string representation of the PreParser object. - :return: a string representation of the PreParser object """ return "PreParser[{}](path={}, name={}, base_path={}, " \ "relative_path_resolver={}, list_of_paths={}, " \ @@ -311,7 +336,6 @@ class PreParser: def __str__(self): """ Returns a string representation of the PreParser object. - :return: a string representation of the PreParser object """ return self.__repr__() @@ -334,6 +358,7 @@ class PreParser: """ Checks if the PreParser object is not equal to another PreParser object. :param other: the other PreParser object + :type other: PreParser :return: True if the PreParser objects are not equal, False otherwise """ return not self.__eq__(other) @@ -341,6 +366,14 @@ class PreParser: def rich_tree(self, prefix="", suffix="", force=True, strip_prefix=""): """ Returns a rich representation of the PreParser object. + :param prefix: the prefix to add to the representation + :type prefix: str + :param suffix: the suffix to add to the representation + :type suffix: str + :param force: if True, the representation is always computed, even if it has already been done + :type force: bool + :param strip_prefix: the prefix to remove from the path + :type strip_prefix: str :return: a rich representation of the PreParser object """ unparsed = False From 00786d84801deed797225684e1d211e5557b3510 Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 16:41:58 +0200 Subject: [PATCH 08/12] Continuous integration of list --- .github/workflows/python-app.yml | 42 ++++++++++++++--------------- .github/workflows/python-deploy.yml | 37 +++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 21 deletions(-) create mode 100644 .github/workflows/python-deploy.yml diff --git a/.github/workflows/python-app.yml b/.github/workflows/python-app.yml index f0b2e45..a14589d 100644 --- a/.github/workflows/python-app.yml +++ b/.github/workflows/python-app.yml @@ -1,7 +1,7 @@ # This workflow will install Python dependencies, run tests and lint with a single version of Python # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions -name: Python application +name: Python Tests and Lint on: push: @@ -40,23 +40,23 @@ jobs: - name: Test with pytest run: | pytest --cov-fail-under=100 -o xfail_strict=true --cov-report=term-missing . - deployment: - runs-on: ubuntu-latest - environment: production - steps: - - uses: actions/checkout@v2 - - name: Set up Python 3.10 - uses: actions/setup-python@v2 - with: - python-version: "3.10" - - name: Build the application - run: | - python -m pip install --upgrade pip - pip install -r requirements.txt - pip install -e . - python -m bootstraparse "example_userfiles" "docs" - - name: deploy - uses: JamesIves/github-pages-deploy-action@v4.3.3 - with: - branch: gh-pages # The branch the action should deploy to. - folder: docs +# deployment: +# runs-on: ubuntu-latest +# environment: production +# steps: +# - uses: actions/checkout@v2 +# - name: Set up Python 3.10 +# uses: actions/setup-python@v2 +# with: +# python-version: "3.10" +# - name: Build the application +# run: | +# python -m pip install --upgrade pip +# pip install -r requirements.txt +# pip install -e . +# python -m bootstraparse "example_userfiles" "docs" +# - name: deploy +# uses: JamesIves/github-pages-deploy-action@v4.3.3 +# with: +# branch: gh-pages # The branch the action should deploy to. +# folder: docs diff --git a/.github/workflows/python-deploy.yml b/.github/workflows/python-deploy.yml new file mode 100644 index 0000000..6160295 --- /dev/null +++ b/.github/workflows/python-deploy.yml @@ -0,0 +1,37 @@ +# This workflow will install Python dependencies, run tests and lint with a single version of Python +# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions + +name: Python Deployment + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + + +jobs: + deployment: + runs-on: ubuntu-latest + environment: production + steps: + - uses: actions/checkout@v2 + - name: Set up Python 3.10 + uses: actions/setup-python@v2 + with: + python-version: "3.10" + - name: Build the application + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + pip install -e . + pip install pydoctor + python -m bootstraparse "example_userfiles" "docs" + - name: Build the documentation + run: | + pydoctor --make-html --html-output=docs/apidoc src/bootstraparse/ + - name: deploy + uses: JamesIves/github-pages-deploy-action@v4.3.3 + with: + branch: gh-pages # The branch the action should deploy to. + folder: docs From dfc8a7b2d2c11c597075cea1b9093942f863ef7f Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 16:57:44 +0200 Subject: [PATCH 09/12] sitecrawler.py : Doc and rtypes --- src/bootstraparse/modules/sitecrawler.py | 49 ++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/src/bootstraparse/modules/sitecrawler.py b/src/bootstraparse/modules/sitecrawler.py index 4470dac..6246f16 100644 --- a/src/bootstraparse/modules/sitecrawler.py +++ b/src/bootstraparse/modules/sitecrawler.py @@ -4,7 +4,22 @@ from bootstraparse.modules import pathresolver, preparser, error_mngr, environme class SiteCrawler: + """ + A sitecrawler is a generator that yields a tuple of the form (PreParser, file) + Its goal is to create a list of preparsers and files to be parsed based on + the files and directories in the initial path. + This generator is to be used in a for loop to parse all the files and produce + the final website. + """ def __init__(self, path, destination, _env): + """ + :param path: The path to the directory to be crawled + :param destination: The path to the directory where the website will be created + :param _env: The environment object + :type path: str + :type destination: str + :type _env: environment.Environment + """ if not os.path.exists(path): error_mngr.log_exception( FileNotFoundError(f'The specified path "{path}" could not be found.'), @@ -32,9 +47,23 @@ class SiteCrawler: self.create_all_paths() def get_all_paths(self): + """ + This method is used to get all the paths to be crawled. + Its goal is to get all the paths to be crawled and to store them in + the self.directories and self.files variables. + """ self.files, self.directories = self.list_recursively(self.initial_path, self.initial_path) def list_recursively(self, path, root): + """ + Recursive method to get all the paths to be crawled. + :param path: The current path to be crawled + :param root: The root path (initial path) + :type path: str + :type root: str + :return: A tuple of the form (files, directories) + :rtype: (list[(str, str)], list[(str, str)]) + """ files = [] directories = [] for element in os.listdir(path): @@ -52,6 +81,9 @@ class SiteCrawler: return files, directories def create_all_paths(self): + """ + This method is used to create all the directories in the destination path. + """ if not os.path.exists(self.destination_path): os.mkdir(self.destination_path) for root, di in self.directories: @@ -60,6 +92,12 @@ class SiteCrawler: os.mkdir(temp_path) def set_all_preparsers(self): + """ + This method is used to set all the preparsers and initialize them. + The preparsers are stored in the self.preparsers variable. + :return: self.preparsers + :rtype: list[preparser.PreParser] + """ for root, file in self.files: preparser_path = os.path.join(self.initial_path, root, file) pp = preparser.PreParser(preparser_path, self._env, dict_of_imports=self.global_dict_of_imports) @@ -70,6 +108,12 @@ class SiteCrawler: return self.preparsers def create_file(self, path): + """ + This method is used to create a file. + :raises FileExistsError: If the file already exists and the force_rewrite option is False + :param path: The path to the file to be created + :type path: str + """ if os.path.exists(path): if not self.force_rewrite: error_mngr.log_exception( @@ -81,6 +125,11 @@ class SiteCrawler: return path def __iter__(self): + """ + This method is used to iterate over the preparsers and files. + :yield: A tuple of the form (PreParser, file) + :ytype: (preparser.PreParser, str) + """ for pre in self.preparsers: yield pre From 6100f716b530bf03db8d6419109c0607ef73fa5b Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 17:16:23 +0200 Subject: [PATCH 10/12] Test doc --- tests/modules/test_preparser.py | 4 ++-- tests/modules/test_sitecrawler.py | 10 +++++++++- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/tests/modules/test_preparser.py b/tests/modules/test_preparser.py index dec0fb9..c43bb43 100644 --- a/tests/modules/test_preparser.py +++ b/tests/modules/test_preparser.py @@ -246,7 +246,7 @@ def test_make_import_list(filename, content, capsys): ]) def test_preparser_content(filename, content): """ - Test the preparser content + Test the PreParser content """ testfile = temp_name(os.path.join(_BASE_PATH_GIVEN, filename)) assert os.path.exists(testfile) @@ -258,7 +258,7 @@ def test_preparser_content(filename, content): def test_subfolder_parsing(): """ - Test the preparser content + Test the PreParser content """ testfile = temp_name(os.path.join(_BASE_PATH_GIVEN, "superimports.bpr")) assert os.path.exists(testfile) diff --git a/tests/modules/test_sitecrawler.py b/tests/modules/test_sitecrawler.py index 5602f75..d4e0335 100644 --- a/tests/modules/test_sitecrawler.py +++ b/tests/modules/test_sitecrawler.py @@ -24,7 +24,15 @@ files = [ def make_new_file(path, content="", mode="w+"): """ - Make a new file + Make a new file and all the directories in the path + :param path: the path to the file + :type path: str + :param content: the content of the file + :type content: str + :param mode: the mode of the file + :type mode: str + :return: the path to the file + :rtype: str """ name = os.path.join(_TEMP_DIRECTORY.name, path) os.makedirs(os.path.dirname(name), exist_ok=True) From ef9b53fcbc8faf0645227a860a114ed7b75d4475 Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 17:16:34 +0200 Subject: [PATCH 11/12] sitecreator.py : Doc and rtypes --- src/bootstraparse/modules/sitecreator.py | 35 ++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/src/bootstraparse/modules/sitecreator.py b/src/bootstraparse/modules/sitecreator.py index 67494cc..ecaec58 100644 --- a/src/bootstraparse/modules/sitecreator.py +++ b/src/bootstraparse/modules/sitecreator.py @@ -8,6 +8,11 @@ def create_website(origin, destination): """ First function called by bparse.py, calls all other modules in the right order. + :param origin: The path of the website to be built. + :param destination: The destination path of the built website. + :type origin: str + :type destination: str + :return: 0 if everything went well, 1 otherwise. """ env = create_environment(origin, destination) crwlr = create_crawler(origin, destination, env) @@ -22,6 +27,12 @@ def create_environment(origin, destination): """ Returns parserEnvironment as an object containing everything needed for app execution. + :param origin: The path of the website to be built. + :param destination: The destination path of the built website. + :type origin: str + :type destination: str + :return: Environment object. + :rtype: environment.Environment """ env = environment.Environment() env.config = config.ConfigLoader(pathresolver.b_path("configs")) @@ -42,11 +53,26 @@ def create_environment(origin, destination): def create_crawler(origin, destination, _env): """ Returns crawler as an object for navigation in the user files. + :param origin: The path of the website to be built. + :param destination: The destination path of the built website. + :param _env: The environment object. + :type origin: str + :type destination: str + :type _env: environment.Environment + :return: Crawler object. + :rtype: sitecrawler.SiteCrawler """ return sitecrawler.SiteCrawler(origin, destination, _env) def preparse_parse(preparser): + """ + Returns a list of containers from a preparser. + :param preparser: The preparser object. + :type preparser: parser.Preparser + :return: List of containers. + :rtype: list + """ io = preparser.do_replacements() parsed_list = parser.parse_line(io) output = context_mngr.ContextManager(parsed_list, name=preparser.name)() @@ -54,6 +80,15 @@ def preparse_parse(preparser): def save(list_of_containers, destination, env): + """ + Saves the list of containers in the destination path. + :param list_of_containers: The list of containers to be saved. + :param destination: The destination path. + :param env: The environment object. + :type list_of_containers: list + :type destination: str + :type env: environment.Environment + """ with open(destination, "w") as output_file: output_file.write(export.ContextConverter(list_of_containers, env.export_mngr, destination).process_pile().read()) From 0e86cc5ca4949c18847556169281840890992be5 Mon Sep 17 00:00:00 2001 From: Maximilien Rigaut Date: Thu, 9 Jun 2022 17:16:41 +0200 Subject: [PATCH 12/12] 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 """