mrrc 0.7.4

A Rust library for reading, writing, and manipulating MARC bibliographic records in ISO 2709 binary format
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# MRRC — MARC Rust Crate

Rust library for MARC bibliographic records (ISO 2709) with pymarc-compatible
Python bindings via PyO3/maturin.

## Key Files

| Path | Purpose |
|------|---------|
| `src/` | Rust core library (parsing, serialization, query DSL) |
| `src-python/` | PyO3 bindings (`mrrc-python` crate) |
| `mrrc/__init__.py` | Python wrapper — re-exports and extends Rust types |
| `mrrc/_mrrc.pyi` | **Canonical Python API** — ground-truth type stubs |
| `.cargo/check.sh` | Local CI script (run before every push) |
| `tests/python/` | Active Python test suite |
| `examples/` | Runnable Rust and Python examples |
| `docs/` | mkdocs-material documentation site |

## Build & Test

```bash
# Full pre-push check (~30s) — always run this before pushing
.cargo/check.sh

# Quick mode (skips docs, audit, maturin rebuild)
.cargo/check.sh --quick

# Individual commands
cargo test --lib --tests --package mrrc -q    # Rust tests
cargo test --doc --package mrrc -q            # Doc tests
uv run maturin develop --release              # Build Python extension
uv run python -m pytest tests/python/ -m "not benchmark" -q  # Python tests
uv run ruff check mrrc/ tests/python/         # Python lint
```

## Architecture

### Rust Core (`src/`)

The `mrrc` crate handles all parsing, serialization, and record manipulation.
Formats: ISO 2709, JSON, MARCXML, CSV, Dublin Core, MODS, BIBFRAME (RDF).

### Python Bindings (`src-python/src/`)

PyO3 `#[pyclass]` types expose Rust structs to Python. The compiled extension
is `_mrrc` (note the underscore).

### Python Wrapper (`mrrc/__init__.py`)

Re-exports Rust types and adds pymarc-compatible conveniences. The wrapper
pattern: `MARCReader` wraps `_MARCReader` via `self._inner` delegation.

**Adding a new feature requires all layers:**

1. Rust implementation in `src/`
2. PyO3 `#[getter]` / `#[pymethods]` in `src-python/src/`
3. Python re-export or wrapper in `mrrc/__init__.py`
4. Type stub update in `mrrc/_mrrc.pyi`

### GIL 3-Phase Model (MARCReader)

1. **Acquire GIL** — receive Python file object or path
2. **Release GIL** — parse record bytes in pure Rust
3. **Acquire GIL** — wrap result as Python object and return

This enables true multi-thread parallelism via `ThreadPoolExecutor`.

## Issue Tracking

This project uses **br** (beads_rust) for issue tracking.

```bash
br ready --json          # Show unblocked work
br create "Title" -t bug|feature|task -p 0-4 --json
br update <id> --status in_progress --json
br close <id> --reason "Completed" --json
br sync --flush-only     # Export DB to JSONL (never auto-commits)
```

Do NOT use `br edit` (opens `$EDITOR`, blocks agents).

## Warnings

- **`docs/history/`** — archival only (89 files). Do not modify.
- **Never close issues before CI passes** — commit, push, verify CI on all
  platforms, then close.

## Workflow

- New issue = new branch from `main`
- Always run `.cargo/check.sh` before pushing
- Use `uv` for all Python invocations

## See Also

- [`AGENTS.md`](AGENTS.md) — expanded agent instructions (testing workflow,
  session completion checklist)