refkit 0.1.1__cp310-abi3-win_amd64.whl

refkit/__init__.py

@@ -0,0 +1,138 @@
+"""Citation parsing, rendering, and BibTeX editing."""
+
+from __future__ import annotations
+
+from importlib.metadata import version as _metadata_version
+from os import PathLike
+
+from . import _native as _core
+from . import types as types
+
+__version__ = _metadata_version("refkit")
+
+
+def _ensure_native_version() -> None:
+    if _core.__version__ == __version__:
+        return
+    raise SystemError(
+        f"The installed refkit extension version ({_core.__version__}) is incompatible "
+        f"with refkit {__version__}. Reinstall refkit from one release."
+    )
+
+
+_ensure_native_version()
+
+BibDocument = _core.BibDocument
+BibEntry = _core.BibEntry
+BibEntryMap = _core.BibEntryMap
+BibField = _core.BibField
+BibFieldMap = _core.BibFieldMap
+Citation = _core.Citation
+CitationGroup = _core.CitationGroup
+Cite = _core.Cite
+Document = _core.Document
+Entry = _core.Entry
+Library = _core.Library
+Locale = _core.Locale
+MissingReferenceError = _core.MissingReferenceError
+RefkitError = _core.RefkitError
+ParseError = _core.ParseError
+Rendered = _core.Rendered
+RenderedDocument = _core.RenderedDocument
+Style = _core.Style
+TidyError = _core.TidyError
+TidyOptions = _core.TidyOptions
+TidyResult = _core.TidyResult
+TidySyntaxError = _core.TidySyntaxError
+TidyWarning = _core.TidyWarning
+build_info = _core.build_info
+build_mode = _core.build_mode
+
+__all__ = [
+    "BibDocument",
+    "BibEntry",
+    "BibEntryMap",
+    "BibField",
+    "BibFieldMap",
+    "Citation",
+    "Cite",
+    "CitationGroup",
+    "RefkitError",
+    "ParseError",
+    "Document",
+    "Entry",
+    "Library",
+    "Locale",
+    "MissingReferenceError",
+    "Rendered",
+    "RenderedDocument",
+    "Style",
+    "TidyError",
+    "TidyOptions",
+    "TidyResult",
+    "TidySyntaxError",
+    "TidyWarning",
+    "build_info",
+    "build_mode",
+    "cite",
+    "full_bibliography",
+    "tidy_bibtex",
+    "tidy_file",
+    "__version__",
+    "types",
+]
+
+
+def tidy_bibtex(
+    source: str,
+    *,
+    options: TidyOptions | None = None,
+) -> TidyResult:
+    """Format BibTeX text and return the formatted source plus warnings."""
+
+    return _core.tidy_bibtex(source, options=options)
+
+
+def tidy_file(
+    path: str | PathLike[str],
+    *,
+    output: str | PathLike[str] | None = None,
+    options: TidyOptions | None = None,
+) -> TidyResult:
+    """Read a BibTeX file, format it, and write the result when `output` is set."""
+
+    result = BibDocument.read(path).tidy(options=options)
+    if output is not None:
+        _core._write_bibtex(output, result.bibtex)
+    return result
+
+
+def cite(
+    source: str | PathLike[str],
+    citation: str | Cite | CitationGroup,
+    *,
+    style: str | Style = "apa",
+    locale: str | Locale | None = "en-US",
+) -> Rendered:
+    """Read `source` and render one citation."""
+
+    library = Library.read(source)
+    loaded_style = Style.load(style) if isinstance(style, str) else style
+    rendered = Document(library, loaded_style, locale=locale).render(
+        [Citation("citation", citation)]
+    )
+    return rendered["citation"]
+
+
+def full_bibliography(
+    source: str | PathLike[str],
+    *,
+    style: str | Style = "apa",
+    locale: str | Locale | None = "en-US",
+) -> Rendered:
+    """Read `source` and render every entry as a bibliography."""
+
+    library = Library.read(source)
+    loaded_style = Style.load(style) if isinstance(style, str) else style
+    document = Document(library, loaded_style, locale=locale)
+    return document.full_bibliography()

refkit/__init__.pyi

