py-wikijs/README.md

Wiki.js Python SDK

A professional Python SDK for Wiki.js API integration.

🎉 Status: Phase 1 MVP Complete! Ready for production use
Current Version: v0.1.0 with complete Wiki.js Pages API integration Next Milestone: v0.2.0 with Users, Groups, and Assets API support

---

🚀 Quick Start

Installation

# Install directly from Gitea
pip install git+https://gitea.hotserv.cloud/lmiranda/py-wikijs.git

# Or clone and install locally
git clone https://gitea.hotserv.cloud/lmiranda/py-wikijs.git
cd wikijs-python-sdk
pip install -e .

Basic Usage

from wikijs import WikiJSClient

# Initialize client
client = WikiJSClient('https://wiki.example.com', auth='your-api-key')

# List pages
pages = client.pages.list()

# Get a specific page
page = client.pages.get(123)

# Create a new page
from wikijs.models import PageCreate
new_page = client.pages.create(PageCreate(
    title="Getting Started",
    path="getting-started",
    content="# Welcome\n\nThis is your first page!"
))

---

✨ Production Features

Structured Logging

from wikijs import WikiJSClient
import logging

# Enable detailed logging
client = WikiJSClient(
    'https://wiki.example.com',
    auth='your-api-key',
    log_level=logging.DEBUG
)

📚 Logging Guide

Metrics & Telemetry

# Get performance metrics
metrics = client.get_metrics()
print(f"Total requests: {metrics['total_requests']}")
print(f"Error rate: {metrics['error_rate']:.2f}%")
print(f"P95 latency: {metrics['latency']['p95']:.2f}ms")

📚 Metrics Guide

Rate Limiting

# Prevent API throttling
client = WikiJSClient(
    'https://wiki.example.com',
    auth='your-api-key',
    rate_limit=10.0  # 10 requests/second
)

📚 Rate Limiting Guide

---

🎯 Current Development Status

Phase 1: MVP Development ✅ COMPLETE

• ✅ Complete: Professional-grade Wiki.js Python SDK
• 🎯 Goal: Basic Wiki.js integration with Pages API
• 📦 Deliverable: Installable package with core functionality

Component	Status	Description
Project Setup	✅ Complete	Repository structure, packaging, CI/CD
Core Client	✅ Complete	HTTP client with authentication and retry logic
Pages API	✅ Complete	Full CRUD operations for wiki pages
Production Features	✅ Complete	Logging, metrics, rate limiting
Testing	✅ Complete	85%+ test coverage with comprehensive test suite
Documentation	✅ Complete	Complete API reference, user guide, and examples
Security	✅ Complete	SECURITY.md policy and best practices

Planned Features

• v0.2.0: Complete API coverage (Users, Groups, Assets)
• v0.3.0: Production features (retry logic, caching, monitoring)
• v1.0.0: Enterprise features (async support, plugins, advanced CLI)

---

📚 Documentation

For Users

• Quick Start: Basic setup and usage
• API Reference: Complete SDK documentation
• User Guide: Comprehensive usage guide with examples
• Examples: Real-world usage examples and code samples

For Contributors

• Contributing Guide: How to contribute to the project
• Development Guide: Setup and development workflow
• Changelog: Version history and changes

For Maintainers

• Architecture: Technical design and patterns
• Development Plan: Complete roadmap and milestones
• Development Notes: Development workflow and coordination

---

🤝 Contributing

We welcome contributions! This project showcases systematic development with professional standards.

Getting Started:

1. Check our Development Plan for current priorities
2. Review the Architecture for technical context
3. See Development Notes for development workflow
4. Start with issues labeled good first issue (Coming soon)

Community:

• 💬 GitHub Discussions: Questions and community chat (Coming soon)
• 🐛 GitHub Issues: Bug reports and feature requests (Coming soon)

---

🛠️ Development Setup

Prerequisites

• Python 3.8+
• Git
• Wiki.js instance for testing

Local Development

# Clone and setup
git clone https://gitea.hotserv.cloud/lmiranda/py-wikijs.git
cd wikijs-python-sdk
pip install -e ".[dev]"

# Run tests
pytest

# Run quality checks
pre-commit run --all-files

---

🏆 Project Features

Current Features

• ✅ Core SDK: Synchronous HTTP client with connection pooling and retry logic
• ✅ Authentication: Multiple methods (API key, JWT, custom)
• ✅ Complete API Coverage: Pages, Users, Groups, and Assets APIs
• ✅ Async Support: Full async/await implementation with aiohttp
• ✅ Intelligent Caching: LRU cache with TTL support for performance
• ✅ Batch Operations: Efficient create_many, update_many, delete_many methods
• ✅ Auto-Pagination: iter_all() methods for seamless pagination
• ✅ Error Handling: Comprehensive exception hierarchy with specific error types
• ✅ Type Safety: Pydantic models with full validation
• ✅ Testing: 87%+ test coverage with 270+ tests
• ✅ Documentation: Complete API reference, user guide, and examples

Planned Enhancements

• 💻 Advanced CLI tools with interactive mode
• 🔧 Plugin system for extensibility
• 🛡️ Enhanced security features and audit logging
• 🔄 Circuit breaker for fault tolerance
• 📊 Performance monitoring and metrics

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Wiki.js: The excellent knowledge management platform this SDK supports
• leomiranda: Developer who created this SDK
• Python Community: For exceptional tools and development standards

---

Ready to contribute? Check out our development documentation or explore the development workflow to see how this project is built!