ordinator 0.1.0__py3-none-any.whl

ordinator/__init__.py

@@ -0,0 +1,10 @@
+"""The machinery: a dataset passed through named, swappable, recorded steps.
+
+A consumer declares its vocabulary as data and answers what this package asks through
+the names it declares. Nothing here imports a consumer, and nothing here is imported on
+import of this package: take the modules you need.
+"""
+
+#: The kernel's own version, apart from any consumer's. Read by this package's
+#: pyproject.toml, which sits beside this file.
+__version__ = "0.1.0"

ordinator/bibliography.py

@@ -0,0 +1,270 @@
+"""Citations, read from ``references.bib`` -- the one place they are written.
+
+A ``references=`` entry is a *string*, and the manifest merges a run's citations
+by exact string equality, so two spellings of one source are two sources: they
+print twice, and a reader comparing two runs sees a difference that is only
+typography.
+
+So a registration cites a *key*::
+
+    references=cite('webb1980')
+
+and the text comes from the BibTeX file the consumer declares with :func:`use`
+(its ``references.bib``). Nothing restates a
+citation in Python, the file is ordinary BibTeX a manuscript can use directly,
+and the short author-year label the qaqc routines stamp on their output is
+*derived* from the same entry rather than stored, so the two forms cannot drift
+apart.
+
+The parser here is deliberately small: enough BibTeX for a hand-maintained file
+of a few dozen entries, and no dependency for a package whose job is not
+bibliography management.
+"""
+
+import re
+from pathlib import Path
+
+#: The bibliography in use, declared through :func:`use`. It is the consumer's and ships
+#: as its package data: an installed wheel has to carry it or a run's manifest could not
+#: name its own sources.
+BIB_PATH = None
+
+_ENTRY = re.compile(r'@(\w+)\s*\{')
+_FIELD = re.compile(r'[\s,]*(\w[\w-]*)\s*=\s*')
+_BARE = re.compile(r'[^,\s]*')
+
+
+class Citation(str):
+    """A citation already formatted -- an entry of the bibliography, or what
+    :func:`credit` built -- which :func:`cite` passes through as written."""
+
+
+def _closing(text, start, close):
+    """The index of the ``close`` that ends what opens just before ``start``,
+    braces nested inside it counted, or ``len(text)`` where nothing does."""
+    depth, i = 0, start
+    while i < len(text) and (depth or text[i] != close):
+        depth += {'{': 1, '}': -1}.get(text[i], 0)
+        i += 1
+    return i
+
+
+def _fields(body):
+    """``{field: value}`` of one entry's body: braced, quoted or bare values."""
+    fields, i = {}, 0
+    while (m := _FIELD.match(body, i)):
+        i = m.end()
+        if i < len(body) and body[i] in '{"':
+            end = _closing(body, i + 1, '}' if body[i] == '{' else '"')
+            value, i = body[i + 1:end], end + 1
+        else:
+            value = _BARE.match(body, i).group()
+            i += len(value)
+        fields[m.group(1).lower()] = ' '.join(value.split())
+    return fields
+
+
+def _parse(text):
+    """``{key: {'type': ..., field: value}}`` for a hand-written BibTeX file.
+
+    An entry ends at the brace that balances its opening one, wherever it sits:
+    a ``}`` on the last field's line closes that entry and not the next one.
+    """
+    entries, pos = {}, 0
+    while (m := _ENTRY.search(text, pos)):
+        end = _closing(text, m.end(), '}')
+        pos = end + 1
+        if m.group(1).lower() in ('comment', 'preamble', 'string'):
+            continue
+        key, _, body = text[m.end():end].partition(',')
+        entries[key.strip()] = {'type': m.group(1).lower(), **_fields(body)}
+    return entries
+
+
+_ENTRIES = {}
+
+
+def use(path):
+    """Read the bibliography citations are taken from."""
+    global BIB_PATH
+    BIB_PATH = Path(path)
+    _ENTRIES.clear()
+    _ENTRIES.update(_parse(BIB_PATH.read_text(encoding='utf8')))
+
+
+def _authors(entry):
+    """The author (or editor) names, ``others`` kept as the et-al marker."""
+    raw = entry.get('author') or entry.get('editor') or ''
+    return [n.strip() for n in raw.split(' and ') if n.strip()]
+
+
+def _surname(name):
+    """``Webb, E. K.`` and ``B. Heinesch`` both give ``Webb`` / ``Heinesch``."""
+    return name.split(',')[0].strip() if ',' in name else name.split()[-1]
+
+
+def _entry(key):
+    try:
+        return _ENTRIES[key]
+    except KeyError:
+        raise KeyError(
+            f"no reference {key!r} in {getattr(BIB_PATH, 'name', 'the bibliography')}; add the entry there "
+            f"rather than writing the citation at the call site") from None
+
+
+def _byline(entry):
+    """``A and B`` for two names, ``A, B, and C`` for more, ``A, et al.`` for
+    an ``and others`` list -- the house style the citations were written in."""
+    names = _authors(entry)
+    if names and names[-1] == 'others':
+        # ``Vitale, D., et al.`` but ``B. Heinesch et al.``: the comma belongs to
+        # the surname-first form, and the software credits are written the other
+        # way round.
+        sep = ', ' if ',' in names[0] else ' '
+        return f"{names[0]}{sep}et al."
+    if len(names) == 2:
+        return f"{names[0]} and {names[1]}"
+    if len(names) > 2:
+        return ", ".join(names[:-1]) + f", and {names[-1]}"
+    return names[0] if names else ''
+
+
+def _format(key):
+    """One entry as the citation string that reaches a manifest."""
+    return Citation(_formatted(_entry(key)))
+
+
+def _formatted(e):
+    who = _byline(e)
+    if e['type'] == 'software':
+        # Credited by name first: the software is the thing being cited, and the
+        # authors qualify it. :func:`credit` appends the routine.
+        text = f"{e['title']} ({who})"
+        if e.get('note'):
+            text = f"{e['title']} ({who}, {e['note']})"
+        link = _link(e)
+        return f"{text}, {link}" if link else text + '.'
+    if e.get('editor') and e['type'] == 'book':
+        who += ' (eds.)'
+
+    year = e.get('year')
+    parts = [f"{who} ({year})." if who and year else who]
+    parts.append(f"{e['title']}.")
+    if e['type'] == 'article':
+        tail = e.get('journal', '')
+        if e.get('volume'):
+            tail = f"{tail} {e['volume']}".strip()
+        if e.get('pages'):
+            tail = f"{tail}, {e['pages']}".strip(', ')
+        if tail:
+            parts.append(f"{tail}.")
+    elif e['type'] == 'incollection':
+        tail = f"In: {e.get('booktitle', '')}"
+        for extra in (e.get('publisher'), e.get('pages')):
+            if extra:
+                tail += f", {extra}"
+        parts.append(f"{tail}.")
+    elif e['type'] == 'book' and e.get('publisher'):
+        parts.append(f"{e['publisher']}.")
+    if e.get('note'):
+        parts.append(f"({e['note']}.)")
+    parts.append(_link(e))
+    return " ".join(p for p in parts if p).strip()
+
+
+def _link(entry):
+    """The one resolver a citation carries: the DOI when the work has one,
+    else its URL. A DOI is written bare in the file (``10.1002/...``) and
+    printed as the ``doi.org`` address so a manifest reader can follow it."""
+    if entry.get('doi'):
+        return f"https://doi.org/{entry['doi']}"
+    return entry.get('url') or ''
+
+
+def cite(*references):
+    """The given works as the list ``references=`` expects, without repeats.
+
+    Each argument is a key in ``references.bib``, or a :class:`Citation`
+    already formatted (what :func:`credit` and this function return). Order is
+    preserved: a registration lists its primary source first, and ``describe``
+    prints them in that order.
+
+    Raises:
+        KeyError: an argument is neither -- a misspelt key would otherwise be
+            published as its own citation in every manifest.
+    """
+    seen, out = set(), []
+    for ref in references:
+        for one in (ref if isinstance(ref, (list, tuple)) else [ref]):
+            text = one if isinstance(one, Citation) else _format(one)
+            if text not in seen:
+                seen.add(text)
+                out.append(text)
+    return out
+
+
+def short(*references):
+    """The works as one ``'A (yyyy); B & C (yyyy)'`` label.
+
+    For the ``reference`` attribute a qaqc routine stamps on its output, where a
+    full bibliographic string would swamp the variable's attrs. Derived from the
+    same entry the registration cites, so a routine cannot stamp one paper while
+    its registration names two.
+
+    Anything with no year (the software credits) is passed over: ``source=``
+    already names those. A key with no entry raises, as it does in :func:`cite`:
+    passed over, it would stamp one paper where the routine names two.
+    """
+    seen, out = set(), []
+    for key in references:
+        entry = _entry(key)
+        if not entry.get('year'):
+            continue
+        raw = _authors(entry)
+        names = [_surname(n) for n in raw if n != 'others']
+        if 'others' in raw or len(names) > 2:
+            who = f"{names[0]} et al."
+        elif len(names) == 2:
+            who = f"{names[0]} & {names[1]}"
+        else:
+            who = names[0] if names else '?'
+        label = f"{who} ({entry['year']})"
+        if label not in seen:
+            seen.add(label)
+            out.append(label)
+    return '; '.join(out)
+
+
+def short_of(references):
+    """The short label for citations that are already formatted.
+
+    The inverse of what a registration does: a bridged method stamps its output
+    with the same author-year label as the entry it twins, and reading it back
+    off that entry's ``references`` is what keeps the two from drifting -- the
+    alternative being the bib keys restated in a second file.
+
+    Anything that is not a formatted entry of ``references.bib`` -- a software
+    credit, a free-text note -- has no year and is passed over, as in
+    :func:`short`.
+    """
+    reverse = {_format(key): key for key in _ENTRIES}
+    return short(*[reverse[text] for text in (references or [])
+                   if text in reverse])
+
+
+def credit(key, what, version=None):
+    """Credit a piece of software for ``what`` -- a routine, a table, a recipe.
+
+    One phrasing for all of them, built from the entry ``key`` names. Two
+    orderings of the same words were in use -- the authors before the routine in
+    one module and after it in another -- so one source deduped as two in the
+    run manifest.
+    """
+    e = _entry(key)
+    name = e['title'] + (f' {version}' if version else '')
+    return Citation(f"{name} ({_byline(e)}, {e['note']}), {what}.")
+
+
+def keys():
+    """Every key ``references.bib`` defines, for tests and for the docs build."""
+    return sorted(_ENTRIES)