@@ -0,0 +1,91 @@
+from os import PathLike
+
+from . import types as types
+from ._native import (
+    BibDocument,
+    BibEntry,
+    BibEntryMap,
+    BibField,
+    BibFieldMap,
+    Citation,
+    CitationGroup,
+    Cite,
+    Document,
+    Entry,
+    Library,
+    Locale,
+    MissingReferenceError,
+    ParseError,
+    RefkitError,
+    Rendered,
+    RenderedDocument,
+    Style,
+    TidyError,
+    TidyOptions,
+    TidyResult,
+    TidySyntaxError,
+    TidyWarning,
+    build_info,
+    build_mode,
+)
+
+__all__ = [
+    "BibDocument",
+    "BibEntry",
+    "BibEntryMap",
+    "BibField",
+    "BibFieldMap",
+    "Citation",
+    "Cite",
+    "CitationGroup",
+    "RefkitError",
+    "ParseError",
+    "Document",
+    "Entry",
+    "Library",
+    "Locale",
+    "MissingReferenceError",
+    "Rendered",
+    "RenderedDocument",
+    "Style",
+    "TidyError",
+    "TidyOptions",
+    "TidyResult",
+    "TidySyntaxError",
+    "TidyWarning",
+    "build_info",
+    "build_mode",
+    "cite",
+    "full_bibliography",
+    "tidy_bibtex",
+    "tidy_file",
+    "__version__",
+    "types",
+]
+
+__version__: str
+
+def tidy_bibtex(
+    source: str,
+    *,
+    options: TidyOptions | None = None,
+) -> TidyResult: ...
+def tidy_file(
+    path: str | PathLike[str],
+    *,
+    output: str | PathLike[str] | None = None,
+    options: TidyOptions | None = None,
+) -> TidyResult: ...
+def cite(
+    source: str | PathLike[str],
+    citation: str | Cite | CitationGroup,
+    *,
+    style: str | Style = "apa",
+    locale: str | Locale | None = "en-US",
+) -> Rendered: ...
+def full_bibliography(
+    source: str | PathLike[str],
+    *,
+    style: str | Style = "apa",
+    locale: str | Locale | None = "en-US",
+) -> Rendered: ...

refkit/_native.pyi

