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!"
))

---

📋 Requirements

System Requirements

• Python: 3.8 or higher
• Wiki.js: 2.2 or higher (tested with 2.5.x series)
• API Access: Valid API key with appropriate permissions

Compatibility Notes

✅ Supported: This SDK is designed for Wiki.js 2.x (versions 2.2 through 2.5.308+) ⚠️ Not Supported: Wiki.js 3.x (alpha) uses a different API schema and is not yet supported

For detailed compatibility information, see docs/compatibility.md.

---

🎯 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
Testing	✅ Complete	87%+ test coverage with comprehensive test suite
Documentation	✅ Complete	Complete API reference, user guide, and examples

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
• Requirements: System and Wiki.js version requirements
• Compatibility Guide: Detailed version compatibility information
• 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

See Requirements for system and Wiki.js version requirements.

Additional development tools:

• Git
• Wiki.js 2.x instance for testing (2.2 or higher)

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!