Metadata-Version: 2.5
Name: bxc
Version: 1.1.0
Summary: A lightweight Python library and CLI tool to format BibTeX references using CSL
Project-URL: Homepage, https://forgejo.fchicout.dev/fchicout/bxc
Project-URL: Issues, https://forgejo.fchicout.dev/fchicout/bxc/issues
Author-email: Fabio Chicout <fchicout@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: bibliography,bibtex,citation,csl,references
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Text Processing :: Markup
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: bibtexparser<2.0.0,>=1.4.3
Requires-Dist: citeproc-py>=0.6.0
Requires-Dist: platformdirs>=4.0.0
Provides-Extra: lint
Requires-Dist: mypy>=2.0.0; extra == 'lint'
Requires-Dist: ruff>=0.14.0; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# bxc (Bibliographic Reference Formatter)

A lightweight Python library and Command Line Interface (CLI) tool designed to format BibTeX bibliography records into academic styles (like IEEE, ABNT, ACM) using **Citation Style Language (CSL)**. It natively outputs to Markdown, HTML, and Plain Text, making it perfect for static blogs, documentation websites, and automated citation pipelines.

---

## Key Features

*   **Zero-Configuration UX:** Automatically resolves, downloads, and caches standard academic styles (e.g., `ieee`, `nature`, `abnt`) on demand from the official CSL repositories.
*   **Offline-First Style Resolution:** Ships with a bundled, compressed snapshot of the entire CSL styles repository (10,000+ styles, ~1.4MB). Style lookups check this local archive before ever touching the network, so `bxc format` works instantly and fully offline for any standard style - the CDN is only used for brand-new styles not yet in the bundle, or when explicitly syncing (`bxc cache update` / `bxc cache rebuild`).
*   **LaTeX to Unicode Normalization:** Seamlessly cleans and converts LaTeX accent escape codes (like `{\`e}`, `\c{c}`) to standard Unicode (e.g., `è`, `ç`) prior to formatting.
*   **Multiple Output Targets:** Renders styled reference lists natively to Markdown, HTML, and Plain Text.
*   **Local Cross-Platform Caching:** Caches downloaded styles locally according to OS-native standards (`~/.cache/bxc/` on Linux, `~/Library/Caches/bxc/` on macOS, `%LOCALAPPDATA%\\bxc\\Cache` on Windows; run `bxc cache status` to see yours).
*   **Flexible Interface:** Use it as a terminal CLI tool or import it as a standard Python library.

---

## Installation

Requires Python 3.12 or newer.

**pip / pipx** (any platform):

```bash
pipx install bxc      # or: pip install bxc
```

**Native installers** are attached to each release on the project page, with a `SHA256SUMS` file to verify them:

| Platform | Package | Install |
|---|---|---|
| Debian 13+, Ubuntu 24.04+ | `bxc_<version>_all.deb` | `sudo apt install ./bxc_<version>_all.deb` |
| Fedora 40+, RHEL / AlmaLinux 10+ | `bxc-<version>-1.noarch.rpm` | `sudo dnf install ./bxc-<version>-1.noarch.rpm` |
| Windows 10+ (x64) | `bxc-<version>-x64.msi` | double-click, or `msiexec /i bxc-<version>-x64.msi` |

The deb and rpm bundle bxc's pure-Python dependencies and use your distribution's `python3` and `python3-lxml`; the package manager installs them for you. They need Python 3.12+, so older distributions (Debian 12, Ubuntu 22.04, RHEL 9) should use `pipx` instead. The Windows installer is self-contained (it ships its own Python) and adds `bxc` to the system `PATH`; it is not code-signed, so Windows SmartScreen may warn on first run. Open a new terminal after installing.

---

## Quick Start

### Command Line Interface (CLI)

Format a `.bib` file to Markdown using IEEE style:
```bash
bxc format citations.bib --style ieee --output markdown
```

Search for a citation style:
```bash
bxc search "ABNT"
```

Clear, sync, or inspect the local cache:
```bash
bxc cache update   # refresh the style search index from the CDN
bxc cache rebuild   # re-download every cached style from the CDN (sync with CDN)
bxc cache status   # show cache location and stats
bxc cache clear    # remove all cached styles and the index
```

`bxc cache update` and `bxc cache rebuild` are the commands that talk to the CDN on purpose - they're how you get styles fresher than the bundled snapshot. Everyday `bxc format` calls never need them: they resolve styles from the bundled local archive first (see [Offline-First Style Resolution](#key-features) above), which is why bxc works out of the box without a network connection.

Maintainers can refresh that bundled archive itself (a periodic task, not something end users run) with:
```bash
python build_styles_bundle.py
```

### Python API

```python
import bxc

# Parses, converts LaTeX escapes, fetches CSL, and formats citation
markdown_ref = bxc.format_bibtex(
    bibtex_source="@article{smith2026, ...}",
    style="ieee",
    output_format="markdown"
)

print(markdown_ref)
```

---

## CLI reference

`bxc format [BIB] --style STYLE [--output plain|markdown|html] [--mode bibliography|citation] [--cite KEYS] [--out-file PATH]`

*   `BIB` (or `--bib/-b`): path to a `.bib` file; use `-` to read from stdin.
*   `--style/-s`: a CSL style name (e.g. `ieee`, `apa`) or the path to a local `.csl` file.
*   `--cite/-c`: comma-separated citation keys to format.
*   Exit codes: `0` success, `1` error (parse failure, style not found, ...), `2` invalid usage, `130` interrupted.

`bxc search [QUERY] [--category CATEGORY]` searches the style registry; `bxc cache {status,update,rebuild,clear}` manages the local cache.

## License

Apache License 2.0. The bundled CSL styles are from the [Citation Style Language styles repository](https://github.com/citation-style-language/styles) and are licensed under CC BY-SA 3.0; see `NOTICE`.
