bibla 2.0.0__py3-none-any.whl

bibla/__init__.py

@@ -0,0 +1,6 @@
+"""bibla is a minimalistic linter (style checker) for biblatex.
+
+bibla with support for libraries managed by JabRef.
+bibla does not come with its own biblatex parser, but leverages the pybtex parser.
+"""
+__version__ = "2.0.0"

bibla/__main__.py

@@ -0,0 +1,121 @@
+"""Main CLI script to launch the linter using Click."""
+import os
+import warnings
+
+import click
+from bibla import __version__
+from bibla.lint import lint as bibl_lint
+from bibla.config import load_config_file, set_config
+from bibla.rule import load_rules
+from bibla.text_utils import format_rules_markdown_tables
+
+
+@click.group()
+@click.option('-c', '--config', help='Custom configuration file path.',
+              type=str)
+@click.option('--select',
+              help='Comma separated list of enabled rules, all other rules '
+                   'will be disabled.',
+              type=str)
+@click.option('--ignore',
+              help='Comma separated list of disabled rules, all other rules '
+                   'will be enabled.',
+              type=str)
+@click.option('--indent-spaces',
+              help='Number of trailing whitespaces for indented line, '
+                   'used by TO1.',
+              type=int)
+@click.option('--max-line-length',
+              help='Max line length before wrap recommended, used by T03.',
+              type=int)
+def cli(config, select, ignore, indent_spaces, max_line_length):
+    """`bibla` base command line script.
+
+    Extra configuration options can be specified with command line arguments.
+    Hierarchy of configuration options is as follows (higher supersedes lower):
+
+        Configuration options specified as command line options (e.g. --ignore)
+        Configuration file specified with --config
+        `bibla.yml` configuration file in the current directory
+        `.bibla.yml` configuration file in the current directory
+        The default configuration file (in bibla/bibla.yml)
+
+
+    :param see help strings above
+    """
+    if config is not None:
+        load_config_file(config)
+    elif os.path.isfile('bibla.yml'):
+        load_config_file('bibla.yml')
+    elif os.path.isfile('.bibla.yml'):
+        load_config_file('.bibla.yml')
+
+    if select is not None:
+        set_config('select', select.split(','))
+    if ignore is not None:
+        set_config('ignore', ignore.split(','))
+    set_config('indent_spaces', indent_spaces)
+    set_config('max_line_length', max_line_length)
+
+
+@cli.command(help="Lint a biblatex bibliography file.")
+@click.argument('bibliography', type=str, nargs=-1)
+def lint(bibliography):
+    """CLI command to lint a BibLaTeX file.
+
+     Use with `bibla lint`.
+
+    :param see help strings above
+    """
+    warnings.filterwarnings("ignore")
+    for bib in bibliography:
+        bibl_lint(bib)
+
+
+@cli.command(help="Show all available rules.")
+@click.option('-m', 'markdown', help='Format rules as markdown table.',
+              is_flag=True)
+def list_all(markdown):
+    """CLI command to list all rules generated with de current config.
+
+    Use with `bibla list-all`.
+
+    :param see help strings above
+    """
+    rules = load_rules().all
+    if markdown:
+        click.echo(format_rules_markdown_tables(rules))
+    else:
+        for rule in rules:
+            click.echo(rule)
+
+
+@cli.command(help="Show all rules enabled by the configuration.")
+@click.option('-m', 'markdown', help='Format rules as markdown table.',
+              is_flag=True)
+def list_enabled(markdown):
+    """CLI command to list all enabled rules generated with de current config.
+
+    Use with `bibla list-enabled`.
+
+    :param see help strings above
+    """
+    rules = load_rules().enabled
+    if markdown:
+        click.echo(format_rules_markdown_tables(rules))
+    else:
+        for rule in rules:
+            click.echo(rule)
+
+
+@cli.command(help="Show the package version.")
+def version():
+    """CLI command to print the version number.
+
+    Use with `bibla version`.
+    """
+    click.echo('bibla version: ' + __version__)
+
+
+if __name__ == '__main__':
+    cli(prog_name='bibla')

bibla/bibla.yml

