personal-projects/py-wikijs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add installation guide and quick test script

Browse Source 
Added comprehensive documentation to help users install and test
py-wikijs in their projects before public release.

Changes:
- INSTALLATION_GUIDE.md: Complete guide for all installation methods
  * GitHub installation (recommended for now)
  * requirements.txt integration
  * pyproject.toml integration
  * Local development setup
  * Usage examples and troubleshooting

- examples/quick_test.py: Verification script
  * Tests package import
  * Tests Wiki.js connectivity (optional)
  * Validates feature availability
  * Provides clear diagnostic output

This prepares the package for testing in external projects before
making the repository public.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
2025-10-25 19:29:57 +00:00
parent c6b9d045e1
commit 54de1ea8e1
2 changed files with 438 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
INSTALLATION_GUIDE.md Normal file
View File

@@ -0,0 +1,287 @@
# Installation Guide - py-wikijs
**Quick reference for installing and using py-wikijs in your projects**
---
## 📦 Installation Methods
### **Method 1: Install from GitHub (Recommended for now)**
Since this package is not yet on PyPI, install directly from GitHub:
```bash
# Install the latest release (v0.1.0)
pip install git+https://github.com/l3ocho/py-wikijs.git@v0.1.0
# Or install from a specific branch
pip install git+https://github.com/l3ocho/py-wikijs.git@main
# Or install from the current development branch
pip install git+https://github.com/l3ocho/py-wikijs.git@claude/test-tool-integration-011CUUU3JXwm8n8waD6UYeea
```
### **Method 2: Install in requirements.txt**
Add to your `requirements.txt`:
```text
# Install specific version tag
git+https://github.com/l3ocho/py-wikijs.git@v0.1.0
# Or install from main branch
git+https://github.com/l3ocho/py-wikijs.git@main
```
Then install:
```bash
pip install -r requirements.txt
```
### **Method 3: Install in pyproject.toml (Poetry/Modern Python)**
Add to your `pyproject.toml`:
```toml
[project.dependencies]
py-wikijs = { git = "https://github.com/l3ocho/py-wikijs.git", tag = "v0.1.0" }
```
Or for Poetry:
```toml
[tool.poetry.dependencies]
py-wikijs = { git = "https://github.com/l3ocho/py-wikijs.git", tag = "v0.1.0" }
```
### **Method 4: Local Development (Editable Install)**
If you're developing both projects simultaneously:
```bash
# Clone the repository
git clone https://github.com/l3ocho/py-wikijs.git
cd py-wikijs
# Install in editable mode
pip install -e .
# Or install with development dependencies
pip install -e ".[dev]"
# Or install with async support
pip install -e ".[async]"
```
Then in your other project, the package will automatically reflect changes.
---
## ✅ Verification
After installation, verify it works:
```bash
# Check installation
python -c "from wikijs import WikiJSClient, __version__; print(f'py-wikijs v{__version__} installed successfully!')"
# Should output: py-wikijs v0.1.0 installed successfully!
```
---
## 🚀 Basic Usage in Your Project
### **Simple Example**
Create a file `test_wikijs.py`:
```python
from wikijs import WikiJSClient
# Initialize client with API key
client = WikiJSClient(
url='https://your-wiki.example.com',
auth='your-api-key-here'
)
# List all pages
pages = client.pages.list()
print(f"Found {len(pages)} pages")
# Get a specific page
page = client.pages.get(page_id=1)
print(f"Page title: {page.title}")
```
### **With Environment Variables (Recommended)**
Create `.env` file:
```env
WIKIJS_URL=https://your-wiki.example.com
WIKIJS_API_KEY=your-api-key-here
```
In your code:
```python
import os
from wikijs import WikiJSClient
# Load from environment
client = WikiJSClient(
url=os.getenv('WIKIJS_URL'),
auth=os.getenv('WIKIJS_API_KEY')
)
```
### **Advanced Features**
```python
from wikijs import WikiJSClient
import logging
# Enable debug logging
client = WikiJSClient(
url='https://wiki.example.com',
auth='your-api-key',
log_level=logging.DEBUG,
rate_limit=10.0, # 10 requests/second
timeout=30.0 # 30 second timeout
)
# Create a new page
from wikijs.models import PageCreate
new_page = client.pages.create(PageCreate(
title="My New Page",
path="documentation/my-new-page",
content="# Welcome\n\nThis is my new page!",
description="A new documentation page",
is_published=True,
is_private=False,
locale="en",
tags=["documentation", "tutorial"]
))
print(f"Created page: {new_page.title} (ID: {new_page.id})")
# Get metrics
metrics = client.get_metrics()
print(f"Total requests: {metrics['total_requests']}")
print(f"Error rate: {metrics['error_rate']:.2f}%")
```
### **Async Usage (Future - v0.2.0)**
When async support is released:
```python
from wikijs.aio import AsyncWikiJSClient
async def main():
async with AsyncWikiJSClient(
url='https://wiki.example.com',
auth='your-api-key'
) as client:
pages = await client.pages.list()
print(f"Found {len(pages)} pages")
# Run with asyncio
import asyncio
asyncio.run(main())
```
---
## 🔧 Dependencies
**Required:**
- Python >= 3.8
- requests >= 2.28.0
- pydantic >= 1.10.0
- typing-extensions >= 4.0.0
**Optional:**
- aiohttp >= 3.8.0 (for async support - coming in v0.2.0)
- click >= 8.0.0 (for CLI tools - future)
- rich >= 12.0.0 (for rich output - future)
---
## 📚 Documentation
- **API Reference**: [docs/api_reference.md](docs/api_reference.md)
- **User Guide**: [docs/user_guide.md](docs/user_guide.md)
- **Examples**: [examples/](examples/)
- **Compatibility**: [docs/compatibility.md](docs/compatibility.md)
---
## ⚠️ Important Notes
### **Before Going Public:**
1. ✅ **Version Tag Created**: v0.1.0 is now tagged
2. ✅ **Package Structure**: Ready for installation
3. ⏳ **PyPI Publishing**: Not yet published (GitHub-only for now)
4. ⏳ **GitHub Release**: Consider creating a GitHub Release page
### **Production Checklist:**
- [ ] Set up proper Wiki.js instance with API access
- [ ] Store API keys securely (use environment variables)
- [ ] Enable appropriate logging for production
- [ ] Set rate limits to respect your Wiki.js server
- [ ] Monitor metrics for performance issues
- [ ] Review security best practices in [docs/SECURITY.md](docs/SECURITY.md)
### **Wiki.js Requirements:**
- **Supported Versions**: Wiki.js 2.2 through 2.5.x
- **Not Supported**: Wiki.js 3.x (different API schema)
- **API Access**: Requires valid API key with appropriate permissions
---
## 🐛 Troubleshooting
### **Import Error**
```python
ModuleNotFoundError: No module named 'wikijs'
```
**Solution**: Ensure package is installed: `pip install git+https://github.com/l3ocho/py-wikijs.git@v0.1.0`
### **Authentication Error**
```python
wikijs.exceptions.AuthenticationError: Invalid API key
```
**Solution**: Check your API key is correct and has necessary permissions in Wiki.js
### **Connection Error**
```python
wikijs.exceptions.ConnectionError: Failed to connect to Wiki.js
```
**Solution**: Verify Wiki.js URL is correct and accessible from your network
---
## 🚀 Next Steps
1. **Install the package** using one of the methods above
2. **Get your Wiki.js API key** from your Wiki.js admin panel
3. **Test basic connectivity** with a simple script
4. **Explore examples** in the [examples/](examples/) directory
5. **Read the documentation** for advanced features
---
## 📞 Support
- **Issues**: https://github.com/l3ocho/py-wikijs/issues
- **Discussions**: https://github.com/l3ocho/py-wikijs/discussions
- **Documentation**: https://github.com/l3ocho/py-wikijs/tree/main/docs
---
**Last Updated**: 2025-10-25
**Package Version**: v0.1.0
**Status**: Production Ready (MVP)