@@ -0,0 +1,272 @@
+from collections.abc import Iterable
+from os import PathLike
+from typing import Literal, TypeAlias
+
+from .types import (
+    BibliographyLayout,
+    Diagnostic,
+    ProjectionRow,
+    RawBlock,
+    RawFailedBlock,
+    RenderedTree,
+    TidyRename,
+)
+
+__version__: str
+build_info: str
+build_mode: Literal["debug", "release"]
+_RecoveryPolicy: TypeAlias = Literal["error", "report"]
+_DuplicateRule: TypeAlias = Literal["doi", "key", "abstract", "citation"]
+_MergeStrategy: TypeAlias = Literal["first", "last", "combine", "overwrite"]
+
+class RefkitError(Exception): ...
+
+class ParseError(RefkitError):
+    diagnostics: list[Diagnostic]
+
+class MissingReferenceError(RefkitError): ...
+class TidyError(RefkitError): ...
+
+class TidySyntaxError(TidyError):
+    line: int
+    column: int
+    byte: int
+    character: str | None
+    message: str
+
+class TidyOptions:
+    def __init__(
+        self,
+        *,
+        omit: Iterable[str] | None = None,
+        curly: bool = False,
+        numeric: bool = False,
+        months: bool = False,
+        space: int = 2,
+        tab: bool = False,
+        align: bool | int | None = 14,
+        blank_lines: bool = False,
+        sort: bool | Iterable[str] | None = None,
+        duplicates: Iterable[_DuplicateRule] | None = None,
+        merge: _MergeStrategy | None = None,
+        strip_enclosing_braces: bool = False,
+        drop_all_caps: bool = False,
+        escape: bool = True,
+        sort_fields: bool | Iterable[str] | None = None,
+        strip_comments: bool = False,
+        trailing_commas: bool = False,
+        encode_urls: bool = False,
+        tidy_comments: bool = True,
+        remove_empty_fields: bool = False,
+        remove_duplicate_fields: bool = True,
+        generate_keys: bool | str | None = None,
+        max_authors: int | None = None,
+        lowercase: bool = True,
+        enclosing_braces: bool | Iterable[str] | None = None,
+        remove_braces: bool | Iterable[str] | None = None,
+        wrap: bool | int | None = None,
+    ) -> None: ...
+
+class TidyWarning:
+    @property
+    def code(self) -> Literal["missing_key", "duplicate_entry"]: ...
+    @property
+    def rule(self) -> _DuplicateRule | None: ...
+    @property
+    def message(self) -> str: ...
+
+class TidyResult:
+    @property
+    def bibtex(self) -> str: ...
+    @property
+    def warnings(self) -> list[TidyWarning]: ...
+    @property
+    def renames(self) -> list[TidyRename]: ...
+    @property
+    def count(self) -> int: ...
+
+def tidy_bibtex(source: str, *, options: TidyOptions | None = None) -> TidyResult: ...
+def _write_bibtex(path: str | PathLike[str], source: str) -> None: ...
+
+class Entry:
+    @property
+    def key(self) -> str: ...
+    @property
+    def entry_type(self) -> str: ...
+    @property
+    def title(self) -> str | None: ...
+    @property
+    def date(self) -> str | None: ...
+    @property
+    def parents(self) -> list[Entry]: ...
+    @property
+    def volume(self) -> str | None: ...
+    @property
+    def doi(self) -> str | None: ...
+
+class Library:
+    @staticmethod
+    def read(path: str | PathLike[str], *, recovery: _RecoveryPolicy = "error") -> Library: ...
+    @staticmethod
+    def parse_bibtex(
+        source: str,
+        *,
+        recovery: _RecoveryPolicy = "error",
+    ) -> Library: ...
+    @staticmethod
+    def parse_yaml(source: str) -> Library: ...
+    @property
+    def diagnostics(self) -> list[Diagnostic]: ...
+    def keys(self) -> list[str]: ...
+    def get_many(self, keys: Iterable[str]) -> list[Entry]: ...
+    def values(self) -> list[Entry]: ...
+    def get(self, key: str) -> Entry | None: ...
+    def is_empty(self) -> bool: ...
+    def select(self, selector: str) -> list[Entry]: ...
+    def project(
+        self, fields: Iterable[str] | None = None, *, keys: Iterable[str] | None = None
+    ) -> list[ProjectionRow]: ...
+    def __len__(self) -> int: ...
+    def __bool__(self) -> bool: ...
+    def __contains__(self, key: str) -> bool: ...
+    def __getitem__(self, key: str) -> Entry: ...
+
+class Style:
+    @staticmethod
+    def load(name: str) -> Style: ...
+    @staticmethod
+    def from_xml(xml: str) -> Style: ...
+    @staticmethod
+    def from_path(path: str | PathLike[str]) -> Style: ...
+    @property
+    def id(self) -> str: ...
+    @property
+    def title(self) -> str: ...
+
+class Locale:
+    @staticmethod
+    def load(code: str) -> Locale: ...
+    @property
+    def code(self) -> str: ...
+
+class Cite:
+    def __init__(
+        self, key: str, *, locator: str | None = None, label: str | None = None
+    ) -> None: ...
+    @property
+    def key(self) -> str: ...
+    @property
+    def locator(self) -> str | None: ...
+    @property
+    def label(self) -> str | None: ...
+
+class CitationGroup:
+    def __init__(self, items: Iterable[str | Cite]) -> None: ...
+    @property
+    def items(self) -> list[Cite]: ...
+    def __len__(self) -> int: ...
+
+class Citation:
+    def __init__(
+        self, id: str, citation: str | Cite | CitationGroup, *, note_number: int | None = None
+    ) -> None: ...
+    @property
+    def note_number(self) -> int | None: ...
+    @property
+    def id(self) -> str: ...
+    @property
+    def group(self) -> CitationGroup: ...
+
+class Rendered:
+    @property
+    def layout(self) -> BibliographyLayout | None: ...
+    @property
+    def text(self) -> str: ...
+    @property
+    def html(self) -> str: ...
+    @property
+    def tree(self) -> RenderedTree: ...
+
+class RenderedDocument:
+    @property
+    def citation_order(self) -> list[str]: ...
+    @property
+    def citations(self) -> dict[str, Rendered]: ...
+    @property
+    def bibliography(self) -> Rendered: ...
+    def __getitem__(self, id: str) -> Rendered: ...
+
+class Document:
+    def __init__(
+        self, library: Library, style: Style, *, locale: str | Locale | None = None
+    ) -> None: ...
+    def render(self, citations: Iterable[Citation]) -> RenderedDocument: ...
+    def cited_bibliography(self, citations: Iterable[Citation]) -> Rendered: ...
+    def full_bibliography(self) -> Rendered: ...
+
+class BibField:
+    @property
+    def name(self) -> str: ...
+    @property
+    def value(self) -> str: ...
+    @value.setter
+    def value(self, value: str) -> None: ...
+    @property
+    def span(self) -> tuple[int, int]: ...
+
+class BibFieldMap:
+    def unique_keys(self) -> list[str]: ...
+    def occurrence_keys(self) -> list[str]: ...
+    def occurrences(self) -> list[BibField]: ...
+    def get_all(self, key: str) -> list[BibField]: ...
+    def is_empty(self) -> bool: ...
+    def get_unique(self, key: str) -> BibField | None: ...
+    def __len__(self) -> int: ...
+    def __bool__(self) -> bool: ...
+    def __contains__(self, key: str) -> bool: ...
+    def __getitem__(self, key: str) -> BibField: ...
+
+class BibEntry:
+    @property
+    def key(self) -> str: ...
+    @property
+    def kind(self) -> str: ...
+    @property
+    def fields(self) -> BibFieldMap: ...
+    @property
+    def span(self) -> tuple[int, int]: ...
+
+class BibEntryMap:
+    def unique_keys(self) -> list[str]: ...
+    def occurrence_keys(self) -> list[str]: ...
+    def occurrences(self) -> list[BibEntry]: ...
+    def get_all(self, key: str) -> list[BibEntry]: ...
+    def is_empty(self) -> bool: ...
+    def get_unique(self, key: str) -> BibEntry | None: ...
+    def __len__(self) -> int: ...
+    def __bool__(self) -> bool: ...
+    def __contains__(self, key: str) -> bool: ...
+    def __getitem__(self, key: str) -> BibEntry: ...
+
+class BibDocument:
+    @property
+    def diagnostics(self) -> list[Diagnostic]: ...
+    @staticmethod
+    def read(path: str | PathLike[str]) -> BibDocument: ...
+    @staticmethod
+    def parse(source: str) -> BibDocument: ...
+    @property
+    def entries(self) -> BibEntryMap: ...
+    @property
+    def comments(self) -> list[str]: ...
+    @property
+    def preamble(self) -> str: ...
+    @property
+    def strings(self) -> dict[str, str]: ...
+    @property
+    def failed_blocks(self) -> list[RawFailedBlock]: ...
+    @property
+    def blocks(self) -> list[RawBlock]: ...
+    def to_bibtex(self) -> str: ...
+    def tidy(self, *, options: TidyOptions | None = None) -> TidyResult: ...
+    def write(self, path: str | PathLike[str]) -> None: ...