@@ -0,0 +1,85 @@
+---
+## DEFAULT bibla CONFIG
+select: [ ]             # List of enabled rules, all other rules will be disabled
+ignore: [ D00, T00, T02, T03, U01* ]  # List of disabled rules, all other rules will be enabled -  The disabled rules from bibl just seem to make less sense for Bibla. Personal choices may apply.
+# Specify max 1 of the two options above. If none are specified, all rules will be enabled
+indent_spaces: 2        # number of trailing whitespaces for indented line, used by TO1
+max_line_length: 120    # max line length before wrap optional, used by T03
+abbreviation_dot: True  # abbreviate middle names with dot (John F. Kennedy) as opposed to without (John F Kennedy), used by E02
+
+# Specification from https://en.wikipedia.org/wiki/bibtex extended with fields used in JabRef.
+# This specification is used to generate M01 and U01 rules
+# These have been further adapted to work with BibLaTeX entry types.
+type_spec:
+  incollection: # A part of a book having its own title.
+    required: [ title, booktitle, publisher, year ]
+    optional: [ volume, number, series, type, chapter, pages, address, edition, month, key, file ]
+  unpublished: # A document having an author and title, but not formally published.
+    required: [title]
+    optional: [month, year, key, file]
+  
+ # For HOGENT students. - previously used ones have been disabled above.
+  article:
+    required: [title, journaltitle, date]
+    optional: [doi, volume, number, pages]
+  book:
+    required: [title, date, publisher]
+    optional: [isbn]
+  inbook:
+    required: [title, booktitle, date, publisher]
+    optional: [isbn ,doi, pages]
+  booklet:
+    required: [title, date, publisher]
+    optional: [isbn , doi, url, howpublished]
+  dataset:
+    required: [title, date, url, urldate]
+    optional: []
+  manual:
+    required: [ title, date]
+    optional: [organization, publisher, isbn, doi, url ]
+  software:
+    required: [ title, date]
+    optional: []
+  misc:
+    required: [ title, date]
+    optional: []
+  online:
+    required: [ title, date, url, urldate]
+    optional: []
+  electronic:
+    required: [ title, date, url, urldate]
+    optional: []
+  www:
+    required: [ title, date, url, urldate]
+    optional: []
+  inproceedings:
+    required: [title, booktitle, date]
+    optional: [ eventtitle, isbn, doi, url]
+  conference:
+    required: [title, booktitle, date]
+    optional: [ eventtitle, isbn, doi, url]
+  report:
+    required: [title, date, type, institution]
+    optional: [doi, url]
+  techreport:
+    required: [title, date, type, institution]
+    optional: [doi, url]
+  thesis:
+    required: [title, date, type, institution]
+    optional: [url]
+  mastersthesis:
+    required: [title, date, type, institution]
+    optional: [url]
+  phdthesis:
+    required: [title, date, type, institution]
+    optional: [url]
+
+alias_entry_types:
+    misc: [software]
+    online: [electronic, www]
+    inproceedings: [conference]
+    report: [techreport]
+    thesis: [mastersthesis, phdthesis]
+
+alternate_fields:
+  date: [year] # Month and day will not be used alone, so when we just check for the year, that'll be fine.

bibla/config.py

@@ -0,0 +1,64 @@
+"""Linter configuration logic."""
+from typing import Dict, Any
+
+import pkg_resources
+import yaml
+
+_config = dict()
+_read_default = False
+
+_DEFAULT_CONFIG_FILE = 'bibla.yml'
+
+
+def get_config() -> Dict:
+    """Return the loaded config or instantiate and return default config."""
+    if not _read_default:
+        _load_default_config()
+    return _config
+
+
+def set_config(key: str, value: Any, default: bool = False):
+    """Set a value in the configurations.
+
+    :param key: configuration entry key
+    :param value: configuration entry value
+    :param default: If true, set as default value to be overwritten by later
+    """
+    if value is not None:
+        if default:
+            _config.setdefault(key, value)
+        else:
+            _config[key] = value
+        _validate_and_clean_config(_config)
+
+
+def load_config_file(file):
+    """Read a YAML config file and use it as the configuration.
+
+    :param file: .yaml config file path
+    """
+    with open(file) as config_file:
+        config = yaml.load(config_file, Loader=yaml.FullLoader)
+        for k, v in config.items():
+            set_config(k, v)
+
+
+def _load_default_config():
+    global _read_default
+    _read_default = True
+    with open(pkg_resources.resource_filename(__name__,
+                                              _DEFAULT_CONFIG_FILE)) as \
+            default_config_file:
+        default_config = yaml.load(default_config_file, Loader=yaml.FullLoader)
+        for k, v in default_config.items():
+            set_config(k, v, default=True)
+
+
+def _validate_and_clean_config(config):
+    if 'select' in config and 'ignore' in config and config['select'] and \
+            config['ignore']:
+        raise ValueError(
+            "Configuration cannot contain both included and selected and "
+            "ignored rules. Use either include or exclude to select"
+            "enabled rules."
+        )

