Metadata-Version: 2.4
Name: pysolrmarc
Version: 0.5.0
Summary: Python wrapper for Solrmarc – converts MARC records to Solr documents via the Solrmarc Java tool
Project-URL: Repository, https://git.slub-dresden.de/prefect-flows/pysolrmarc
Author-email: Ralph Borowski <Ralph.Borowski@slub-dresden.de>, Thomas Baer <thomas.baer@slub-dresden.de>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# pysolrmarc

A Python wrapper for [Solrmarc](https://github.com/solrmarc/solrmarc) that converts binary MARC records into Solr documents by communicating with the Solrmarc Java process via stdin/stdout (NDJSON).

## Installation

```bash
pip install pysolrmarc
```

## Prerequisites

- **Java 8+** must be installed and available on `PATH`.
- A **Solrmarc** installation directory (default: `/opt/solrmarc`) containing:
  - `solrmarc/solrmarc_core_ant.jar`
  - `solrmarc/lib/` (Java dependencies)
  - `solrmarc/lib_solrj/` and `solrmarc/lib_local/`
  - `solrmarc/log4j.properties`
  - A mapping properties file (e.g. `index.kxp.tit.properties`)
  - A reader options file (e.g. `marcreader.properties`)

## Quick Start

```python
import pysolrmarc

with pysolrmarc.Solrmarc(
    mapping="/opt/solrmarc/mappings/ahn/index.kxp.tit.properties",
    reader_opts="/opt/solrmarc/mappings/ahn/marcreader.properties",
) as sm:
    solr_doc = sm.convert(binary_marc_record)
    print(solr_doc)
```

The context manager ensures the Java process is terminated gracefully when done. You can also use it without `with` and call `close()` manually:

```python
sm = pysolrmarc.Solrmarc(
    mapping="/opt/solrmarc/mappings/ahn/index.kxp.tit.properties",
    reader_opts="/opt/solrmarc/mappings/ahn/marcreader.properties",
    path="/opt/solrmarc",
)
try:
    solr_doc = sm.convert(binary_marc_record)
finally:
    sm.close()
```

## API Reference

### `Solrmarc(mapping, reader_opts, path="/opt/solrmarc")`

Creates a new `Solrmarc` instance and starts the Java process.

| Parameter | Type | Description |
|---|---|---|
| `mapping` | `str` | Full path to the Solrmarc mapping properties file. |
| `reader_opts` | `str` | Full path to the reader options configuration file. |
| `path` | `str` | Root path of the Solrmarc installation (default: `/opt/solrmarc`). |

Supports the context manager protocol (`with` statement).

### `convert(marc, retries=2) -> dict | None`

Converts a single binary MARC record to a Solr document dict.

| Parameter | Type | Description |
|---|---|---|
| `marc` | `bytes` | Binary MARC record data. |
| `retries` | `int` | Number of retry attempts on timeout (default: 2). |

Returns a `dict` representing the Solr document, or `None` if Solrmarc returned an empty response.

Raises an `Exception` if JSON decoding fails or all retries are exhausted.

### `start() -> None`

Starts the Solrmarc Java process. Called automatically on `__init__`. Use to restart after calling `stop()`.

### `stop() -> None`

Kills the Solrmarc process forcefully (sends `SIGKILL`).

### `restart() -> None`

Stops and restarts the Solrmarc instance.

### `close() -> None`

Terminates the Solrmarc process gracefully (sends `SIGTERM`). Called automatically when exiting a `with` block.

## Build and Publish

```bash
pip install hatch
hatch build
uv publish dist/*
```

To publish to a private registry:

```bash
uv publish --publish-url https://git.slub-dresden.de/api/v4/projects/2300/packages/pypi dist/*
```

## License

MIT – see [LICENSE](LICENSE).