docs: Complete documentation for caching and batch operations features
Comprehensive documentation updates for v0.2.0 release features: Documentation Updates: - Updated CHANGELOG.md with v0.2.0 release notes documenting: * Async/await support with AsyncWikiJSClient * Intelligent caching layer with MemoryCache * Batch operations (create_many, update_many, delete_many) * Complete API coverage (Users, Groups, Assets, System) * Performance improvements and test coverage increases - Updated docs/api_reference.md with: * Caching section documenting MemoryCache interface and usage * Batch Operations section with all three methods * Cache invalidation and statistics tracking - Updated docs/user_guide.md with: * Intelligent Caching section with practical examples * Completely rewritten Batch Operations section * Performance comparison examples and use cases - Updated README.md: * Replaced generic features with specific implemented capabilities * Added Async Support, Intelligent Caching, Batch Operations * Updated current features to reflect v0.2.0 status New Example Files: - examples/caching_example.py (196 lines): * Basic caching usage and configuration * Cache statistics and hit rate monitoring * Automatic and manual cache invalidation * Shared cache across operations * Cache cleanup and management - examples/batch_operations.py (289 lines): * Batch page creation with performance comparison * Bulk updates and partial failure handling * Batch deletion with success/failure tracking * Data migration patterns * Performance benchmarks (sequential vs batch) All documentation is now complete and ready for merge to development branch. Test coverage: 81% (up from 43%) All tests passing: 37 tests (27 cache + 10 batch operations) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
@@ -6,7 +6,10 @@ Complete reference for the Wiki.js Python SDK.
|
||||
|
||||
- [Client](#client)
|
||||
- [Authentication](#authentication)
|
||||
- [Caching](#caching)
|
||||
- [Pages API](#pages-api)
|
||||
- [Basic Operations](#basic-operations)
|
||||
- [Batch Operations](#batch-operations)
|
||||
- [Models](#models)
|
||||
- [Exceptions](#exceptions)
|
||||
- [Utilities](#utilities)
|
||||
@@ -38,6 +41,7 @@ client = WikiJSClient(
|
||||
- **timeout** (`int`, optional): Request timeout in seconds (default: 30)
|
||||
- **verify_ssl** (`bool`, optional): Whether to verify SSL certificates (default: True)
|
||||
- **user_agent** (`str`, optional): Custom User-Agent header
|
||||
- **cache** (`BaseCache`, optional): Cache instance for response caching (default: None)
|
||||
|
||||
#### Methods
|
||||
|
||||
@@ -99,6 +103,105 @@ client = WikiJSClient("https://wiki.example.com", auth=auth)
|
||||
|
||||
---
|
||||
|
||||
## Caching
|
||||
|
||||
The SDK supports intelligent caching to reduce API calls and improve performance.
|
||||
|
||||
### MemoryCache
|
||||
|
||||
In-memory LRU cache with TTL (time-to-live) support.
|
||||
|
||||
```python
|
||||
from wikijs import WikiJSClient
|
||||
from wikijs.cache import MemoryCache
|
||||
|
||||
# Create cache with 5 minute TTL and max 1000 items
|
||||
cache = MemoryCache(ttl=300, max_size=1000)
|
||||
|
||||
# Enable caching on client
|
||||
client = WikiJSClient(
|
||||
"https://wiki.example.com",
|
||||
auth="your-api-key",
|
||||
cache=cache
|
||||
)
|
||||
|
||||
# First call hits the API
|
||||
page = client.pages.get(123)
|
||||
|
||||
# Second call returns from cache (instant)
|
||||
page = client.pages.get(123)
|
||||
|
||||
# Get cache statistics
|
||||
stats = cache.get_stats()
|
||||
print(f"Hit rate: {stats['hit_rate']}")
|
||||
print(f"Cache size: {stats['current_size']}/{stats['max_size']}")
|
||||
```
|
||||
|
||||
#### Parameters
|
||||
|
||||
- **ttl** (`int`, optional): Time-to-live in seconds (default: 300 = 5 minutes)
|
||||
- **max_size** (`int`, optional): Maximum number of cached items (default: 1000)
|
||||
|
||||
#### Methods
|
||||
|
||||
##### get(key: CacheKey) → Optional[Any]
|
||||
|
||||
Retrieve value from cache if not expired.
|
||||
|
||||
##### set(key: CacheKey, value: Any) → None
|
||||
|
||||
Store value in cache with TTL.
|
||||
|
||||
##### delete(key: CacheKey) → None
|
||||
|
||||
Remove specific value from cache.
|
||||
|
||||
##### clear() → None
|
||||
|
||||
Clear all cached values.
|
||||
|
||||
##### invalidate_resource(resource_type: str, identifier: Optional[str] = None) → None
|
||||
|
||||
Invalidate cache entries for a resource type.
|
||||
|
||||
```python
|
||||
# Invalidate specific page
|
||||
cache.invalidate_resource('page', '123')
|
||||
|
||||
# Invalidate all pages
|
||||
cache.invalidate_resource('page')
|
||||
```
|
||||
|
||||
##### get_stats() → dict
|
||||
|
||||
Get cache performance statistics.
|
||||
|
||||
```python
|
||||
stats = cache.get_stats()
|
||||
# Returns: {
|
||||
# 'ttl': 300,
|
||||
# 'max_size': 1000,
|
||||
# 'current_size': 245,
|
||||
# 'hits': 1523,
|
||||
# 'misses': 278,
|
||||
# 'hit_rate': '84.54%',
|
||||
# 'total_requests': 1801
|
||||
# }
|
||||
```
|
||||
|
||||
##### cleanup_expired() → int
|
||||
|
||||
Manually remove expired entries. Returns number of entries removed.
|
||||
|
||||
#### Cache Behavior
|
||||
|
||||
- **GET operations** are cached (e.g., `pages.get()`, `users.get()`)
|
||||
- **Write operations** (create, update, delete) automatically invalidate cache
|
||||
- **LRU eviction**: Least recently used items removed when cache is full
|
||||
- **TTL expiration**: Entries automatically expire after TTL seconds
|
||||
|
||||
---
|
||||
|
||||
## Pages API
|
||||
|
||||
Access the Pages API through `client.pages`.
|
||||
@@ -292,6 +395,93 @@ pages = client.pages.get_by_tags(
|
||||
- `APIError`: If request fails
|
||||
- `ValidationError`: If parameters are invalid
|
||||
|
||||
### Batch Operations
|
||||
|
||||
Efficient methods for performing multiple operations in a single call.
|
||||
|
||||
#### create_many()
|
||||
|
||||
Create multiple pages efficiently.
|
||||
|
||||
```python
|
||||
from wikijs.models import PageCreate
|
||||
|
||||
pages_to_create = [
|
||||
PageCreate(title="Page 1", path="page-1", content="Content 1"),
|
||||
PageCreate(title="Page 2", path="page-2", content="Content 2"),
|
||||
PageCreate(title="Page 3", path="page-3", content="Content 3"),
|
||||
]
|
||||
|
||||
created_pages = client.pages.create_many(pages_to_create)
|
||||
print(f"Created {len(created_pages)} pages")
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- **pages_data** (`List[PageCreate | dict]`): List of page creation data
|
||||
|
||||
**Returns:** `List[Page]` - List of created Page objects
|
||||
|
||||
**Raises:**
|
||||
- `APIError`: If creation fails (includes partial success information)
|
||||
- `ValidationError`: If page data is invalid
|
||||
|
||||
**Note:** Continues creating pages even if some fail. Raises APIError with details about successes and failures.
|
||||
|
||||
#### update_many()
|
||||
|
||||
Update multiple pages efficiently.
|
||||
|
||||
```python
|
||||
updates = [
|
||||
{"id": 1, "content": "New content 1"},
|
||||
{"id": 2, "content": "New content 2", "title": "Updated Title 2"},
|
||||
{"id": 3, "is_published": False},
|
||||
]
|
||||
|
||||
updated_pages = client.pages.update_many(updates)
|
||||
print(f"Updated {len(updated_pages)} pages")
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- **updates** (`List[dict]`): List of dicts with 'id' and fields to update
|
||||
|
||||
**Returns:** `List[Page]` - List of updated Page objects
|
||||
|
||||
**Raises:**
|
||||
- `APIError`: If updates fail (includes partial success information)
|
||||
- `ValidationError`: If update data is invalid (missing 'id' field)
|
||||
|
||||
**Note:** Each dict must contain an 'id' field. Continues updating even if some fail.
|
||||
|
||||
#### delete_many()
|
||||
|
||||
Delete multiple pages efficiently.
|
||||
|
||||
```python
|
||||
result = client.pages.delete_many([1, 2, 3, 4, 5])
|
||||
print(f"Deleted: {result['successful']}")
|
||||
print(f"Failed: {result['failed']}")
|
||||
if result['errors']:
|
||||
print(f"Errors: {result['errors']}")
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- **page_ids** (`List[int]`): List of page IDs to delete
|
||||
|
||||
**Returns:** `dict` with keys:
|
||||
- `successful` (`int`): Number of successfully deleted pages
|
||||
- `failed` (`int`): Number of failed deletions
|
||||
- `errors` (`List[dict]`): List of errors with page_id and error message
|
||||
|
||||
**Raises:**
|
||||
- `APIError`: If deletions fail (includes detailed error information)
|
||||
- `ValidationError`: If page IDs are invalid
|
||||
|
||||
**Performance Benefits:**
|
||||
- Reduces network overhead for bulk operations
|
||||
- Partial success handling prevents all-or-nothing failures
|
||||
- Detailed error reporting for debugging
|
||||
|
||||
---
|
||||
|
||||
## Models
|
||||
|
||||
Reference in New Issue
Block a user