bibla/lint.py

@@ -0,0 +1,130 @@
+"""Main linter logic."""
+import logging
+import sys
+from dataclasses import dataclass
+from typing import List, Iterable
+from pybtex.database import BibliographyDataError
+import re
+
+import pybtex
+from pybtex.database import parse_file
+from bibla.rule import load_rules, Rule, EntryRule, TextRule
+from bibla.text_utils import find_entry_line_number, MONTH_NAMES
+
+logger = logging.getLogger()
+logger.setLevel(logging.WARNING)
+
+handler = logging.StreamHandler(sys.stdout)
+handler.setLevel(logging.WARNING)
+logger.addHandler(handler)
+
+
+@dataclass
+class LintWarning:
+    """Dataclass to represent and report a linter rule violation."""
+
+    # file path of the detected violation
+    file: str
+    # line number of the detected violation
+    line: int
+    # the violated rule
+    rule: Rule
+
+    def log(self):
+        """Print the warning with details to stdout."""
+        msg = "{}:{} {}".format(self.file, self.line, str(self.rule))
+        logger.warning(msg)
+
+
+def lint(bibliography: str, verbose: bool = True) -> List[LintWarning]:
+    """Execute the main linter program.
+
+    The linter will first scan the bibliography text file and check all text
+    rules for each line in the text file. Next, the file will be parsed by the
+    pybtex parser and all entry rules will be checked.
+
+    :param bibliography: a .bib bibliography file path
+    :param verbose: log linter warnings to stdout
+    :return: a list of LintWarning objects representing the linter violations
+    found while running
+    """
+    try:
+        bib_data = parse_file(bibliography, macros=MONTH_NAMES)
+    except BibliographyDataError as e:
+        # Extract the key from the error message
+        match = re.search(r'repeated bibliograhpy entry: (.*)', str(e))
+        if match:
+            duplicate_key = match.group(1)
+            print(f"{bibliography} D03: Duplicate entry with key '{duplicate_key}'")
+        else:
+            print(f"Warning: {e}")
+        return []
+    except pybtex.scanner.TokenRequired as e:
+        print(f"E00: {e}")
+        return []
+    except Error as e:
+        print(f"Error: {e}")
+        return []
+    
+    bib_data.file = bibliography
+    with open(bibliography, 'r') as bib_file:
+        bib_text = bib_file.read()
+
+    rules = load_rules()
+
+    text_warnings = _apply_text_rules(bibliography, bib_text,
+                                      rules.enabled_text_rules)
+    entry_warnings = _apply_entry_rules(bibliography, bib_data, bib_text,
+                                        rules.enabled_entry_rules)
+
+    warnings = text_warnings + entry_warnings
+
+    warnings.sort(key=lambda w: w.rule.rule_id)
+    warnings.sort(key=lambda w: w.line)
+    if verbose:
+        for warning in warnings:
+            warning.log()
+    return warnings
+
+
+def _apply_text_rules(bibliography: str, bib_text: str,
+                      text_rules: Iterable[TextRule]) -> List[LintWarning]:
+    """Check all text rules in the bibliography text file.
+
+    :param bibliography: bibliography file path
+    :param bib_text: bibliography file contents
+    :param text_rules: list of text rules to be evaluated on each line of
+    the file
+    :return: a list of LinterWarnings representing found rule violations
+    """
+    warnings = []
+    for i, line in enumerate(bib_text.split('\n')):
+        line_number = i + 1
+        for rule in text_rules:
+            result = rule(line_number, line, bib_text)
+            if not result:
+                warnings.append(LintWarning(bibliography, line_number, rule))
+    return warnings
+
+
+def _apply_entry_rules(bibliography: str,
+                       bib_data: pybtex.database.BibliographyData,
+                       bib_text: str, entry_rules: Iterable[EntryRule]) \
+        -> List[LintWarning]:
+    """Check all entry rules in the bibliography text file.
+
+    :param bibliography: bibliography file path
+    :param bib_data: parsed bibliography data containing entries
+    :param bib_text: bibliography file contents
+    :param text_rules: list of text rules to be evaluated on each line of
+    the file
+    :return: a list of LinterWarnings representing found rule violations
+    """
+    warnings = []
+    for key, entry in bib_data.entries.items():
+        for rule in entry_rules:
+            line_number, offset = find_entry_line_number(bib_text, key)
+            result = rule(key, entry, bib_data)
+            if not result:
+                warnings.append(LintWarning(bibliography, line_number, rule))
+    return warnings

