🎉 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 from PyPI (recommended)
pip install py-wikijs

# Or install from GitHub
pip install git+https://github.com/l3ocho/py-wikijs.git

# Or clone and install locally for development
git clone https://github.com/l3ocho/py-wikijs.git
cd py-wikijs
pip install -e ".[dev]"

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.

✨ 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
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:

Check our Development Plan for current priorities
Review the Architecture for technical context
See Development Notes for development workflow
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://github.com/l3ocho/py-wikijs.git
cd py-wikijs
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
✅ Production Features: Structured logging, metrics, rate limiting
✅ Testing: 87%+ test coverage with 270+ tests
✅ Documentation: Complete API reference, user guide, and examples
✅ Security: Security policy and vulnerability reporting

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!