ready for try
This commit is contained in:
305
examples/README.md
Normal file
305
examples/README.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# Examples
|
||||
|
||||
This directory contains practical examples demonstrating how to use the Wiki.js Python SDK for various tasks.
|
||||
|
||||
## 📁 Example Files
|
||||
|
||||
### [`basic_usage.py`](basic_usage.py)
|
||||
**Getting Started Examples**
|
||||
|
||||
Demonstrates fundamental operations:
|
||||
- Connecting to Wiki.js
|
||||
- Listing and searching pages
|
||||
- Creating, updating, and deleting pages
|
||||
- Working with page metadata and tags
|
||||
- Basic error handling
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
export WIKIJS_URL='https://your-wiki.example.com'
|
||||
export WIKIJS_API_KEY='your-api-key'
|
||||
python examples/basic_usage.py
|
||||
```
|
||||
|
||||
### [`content_management.py`](content_management.py)
|
||||
**Advanced Content Management**
|
||||
|
||||
Shows advanced content operations:
|
||||
- Template-based page creation
|
||||
- Bulk operations and batch processing
|
||||
- Content migration and format conversion
|
||||
- Content auditing and analysis
|
||||
- Automated content updates
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
export WIKIJS_URL='https://your-wiki.example.com'
|
||||
export WIKIJS_API_KEY='your-api-key'
|
||||
python examples/content_management.py
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
1. **Set up your environment:**
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/yourusername/wikijs-python-sdk
|
||||
cd wikijs-python-sdk
|
||||
|
||||
# Install the SDK
|
||||
pip install -e .
|
||||
|
||||
# Set environment variables
|
||||
export WIKIJS_URL='https://your-wiki.example.com'
|
||||
export WIKIJS_API_KEY='your-api-key'
|
||||
```
|
||||
|
||||
2. **Get your API key:**
|
||||
- Log into your Wiki.js admin panel
|
||||
- Go to Administration → API Keys
|
||||
- Create a new API key with appropriate permissions
|
||||
- Copy the generated key
|
||||
|
||||
3. **Run an example:**
|
||||
```bash
|
||||
python examples/basic_usage.py
|
||||
```
|
||||
|
||||
## 📋 Example Scenarios
|
||||
|
||||
### Content Creation Workflows
|
||||
|
||||
```python
|
||||
from wikijs import WikiJSClient
|
||||
from wikijs.models import PageCreate
|
||||
|
||||
# Template-based page creation
|
||||
def create_meeting_notes(client, meeting_data):
|
||||
content = f"""# {meeting_data['title']}
|
||||
|
||||
**Date:** {meeting_data['date']}
|
||||
**Attendees:** {', '.join(meeting_data['attendees'])}
|
||||
|
||||
## Agenda
|
||||
{meeting_data['agenda']}
|
||||
|
||||
## Action Items
|
||||
{meeting_data['actions']}
|
||||
"""
|
||||
|
||||
page_data = PageCreate(
|
||||
title=meeting_data['title'],
|
||||
path=f"meetings/{meeting_data['date']}-{meeting_data['slug']}",
|
||||
content=content,
|
||||
tags=['meeting'] + meeting_data.get('tags', [])
|
||||
)
|
||||
|
||||
return client.pages.create(page_data)
|
||||
```
|
||||
|
||||
### Content Analysis
|
||||
|
||||
```python
|
||||
def analyze_wiki_health(client):
|
||||
"""Analyze wiki content health metrics."""
|
||||
|
||||
pages = client.pages.list()
|
||||
|
||||
# Calculate metrics
|
||||
total_pages = len(pages)
|
||||
published_pages = len([p for p in pages if p.is_published])
|
||||
tagged_pages = len([p for p in pages if p.tags])
|
||||
|
||||
# Word count analysis
|
||||
word_counts = [p.word_count for p in pages]
|
||||
avg_words = sum(word_counts) / len(word_counts) if word_counts else 0
|
||||
|
||||
return {
|
||||
'total_pages': total_pages,
|
||||
'published_ratio': published_pages / total_pages,
|
||||
'tagged_ratio': tagged_pages / total_pages,
|
||||
'avg_word_count': avg_words
|
||||
}
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
|
||||
```python
|
||||
def bulk_update_tags(client, search_term, new_tags):
|
||||
"""Add tags to pages matching a search term."""
|
||||
|
||||
pages = client.pages.search(search_term)
|
||||
updated_count = 0
|
||||
|
||||
for page in pages:
|
||||
try:
|
||||
# Merge existing and new tags
|
||||
updated_tags = list(set(page.tags + new_tags))
|
||||
|
||||
update_data = PageUpdate(tags=updated_tags)
|
||||
client.pages.update(page.id, update_data)
|
||||
updated_count += 1
|
||||
|
||||
except Exception as e:
|
||||
print(f"Failed to update {page.title}: {e}")
|
||||
|
||||
return updated_count
|
||||
```
|
||||
|
||||
## 🛠️ Development Examples
|
||||
|
||||
### Custom Authentication
|
||||
|
||||
```python
|
||||
from wikijs.auth import AuthHandler
|
||||
|
||||
class CustomAuth(AuthHandler):
|
||||
"""Custom authentication handler example."""
|
||||
|
||||
def __init__(self, custom_token):
|
||||
self.token = custom_token
|
||||
|
||||
def get_headers(self):
|
||||
return {
|
||||
'Authorization': f'Custom {self.token}',
|
||||
'X-Custom-Header': 'MyApp/1.0'
|
||||
}
|
||||
|
||||
def validate_credentials(self):
|
||||
if not self.token:
|
||||
raise ValueError("Custom token is required")
|
||||
|
||||
# Usage
|
||||
client = WikiJSClient(
|
||||
base_url="https://wiki.example.com",
|
||||
auth=CustomAuth("your-custom-token")
|
||||
)
|
||||
```
|
||||
|
||||
### Error Handling Patterns
|
||||
|
||||
```python
|
||||
from wikijs.exceptions import (
|
||||
APIError, AuthenticationError, ValidationError,
|
||||
ConnectionError, TimeoutError
|
||||
)
|
||||
|
||||
def robust_page_operation(client, operation_func):
|
||||
"""Wrapper for robust page operations with retry logic."""
|
||||
|
||||
max_retries = 3
|
||||
retry_delay = 1
|
||||
|
||||
for attempt in range(max_retries):
|
||||
try:
|
||||
return operation_func()
|
||||
|
||||
except (ConnectionError, TimeoutError) as e:
|
||||
if attempt == max_retries - 1:
|
||||
raise
|
||||
print(f"Attempt {attempt + 1} failed: {e}. Retrying...")
|
||||
time.sleep(retry_delay * (2 ** attempt))
|
||||
|
||||
except AuthenticationError:
|
||||
print("Authentication failed. Check your API key.")
|
||||
raise
|
||||
|
||||
except ValidationError as e:
|
||||
print(f"Invalid input: {e}")
|
||||
raise
|
||||
|
||||
except APIError as e:
|
||||
print(f"API error: {e}")
|
||||
raise
|
||||
|
||||
# Usage
|
||||
result = robust_page_operation(
|
||||
client,
|
||||
lambda: client.pages.get(123)
|
||||
)
|
||||
```
|
||||
|
||||
## 🔧 Configuration Examples
|
||||
|
||||
### Environment-based Configuration
|
||||
|
||||
```python
|
||||
import os
|
||||
from wikijs import WikiJSClient
|
||||
|
||||
def create_client_from_env():
|
||||
"""Create client from environment variables."""
|
||||
|
||||
config = {
|
||||
'base_url': os.getenv('WIKIJS_URL'),
|
||||
'auth': os.getenv('WIKIJS_API_KEY'),
|
||||
'timeout': int(os.getenv('WIKIJS_TIMEOUT', '30')),
|
||||
'verify_ssl': os.getenv('WIKIJS_VERIFY_SSL', 'true').lower() == 'true'
|
||||
}
|
||||
|
||||
# Validate required settings
|
||||
if not config['base_url'] or not config['auth']:
|
||||
raise ValueError("WIKIJS_URL and WIKIJS_API_KEY are required")
|
||||
|
||||
return WikiJSClient(**config)
|
||||
```
|
||||
|
||||
### Configuration File
|
||||
|
||||
```python
|
||||
import json
|
||||
from wikijs import WikiJSClient
|
||||
|
||||
def create_client_from_file(config_file='config.json'):
|
||||
"""Create client from configuration file."""
|
||||
|
||||
with open(config_file, 'r') as f:
|
||||
config = json.load(f)
|
||||
|
||||
return WikiJSClient(
|
||||
base_url=config['wikijs']['url'],
|
||||
auth=config['wikijs']['api_key'],
|
||||
timeout=config.get('timeout', 30),
|
||||
verify_ssl=config.get('verify_ssl', True)
|
||||
)
|
||||
|
||||
# config.json example:
|
||||
# {
|
||||
# "wikijs": {
|
||||
# "url": "https://wiki.example.com",
|
||||
# "api_key": "your-api-key"
|
||||
# },
|
||||
# "timeout": 45,
|
||||
# "verify_ssl": true
|
||||
# }
|
||||
```
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
- **[API Reference](../docs/api_reference.md)** - Complete API documentation
|
||||
- **[User Guide](../docs/user_guide.md)** - Comprehensive usage guide
|
||||
- **[Contributing](../docs/CONTRIBUTING.md)** - How to contribute to the project
|
||||
- **[Wiki.js Documentation](https://docs.js.wiki/)** - Official Wiki.js documentation
|
||||
|
||||
## 💡 Tips for Success
|
||||
|
||||
1. **Always use context managers** for automatic resource cleanup
|
||||
2. **Handle exceptions appropriately** for robust applications
|
||||
3. **Use environment variables** for configuration
|
||||
4. **Test your code** with different scenarios
|
||||
5. **Be respectful** of the Wiki.js server (don't overwhelm with requests)
|
||||
6. **Keep your API key secure** and never commit it to version control
|
||||
|
||||
## 🆘 Getting Help
|
||||
|
||||
If you encounter issues with these examples:
|
||||
|
||||
1. **Check your configuration** - Ensure URL and API key are correct
|
||||
2. **Verify connectivity** - Test that you can reach the Wiki.js instance
|
||||
3. **Check permissions** - Ensure your API key has necessary permissions
|
||||
4. **Enable debug logging** - Use logging to see what's happening
|
||||
5. **Create an issue** - Report bugs or request help on GitHub
|
||||
|
||||
---
|
||||
|
||||
**Happy coding! 🚀**
|
||||
Reference in New Issue
Block a user