Metadata-Version: 2.4
Name: api-ulp
Version: 0.1.0
Summary: A simple Python client for the ULP search API.
License: MIT
Project-URL: Homepage, https://github.com/your-username/api-ulp
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.20.0

# api-ulp

A simple Python client for the ULP search API.

## Installation

```bash
pip install api-ulp
```

## Requirements

- Python 3.7+
- `requests` >= 2.20.0

## Quick Start

```python
from api_ulp import ApiUlp

client = ApiUlp(api_key="YOUR_API_KEY")
results = client.search(query="hello world", limit=10)
print(results)
```

## Usage

### Initialize the client

```python
from api_ulp import ApiUlp

client = ApiUlp(api_key="YOUR_API_KEY")
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_key` | str | Yes | Your ULP API key |

---

### `search(query, limit)`

Performs a POST search request against the ULP API.

```python
results = client.search(query="search_target", limit=100)
print(results)
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query`   | str  | Yes      | —       | The search term / target |
| `limit`   | int  | No       | `100`   | Maximum number of results to return |

**Returns:** `dict` — Parsed JSON response from the API.

---

## Error Handling

```python
import requests
from api_ulp import ApiUlp

client = ApiUlp(api_key="YOUR_API_KEY")

try:
    results = client.search(query="hello", limit=50)
    print(results)
except ValueError as e:
    # Bad arguments (empty query, invalid limit, missing key)
    print(f"Invalid input: {e}")
except requests.exceptions.HTTPError as e:
    # API returned 4xx or 5xx
    print(f"API error: {e}")
except requests.exceptions.ConnectionError as e:
    # Could not reach the server
    print(f"Connection error: {e}")
except requests.exceptions.Timeout as e:
    # Request took longer than 30 seconds
    print(f"Timeout: {e}")
```

---

## API Details

| Property | Value |
|----------|-------|
| Endpoint | `POST https://api-1-wi9u.onrender.com/api/search` |
| Auth Header | `X-API-Key: YOUR_KEY` |
| Content-Type | `application/json` |
| Timeout | 30 seconds |

### Raw request equivalent

```python
import requests

url = "https://api-1-wi9u.onrender.com/api/search"
headers = {"X-API-Key": "YOUR_KEY", "Content-Type": "application/json"}
data = {"query": "search_target", "limit": 100}

response = requests.post(url, headers=headers, json=data)
print(response.json())
```

---

## License

MIT
