Metadata-Version: 2.4
Name: goldrush
Version: 0.2.0
Summary: Generate Gold Rush (CoAlliance) matchKey for pymarc records
Author: Ed Summers
Author-email: Ed Summers <ehs@pobox.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pymarc>=5.3.1
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# goldrush

**Note: This is alpha software. If you rely on this library you should do so with the
understanding that you might find errors in the Gold Rush key that is generated.
Lets make it better together!**

---

[![Build status](https://gitlab.com/pymarc/goldrush/badges/main/pipeline.svg)](https://gitlab.com/pymarc/goldrush/-/commits/main)

*goldrush* is a Python implementation of the [Gold Rush match key algorithm] for
identifying "duplicate" MARC records, or records that appear to be about the
same bibliographic item. It provides a function that you pass a pymarc Record
and get back the Gold Rush key as a string.

goldrush is a class-for-class port of the canonical, production-verified Java
reference implementation, [coalliance-matchkey], maintained by the Colorado
Alliance of Research Libraries (CoAlliance). It targets algorithm version
**`_v03182026`**, whose version string is embedded in every generated key (just
before the trailing format character) so you can tell which algorithm produced a
given key. See [`docs/CoAlliance_Match_Key.md`](docs/CoAlliance_Match_Key.md)
for the field-by-field specification.

The initial code was found in [pymarc_dedupe] created by Max Kadel and Jane
Sandberg at Princeton University Library. The goldrush module was created
because pymarc_dedupe included other functionality that was unrelated to Gold
Rush, and pymarc_dedupe was not installable as a module via PyPI.

## Usage

First install:

```
pip install goldrush
```

Then load a pymarc record and generate a key:

```python
>>> from goldrush import goldrush
>>> from pymarc import MARCReader
>>> record = next(MARCReader(open('marc.dat', 'rb')))
>>> goldrush(record)
'pragmaticprogrammerfromjourneymantomaster___________________________________________________________2000____1__addisa________________________________________hunt_________________v03182026p'
```

The CoAlliance indexer optionally uses the MARC *filename* as a hint when
deciding whether a record is electronic or print. To match that behaviour, pass
the filename:

```python
>>> goldrush(record, marc_filename_hint='cu-electronic-2026-04.marc')
```

Pass nothing (the default) for pure-MARC format detection.

## Verifying against the reference

The reference implementation is the behavioural contract. The tests port its
JUnit suite to pytest and additionally diff goldrush's output for every record in
`tests/marc.dat` against a golden file (`tests/marc.dat.keys`) generated by the
reference `coa_matchkey_v03182026.jar`. To regenerate the golden file (requires
Java and marc4j 2.9.6 on the classpath):

```
java -Dorg.coalliance.indexing.fileName= \
     -cp coa_matchkey_v03182026.jar:marc4j-2.9.6.jar \
     org.coalliance.matchkey.cli.MatchKeyCli tests/marc.dat > tests/marc.dat.keys
```

## Credits and licensing

goldrush is licensed under the [Apache License, Version 2.0](LICENSE).

The Gold Rush matchKey algorithm is the work of the
[Colorado Alliance of Research Libraries], and goldrush's field-extraction and
normalization logic (`src/goldrush/fields/`, `src/goldrush/util/`,
`generator.py`, and `version.py`) is a port of their Apache-2.0 reference
implementation, [coalliance-matchkey] (Copyright 2026 Colorado Alliance of
Research Libraries). The ISBN-validation logic additionally derives from the
solrmarc-marc4j project. These attributions are recorded in [NOTICE](NOTICE).

[Gold Rush match key algorithm]: https://coalliance.org/sites/default/files/GoldRush-Match_KeyJanuary2024_0.doc
[coalliance-matchkey]: https://github.com/co-alliance/coalliance-matchkey
[Colorado Alliance of Research Libraries]: https://coalliance.org
[pymarc_dedupe]: https://github.com/pulibrary/pymarc_dedupe