bibla/rule.py

@@ -0,0 +1,158 @@
+"""Structure to manage rules in a unified way."""
+import fnmatch
+import os
+from typing import Callable, Dict, List
+from pybtex.database import Entry
+from bibla.config import get_config
+
+
+class Rule:
+    """Generic rule class.
+
+    :param rule_id: identifying code for this rule, starting with a letter
+    indicating the rule type, followed by a number or a string specification.
+    :param description: a full sentence description of the rule
+    """
+
+    def __init__(self, rule_id: str, description: str, rule: Callable):
+        """Create Rule object.
+
+        :param rule_id: identifying code for this rule, starting with a letter
+        indicating the rule type, followed by a number or a string
+        specification.
+        :param description: a full sentence description of the rule
+        :param rule: a callable returning a boolean to execute when checking
+        this rule
+        """
+        self.rule_id = rule_id
+        self.description = description
+        self._rule = rule
+
+    def __str__(self):
+        """Return rule as string representation."""
+        return "{}: {}".format(self.rule_id, self.description)
+
+    def __call__(self, *args, **kwargs):
+        """Handle Rule objects as callables.
+
+        When calling a rule, it is evaluated over (a part of) the bibliography.
+        :param args, kwargs: Rule arguments
+        :return: True if the bibliography is consistent with the rule, False if
+        the rule is violated.
+        """
+        return self._rule(*args, **kwargs)
+
+    @property
+    def enabled(self):
+        """Evaluate wheter a rule should be checked this run.
+
+        :return: True if the rule should be checked based on the configuration
+        used for running the linter, False otherwise
+        """
+        if get_config()['select']:
+            for pattern in get_config()['select']:
+                if fnmatch.fnmatch(self.rule_id, pattern):
+                    return True
+            return False
+        if get_config()['ignore']:
+            for pattern in get_config()['ignore']:
+                if fnmatch.fnmatch(self.rule_id, pattern):
+                    return False
+            return True
+        return True
+
+
+class EntryRule(Rule):
+    """Rule type evaluating a parsed bibliography entry."""
+
+    def __init__(self, rule_id, description,
+                 rule: Callable[[str, Entry, Dict[str, Entry]], bool]):
+        """Create EntryRule object.
+
+        :param key: The key of the current bibliography entry
+        :param entry: The current bibliography entry
+        :param database: All bibliography entries
+        """
+        super().__init__(rule_id, description, rule)
+
+
+class TextRule(Rule):
+    """Rule type evaluating a text line in the bibliography entry."""
+
+    def __init__(self, rule_id, description,
+                 rule: Callable[[int, str, str], bool]):
+        """Create TextRule object.
+
+        :param line_number: The number of the current line in the bibliography
+        :param line: The content of the current line in the bibliography
+        :param text: The entire bibliography
+        """
+        super().__init__(rule_id, description, rule)
+
+
+class RuleStore:
+    """Container for all loaded rules."""
+
+    def __init__(self):
+        """Create RuleStore object."""
+        self._rules = []
+
+    def register(self, rule: Rule):
+        """Register a new rule.
+
+        :param: a Rule object to register
+        """
+        position = 0
+        while position < len(self._rules) \
+                and self._rules[position].rule_id < rule.rule_id:
+            position += 1
+        self._rules.insert(position, rule)
+
+    @property
+    def all(self) -> List[Rule]:
+        """Return all loaded rules."""
+        return self._rules
+
+    @property
+    def enabled(self) -> List[Rule]:
+        """Return all loaded rules enabled by the configuration."""
+        return [rule for rule in self._rules if rule.enabled]
+
+    @property
+    def enabled_entry_rules(self) -> List[EntryRule]:
+        """Return all loaded entry rules."""
+        return [rule for rule in self.enabled if isinstance(rule, EntryRule)]
+
+    @property
+    def enabled_text_rules(self) -> List[TextRule]:
+        """Return all loaded text rules."""
+        return [rule for rule in self.enabled if isinstance(rule, TextRule)]
+
+
+_ALL_RULES: RuleStore = RuleStore()
+
+
+def register_entry_rule(rule_id, description: str) -> Callable:
+    """Register a function as an entry rule."""
+    def decorator(f: Callable[[str, Entry, Dict[str, Entry]], bool]):
+        rule = EntryRule(rule_id, description, f)
+        _ALL_RULES.register(rule)
+    return decorator
+
+
+def register_text_rule(rule_id: str, description: str) -> Callable:
+    """Register a function as a text rule."""
+    def decorator(f: Callable[[int, str, str], bool]):
+        rule = TextRule(rule_id, description, f)
+        _ALL_RULES.register(rule)
+    return decorator
+
+
+def load_rules() -> RuleStore:
+    """Import all modules in the `bibla/rules` package."""
+    for module in os.listdir(os.path.join(os.path.dirname(__file__), 'rules')):
+        if module == '__init__.py' or module[-3:] != '.py':
+            continue
+        __import__('bibla.rules.' + module[:-3], locals(), globals())
+    del module
+    return _ALL_RULES

