py-wikijs/README.md

# Wiki.js Python SDK

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Support](https://img.shields.io/badge/python-3.8+-blue.svg)](https://python.org)
[![Repository](https://img.shields.io/badge/repo-Gitea-green.svg)](https://gitea.hotserv.cloud/lmiranda/py-wikijs)
[![Issues](https://img.shields.io/badge/issues-Gitea-blue.svg)](https://gitea.hotserv.cloud/lmiranda/py-wikijs/issues)

**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
```bash
# 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
```python
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!"
))
```

---

## 🎯 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](#quick-start)**: Basic setup and usage
- **[API Reference](docs/api_reference.md)**: Complete SDK documentation
- **[User Guide](docs/user_guide.md)**: Comprehensive usage guide with examples
- **[Examples](examples/)**: Real-world usage examples and code samples

### **For Contributors** 
- **[Contributing Guide](docs/CONTRIBUTING.md)**: How to contribute to the project
- **[Development Guide](docs/development.md)**: Setup and development workflow
- **[Changelog](docs/CHANGELOG.md)**: Version history and changes

### **For Maintainers**
- **[Architecture](docs/wikijs_sdk_architecture.md)**: Technical design and patterns
- **[Development Plan](docs/wikijs_sdk_release_plan.md)**: Complete roadmap and milestones
- **[Development Notes](CLAUDE.md)**: Development workflow and coordination

---

## 🤝 Contributing

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

**Getting Started:**
1. Check our [Development Plan](docs/wikijs_sdk_release_plan.md) for current priorities
2. Review the [Architecture](docs/wikijs_sdk_architecture.md) for technical context
3. See [Development Notes](CLAUDE.md) 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
```bash
# 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](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](docs/) or explore the [development workflow](CLAUDE.md) to see how this project is built!