SMW Reader

A modular Python client library for accessing Semantic MediaWiki (SMW) API endpoints.

Features

🚀 Fluent Query Builder: A programmatic and readable way to construct complex queries.
🎯 Convenience Methods: A purpose-built method for querying categories (query_category).
🏗️ Modular Design: Following the open/closed principle, easily extensible with new API endpoints.
🛡️ Type Safety: Full type hints throughout the codebase.
🚨 Robust Error Handling: Custom exceptions for different error scenarios.
📦 No External Dependencies: Uses only Python standard library for HTTP requests.
🧪 Comprehensive Testing: Full test suite with pytest.

Installation

# Recommended: Install with uv (fast, modern Python package manager)
uv add smw-reader

# Or with optional HTTP client support
uv add 'smw-reader[aiohttp]'  # For async HTTP with aiohttp
uv add 'smw-reader[httpx]'    # For async HTTP with httpx
uv add 'smw-reader[async]'    # For full async support

# Alternatively, use pip directly
pip install smw-reader

# Development installation
git clone <repository-url>
cd smw-reader
uv sync

Quick Start

from smw_reader import SMWClient, QueryBuilder

# Create a client instance
site = SMWClient("https://your-wiki.org/w/")

# Build a query using the QueryBuilder
builder = QueryBuilder()
builder.add_conditions("Category:Person").add_printouts("Name", "Age")

# Execute the query
result = site.ask.query(builder, limit=10)

print(result)

# You can also use the convenience method for categories
result_category = site.ask.query_category("Person", printouts=["Name", "Age"], limit=10)

print(result_category)

Building Queries

The recommended way to build queries is using the QueryBuilder, which provides a fluent interface for adding conditions and printouts.

from smw_reader import QueryBuilder

# Start with a new builder
builder = QueryBuilder()

# Chain methods to add conditions and printouts
builder.add_conditions(
    "Category:Software",
    "License::GPL"
).add_printouts(
    "Name",
    "Homepage URL",
    "Version"
)

# The builder can be passed directly to the query method
result = site.ask.query(builder, limit=20)

For more advanced use cases, including raw query strings and dictionary-based conditions, please see the detailed examples in the documentation.

Convenience Methods

For common tasks, convenience methods provide a simpler interface.

`query_category()`

Query all pages in a specific category.

# Query by category - printouts are auto-formatted
result = site.ask.query_category(
    category="Software",
    printouts=["Name", "License", "Version"],  # No "?" prefix needed!
    limit=20
)

Error Handling

The library provides specific exceptions for different error scenarios:

from smw_reader.exceptions import (
    SMWAPIError,           # Base API error
    SMWConnectionError,    # Network/connection issues
    SMWServerError,        # Server-side errors
    SMWValidationError,    # Invalid parameters
    SMWAuthenticationError # Authentication failures
)

try:
    result = site.ask.query("[[Category:Test]]")
except SMWConnectionError:
    print("Network issue")
except SMWAPIError as e:
    print(f"API error: {e}")

Architecture

The library follows a modular architecture:

SMWClient: Main client class that handles HTTP requests and endpoint registration.
APIEndpoint: Abstract base class for API endpoints.
QueryBuilder: A fluent interface for building query strings.
HTTPClient: Abstract interface for HTTP clients.
RequestsHTTPClient: Concrete implementation using urllib.

Development

See the project’s development guide in the documentation (docs/sphinx/DEVELOPMENT.md) for setup, workflow, and contributing information.