diff --git a/se/se_epub_lint.py b/se/se_epub_lint.py index adc4a5d3..682604d3 100644 --- a/se/se_epub_lint.py +++ b/se/se_epub_lint.py @@ -591,7 +591,14 @@ def _build_section_tree(self) -> List[EbookSection]: def _find_ebook_section(section_id: str, sections: List[EbookSection]) -> Union[EbookSection, None]: """ Find an ebook section in a tree of sections. - """ + + INPUTS + section_id: The name of the section to be found + sections: A list of EbookSections + + OUTPUTS + The entry from sections, if any, that contains section_id + """ for section in sections: if section.section_id == section_id: @@ -604,7 +611,7 @@ def _find_ebook_section(section_id: str, sections: List[EbookSection]) -> Union[ return None -def _lint_metadata_checks(self): +def _lint_metadata_checks(self) -> list: """ Process main metadata checks @@ -902,7 +909,7 @@ def _get_malformed_urls(dom: se.easy_xml.EasyXmlTree, filename: Path) -> list: filename: The filename being processed OUTPUTS - A list of LintMessages objects. + A list of LintMessage objects. """ messages = [] @@ -1058,7 +1065,7 @@ def _lint_css_checks(self, local_css_path: str, abbr_with_whitespace: list) -> t local_css_rules: Dictionary of the local CSS rules OUTPUTS - messages + A list of LintMessage objects """ messages = []; @@ -1510,15 +1517,15 @@ def _lint_special_file_checks(filename: str, dom: se.easy_xml.EasyXmlTree, file_ def _lint_xhtml_css_checks(filename: str, dom: se.easy_xml.EasyXmlTree, local_css_path: str) -> list: """ - Helper function used in self.lint() Process CSS checks on an .xhtml file INPUTS filename: The name of the file being checked - dom: A dom tree to check + dom: The dom tree of the file being checked + local_css_path: The path to the local CSS file OUTPUTS - A list of LintMessages representing CSS errors found in the file + A list of LintMessage objects """ messages = []; @@ -1606,15 +1613,15 @@ def _lint_xhtml_css_checks(filename: str, dom: se.easy_xml.EasyXmlTree, local_cs def _lint_xhtml_metadata_checks(filename: str, dom: se.easy_xml.EasyXmlTree, self) -> list: """ - Helper function used in self.lint() Process metadata checks on an .xhtml file INPUTS filename: The name of the file being checked - dom: A dom tree to check + dom: The dom of the file being checked + self OUTPUTS - A list of LintMessages representing metadata errors found in the file + A list of LintMessage objects """ messages = []; @@ -1648,17 +1655,17 @@ def _lint_xhtml_metadata_checks(filename: str, dom: se.easy_xml.EasyXmlTree, sel def _lint_xhtml_syntax_checks(filename: str, dom: se.easy_xml.EasyXmlTree, self, file_contents: str, ebook_flags: dict, language: str) -> list: """ - Helper function used in self.lint() Process syntax checks on an .xhtml file INPUTS filename: The name of the file being checked - dom: A dom tree to check + dom: The dom tree of the file being checked file_contents: The contents of the file being checked - ebook_flags: A dictionary containing several pieces of information about an ebook + ebook_flags: A dictionary containing several flags about an ebook + language: The language identified in the metadata OUTPUTS - A list of LintMessages representing syntax errors found in the file + A list of LintMessage objects """ messages = []; @@ -2233,18 +2240,18 @@ def _lint_xhtml_syntax_checks(filename: str, dom: se.easy_xml.EasyXmlTree, self, def _lint_xhtml_typography_checks(filename: str, dom: se.easy_xml.EasyXmlTree, file_contents: str, special_file: str, ebook_flags: dict, self) -> list: """ - Helper function used in self.lint() Process typography checks on an .xhtml file INPUTS filename: The name of the file being checked - dom: A dom tree to check + dom: The dom tree of the file being checked file_contents: The contents of the file being checked special_file: A string containing the type of special file the current file is, if any + ebook_flags: A dictionary containing several flags about an ebook self OUTPUTS - A list of LintMessages representing typography errors found in the file + A list of LintMessage objects """ messages = []; @@ -2718,16 +2725,15 @@ def _lint_xhtml_typography_checks(filename: str, dom: se.easy_xml.EasyXmlTree, f def _lint_xhtml_xhtml_checks(filename: str, dom: se.easy_xml.EasyXmlTree, file_contents: str) -> list: """ - Helper function used in self.lint() Process XHTML checks on an .xhtml file INPUTS filename: The name of the file being checked - dom: A dom tree to check + dom: The dom tree of the file being checked file_contents: The contents of the file being checked OUTPUTS - A list of LintMessages representing XHTML errors found in the file + A list of LintMessage objects """ messages = []; @@ -2786,17 +2792,16 @@ def _lint_xhtml_xhtml_checks(filename: str, dom: se.easy_xml.EasyXmlTree, file_c def _lint_xhtml_typo_checks(filename: str, dom: se.easy_xml.EasyXmlTree, file_contents: str, special_file: str) -> list: """ - Helper function used in self.lint() Process typo checks on an .xhtml file INPUTS filename: The name of the file being checked - dom: A dom tree to check + dom: The dom tree of the file being checked file_contents: The contents of the file being checked special_file: A string containing the type of special file the current file is, if any OUTPUTS - A list of LintMessages representing possible typos found in the file + A list of LintMessage objects """ messages = []; @@ -3019,6 +3024,17 @@ def _lint_xhtml_typo_checks(filename: str, dom: se.easy_xml.EasyXmlTree, file_co return messages def _lint_image_metadata_checks(self, has_images: bool) -> list: + """ + Process metadata checks on an image file + + INPUTS + self + has_images: Flag indicating whether the ebook has images + + OUTPUTS + A list of LintMessage objects + """ + messages = []; # Check for some accessibility metadata regarding images @@ -3045,7 +3061,20 @@ def _lint_image_metadata_checks(self, has_images: bool) -> list: return messages -def _lint_process_ignore_file(self, skip_lint_ignore: bool, messages: list, allowed_messages: list) -> list: +def _lint_process_ignore_file(self, skip_lint_ignore: bool, allowed_messages: list, messages: list) -> list: + """ + Parse a lint ignore file if pressent and if applicable remove its ignored messages + + INPUTS + self + skip_lint_ignore: Flag indicating whether the lint ignore file should be respected + messages: The list of LintMessages that have been generated so far + allowed_messages: A list of messages from the lint ignore file to allow for this run + + OUTPUTS + A list of LintMessage objects + """ + # This is a dict with where keys are the path and values are a list of code dicts. # Each code dict has a key "code" which is the actual code, and a key "used" which is a # bool indicating whether or not the code has actually been caught in the linting run. @@ -3129,6 +3158,7 @@ def lint(self, skip_lint_ignore: bool, allowed_messages: Optional[List[str]] = N INPUTS self skip_lint_ignore: Flag indicating whether ignore file should be used + allowed_messages: Optional list of messages from lint ignore file to allow this run OUTPUTS A list of LintMessage objects. @@ -3695,7 +3725,7 @@ def lint(self, skip_lint_ignore: bool, allowed_messages: Optional[List[str]] = N if not allowed_messages: allowed_messages = [] - messages = _lint_process_ignore_file(self, skip_lint_ignore, messages, allowed_messages) + messages = _lint_process_ignore_file(self, skip_lint_ignore, allowed_messages, messages) messages = natsorted(messages, key=lambda x: ((str(x.filename.name) if x.filename else "") + " " + x.code), alg=ns.PATH)