Phase 2 build initial
This commit is contained in:
Claude Code
445
hcfs-python/docs/sdk/overview.rst
Normal file
445
hcfs-python/docs/sdk/overview.rst
Normal file
@@ -0,0 +1,445 @@
|
||||
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
|
||||
Reference in New Issue
Block a user