Metadata-Version: 2.4
Name: csan
Version: 0.7.1
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Text Processing
Classifier: Topic :: Text Processing :: Indexing
Summary: Cutter call numbers for library cataloging (Cutter-Sanborn and Library of Congress)
Keywords: cutter,cutter-sanborn,library-of-congress,call-number,library,cataloging
Author-email: VERALVX <veralvx@veralvx.com>
License: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/veralvx/csan/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/veralvx/csan/issues
Project-URL: Repository, https://github.com/veralvx/csan

# csan (Python package)

Generate Cutter-Sanborn three-figure and Library of Congress cutter numbers
for library cataloging from author names and titles. The package provides
Python bindings to the Rust [`csan-core`](https://crates.io/crates/csan-core)
library and the `csan` command-line tool, as abi3 wheels for CPython 3.9+
on Linux, macOS, and Windows.

```sh
pip install csan        # library + CLI
uv tool install csan    # just the CLI, isolated
```

```python
import csan

csan.cutter_sanborn(forename="Charles", surname="Dickens",
                    title="Oliver Twist")  # 'D548o'
csan.cutter_loc(surname="Carter")  # 'C378'

csan.cutter_sanborn_detailed(surname="Borges")
# {'alpha_prefix': 'B', 'alpha_suffix': None, 'entry': 'Borg',
#  'formatted': 'B732', 'numeric': 732}
```

Every function accepts `forename`, `surname`, and `title` keyword
arguments (at least one must be non-blank; blank strings count as absent).
`cutter_sanborn*` also take `prefix_len` and `suffix_len`; `cutter_loc*`
take `max_len` (clamped to 4). The `*_detailed` variants return a dict of
the number's parts plus the rendered call number under `"formatted"`.
Unusable input raises `ValueError`.

The console script is the same interface as the standalone Rust binary:

```sh
csan --forename Charles --surname Dickens --title "Oliver Twist"   # D548o
csan --method cutter-loc --surname Carter                         # C378
```

## Building from source

Built with [maturin](https://www.maturin.rs/) from
[`crates/csan-py`](https://github.com/veralvx/csan/tree/main/crates/csan-py)
in the main repository (Rust toolchain required):

```sh
pip install maturin
maturin develop -m crates/csan-py/Cargo.toml       # editable install
maturin build --release -m crates/csan-py/Cargo.toml
```

Each [GitHub release](https://github.com/veralvx/csan/releases) carries
the wheels (Linux manylinux and musllinux, macOS, and Windows, on x86_64
and aarch64) and the sdist that are published to PyPI.

## License

Licensed under either of
[Apache License, Version 2.0](https://github.com/veralvx/csan/blob/main/LICENSE-APACHE)
or [MIT license](https://github.com/veralvx/csan/blob/main/LICENSE-MIT)
at your option.