151
examples/quick_test.py Executable file
View File

@@ -0,0 +1,151 @@
#!/usr/bin/env python3
"""Quick test script to verify py-wikijs installation and connectivity.
This script helps you verify that py-wikijs is installed correctly and can
connect to your Wiki.js instance.
Usage:
python quick_test.py
Or set environment variables:
export WIKIJS_URL="https://your-wiki.example.com"
export WIKIJS_API_KEY="your-api-key-here"
python quick_test.py
"""
import os
import sys
from typing import Optional
def test_import() -> bool:
"""Test that py-wikijs can be imported."""
print("=" * 60)
print("TEST 1: Package Import")
print("=" * 60)
try:
from wikijs import WikiJSClient, __version__
print(f"✅ Successfully imported py-wikijs v{__version__}")
return True
except ImportError as e:
print(f"❌ Failed to import py-wikijs: {e}")
print("\nInstall with: pip install git+https://github.com/l3ocho/py-wikijs.git@v0.1.0")
return False
def test_connectivity(url: Optional[str] = None, api_key: Optional[str] = None) -> bool:
"""Test connectivity to Wiki.js instance."""
print("\n" + "=" * 60)
print("TEST 2: Wiki.js Connectivity")
print("=" * 60)
# Get credentials
url = url or os.getenv("WIKIJS_URL")
api_key = api_key or os.getenv("WIKIJS_API_KEY")
if not url or not api_key:
print("⚠️ Skipping connectivity test - credentials not provided")
print("\nTo test connectivity, set environment variables:")
print(" export WIKIJS_URL='https://your-wiki.example.com'")
print(" export WIKIJS_API_KEY='your-api-key-here'")
return False
try:
from wikijs import WikiJSClient
print(f"🔗 Connecting to: {url}")
client = WikiJSClient(url=url, auth=api_key)
# Try to list pages
pages = client.pages.list()
print(f"✅ Successfully connected to Wiki.js")
print(f"✅ Found {len(pages)} page(s)")
# Show first page if available
if pages:
first_page = pages[0]
print(f"\nFirst page:")
print(f" - ID: {first_page.id}")
print(f" - Title: {first_page.title}")
print(f" - Path: {first_page.path}")
return True
except Exception as e:
print(f"❌ Failed to connect: {e}")
print("\nPlease verify:")
print(" 1. Wiki.js URL is correct and accessible")
print(" 2. API key is valid and has necessary permissions")
print(" 3. Wiki.js version is 2.2 or higher (not 3.x)")
return False
def test_features() -> bool:
"""Test that key features are available."""
print("\n" + "=" * 60)
print("TEST 3: Feature Availability")
print("=" * 60)
try:
from wikijs import (
APIKeyAuth,
AuthenticationError,
JWTAuth,
Page,
PageCreate,
WikiJSClient,
)
print("✅ Core client: WikiJSClient")
print("✅ Authentication: APIKeyAuth, JWTAuth")
print("✅ Models: Page, PageCreate")
print("✅ Exceptions: AuthenticationError")
print("✅ All core features available")
return True
except ImportError as e:
print(f"❌ Missing features: {e}")
return False
def main() -> int:
"""Run all tests."""
print("\n🧪 py-wikijs Installation & Connectivity Test")
print("=" * 60)
results = []
# Test 1: Import
results.append(test_import())
# Test 2: Connectivity (optional)
results.append(test_connectivity())
# Test 3: Features
results.append(test_features())
# Summary
print("\n" + "=" * 60)
print("TEST SUMMARY")
print("=" * 60)
passed = sum(results)
total = len(results)
print(f"Tests passed: {passed}/{total}")
if all(results):
print("\n🎉 All tests passed! py-wikijs is ready to use.")
return 0
elif results[0] and results[2]: # Import and features work
print("\n✅ Installation verified!")
print("ℹ️ Set WIKIJS_URL and WIKIJS_API_KEY to test connectivity")
return 0
else:
print("\n❌ Some tests failed. Please check the errors above.")
return 1
if __name__ == "__main__":
sys.exit(main())