>{{blog-header-logo text-dark text-center border-bottom}}
+div>>{{row flex-nowrap justify-content-between align-items-center}}
+header>>{{blog-header py-3}}
+<
::< filename > syntax you can import another file and have it's contents dumped into your file.
+- Markup, a subset of markdown is already supported and the rest is incomming !
+- Aliases : With the @[alias_name] syntax you can create an alias for a string of text, with replacement capabilities.
+- Images: With the @{imagename} syntax you can specify an image template to import, with replacement capabilities.
+
+And much much more !
-Inline Element:
-[Link text]('http://this.is.a.link')
-*This is in italic*
-**This is strong**
-~~This is stricken through~~
-__This is underlined__
-(#1)This is a custom span(#1)
-
-
-Oneline elements:
-- This is an unordered list item
-- This is an unordered list item
-- This is an unordered list item{class='blue', 123}{{cinsertion}}[var='test', number=11]
-#. This is an ordered list item
-#. This is an ordered list item
-#. This is an ordered list item{class='blue', 123}{{cinsertion}}[var='test', number=11]
-
-This is a long text segment. This is a long text segment. This is a long text segment. This is a long text segment. This is a long text segment.
-This is still the same long text segment. This is still the same long text segment. This is still the same long text segment.
-
-Use a double linebreak to force linebreaks.
-
+We encourage you to read the [documentation]("apidoc/index.html") to learn more about bootstraparse
+or explore the [source code]("https://github.com/idle-org/bootstraparse")
+div>>{{nav-scroller py-1 mb-2}}
+div>>{{container}}
@[end]
diff --git a/setup.cfg b/setup.cfg
index 411d36e..c9948d3 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -2,15 +2,14 @@
name = bootstraparse
description = A custom markdown parser for Bootstrap & Python
author = Vkyfox
-version = 1.0.3
+version = 1.0.4
license = Mozilla Public License Version 2.0
license_file = LICENSE
platforms = unix, linux, osx, cygwin, win32
classifiers =
Programming Language :: Python :: 3
Programming Language :: Python :: 3 :: Only
- Programming Language :: Python :: 3.7
- Programming Language :: Python :: 3.8
+ Programming Language :: Python :: 3.10
Programming Language :: Python :: 3.9
[options]
@@ -19,7 +18,7 @@ packages =
bootstraparse.modules
install_requires =
pyyaml>=6.0
-python_requires = >=3.6
+python_requires = >=3.9
package_dir =
=src
diff --git a/src/bootstraparse/__init__.py b/src/bootstraparse/__init__.py
index e69de29..10ae695 100644
--- a/src/bootstraparse/__init__.py
+++ b/src/bootstraparse/__init__.py
@@ -0,0 +1,5 @@
+"""
+Bootstraparse is a tool to parse a folder and create a website from it.
+After installing it with pip, you can use it by running the following command:
+ - bootstraparse
+"""
diff --git a/src/bootstraparse/__main__.py b/src/bootstraparse/__main__.py
index d4028d3..bbee6dc 100755
--- a/src/bootstraparse/__main__.py
+++ b/src/bootstraparse/__main__.py
@@ -1,6 +1,6 @@
#!/usr/bin/python3
-# Main program, use this to start parsing
+""" Main program, use this to start parsing"""
from bootstraparse.modules import sitecreator, error_mngr
import argparse
diff --git a/src/bootstraparse/configs/parser_config.yml b/src/bootstraparse/configs/parser_config.yml
index e2d11c9..0f5778b 100644
--- a/src/bootstraparse/configs/parser_config.yml
+++ b/src/bootstraparse/configs/parser_config.yml
@@ -2,7 +2,7 @@ global:
template: "bootstrap.yml"
output: "example_site/"
bootstrap_version: "3.3.7"
- version: "1.0.3"
+ version: "1.0.4"
bootstrap_location: ""
logging:
diff --git a/src/bootstraparse/modules/__init__.py b/src/bootstraparse/modules/__init__.py
index e69de29..a8100a0 100644
--- a/src/bootstraparse/modules/__init__.py
+++ b/src/bootstraparse/modules/__init__.py
@@ -0,0 +1,3 @@
+"""
+The modules in this folder are used to parse the website.
+"""
diff --git a/src/bootstraparse/modules/config.py b/src/bootstraparse/modules/config.py
index b5eef6d..3f29cab 100644
--- a/src/bootstraparse/modules/config.py
+++ b/src/bootstraparse/modules/config.py
@@ -1,11 +1,11 @@
-# Interprets config files
-# The Config will be loaded by the environment at runtime and should be accessed that way
-# Usage:
-# from bootstraparse.modules.config import ConfigLoader
-# config = ConfigLoader([list of config files], extensions=[list of extensions])
-# config['file']['key']
-# The ConfigLoader class has load_from_file and load_from_folder methods and __getitem__ for accessing loaded elements
-
+"""Interprets config files
+The Config will be loaded by the environment at runtime and should be accessed that way
+Usage:
+ - from bootstraparse.modules.config import ConfigLoader
+ - config = ConfigLoader([list of config files], extensions=[list of extensions])
+ - config['file']['key']
+The ConfigLoader class has load_from_file and load_from_folder methods and __getitem__ for accessing loaded elements
+"""
import os
import rich
diff --git a/src/bootstraparse/modules/context_mngr.py b/src/bootstraparse/modules/context_mngr.py
index 7f1229b..fa787bc 100644
--- a/src/bootstraparse/modules/context_mngr.py
+++ b/src/bootstraparse/modules/context_mngr.py
@@ -1,16 +1,16 @@
-# Interprets where the parser is located and resolves errors
-# You're probably here for the ContextManager class.
-# Containers have class_name, debug_map and validate methods for debug,
-# self.content: accessible via __getitem__, __setitem__, add, __len__, __iter__ and __getslice__.
-# self.optionals: accessible via __rshift__ (remapped to return self.map[other]())
-# and self.map: accessible via __invert__ (remapped to return self.optionals)
-# Usage:
-# from bootstraparse.modules.context_mngr import ContextManager
-# ctx = ContextManager()
-# container = BaseContainer()
-# container[number] -> The number element in the content
-# "class_insert" >> container[number] -> Get an element from one of the mapped methods
-
+"""Interprets where the parser is located and resolves errors
+You're probably here for the ContextManager class.
+Containers have class_name, debug_map and validate methods for debug,
+ - self.content: accessible via __getitem__, __setitem__, add, __len__, __iter__ and __getslice__.
+ - self.optionals: accessible via __rshift__ (remapped to return self.map[other]())
+ - and self.map: accessible via __invert__ (remapped to return self.optionals)
+Usage:
+ - from bootstraparse.modules.context_mngr import ContextManager
+ - ctx = ContextManager()
+ - container = BaseContainer()
+ - container[number] -> The number element in the content
+ - "class_insert" >> container[number] -> Get an element from one of the mapped methods
+"""
from bootstraparse.modules import syntax, error_mngr, export
from bootstraparse.modules.error_mngr import MismatchedContainerError, log_exception, log_message, LonelyOptionalError # noqa
@@ -208,7 +208,7 @@ class BaseContainer:
:rtype : str
"""
return '{} ({})'.format(", ".join(map(str, self.content)),
- ", ".join(map(str, self.get_optionals())) if self.get_optionals() else "")
+ ", ".join(map(str, self.get_optionals().content)) if self.get_optionals() else "")
def __repr__(self):
"""
@@ -551,6 +551,7 @@ class ContextManager:
while index < len(self.parsed_list):
token = self.parsed_list[index]
token.line_number = line_number
+ token.index = index
token.file_name = self.name
token.ident = self.ident
self.pile.append(token)
@@ -583,16 +584,17 @@ class ContextManager:
# Error if closing token does not have a start
elif isinstance(token, syntax.ClosedSemanticType):
- raise MismatchedContainerError(token)
+ raise MismatchedContainerError(token, self.parsed_list)
# Starting token by default (can cause unintended behaviours on bad implementations)
elif isinstance(token, syntax.TokensToMatch):
self._add_matched(token.label, index)
else:
- raise MismatchedContainerError(token)
+ raise MismatchedContainerError(token, self.parsed_list)
except MismatchedContainerError as e:
+ error_mngr.log_message(f"In context: {e.get_context()}", level="CRITICAL")
error_mngr.log_exception(e, level="CRITICAL") # FUTURE: Try to guess some hints.
index += 1
diff --git a/src/bootstraparse/modules/environment.py b/src/bootstraparse/modules/environment.py
index fad2769..305113c 100644
--- a/src/bootstraparse/modules/environment.py
+++ b/src/bootstraparse/modules/environment.py
@@ -1,19 +1,20 @@
-# Module for containing super important variables
-# Environment has self._mParams for mandatory parameters, self._sParams for secondary parameters and
-# self.wasInitialised and integrity_check for debug.
-# __getattr__ and __setattr__ check for existing super, s or m parameters, returns error if not found.
-# Usage:
-# from bootstraparse.modules.environment import Environment
-# env = Environment()
-# env.integrity_check() -> Checks if all mandatory parameters are set.
-# env["config"] -> returns config object
-# env["template"] -> returns template object
-# env["export_mngr"] -> returns export manager object
-# env["global_path"] -> returns global path ???
-# env["user_path"] -> returns user path ???
-# env["site_path"] -> returns site path
-# env["export"] -> returns export object ???
-# env["site_crawler"] -> returns site crawler object
+"""Module for containing super important variables
+Environment has self._mParams for mandatory parameters, self._sParams for secondary parameters and
+ - self.wasInitialised and integrity_check for debug.
+ - __getattr__ and __setattr__ check for existing super, s or m parameters, returns error if not found.
+Usage:
+ - from bootstraparse.modules.environment import Environment
+ - env = Environment()
+ - env.integrity_check() -> Checks if all mandatory parameters are set.
+ - env["config"] -> returns config object
+ - env["template"] -> returns template object
+ - env["export_mngr"] -> returns export manager object
+ - env["global_path"] -> returns global path ???
+ - env["user_path"] -> returns user path ???
+ - env["site_path"] -> returns site path
+ - env["export"] -> returns export object ???
+ - env["site_crawler"] -> returns site crawler object
+ """
from bootstraparse.modules import error_mngr
diff --git a/src/bootstraparse/modules/error_mngr.py b/src/bootstraparse/modules/error_mngr.py
index c460ee4..3f08ce4 100644
--- a/src/bootstraparse/modules/error_mngr.py
+++ b/src/bootstraparse/modules/error_mngr.py
@@ -1,12 +1,14 @@
-# Dedicated module for defining and interpreting errors as well as generating error messages
-# You're probably here for log_message or log_exception.
-# They take: message, level=("ERROR, "INFO", "WARNING", "DEBUG", "CRITICAL")
-# There's also a dict_check(dic, *args) that returns true if all args are keys in the dict.
-# Usage:
-# from bootstraparse.modules.error_mngr import log_message, log_exception
-# log_message("This is a message", level="INFO") level=("ERROR, "INFO", "WARNING", "DEBUG", "CRITICAL")
-# log_exception(Exception("This is an exception"), level="ERROR")
-# dict_check({"a": 1, "b": 2}, "a", "b") # returns [True, True]
+"""
+Dedicated module for defining and interpreting errors as well as generating error messages
+You're probably here for log_message or log_exception.
+ - They take: message, level=("ERROR, "INFO", "WARNING", "DEBUG", "CRITICAL")
+There's also a dict_check(dic, *args) that returns true if all args are keys in the dict.
+Usage:
+ - from bootstraparse.modules.error_mngr import log_message, log_exception
+ - log_message("This is a message", level="INFO") level=("ERROR, "INFO", "WARNING", "DEBUG", "CRITICAL")
+ - log_exception(Exception("This is an exception"), level="ERROR")
+ - dict_check({"a": 1, "b": 2}, "a", "b") # returns [True, True]
+"""
import logging
import traceback
@@ -93,6 +95,54 @@ class BootstraparseError(Exception):
pass
+class BootstraparseTokenError(BootstraparseError):
+ """
+ Error on a token, provides if possible the line and column number of the error,
+ the file name and the message of the error
+ and if possible a context for the error
+ """
+ def __init__(self, token, pile, message):
+ self.token = token
+ self.pile = pile
+ if token is not None:
+ self.line = token.line_number
+ self.index = token.index
+ self.label = token.label
+ self.name = token.file_name
+ else:
+ self.line = None
+ self.index = None
+ self.label = None
+ self.name = None
+ self.context = self.get_context()
+ super().__init__(message+"\n"+self.context_multiline())
+
+ def get_context(self, context_size=5):
+ """
+ Returns the context of the error
+ :return: The context of the error
+ :rtype: str
+ """
+ if self.pile:
+ st = max(0, self.index - context_size)
+ en = min(len(self.pile), self.index + context_size)
+ return self.pile[st:en]
+ return []
+
+ def context_multiline(self, context_size=10):
+ """
+ Returns the context of the error as a multiline string
+ :return: The context of the error
+ :rtype: str
+ """
+ if self.pile:
+ return "\n".join([
+ f"{' ' if i!=context_size else '> '}{i-context_size:2d}: {j}"
+ for i, j in enumerate(self.get_context(context_size)) if j.label != "linebreak"
+ ])
+ return ""
+
+
class ParsingError(Exception):
"""
Exception class for parsing errors
@@ -131,17 +181,18 @@ class ParsingError(Exception):
return str(self.message)
-class MismatchedContainerError(BootstraparseError):
+class MismatchedContainerError(BootstraparseTokenError):
"""
The token is not final and cannot be contained. Indicative of a mismatched token.
"""
- def __init__(self, token):
+ def __init__(self, token, pile=None):
"""
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
+ self.pile = pile
if token:
self.line = token.line_number
self.label = token.label
@@ -150,7 +201,7 @@ class MismatchedContainerError(BootstraparseError):
self.line = None
self.label = None
self.name = None
- super().__init__(f"Could not process {self.label} at line {self.line} in file {self.name}.")
+ super().__init__(token, pile, f"Could not process {self.label} at line {self.line} in file {self.name}.")
class LonelyOptionalError(BootstraparseError):
diff --git a/src/bootstraparse/modules/export.py b/src/bootstraparse/modules/export.py
index 38f7edc..0bb9b69 100644
--- a/src/bootstraparse/modules/export.py
+++ b/src/bootstraparse/modules/export.py
@@ -1,10 +1,12 @@
-# Module for final generation of the translated website
-# Usage:
-# from bootstraparse.modules.export import ExportManager, ExportRequest, ExportResponse
-# rqs = ExportRequest("strucural_elements", "div", "optionals", {"id": "my_id", "class": "my_class"})
-# rsp = ExportResponse("start_string", "end_string")
-# em = ExportManager(config_file, template_file)
-# em(ExportRequest()) -> ExportResponse()
+"""
+Module for final generation of the translated website
+Usage:
+ - from bootstraparse.modules.export import ExportManager, ExportRequest, ExportResponse
+ - rqs = ExportRequest("strucural_elements", "div", "optionals", {"id": "my_id", "class": "my_class"})
+ - rsp = ExportResponse("start_string", "end_string")
+ - em = ExportManager(config_file, template_file)
+ - em(ExportRequest()) -> ExportResponse()
+"""
from io import StringIO
from bootstraparse.modules import config, pathresolver, error_mngr, context_mngr
diff --git a/src/bootstraparse/modules/parser.py b/src/bootstraparse/modules/parser.py
index 180065b..497912a 100644
--- a/src/bootstraparse/modules/parser.py
+++ b/src/bootstraparse/modules/parser.py
@@ -1,9 +1,10 @@
-# Main parser, gets config files and parses them for the context manager.
-# parse_line takes a io and outputs it all as a list of parsed elements
-# Usage:
-# from bootstraparse.modules.parser import parse_line
-# parse_line(io) -> [element, element, element]
-
+"""
+Main parser, gets config files and parses them for the context manager.
+parse_line takes a io and outputs it all as a list of parsed elements
+Usage:
+ - from bootstraparse.modules.parser import parse_line
+ - parse_line(io) -> [element, element, element]
+"""
from io import StringIO
import bootstraparse.modules.syntax as syntax
diff --git a/src/bootstraparse/modules/pathresolver.py b/src/bootstraparse/modules/pathresolver.py
index 4ab0914..6c3a149 100644
--- a/src/bootstraparse/modules/pathresolver.py
+++ b/src/bootstraparse/modules/pathresolver.py
@@ -1,11 +1,12 @@
-# Module for resolving relative path problems
-# PathResolver takes a relative path in the module and outputs the absolute path,
-# BoostraPath can deal with relative paths in the installation folder.
-# Usage:
-# from bootstraparse.modules.pathresolver import PathResolver, b_path
-# b_path("../relative/path/to/file") # returns absolute path to file from the bootstraparse folder
-# path= PathResolver("../relative/path/to/file") # Make a PathResolver object pointing at the first path given
-
+"""
+Module for resolving relative path problems
+PathResolver takes a relative path in the module and outputs the absolute path,
+BoostraPath can deal with relative paths in the installation folder.
+Usage:
+ - from bootstraparse.modules.pathresolver import PathResolver, b_path
+ - b_path("../relative/path/to/file") # returns absolute path to file from the bootstraparse folder
+ - path= PathResolver("../relative/path/to/file") # Make a PathResolver object pointing at the first path given
+"""
import os
diff --git a/src/bootstraparse/modules/preparser.py b/src/bootstraparse/modules/preparser.py
index ad3df05..e028c1e 100644
--- a/src/bootstraparse/modules/preparser.py
+++ b/src/bootstraparse/modules/preparser.py
@@ -1,11 +1,12 @@
-# Module for pre-parsing user files in preparation for the parser
-# Usage:
-# from bootstraparse.modules.preparser import preparser
-# pp = preparser(file, enviroment)
-# pp.do_import() # imports all the modules and adds them to the file, do the same for all the files that are to be imported # noqa
-# pp.do_replacements() # replaces all images and shortcuts in the file
-# pp.readlines() # returns the lines of ORIGINAL file
-# pp.get_all_lines() # returns the lines of the file after replacements and imports
+"""Module for pre-parsing user files in preparation for the parser
+Usage:
+ - from bootstraparse.modules.preparser import preparser
+ - pp = preparser(file, enviroment)
+ - pp.do_import() # imports all the modules and adds them to the file, do the same for all the files that are to be imported - # noqa
+ - pp.do_replacements() # replaces all images and shortcuts in the file
+ - pp.readlines() # returns the lines of ORIGINAL file
+ - pp.get_all_lines() # returns the lines of the file after replacements and imports
+"""
import os
diff --git a/src/bootstraparse/modules/sitecrawler.py b/src/bootstraparse/modules/sitecrawler.py
index 6620475..d310dc0 100644
--- a/src/bootstraparse/modules/sitecrawler.py
+++ b/src/bootstraparse/modules/sitecrawler.py
@@ -1,4 +1,14 @@
-# Module for file and directories repartition
+"""
+Module for file and directories repartition
+Usage:
+ - from bootstraparse.modules import SiteCrawler
+ - crawler = SiteCrawler(origin_path, dest_path, _env)
+ - crawler.set_all_preparsers()
+ - crawler.copy_unparsable_files()
+ - for element, destination in crawler:
+ - - save(preparse_parse(element), destination, _env)
+"""
+
import os
import shutil
from bootstraparse.modules import pathresolver, preparser, error_mngr, environment, export
diff --git a/src/bootstraparse/modules/sitecreator.py b/src/bootstraparse/modules/sitecreator.py
index 6bad6e0..78c15a1 100644
--- a/src/bootstraparse/modules/sitecreator.py
+++ b/src/bootstraparse/modules/sitecreator.py
@@ -1,4 +1,9 @@
-# Module sequencing the successive actions necessary for website building
+"""
+Module sequencing the successive actions necessary for website building
+Usage:
+ - create_website(origin, destination)
+"""
+
import os
from bootstraparse.modules import pathresolver, sitecrawler, environment, config, export, parser, context_mngr
diff --git a/src/bootstraparse/modules/syntax.py b/src/bootstraparse/modules/syntax.py
index 1d6d031..8d68ec4 100644
--- a/src/bootstraparse/modules/syntax.py
+++ b/src/bootstraparse/modules/syntax.py
@@ -1,3 +1,4 @@
+"""
# Dedicated module for the syntax of all the parsing
# All tokens inherit a SemanticType among SemanticType, ExplicitSemanticType and EmptySemanticType
# All tokens have a label, and __eq__ and __ne__ methods.
@@ -8,6 +9,7 @@
# line_to_replace.parse_line('string') # returns a List of tokens parsed for replacements
# imports.parse_line('string', True) # returns a List of tokens parsed for imports
# any_token.create_diagram("filename") # Debugging
+"""
import os
from itertools import zip_longest
@@ -555,10 +557,9 @@ alias = alias_element + pp.Opt(optional)
# Syntax elements
line_to_replace = pp.OneOrMore(
- pp.SkipTo(image ^ alias)('text').add_parse_action(of_type(TextToken))
- ^ image.add_parse_action(of_type(ImageToken))
- ^ alias.add_parse_action(of_type(AliasToken))
-) ^ pp.rest_of_line('text').add_parse_action(of_type(TextToken))
+ pp.SkipTo(image)('text').add_parse_action(of_type(TextToken)) + image.add_parse_action(of_type(ImageToken)) |
+ pp.SkipTo(alias)('text').add_parse_action(of_type(TextToken)) + alias.add_parse_action(of_type(AliasToken))
+) | pp.rest_of_line('text').add_parse_action(of_type(TextToken))
##############################################################################
diff --git a/src/bootstraparse/modules/template_mngr.py b/src/bootstraparse/modules/template_mngr.py
index b241949..7635bea 100644
--- a/src/bootstraparse/modules/template_mngr.py
+++ b/src/bootstraparse/modules/template_mngr.py
@@ -1 +1,3 @@
-# Module for interpreting default or custom templates.
+"""
+Module for interpreting default or custom templates.
+"""
diff --git a/src/bootstraparse/modules/tools.py b/src/bootstraparse/modules/tools.py
index e6b68b5..01977c4 100644
--- a/src/bootstraparse/modules/tools.py
+++ b/src/bootstraparse/modules/tools.py
@@ -1,11 +1,13 @@
-###############################################################################
-# List of tools for testing
-###############################################################################
-# Usage:
-# from bootstraparse.modules.tools import __GLk, __GL, find_*_in_file
-# __GLk(n) # Returns a file link n traceback objects back
-# __GL() # Returns a line number at current position
-# find_*_in_file(file) # Try to find (class, function or variable) in file and return its line number
+"""
+List of tools for testing
+=========================
+
+Usage:
+ - from bootstraparse.modules.tools import __GLk, __GL, find_*_in_file
+ - __GLk(n) # Returns a file link n traceback objects back
+ - __GL() # Returns a line number at current position
+ - find_*_in_file(file) # Try to find (class, function or variable) in file and return its line number
+"""
import inspect
import os
diff --git a/tests/modules/test_syntax_context.py b/tests/modules/test_syntax_context.py
index 928308c..21e1d75 100644
--- a/tests/modules/test_syntax_context.py
+++ b/tests/modules/test_syntax_context.py
@@ -47,6 +47,7 @@ def test_counterpart_container(type_n, expected_counterpart, expected_container,
try:
token = type_n(["test"]) # noqa
token.line_number = 1
+ token.index = 1
assert token.counterpart() == expected_counterpart
if expected_container == "error":
with pytest.raises(error_mngr.MismatchedContainerError):