Metadata-Version: 2.4
Name: bimiyun-python
Version: 0.1.0
Summary: Bimiyun Search API Python SDK
License-File: LICENSE
Author: Bimiyun Team
Author-email: support@bimiyun.com
Requires-Python: >=3.8,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: 3.14
Requires-Dist: requests (>=2.28.0,<3.0.0)
Description-Content-Type: text/markdown

# Bimiyun Python SDK

A Python SDK for the Bimiyun Search API, providing a simple and intuitive interface for accessing Bimiyun's powerful search capabilities.

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage Examples](#usage-examples)
- [API Reference](#api-reference)
- [Configuration](#configuration)
- [Error Handling](#error-handling)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)

## Installation

You can install the Bimiyun Python SDK using pip:

```bash
pip install bimiyun-python
```

## Quick Start

```python
# To install: pip install bimiyun-python
from bimiyun import BimiyunClient
client = BimiyunClient("ak-********************")
response = client.search(
    query="artificial intelligence",
    safe=True,
    mode="fulltext",
    max_results=5
)
print(response)
```

## Usage Examples

### Basic Search

```python
from bimiyun import BimiyunClient
client = BimiyunClient("ak-********************")
response = client.search("python programming")
print(response)
```

### Search with All Parameters

```python
from bimiyun import BimiyunClient
client = BimiyunClient("ak-********************")
response = client.search(query="machine learning tutorials", lang="en", safe=True, mode="fulltext", max_results=5)
print(response)
```

### Custom Configuration

You can specify additional configuration options:

```python
from bimiyun import BimiyunClient

client = BimiyunClient(
    "ak-********************",
    base_url="https://custom.bimiyun.com",
    timeout=60
)

response = client.search("test query")
print(response)
```

### API Response Format

The `search()` method returns the raw API response in the following format:

```python
{
  "organic": [
    {
      "title": "Result Title",
      "date": "",
      "link": "https://example.com",
      "position": 1,
      "site_name": "Example.com",
      "snippet": "Description text...",
      "text": "Full text..."
    }
  ]
}
```

**Field descriptions:**
- `title`: Search result title
- `date`: Publication date (if available)
- `link`: URL of the search result
- `position`: Position in the results list
- `site_name`: Name of the website
- `snippet`: Brief description or excerpt from the page
- `text`: Full text of the page

## API Reference

### BimiyunClient

The main client class for interacting with the Bimiyun API.

#### Constructor

```python
BimiyunClient(api_key: str, base_url: str = "https://search.bimiyun.com", timeout: int = 30)
```

- `api_key`: Your Bimiyun API key (required)
- `base_url`: Base URL for the API (default: `https://search.bimiyun.com`)
- `timeout`: Request timeout in seconds (default: 30)

#### Methods

##### search(query: str = "", lang: str = "", safe: bool = True, mode: str = "fulltext", max_results: int = 5) -> Dict[str, Any]

Perform a search with the given query and return the raw API response.

**Parameters:**
- `query`: Search query string (optional)
- `lang`: Language code for search results (e.g., 'am' for Amharic, 'en' for English) (optional)
- `safe`: Safe search mode: True or False (optional, default: True)
- `mode`: Result detail mode: 'snippet' for brief descriptions or 'fulltext' for detailed content (optional, default: 'fulltext')
- `max_results`: Maximum number of results to return (1-10, optional, default: 5)

**Returns:**
- Raw API response dictionary containing the search results

## Configuration

### Environment Variables

You can configure the API key using environment variables:

```bash
export BIMIYUN_API_KEY="your-api-key"
```

Then in your code:

```python
import os
from bimiyun import BimiyunClient

client = BimiyunClient(os.environ.get("BIMIYUN_API_KEY"))
```

## Error Handling

The SDK raises exceptions for API errors:

```python
from bimiyun import BimiyunClient

try:
    client = BimiyunClient("ak-********************")
    response = client.search("test query")
    results = response.get("organic", [])
    # Process results...

except Exception as e:
    if "timed out" in str(e):
        print("Network timeout error")
    elif "API request failed" in str(e):
        print("API error")
    else:
        print(f"Error: {e}")
```

Common error conditions:
- Invalid API key
- Rate limiting
- Network timeouts
- Invalid parameters

## Testing

The SDK includes a simple test file. To run the test:

1. First, replace the placeholder API key in `tests/test_search.py` with your actual API key
2. Then run the test:

```bash
python tests/test_search.py
```

## Contributing

Contributions are welcome! Please see our contributing guide for more information.

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Support

If you encounter any issues or have questions, please:

1. Check the [documentation](https://bimiyun.com/documentation.html)
2. Open an issue on GitHub
3. Contact support at support@bimiyun.com

## Changelog

### 0.1.0
- Basic search functionality
- Advanced search with SearchRequest
- Result extraction methods
- API status check
- Error handling
- Comprehensive data models