bibla/rules/__init__.py

@@ -0,0 +1,6 @@
+"""Package that contains modules with linter rules.
+
+Modules in this package will automatically be imported when loading rules.
+If these modules contain linter rule functions registered with
+`@register_entry_rule`, they will be added to the linter.
+"""

bibla/rules/database_rules.py

@@ -0,0 +1,59 @@
+"""Linter rules checking the consistency of the entire BibLaTeX file."""
+import re
+from fuzzywuzzy import fuzz
+from unidecode import unidecode
+from bibla.rule import register_entry_rule, register_text_rule
+
+
+@register_entry_rule('D00', 'Entry not in alphabetical order by key')
+def keys_alphabetical(key, entry, database):
+    """Raise a linter warning when entries are not in alphabetical order by key.
+
+    :param key: The key of the current bibliography entry
+    :param entry: The current bibliography entry
+    :param database: All bibliography entries
+    :return: True if the key of the current entry is alphabetically larger than
+    or equal to the key of the previous entry, False otherwise.
+    """
+    keys = list(database.entries.keys())
+    entry_num = keys.index(key)
+    if entry_num == len(keys) - 1:
+        return True
+    else:
+        return entry.key.lower() <= keys[entry_num + 1].lower()
+
+
+@register_text_rule('D01', 'Preamble should begin at first line of document')
+def line_length(line_number, line, text):
+    """Raise a linter warning when the preamble is not on the first line.
+
+    :param line_number: The number of the current line in the bibliography
+    :param line: The content of the current line in the bibliography
+    :param text: The entire bibliography
+    :return: True if no preamble is present or the preambel starts at line 1 of
+    the biblatex file, False otherwise.
+    """
+    regex = re.compile(r'^\s*@preamble')
+    return not regex.match(line.lower()) or line_number == 0
+
+
+@register_entry_rule('D02', 'Possible duplicate entry based on similar titles')
+def title_duplicate(key, entry, database):
+    """Raise a linter warning when entries with a similar titles are present.
+
+    :param key: The key of the current bibliography entry
+    :param entry: The current bibliography entry
+    :param database: All bibliography entries
+    :return: True if the fuzzy match partial ratio of the title of the current
+    entry with any other entry exceeds 90%, False otherwise.
+    """
+    if 'title' not in entry.fields:
+        return True
+    for e in database.entries.values():
+        if 'title' not in e.fields:
+            continue
+        t1 = unidecode(entry.fields['title']).lower()
+        t2 = unidecode(e.fields['title']).lower()
+        if e != entry and fuzz.partial_ratio(t1, t2) > 90:
+            return False
+    return True