refkit/agent.py

@@ -0,0 +1,97 @@
+"""Use RefKit from code-mode agents."""
+
+import sys as _sys
+from importlib.metadata import version as _version
+from pathlib import Path as _Path
+from textwrap import indent as _indent
+from types import ModuleType as _ModuleType
+
+import agent_plugins as _agent_plugins
+
+_DISTRIBUTION_NAME = "refkit"
+_SKILL_NAME = "refkit"
+
+AgentPluginError = _agent_plugins.AgentPluginError
+
+
+def agent_plugin() -> _agent_plugins.Plugin:
+    """Return the Agent Plugin installed with this RefKit version.
+
+    Raises:
+        AgentPluginError: The installed distribution has no usable plugin marker.
+    """
+
+    return _agent_plugins.locate(_DISTRIBUTION_NAME)
+
+
+def agent_skill() -> _agent_plugins.Skill:
+    """Return the packaged RefKit Agent Skill.
+
+    Raises:
+        AgentPluginError: The installed plugin or its RefKit skill cannot be resolved.
+    """
+
+    return agent_plugin().skill(_SKILL_NAME)
+
+
+def instructions() -> str:
+    """Return the installed RefKit Agent Skill instructions as Markdown."""
+
+    return agent_skill().body.lstrip("\n")
+
+
+def resources() -> dict[str, _Path]:
+    """Return installed skill files keyed by skill-relative path."""
+
+    skill = agent_skill()
+    return {path.relative_to(skill.path).as_posix(): path for path in skill.files}
+
+
+def _module_help(summary: str) -> str:
+    introduction = f"""{summary}
+
+Installed refkit version: {_version(_DISTRIBUTION_NAME)}.
+
+Use `refkit.Library` to inspect normalized bibliography data, `refkit.Document`
+to render ordered citations, and `refkit.BibDocument` to edit raw BibTeX.
+
+    import refkit.agent as agent
+
+    print(agent.instructions())
+    print(agent.resources()["references/inspect.md"].read_text(encoding="utf-8"))
+
+Packaged instructions describe the installed API. Read the task resource before
+executing its example. The website at https://peter-gy.github.io/refkit/ describes
+the current published API and can differ from this installed version.
+"""
+    try:
+        skill = agent_skill()
+        tree = _indent(skill.tree(), "    ")
+    except AgentPluginError as error:
+        return f"{introduction}\nAgent Plugin unavailable: {error}\nReinstall refkit.\n"
+    return f"{introduction}\nInstalled task resources:\n\n{tree}\n"
+
+
+__all__ = [
+    "AgentPluginError",
+    "agent_plugin",
+    "agent_skill",
+    "instructions",
+    "resources",
+]
+
+
+class _AgentModule(_ModuleType):
+    @property
+    def __doc__(self) -> str | None:  # pyrefly: ignore [bad-override]
+        summary = self.__dict__.get("__doc__")
+        if not isinstance(summary, str):  # pragma: no cover - interpreter module state
+            return None
+        return _module_help(summary)
+
+    @__doc__.setter
+    def __doc__(self, value: str | None) -> None:  # pragma: no cover - interpreter hook
+        self.__dict__["__doc__"] = value
+
+
+_sys.modules[__name__].__class__ = _AgentModule

refkit/py.typed

@@ -0,0 +1 @@
+