Metadata-Version: 2.3
Name: tika_rest_client
Version: 1.0.2
Summary: Python REST client for Apache Tika REST server
License: cc-by-sa-nc
Author: Théo
Author-email: theo.nardin@cri-paris.org
Requires-Python: >=3.12
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: beautifulsoup4 (>=4.15.0,<5.0.0)
Requires-Dist: ipykernel (>=7.3.0,<8.0.0)
Requires-Dist: requests (>=2.34.2,<3.0.0)
Description-Content-Type: text/markdown

# Tika REST Client

[![PyPi version](https://badgen.net/pypi/v/tika-rest-client/)](https://pypi.org/project/pip/tika-rest-client)

Python client for Apache Tika REST endpoints.

## Overview

`tika_rest_client` provides a small, typed interface for common Apache Tika operations:

- server health/version checks,
- language identification,
- text extraction (plain text or paginated),
- metadata extraction.

It wraps HTTP/network failures with library-specific exceptions and returns structured response models.

## Installation

```bash
pip install tika-rest-client
```

## Requirements

- Python 3.12+
- A running Apache Tika server (for example on `http://localhost:8080`)

## Quick Start

```python
import io
from tika_rest_client import TikaRestClient

# IMPORTANT:
# In the current implementation, `host` is used as the full base URL.
# Example: "http://localhost:8080"
client = TikaRestClient(host="http://localhost:8080")

# Health check
print(client.check_connection())  # True / False

# Version
version = client.check_version()
print(version.response)  # e.g. "3.4.4"

# Language detection
lang = client.identify_language("Hello world")
print(lang.response)  # "en"

# Metadata extraction
metadata = client.extract_file_metadata(io.BytesIO(b"example content"))
print(metadata.metadata.general.content_type)
```

## Main API

### `check_connection()`

Returns `True` if the Tika server responds with HTTP 200 on the version endpoint, otherwise `False`.

### `check_version()`

Returns a `PlainTextResponse` containing the server version.
Raises `TikaRestClientNetworkException` on HTTP errors.

### `identify_language(input_to_test)`

Accepts one of:

- `str`
- `bytes`
- buffered file-like object (`io.BytesIO`, `BinaryIO`)

Returns `PlainTextResponse`.
Raises:

- `InputFormatNotAvailableForThisEndpoint` for unsupported input types,
- `LanguageIdentificationError` when a language detection request fails.

### `extract_file_content(file_content, paginate, boilerplate, ocr)`

Extracts textual content from binary file data.

- If `paginate=False`: returns `PlainTextResponse`.
- If `paginate=True`: returns `DocumentDividedInMatrixResponse`.

Parameters:

- `file_content`: file bytes wrapped in `io.BytesIO`
- `paginate`: enable page-oriented output model
- `boilerplate`: use boilerplate endpoint variant
- `ocr`: enable OCR header for Tika

### `extract_file_metadata(content)`

Extracts metadata and returns `TikaMetadataResponse`.

## Response Models

Depending on the method, the client returns:

- `PlainTextResponse`
- `DocumentDividedInMatrixResponse`
- `TikaMetadataResponse`

Each response includes `client_info` plus method-specific payload.

## Error Handling

Library-specific exceptions include:

- `InputFormatNotAvailableForThisEndpoint`
- `LanguageIdentificationError`
- `TikaRestClientNetworkException`

Example:

```python
from tika_rest_client.exception import TikaRestClientNetworkException

try:
    print(client.check_version().response)
except TikaRestClientNetworkException:
    print("Unable to reach Tika server.")
```

## Contributing

Contributions are welcome.

When opening a pull request:

1. Keep style consistent with the project.
2. Add or update tests when behavior changes.
3. Document public API changes.

## License

This project is licensed under the Creative Commons CC-BY-SA

[![licensebuttons by-nc-sa](https://licensebuttons.net/l/by-nc-sa/3.0/88x31.png)](https://creativecommons.org/licenses/by-nc-sa/4.0)

