bimiyun-python 0.1.0

Bimiyun Search API Python SDK

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
• Quick Start
• Usage Examples
• API Reference
• Configuration
• Error Handling
• Testing
• Contributing
• License

Installation

You can install the Bimiyun Python SDK using pip:

pip install bimiyun-python

Quick Start

# 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

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

Search with All Parameters

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:

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:

{
  "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

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:

export BIMIYUN_API_KEY="your-api-key"

Then in your code:

import os
from bimiyun import BimiyunClient

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

Error Handling

The SDK raises exceptions for API errors:

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:

python tests/test_search.py

Contributing

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

License

MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions, please:

1. Check the documentation
2. Open an issue on GitHub
3. Contact support at [e-mail]

Changelog

0.1.0

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