445 lines
11 KiB
ReStructuredText
445 lines
11 KiB
ReStructuredText
SDK Overview
|
|
============
|
|
|
|
The HCFS Python SDK provides a comprehensive, production-ready interface for interacting with the HCFS API. It offers both synchronous and asynchronous clients with built-in caching, retry mechanisms, and advanced features.
|
|
|
|
.. currentmodule:: hcfs.sdk
|
|
|
|
Features
|
|
--------
|
|
|
|
🚀 **Dual Client Support**
|
|
- Synchronous client for traditional applications
|
|
- Asynchronous client with full async/await support
|
|
- WebSocket streaming capabilities
|
|
|
|
⚡ **Performance Optimized**
|
|
- Built-in caching with configurable strategies
|
|
- Connection pooling and keep-alive
|
|
- Batch operations for high throughput
|
|
- Smart retry mechanisms with backoff
|
|
|
|
🛡️ **Production Ready**
|
|
- Comprehensive error handling
|
|
- Rate limiting and timeout management
|
|
- Request/response validation
|
|
- Analytics and monitoring
|
|
|
|
🔧 **Developer Friendly**
|
|
- Type hints throughout
|
|
- Rich configuration options
|
|
- Extensive examples and documentation
|
|
- Decorator-based utilities
|
|
|
|
Installation
|
|
------------
|
|
|
|
Install from PyPI:
|
|
|
|
.. code-block:: bash
|
|
|
|
pip install hcfs-sdk
|
|
|
|
Or install with all optional dependencies:
|
|
|
|
.. code-block:: bash
|
|
|
|
pip install hcfs-sdk[all]
|
|
|
|
Quick Start
|
|
-----------
|
|
|
|
Synchronous Client
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from hcfs.sdk import HCFSClient, Context
|
|
|
|
# Initialize client
|
|
client = HCFSClient(
|
|
base_url="https://api.hcfs.dev/v1",
|
|
api_key="your-api-key"
|
|
)
|
|
|
|
# Create a context
|
|
context = Context(
|
|
path="/docs/quickstart",
|
|
content="This is a quick start guide",
|
|
summary="Getting started with HCFS"
|
|
)
|
|
|
|
created_context = client.create_context(context)
|
|
print(f"Created context: {created_context.id}")
|
|
|
|
# Search contexts
|
|
results = client.search_contexts("quick start guide")
|
|
for result in results:
|
|
print(f"Found: {result.context.path} (score: {result.score:.3f})")
|
|
|
|
# Clean up
|
|
client.close()
|
|
|
|
Asynchronous Client
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
import asyncio
|
|
from hcfs.sdk import HCFSAsyncClient, Context
|
|
|
|
async def main():
|
|
async with HCFSAsyncClient(
|
|
base_url="https://api.hcfs.dev/v1",
|
|
api_key="your-api-key"
|
|
) as client:
|
|
# Create multiple contexts concurrently
|
|
contexts = [
|
|
Context(path=f"/docs/guide-{i}", content=f"Guide {i}")
|
|
for i in range(5)
|
|
]
|
|
|
|
# Batch create
|
|
result = await client.batch_create_contexts(contexts)
|
|
print(f"Created {result.success_count} contexts")
|
|
|
|
# Async iteration
|
|
async for context in client.iterate_contexts():
|
|
print(f"Context: {context.path}")
|
|
if context.id > 100: # Stop after some point
|
|
break
|
|
|
|
asyncio.run(main())
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
The SDK is highly configurable through the :class:`ClientConfig` class:
|
|
|
|
.. code-block:: python
|
|
|
|
from hcfs.sdk import HCFSClient, ClientConfig, CacheConfig, RetryConfig
|
|
|
|
config = ClientConfig(
|
|
base_url="https://api.hcfs.dev/v1",
|
|
api_key="your-api-key",
|
|
timeout=30.0,
|
|
|
|
# Cache configuration
|
|
cache=CacheConfig(
|
|
enabled=True,
|
|
max_size=2000,
|
|
ttl_seconds=3600,
|
|
strategy="lru"
|
|
),
|
|
|
|
# Retry configuration
|
|
retry=RetryConfig(
|
|
enabled=True,
|
|
max_attempts=3,
|
|
base_delay=1.0,
|
|
strategy="exponential_backoff"
|
|
),
|
|
|
|
# Connection settings
|
|
max_connections=100,
|
|
max_keepalive_connections=20
|
|
)
|
|
|
|
client = HCFSClient(config=config)
|
|
|
|
Core Classes
|
|
------------
|
|
|
|
.. autosummary::
|
|
:toctree: generated/
|
|
|
|
HCFSClient
|
|
HCFSAsyncClient
|
|
Context
|
|
SearchResult
|
|
ContextFilter
|
|
PaginationOptions
|
|
SearchOptions
|
|
ClientConfig
|
|
|
|
Client Classes
|
|
~~~~~~~~~~~~~~
|
|
|
|
:class:`HCFSClient`
|
|
Synchronous client for HCFS API operations. Best for traditional applications
|
|
and when you don't need async/await support.
|
|
|
|
:class:`HCFSAsyncClient`
|
|
Asynchronous client with full async/await support. Includes WebSocket
|
|
streaming capabilities and is ideal for high-performance applications.
|
|
|
|
Data Models
|
|
~~~~~~~~~~~
|
|
|
|
:class:`Context`
|
|
Represents a context object with path, content, metadata, and other properties.
|
|
Includes validation and conversion methods.
|
|
|
|
:class:`SearchResult`
|
|
Contains a context and its relevance score from search operations.
|
|
Supports sorting and comparison operations.
|
|
|
|
:class:`ContextFilter`
|
|
Defines filtering criteria for listing contexts. Supports path prefixes,
|
|
authors, status, date ranges, and custom filters.
|
|
|
|
Configuration Models
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
:class:`ClientConfig`
|
|
Main configuration class that combines all subsystem configurations.
|
|
Supports environment variables and YAML configuration files.
|
|
|
|
:class:`CacheConfig`
|
|
Cache configuration with support for multiple eviction strategies.
|
|
|
|
:class:`RetryConfig`
|
|
Retry configuration with multiple backoff strategies and error handling.
|
|
|
|
Advanced Features
|
|
-----------------
|
|
|
|
Caching
|
|
~~~~~~~
|
|
|
|
The SDK includes intelligent caching with configurable strategies:
|
|
|
|
.. code-block:: python
|
|
|
|
from hcfs.sdk import HCFSClient, CacheConfig
|
|
from hcfs.sdk.decorators import cached_context
|
|
|
|
# Configure caching
|
|
cache_config = CacheConfig(
|
|
enabled=True,
|
|
strategy="lru", # LRU, LFU, TTL, FIFO
|
|
max_size=1000,
|
|
ttl_seconds=3600
|
|
)
|
|
|
|
client = HCFSClient(
|
|
base_url="https://api.hcfs.dev/v1",
|
|
api_key="your-api-key",
|
|
cache=cache_config
|
|
)
|
|
|
|
# Cache statistics
|
|
stats = client.get_cache_stats()
|
|
print(f"Cache hit rate: {stats.get('hit_rate', 0):.2%}")
|
|
|
|
Retry Logic
|
|
~~~~~~~~~~~
|
|
|
|
Automatic retry with configurable strategies:
|
|
|
|
.. code-block:: python
|
|
|
|
from hcfs.sdk import RetryConfig, RetryStrategy
|
|
|
|
retry_config = RetryConfig(
|
|
enabled=True,
|
|
max_attempts=5,
|
|
strategy=RetryStrategy.EXPONENTIAL_BACKOFF,
|
|
base_delay=1.0,
|
|
max_delay=60.0,
|
|
jitter=True,
|
|
retry_on_status=[429, 500, 502, 503, 504]
|
|
)
|
|
|
|
client = HCFSClient(
|
|
base_url="https://api.hcfs.dev/v1",
|
|
api_key="your-api-key",
|
|
retry=retry_config
|
|
)
|
|
|
|
Batch Operations
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Efficient batch processing with error handling:
|
|
|
|
.. code-block:: python
|
|
|
|
contexts = [
|
|
Context(path=f"/batch/item-{i}", content=f"Content {i}")
|
|
for i in range(100)
|
|
]
|
|
|
|
# Batch create with automatic error handling
|
|
result = client.batch_create_contexts(contexts)
|
|
|
|
print(f"Success: {result.success_count}")
|
|
print(f"Errors: {result.error_count}")
|
|
print(f"Success rate: {result.success_rate:.2%}")
|
|
|
|
# Handle failures
|
|
for error in result.failed_items:
|
|
print(f"Failed item {error['index']}: {error['error']}")
|
|
|
|
WebSocket Streaming
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
Real-time updates with the async client:
|
|
|
|
.. code-block:: python
|
|
|
|
import asyncio
|
|
from hcfs.sdk import HCFSAsyncClient
|
|
|
|
async def handle_event(event):
|
|
print(f"Received {event.event_type}: {event.data}")
|
|
|
|
async def main():
|
|
async with HCFSAsyncClient(
|
|
base_url="https://api.hcfs.dev/v1",
|
|
api_key="your-api-key"
|
|
) as client:
|
|
# Connect to WebSocket
|
|
await client.connect_websocket(
|
|
path_prefix="/docs",
|
|
event_types=["created", "updated", "deleted"]
|
|
)
|
|
|
|
# Add event listener
|
|
client.add_event_listener(handle_event)
|
|
|
|
# Keep connection alive
|
|
await asyncio.sleep(60)
|
|
|
|
asyncio.run(main())
|
|
|
|
Analytics and Monitoring
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Built-in analytics for monitoring SDK usage:
|
|
|
|
.. code-block:: python
|
|
|
|
# Get usage analytics
|
|
analytics = client.get_analytics()
|
|
|
|
print("Operation counts:")
|
|
for operation, count in analytics.operation_count.items():
|
|
print(f" {operation}: {count}")
|
|
|
|
print(f"Cache hit rate: {analytics.get_cache_hit_rate():.2%}")
|
|
print(f"Error rate: {analytics.get_error_rate():.2%}")
|
|
|
|
Decorators
|
|
~~~~~~~~~~
|
|
|
|
Utility decorators for common patterns:
|
|
|
|
.. code-block:: python
|
|
|
|
from hcfs.sdk.decorators import cached_context, retry_on_failure, rate_limited
|
|
|
|
@cached_context()
|
|
@retry_on_failure()
|
|
@rate_limited(requests_per_second=5.0)
|
|
def expensive_operation(client, query):
|
|
return client.search_contexts(query)
|
|
|
|
Error Handling
|
|
--------------
|
|
|
|
The SDK provides comprehensive error handling with specific exception types:
|
|
|
|
.. code-block:: python
|
|
|
|
from hcfs.sdk.exceptions import (
|
|
HCFSError, HCFSConnectionError, HCFSAuthenticationError,
|
|
HCFSNotFoundError, HCFSValidationError, HCFSRateLimitError
|
|
)
|
|
|
|
try:
|
|
context = client.get_context(999999)
|
|
except HCFSNotFoundError:
|
|
print("Context not found")
|
|
except HCFSAuthenticationError:
|
|
print("Authentication failed")
|
|
except HCFSRateLimitError as e:
|
|
print(f"Rate limited. Retry after {e.retry_after} seconds")
|
|
except HCFSConnectionError:
|
|
print("Connection failed")
|
|
except HCFSError as e:
|
|
print(f"HCFS error: {e.message}")
|
|
|
|
Best Practices
|
|
--------------
|
|
|
|
1. **Use Context Managers**
|
|
Always use context managers (``with`` or ``async with``) to ensure proper cleanup:
|
|
|
|
.. code-block:: python
|
|
|
|
with HCFSClient(...) as client:
|
|
# Use client
|
|
pass
|
|
|
|
async with HCFSAsyncClient(...) as client:
|
|
# Use async client
|
|
pass
|
|
|
|
2. **Configure Timeouts**
|
|
Set appropriate timeouts for your use case:
|
|
|
|
.. code-block:: python
|
|
|
|
client = HCFSClient(
|
|
base_url="...",
|
|
api_key="...",
|
|
timeout=30.0 # 30 second timeout
|
|
)
|
|
|
|
3. **Enable Caching**
|
|
Use caching for read-heavy workloads:
|
|
|
|
.. code-block:: python
|
|
|
|
cache_config = CacheConfig(
|
|
enabled=True,
|
|
max_size=2000,
|
|
ttl_seconds=3600
|
|
)
|
|
|
|
4. **Handle Errors Gracefully**
|
|
Always handle potential errors:
|
|
|
|
.. code-block:: python
|
|
|
|
try:
|
|
result = client.search_contexts(query)
|
|
except HCFSError as e:
|
|
logger.error(f"Search failed: {e}")
|
|
result = []
|
|
|
|
5. **Use Batch Operations**
|
|
For multiple operations, use batch methods:
|
|
|
|
.. code-block:: python
|
|
|
|
# Better than multiple individual creates
|
|
result = client.batch_create_contexts(contexts)
|
|
|
|
6. **Monitor Performance**
|
|
Regularly check analytics:
|
|
|
|
.. code-block:: python
|
|
|
|
analytics = client.get_analytics()
|
|
if analytics.get_error_rate() > 0.05: # 5% error rate
|
|
logger.warning("High error rate detected")
|
|
|
|
Next Steps
|
|
----------
|
|
|
|
- Read the :doc:`clients` documentation for detailed client usage
|
|
- Explore :doc:`models` for data structure details
|
|
- Check out :doc:`examples` for real-world usage patterns
|
|
- See :doc:`utilities` for helper functions and decorators |