Metadata-Version: 2.4
Name: iscc-lib
Version: 0.0.2
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
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 :: Multimedia
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries
Summary: High-performance Python bindings for ISO 24138:2024 (ISCC)
Keywords: iscc,content-id,media,fingerprint,iso24138
Author-email: Titusz Pan <tp@py7.de>
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://lib.iscc.codes
Project-URL: Homepage, https://lib.iscc.codes
Project-URL: Issues, https://github.com/iscc/iscc-lib/issues
Project-URL: Repository, https://github.com/iscc/iscc-lib

# iscc-lib

[![CI](https://github.com/iscc/iscc-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/iscc/iscc-lib/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/iscc-lib.svg)](https://pypi.org/project/iscc-lib/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

> **Experimental:** This library is in early development (v0.0.x). APIs may change without notice.
> Not recommended for production use yet.

High-performance Python bindings for [ISO 24138:2024](https://www.iso.org/standard/77899.html) --
International Standard Content Code (ISCC). Built on a Rust core for speed, with a Pythonic API that
is a drop-in replacement for [iscc-core](https://github.com/iscc/iscc-core).

## What is ISCC

The ISCC is a similarity-preserving fingerprint and identifier for digital media assets. ISCCs are
generated algorithmically from digital content, just like cryptographic hashes. However, instead of
using a single cryptographic hash function to identify data only, the ISCC uses various algorithms
to create a composite identifier that exhibits similarity-preserving properties (soft hash).

## Installation

```bash
pip install iscc-lib
```

## Quick Start

```python
import iscc_lib as ic

result = ic.gen_meta_code_v0("ISCC Test Document!")
print(f"Meta-Code: {result['iscc']}")
```

## API Overview

### Code Generators

| Function               | Description                                    |
| ---------------------- | ---------------------------------------------- |
| `gen_meta_code_v0`     | Generate a Meta-Code from metadata fields      |
| `gen_text_code_v0`     | Generate a Text-Code from plain text           |
| `gen_image_code_v0`    | Generate an Image-Code from pixel data         |
| `gen_audio_code_v0`    | Generate an Audio-Code from Chromaprint data   |
| `gen_video_code_v0`    | Generate a Video-Code from frame signatures    |
| `gen_mixed_code_v0`    | Generate a Mixed-Code from Content-Codes       |
| `gen_data_code_v0`     | Generate a Data-Code from bytes or stream      |
| `gen_instance_code_v0` | Generate an Instance-Code from bytes or stream |
| `gen_iscc_code_v0`     | Generate a composite ISCC-CODE                 |

### Utilities

- **Text processing:** `text_clean`, `text_remove_newlines`, `text_trim`, `text_collapse`
- **Algorithm primitives:** `alg_simhash`, `alg_minhash_256`, `alg_cdc_chunks`, `sliding_window`
- **Soft hashing:** `soft_hash_video_v0`
- **Encoding:** `encode_base64`
- **Codec:** `iscc_decompose`
- **Streaming:** `DataHasher`, `InstanceHasher` for incremental processing
- **Diagnostics:** `conformance_selftest`

Streaming functions (`gen_data_code_v0`, `gen_instance_code_v0`) accept both `bytes` and file-like
objects (`BinaryIO`).

## Links

- [Documentation](https://lib.iscc.codes)
- [Repository](https://github.com/iscc/iscc-lib)
- [ISCC Specification (ISO 24138)](https://www.iso.org/standard/77899.html)
- [ISCC Foundation](https://iscc.io)

## License

Apache-2.0

