bxc 1.1.0__py3-none-any.whl

bxc/__init__.py

@@ -0,0 +1,76 @@
+"""
+bxc - Bibliographic Reference Formatter
+"""
+
+import os
+from bxc.parser import parse_bibtex
+from bxc.exceptions import BxcError, BibTeXParseError, StyleNotFoundError
+from bxc.cache import (
+    get_cache_dir,
+    resolve_style,
+    update_cache,
+    clear_cache,
+    rebuild_cache,
+    get_cache_status,
+)
+from bxc.registry import search_styles
+
+__version__ = "1.1.0"
+
+def format_bibtex(
+    bibtex_source: str,
+    style: str,
+    output_format: str = "plain",
+    mode: str = "bibliography",
+    cite: str | None = None,
+    is_path: bool = False
+) -> str:
+    """
+    Formats BibTeX references using a CSL style.
+    """
+    if bibtex_source is None or style is None:
+        raise TypeError("bibtex_source and style cannot be None")
+    if not isinstance(bibtex_source, str) or not isinstance(style, str):
+        raise TypeError("bibtex_source and style must be strings")
+        
+    valid_formats = {"plain", "markdown", "html"}
+    if output_format not in valid_formats:
+        raise BxcError(f"Unsupported output format: '{output_format}'")
+        
+    valid_modes = {"bibliography", "citation"}
+    if mode not in valid_modes:
+        raise BxcError(f"Unsupported selection mode: '{mode}'")
+
+    if bibtex_source == "-":
+        is_path = True
+    elif not is_path and bibtex_source and not bibtex_source.strip().startswith("@"):
+        if bibtex_source.endswith(".bib") or os.path.exists(bibtex_source):
+            is_path = True
+            
+    entries = parse_bibtex(bibtex_source, is_path=is_path)
+    style_path = resolve_style(style)
+    
+    from bxc.formatter import format_references
+    return format_references(
+        entries=entries,
+        style_path=style_path,
+        format=output_format,
+        mode=mode,
+        cite=cite
+    )
+
+
+__all__ = [
+    "parse_bibtex",
+    "format_bibtex",
+    "BxcError",
+    "BibTeXParseError",
+    "StyleNotFoundError",
+    "get_cache_dir",
+    "resolve_style",
+    "update_cache",
+    "clear_cache",
+    "rebuild_cache",
+    "get_cache_status",
+    "search_styles",
+]

bxc/author.py

@@ -0,0 +1,62 @@
+"""
+Author and editor parsing for BibTeX files.
+"""
+
+import re
+
+
+class AuthorParser:
+    """
+    Parses BibTeX author and editor name strings into structured CSL formats.
+    """
+
+    def parse_authors(self, author_str: str) -> list[dict[str, str]]:
+        """
+        Parses a BibTeX author/editor string (separated by 'and') into CSL-JSON family/given components.
+        """
+        if not author_str:
+            return []
+        # Split by 'and' case-insensitively; a single \s (not \s+) avoids any
+        # quantifier ambiguity, since leftover whitespace is stripped below anyway.
+        parts = re.split(r'\sand\s', author_str, flags=re.IGNORECASE)
+        authors = []
+        for part in parts:
+            part = part.strip()
+            if part:
+                authors.append(self._parse_name(part))
+        return authors
+
+    @staticmethod
+    def _is_braced_literal(part: str) -> bool:
+        return part.startswith('{') and part.endswith('}') and '{' not in part[1:-1] and '}' not in part[1:-1]
+
+    @staticmethod
+    def _split_name(part: str) -> tuple[str, str, str]:
+        """Returns (family, given, suffix) for a single BibTeX name."""
+        if ',' in part:
+            pieces = [x.strip() for x in part.split(',')]
+            if len(pieces) >= 3:
+                # "von Last, Jr, First"
+                return pieces[0], ", ".join(pieces[2:]), pieces[1]
+            return pieces[0], pieces[1], ""
+        words = part.rsplit(None, 1)
+        if len(words) == 2:
+            return words[1].strip(), words[0].strip(), ""
+        return part.strip(), "", ""
+
+    def _parse_name(self, part: str) -> dict[str, str]:
+        if part.lower() == "others":
+            return {"literal": "et al."}
+        if self._is_braced_literal(part):
+            # Fully braced name is an institution / single literal name
+            return {"literal": part[1:-1].strip()}
+        family, given, suffix = self._split_name(part)
+        # Clean curly braces that protect case
+        author = {
+            "family": family.replace('{', '').replace('}', ''),
+            "given": given.replace('{', '').replace('}', ''),
+        }
+        suffix = suffix.replace('{', '').replace('}', '')
+        if suffix:
+            author["suffix"] = suffix
+        return author

