py-wikijs/INSTALLATION_GUIDE.md

Installation Guide - py-wikijs

Quick reference for installing and using py-wikijs in your projects

---

📦 Installation Methods

Method 1: Install from GitHub (Recommended for now)

Since this package is not yet on PyPI, install directly from GitHub:

# Install the latest release (v0.1.0)
pip install git+https://github.com/l3ocho/py-wikijs.git@v0.1.0

# Or install from a specific branch
pip install git+https://github.com/l3ocho/py-wikijs.git@main

# Or install from the current development branch
pip install git+https://github.com/l3ocho/py-wikijs.git@claude/test-tool-integration-011CUUU3JXwm8n8waD6UYeea

Method 2: Install in requirements.txt

Add to your requirements.txt:

# Install specific version tag
git+https://github.com/l3ocho/py-wikijs.git@v0.1.0

# Or install from main branch
git+https://github.com/l3ocho/py-wikijs.git@main

Then install:

pip install -r requirements.txt

Method 3: Install in pyproject.toml (Poetry/Modern Python)

Add to your pyproject.toml:

[project.dependencies]
py-wikijs = { git = "https://github.com/l3ocho/py-wikijs.git", tag = "v0.1.0" }

Or for Poetry:

[tool.poetry.dependencies]
py-wikijs = { git = "https://github.com/l3ocho/py-wikijs.git", tag = "v0.1.0" }

Method 4: Local Development (Editable Install)

If you're developing both projects simultaneously:

# Clone the repository
git clone https://github.com/l3ocho/py-wikijs.git
cd py-wikijs

# Install in editable mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

# Or install with async support
pip install -e ".[async]"

Then in your other project, the package will automatically reflect changes.

---

✅ Verification

After installation, verify it works:

# Check installation
python -c "from wikijs import WikiJSClient, __version__; print(f'py-wikijs v{__version__} installed successfully!')"

# Should output: py-wikijs v0.1.0 installed successfully!

---

🚀 Basic Usage in Your Project

Simple Example

Create a file test_wikijs.py:

from wikijs import WikiJSClient

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

# List all pages
pages = client.pages.list()
print(f"Found {len(pages)} pages")

# Get a specific page
page = client.pages.get(page_id=1)
print(f"Page title: {page.title}")

With Environment Variables (Recommended)

Create .env file:

WIKIJS_URL=https://your-wiki.example.com
WIKIJS_API_KEY=your-api-key-here

In your code:

import os
from wikijs import WikiJSClient

# Load from environment
client = WikiJSClient(
    url=os.getenv('WIKIJS_URL'),
    auth=os.getenv('WIKIJS_API_KEY')
)

Advanced Features

from wikijs import WikiJSClient
import logging

# Enable debug logging
client = WikiJSClient(
    url='https://wiki.example.com',
    auth='your-api-key',
    log_level=logging.DEBUG,
    rate_limit=10.0,  # 10 requests/second
    timeout=30.0       # 30 second timeout
)

# Create a new page
from wikijs.models import PageCreate

new_page = client.pages.create(PageCreate(
    title="My New Page",
    path="documentation/my-new-page",
    content="# Welcome\n\nThis is my new page!",
    description="A new documentation page",
    is_published=True,
    is_private=False,
    locale="en",
    tags=["documentation", "tutorial"]
))

print(f"Created page: {new_page.title} (ID: {new_page.id})")

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

Async Usage (Future - v0.2.0)

When async support is released:

from wikijs.aio import AsyncWikiJSClient

async def main():
    async with AsyncWikiJSClient(
        url='https://wiki.example.com',
        auth='your-api-key'
    ) as client:
        pages = await client.pages.list()
        print(f"Found {len(pages)} pages")

# Run with asyncio
import asyncio
asyncio.run(main())

---

🔧 Dependencies

Required:

• Python >= 3.8
• requests >= 2.28.0
• pydantic >= 1.10.0
• typing-extensions >= 4.0.0

Optional:

• aiohttp >= 3.8.0 (for async support - coming in v0.2.0)
• click >= 8.0.0 (for CLI tools - future)
• rich >= 12.0.0 (for rich output - future)

---

📚 Documentation

• API Reference: docs/api_reference.md
• User Guide: docs/user_guide.md
• Examples: examples/
• Compatibility: docs/compatibility.md

---

⚠️ Important Notes

Before Going Public:

1. ✅ Version Tag Created: v0.1.0 is now tagged
2. ✅ Package Structure: Ready for installation
3. ⏳ PyPI Publishing: Not yet published (GitHub-only for now)
4. ⏳ GitHub Release: Consider creating a GitHub Release page

Production Checklist:

• Set up proper Wiki.js instance with API access
• Store API keys securely (use environment variables)
• Enable appropriate logging for production
• Set rate limits to respect your Wiki.js server
• Monitor metrics for performance issues
• Review security best practices in docs/SECURITY.md

Wiki.js Requirements:

• Supported Versions: Wiki.js 2.2 through 2.5.x
• Not Supported: Wiki.js 3.x (different API schema)
• API Access: Requires valid API key with appropriate permissions

---

🐛 Troubleshooting

Import Error

ModuleNotFoundError: No module named 'wikijs'

Solution: Ensure package is installed: pip install git+https://github.com/l3ocho/py-wikijs.git@v0.1.0

Authentication Error

wikijs.exceptions.AuthenticationError: Invalid API key

Solution: Check your API key is correct and has necessary permissions in Wiki.js

Connection Error

wikijs.exceptions.ConnectionError: Failed to connect to Wiki.js

Solution: Verify Wiki.js URL is correct and accessible from your network

---

🚀 Next Steps

1. Install the package using one of the methods above
2. Get your Wiki.js API key from your Wiki.js admin panel
3. Test basic connectivity with a simple script
4. Explore examples in the examples/ directory
5. Read the documentation for advanced features

---

📞 Support

• Issues: https://github.com/l3ocho/py-wikijs/issues
• Discussions: https://github.com/l3ocho/py-wikijs/discussions
• Documentation: https://github.com/l3ocho/py-wikijs/tree/main/docs

---

Last Updated: 2025-10-25 Package Version: v0.1.0 Status: Production Ready (MVP)