930fe50e60
Phase 2, Task 2.2.1: Users API Implementation (Sync) This commit adds comprehensive user management capabilities to the Wiki.js Python SDK with full CRUD operations. User Data Models (wikijs/models/user.py): ----------------------------------------- 1. **User** - Complete user data model - Profile information (name, email, location, job title) - Authentication details (provider, verified, active status) - Group memberships with UserGroup nested model - Timestamps (created, updated, last login) - Email validation with pydantic EmailStr - Name validation (2-255 characters) 2. **UserCreate** - User creation model - Required: email, name, password - Optional: groups, profile fields, provider settings - Validation: email format, password strength (min 6 chars) - Welcome email configuration - Password change enforcement 3. **UserUpdate** - User update model - All fields optional for partial updates - Email, name, password updates - Profile field updates - Group membership changes - Status flags (active, verified) 4. **UserGroup** - Group membership model - Group ID and name - Used in User model for group associations Users Endpoint (wikijs/endpoints/users.py): ------------------------------------------- Complete CRUD Operations: 1. **list()** - List users with filtering - Pagination (limit, offset) - Search by name/email - Ordering (name, email, createdAt, lastLoginAt) - Client-side pagination fallback 2. **get(user_id)** - Get user by ID - Fetch single user with full details - Include group memberships - Comprehensive error handling 3. **create(user_data)** - Create new user - Accept UserCreate object or dict - Full validation before API call - Returns created User object - Handles creation failures gracefully 4. **update(user_id, user_data)** - Update existing user - Partial updates supported - Only sends changed fields - Returns updated User object - Validates all updates 5. **delete(user_id)** - Delete user - Permanent deletion - Returns boolean success - Clear error messages 6. **search(query)** - Search users - Search by name or email - Optional result limiting - Uses list() with search filter Helper Methods: - _normalize_user_data() - API response normalization - Handles field name mapping (camelCase → snake_case) - Group data structure conversion Integration: ------------ - Added UsersEndpoint to WikiJSClient - Updated endpoints module exports - Added user models to main package exports - Installed email-validator dependency for EmailStr GraphQL Queries: ---------------- - users.list - List/search users - users.single - Get user by ID - users.create - Create new user - users.update - Update existing user - users.delete - Delete user All queries include proper error handling and response validation. Code Quality: ------------- ✅ Compiles without errors ✅ Type hints on all methods ✅ Comprehensive docstrings ✅ Input validation ✅ Proper exception handling ✅ Follows existing code patterns Next Steps: ----------- - Implement AsyncUsersEndpoint (async version) - Write comprehensive tests - Add usage documentation - Create examples Phase 2, Task 2.2.1 Progress: ~50% Complete Users API (sync): ✅ COMPLETE Users API (async): ⏳ IN PROGRESS This establishes the foundation for complete user management in the Wiki.js Python SDK. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
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/wikijs-sdk-python.git
# Or clone and install locally
git clone https://gitea.hotserv.cloud/lmiranda/wikijs-sdk-python.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!"
))
🎯 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
- 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
- Python 3.8+
- Git
- Wiki.js instance for testing
Local Development
# Clone and setup
git clone https://gitea.hotserv.cloud/lmiranda/wikijs-sdk-python.git
cd wikijs-python-sdk
pip install -e ".[dev]"
# Run tests
pytest
# Run quality checks
pre-commit run --all-files
🏆 Project Features
Current (MVP Complete)
- ✅ Synchronous HTTP client with connection pooling and retry logic
- ✅ Multiple authentication methods (API key, JWT, custom)
- ✅ Complete Pages API with CRUD operations, search, and filtering
- ✅ Comprehensive error handling with specific exception types
- ✅ Type-safe models with validation using Pydantic
- ✅ Extensive test coverage (87%+) with robust test suite
- ✅ Complete documentation with API reference and user guide
- ✅ Practical examples and code samples
Planned Enhancements
- ⚡ Async/await support
- 💾 Intelligent caching
- 🔄 Retry logic with backoff
- 💻 CLI tools
- 🔧 Plugin system
- 🛡️ Advanced security features
📄 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!