bxc/cache.py

@@ -0,0 +1,450 @@
+"""
+Cache management module for bxc.
+"""
+
+import os
+import shutil
+import platformdirs
+import tarfile
+import tempfile
+import urllib.request
+import urllib.error
+import xml.etree.ElementTree as ET
+import json
+import re
+import shutil as _shutil
+from typing import Any
+from bxc.exceptions import StyleNotFoundError, BxcError
+
+CSL_REMOTE_URL_PREFIX = "https://raw.githubusercontent.com/citation-style-language/styles/master/"
+
+# Local fallback for when the CDN above is unreachable or rate-limited: a
+# bundled snapshot of the full CSL styles repository (top-level + dependent/),
+# compressed with LZMA2 (xz) at max settings so it stays readable via the
+# standard library's tarfile/lzma modules without adding a runtime dependency.
+BUNDLED_STYLES_ARCHIVE = os.path.join(os.path.dirname(__file__), "styles_bundle.tar.xz")
+STYLES_INDEX_FILENAME = "styles_index.json"
+BUNDLED_STYLES_INDEX = os.path.join(os.path.dirname(__file__), STYLES_INDEX_FILENAME)
+
+# A CSL style id is a short lowercase slug; anything else (path separators, "..",
+# absolute paths, drive letters) must never reach the filesystem or the remote URL.
+STYLE_NAME_PATTERN = re.compile(r"[a-z0-9][a-z0-9._-]{0,127}")
+
+
+def validate_style_name(style_filename: str) -> str:
+    """Returns the style file name if it is a safe slug ending in .csl, else raises StyleNotFoundError."""
+    stem = style_filename[:-4] if style_filename.endswith(".csl") else style_filename
+    if not STYLE_NAME_PATTERN.fullmatch(stem) or ".." in stem:
+        raise StyleNotFoundError(
+            f"Invalid CSL style name '{style_filename}': expected a lowercase name such as 'ieee' "
+            "or the path to an existing .csl file."
+        )
+    return style_filename
+
+
+def _user_agent() -> str:
+    from bxc import __version__
+
+    return f"bxc-bibliographic-formatter/{__version__}"
+
+
+class CacheManager:
+    """
+    Manages the local OS-native CSL cache directory and remote updates.
+    """
+
+    def __init__(self, remote_url: str | None = None) -> None:
+        self.remote_url_prefix = remote_url or CSL_REMOTE_URL_PREFIX
+
+    def get_cache_dir(self) -> str:
+        """
+        Returns the absolute path to the local OS-native CSL cache directory.
+        Uses the BXC_CACHE_DIR environment variable if set to allow test isolation.
+        """
+        base_dir = os.environ.get("BXC_CACHE_DIR")
+        if not base_dir:
+            base_dir = platformdirs.user_cache_dir(appname="bxc")
+        
+        styles_dir = os.path.join(base_dir, "styles")
+        return styles_dir
+
+    def _fetch_url(self, url: str) -> bytes:
+        req = urllib.request.Request(
+            url,
+            headers={"User-Agent": _user_agent()}
+        )
+        with urllib.request.urlopen(req, timeout=10) as response:
+            return response.read()
+
+    def _write_cache_file_atomic(self, cache_dir: str, cache_path: str, content: bytes) -> None:
+        # Use delete=False for cross-platform (Windows) compatibility
+        tmp_file = tempfile.NamedTemporaryFile(dir=cache_dir, suffix=".tmp", delete=False)
+        temp_path = tmp_file.name
+        try:
+            tmp_file.write(content)
+            tmp_file.close()  # Must close before os.replace
+            os.replace(temp_path, cache_path)
+        except Exception:
+            tmp_file.close()
+            if os.path.exists(temp_path):
+                try:
+                    os.remove(temp_path)
+                except OSError:
+                    pass
+            raise
+
+    def _extract_from_bundle(self, style_name: str) -> bytes | None:
+        """
+        Looks up style_name in the bundled local CSL archive shipped with bxc.
+        Returns the raw CSL bytes if found, or None if the archive is missing
+        or doesn't contain this style.
+        """
+        if not os.path.exists(BUNDLED_STYLES_ARCHIVE):
+            return None
+        try:
+            with tarfile.open(BUNDLED_STYLES_ARCHIVE, mode="r:xz") as archive:
+                for member_name in (f"./{style_name}", f"./dependent/{style_name}"):
+                    try:
+                        member = archive.getmember(member_name)
+                    except KeyError:
+                        continue
+                    extracted = archive.extractfile(member)
+                    if extracted is not None:
+                        return extracted.read()
+        except (tarfile.TarError, OSError):
+            return None
+        return None
+
+    def _download_from_cdn(self, style_name: str, cache_dir: str, cache_path: str) -> Exception | None:
+        """
+        Tries every candidate CDN URL for style_name. On success, writes the
+        result to cache_path and returns None. On total failure, returns the
+        last error encountered instead of raising, so callers can decide what
+        to try next (e.g. the bundled archive) before giving up.
+        """
+        remote_base = os.environ.get("BXC_REMOTE_URL", self.remote_url_prefix)
+        if not remote_base.endswith("/"):
+            remote_base += "/"
+
+        # Dependent styles (e.g. journal-specific variants) live under a
+        # dependent/ prefix on the real CSL repository, not at the top level.
+        candidate_urls = [f"{remote_base}{style_name}", f"{remote_base}dependent/{style_name}"]
+
+        last_error: Exception | None = None
+        for url in candidate_urls:
+            try:
+                content = self._fetch_url(url)
+                self._write_cache_file_atomic(cache_dir, cache_path, content)
+                return None
+            except urllib.error.HTTPError as e:
+                last_error = e
+                if e.code == 404:
+                    continue  # try the next candidate path
+                break  # a non-404 HTTP error means the CDN itself is misbehaving
+            except Exception as e:
+                last_error = e
+                break  # network-level failure (DNS/timeout/connection) - no point retrying paths
+        return last_error
+
+    def download_style(self, style_name: str, cache_path: str, prefer_bundle: bool = True) -> None:
+        """
+        Resolves a CSL style and saves it to cache_path.
+
+        By default (prefer_bundle=True), checks the local bundled archive
+        shipped with bxc first - instant, offline, and avoids hammering the
+        CDN for the 10,000+ styles already snapshotted locally - and only
+        talks to the network for styles the bundle doesn't have. This is
+        what everyday style resolution (`bxc format`) uses.
+
+        Sync-oriented callers that specifically want fresh content from the
+        CDN (`bxc cache update` / `bxc cache rebuild`) pass prefer_bundle=False
+        to check the CDN first instead, still falling back to the bundle if
+        the CDN is unreachable. Ensures thread-safe and process-safe atomic
+        writes either way.
+
+        An explicit BXC_REMOTE_URL override always wins over prefer_bundle:
+        pointing bxc at a specific remote (a private mirror, a test mock
+        server) is a deliberate signal to talk to that remote, not to get
+        silently intercepted by the bundled snapshot.
+        """
+        cache_dir = os.path.dirname(cache_path)
+        os.makedirs(cache_dir, exist_ok=True)
+
+        effective_prefer_bundle = prefer_bundle and "BXC_REMOTE_URL" not in os.environ
+
+        if effective_prefer_bundle:
+            bundled_content = self._extract_from_bundle(style_name)
+            if bundled_content is not None:
+                self._write_cache_file_atomic(cache_dir, cache_path, bundled_content)
+                return
+            last_error = self._download_from_cdn(style_name, cache_dir, cache_path)
+            if last_error is None:
+                return
+        else:
+            last_error = self._download_from_cdn(style_name, cache_dir, cache_path)
+            if last_error is None:
+                return
+            bundled_content = self._extract_from_bundle(style_name)
+            if bundled_content is not None:
+                self._write_cache_file_atomic(cache_dir, cache_path, bundled_content)
+                return
+
+        if isinstance(last_error, urllib.error.HTTPError):
+            if last_error.code == 404:
+                raise StyleNotFoundError(
+                    f"Failed to download CSL style '{style_name}': not found on remote server (404)."
+                ) from last_error
+            raise StyleNotFoundError(
+                f"Failed to download CSL style '{style_name}' (HTTP {last_error.code})."
+            ) from last_error
+        raise StyleNotFoundError(
+            f"Failed to download CSL style '{style_name}': not found locally and "
+            f"could not be fetched from the remote repository: {last_error}"
+        ) from last_error
+
+    def extract_independent_parent(self, csl_content: bytes) -> str | None:
+        """
+        Parses CSL XML content and extracts the style name of the independent parent if present.
+        """
+        if not csl_content:
+            raise BxcError("CSL style file is empty.")
+        try:
+            root = ET.fromstring(csl_content)
+            for elem in root.iter():
+                tag = elem.tag
+                if tag.endswith("link") or tag == "link":
+                    rel = elem.attrib.get("rel")
+                    href = elem.attrib.get("href")
+                    if rel == "independent-parent" and href:
+                        parent_name = href.rstrip("/").split("/")[-1]
+                        return parent_name
+        except ET.ParseError as e:
+            raise BxcError(f"XML parse error: {e}") from e
+        return None
+
+    def _resolve_parent_or_path(self, content: bytes, path: str, visited: set[str]) -> str:
+        parent_name = self.extract_independent_parent(content)
+        if parent_name:
+            return self.resolve_style(parent_name, visited)
+        return os.path.abspath(path)
+
+    def _read_and_resolve(self, path: str, visited: set[str], error_context: str) -> str:
+        try:
+            with open(path, "rb") as f:
+                content = f.read()
+        except Exception as e:
+            raise BxcError(f"{error_context}: {e}") from e
+        return self._resolve_parent_or_path(content, path, visited)
+
+    def _resolve_local_style(self, style_identifier: str, visited: set[str]) -> str:
+        if not os.path.isfile(style_identifier):
+            raise StyleNotFoundError(
+                f"Local CSL style file '{style_identifier}' could not be resolved. "
+                "The file does not exist or is not a valid file."
+            )
+        abs_path = os.path.abspath(style_identifier)
+        return self._read_and_resolve(
+            abs_path, visited, f"Failed to read local CSL style '{style_identifier}'"
+        )
+
+    def _resolve_cached_style(self, style_identifier: str, visited: set[str]) -> str:
+        style_name_lower = style_identifier.lower()
+        style_filename = style_name_lower if style_name_lower.endswith(".csl") else f"{style_name_lower}.csl"
+        validate_style_name(style_filename)
+
+        cache_dir = self.get_cache_dir()
+        cache_path = os.path.join(cache_dir, style_filename)
+        cache_exists = os.path.exists(cache_path) and os.path.isfile(cache_path)
+
+        if cache_exists and os.path.getsize(cache_path) == 0:
+            self.download_style(style_filename, cache_path)
+            return self._read_and_resolve(
+                cache_path, visited, f"Failed to read cached CSL style '{cache_path}' after download"
+            )
+
+        if cache_exists:
+            try:
+                return self._read_and_resolve(cache_path, visited, "")
+            except Exception:
+                pass  # corrupted/unreadable cache entry - fall through and redownload
+
+        self.download_style(style_filename, cache_path)
+        return self._read_and_resolve(
+            cache_path, visited, f"Failed to read cached CSL style '{cache_path}'"
+        )
+
+    @staticmethod
+    def _normalize_style_identifier(style_identifier: str) -> tuple[str, bool]:
+        is_local_path = style_identifier.lower().endswith(".csl") or os.path.exists(style_identifier)
+        if is_local_path:
+            norm_id = os.path.abspath(style_identifier)
+        else:
+            norm_id = style_identifier.lower()
+            if not norm_id.endswith(".csl"):
+                norm_id = f"{norm_id}.csl"
+        return norm_id, is_local_path
+
+    def resolve_style(self, style_identifier: str, visited: set[str] | None = None) -> str:
+        """
+        Resolves a style name or a local path to the absolute path of a CSL style file.
+        """
+        if visited is None:
+            visited = set()
+
+        norm_id, is_local_path = self._normalize_style_identifier(style_identifier)
+        if norm_id in visited:
+            raise BxcError(f"Circular dependency detected in style resolution for '{style_identifier}'")
+        visited.add(norm_id)
+
+        if is_local_path:
+            return self._resolve_local_style(style_identifier, visited)
+        return self._resolve_cached_style(style_identifier, visited)
+
+    def update_cache(self) -> bool:
+        """
+        Refreshes the style index. Returns True when a fresh index was downloaded from the
+        remote, False when the default remote has none (HTTP 404) and the bundled index
+        was installed instead.
+        """
+        cache_dir = self.get_cache_dir()
+        base_dir = os.path.dirname(cache_dir)
+        os.makedirs(base_dir, exist_ok=True)
+        
+        index_path = os.path.join(base_dir, STYLES_INDEX_FILENAME)
+        
+        remote_base = os.environ.get("BXC_REMOTE_URL", self.remote_url_prefix)
+        if not remote_base.endswith("/"):
+            remote_base += "/"
+        url = f"{remote_base}{STYLES_INDEX_FILENAME}"
+        
+        tmp_file = tempfile.NamedTemporaryFile(dir=base_dir, suffix=".tmp", delete=False)
+        temp_path = tmp_file.name
+        
+        try:
+            req = urllib.request.Request(
+                url,
+                headers={"User-Agent": _user_agent()}
+            )
+            with urllib.request.urlopen(req, timeout=10) as response:
+                content = response.read()
+                
+            json.loads(content.decode("utf-8"))
+            
+            tmp_file.write(content)
+            tmp_file.close()
+            
+            os.replace(temp_path, index_path)
+            return True
+        except Exception as e:
+            tmp_file.close()
+            if os.path.exists(temp_path):
+                try:
+                    os.remove(temp_path)
+                except OSError:
+                    pass
+            # The upstream CSL repository does not publish styles_index.json; when using the
+            # default remote (no explicit override), refresh from the bundled index instead.
+            using_default_remote = "BXC_REMOTE_URL" not in os.environ and self.remote_url_prefix == CSL_REMOTE_URL_PREFIX
+            if (
+                using_default_remote
+                and isinstance(e, urllib.error.HTTPError)
+                and e.code == 404
+                and os.path.isfile(BUNDLED_STYLES_INDEX)
+            ):
+                _shutil.copyfile(BUNDLED_STYLES_INDEX, index_path)
+                return False
+            raise BxcError(f"Failed to update cache: {e}") from e
+
+    def clear_cache(self) -> None:
+        """
+        Clears all cached CSL styles and deletes the index file.
+        """
+        cache_dir = self.get_cache_dir()
+        if os.path.exists(cache_dir):
+            for filename in os.listdir(cache_dir):
+                file_path = os.path.join(cache_dir, filename)
+                try:
+                    if os.path.isfile(file_path) or os.path.islink(file_path):
+                        os.unlink(file_path)
+                    elif os.path.isdir(file_path):
+                        shutil.rmtree(file_path)
+                except Exception as e:
+                    raise BxcError(f"Failed to delete cached style file '{file_path}': {e}")
+                    
+        base_dir = os.path.dirname(cache_dir)
+        index_path = os.path.join(base_dir, STYLES_INDEX_FILENAME)
+        if os.path.exists(index_path):
+            try:
+                os.remove(index_path)
+            except Exception as e:
+                raise BxcError(f"Failed to delete style index file '{index_path}': {e}")
+
+    def get_cache_status(self) -> dict[str, Any]:
+        """
+        Returns status information about the cache.
+        """
+        cache_dir = self.get_cache_dir()
+        base_dir = os.path.dirname(cache_dir)
+        index_path = os.path.join(base_dir, STYLES_INDEX_FILENAME)
+        
+        styles_count = 0
+        corrupted_count = 0
+        if os.path.exists(cache_dir):
+            for filename in os.listdir(cache_dir):
+                file_path = os.path.join(cache_dir, filename)
+                if os.path.isfile(file_path) and filename.endswith(".csl"):
+                    styles_count += 1
+                    if os.path.getsize(file_path) == 0:
+                        corrupted_count += 1
+                        
+        return {
+            "cache_dir": cache_dir,
+            "index_exists": os.path.exists(index_path),
+            "styles_count": styles_count,
+            "corrupted_count": corrupted_count
+        }
+
+    def rebuild_cache(self) -> None:
+        """
+        Rebuilds the cache by updating the index and re-downloading all cached CSL styles.
+        This is a "sync with CDN" operation, so it checks the CDN first for
+        fresh content rather than the (static) bundled archive - it only
+        falls back to the bundle if the CDN itself is unreachable.
+        """
+        self.update_cache()
+
+        cache_dir = self.get_cache_dir()
+        if os.path.exists(cache_dir):
+            for filename in os.listdir(cache_dir):
+                file_path = os.path.join(cache_dir, filename)
+                if os.path.isfile(file_path) and filename.endswith(".csl"):
+                    self.download_style(filename, file_path, prefer_bundle=False)
+
+
+# --- Global Backward Compatible API Functions ---
+
+_default_cache_manager = CacheManager()
+
+
+def get_cache_dir() -> str:
+    return _default_cache_manager.get_cache_dir()
+
+
+def resolve_style(style_identifier: str, visited: set[str] | None = None) -> str:
+    return _default_cache_manager.resolve_style(style_identifier, visited)
+
+
+def update_cache() -> bool:
+    return _default_cache_manager.update_cache()
+
+
+def clear_cache() -> None:
+    return _default_cache_manager.clear_cache()
+
+
+def get_cache_status() -> dict[str, Any]:
+    return _default_cache_manager.get_cache_status()
+
+
+def rebuild_cache() -> None:
+    return _default_cache_manager.rebuild_cache()