API Reference

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

class smw_reader.APIEndpoint(client)

Abstract base class for SMW API endpoints.

This interface allows for easy extension of new API endpoints while maintaining the open/closed principle.

abstract property endpoint_name: str: The name of the API endpoint (e.g., ‘ask’, ‘askargs’, ‘smwbrowse’).

abstractmethod execute(**params)

Execute the API endpoint with given parameters.

Parameters:: **params (Any) – Endpoint-specific parameters.
Return type:: dict[str, Any]
Returns:: The API response as a dictionary.
Raises:: SMWAPIError – If the API request fails.

class smw_reader.AskEndpoint(client)

Implementation of the SMW ‘ask’ API endpoint.

The ‘ask’ endpoint allows executing semantic queries using SMW’s query language. This endpoint supports the full semantic query syntax with conditions, printouts, and parameters.

The recommended way to build complex queries is by using the QueryBuilder. See the query method for more details.

property endpoint_name: str: The name of the API endpoint.

execute(**params)

Execute a semantic query using the ‘ask’ endpoint.

Parameters:: **params (Any) – Query parameters including: - query: The semantic query string - limit: Maximum number of results - offset: Offset for pagination - sort: Sort field - order: Sort order (‘asc’ or ‘desc’) - p_…: Special parameters for ‘Special:Ask’ (e.g., p_limit=100)
Return type:: dict[str, Any]
Returns:: The query results as a dictionary.
Raises:: SMWValidationError – If the query is invalid.

query(query, **params)

Convenience method for executing semantic queries.

This method accepts either a raw SMW query string or a QueryBuilder instance, which allows for programmatic construction of queries.

Examples

Using a raw query string:

>>> site.ask.query("[[Category:Cities]]|?Population")

Using the QueryBuilder:

>>> from smw_reader import QueryBuilder
>>> builder = QueryBuilder()
>>> builder.add_conditions("Category:Cities").add_printouts("Population")
>>> site.ask.query(builder)

Parameters:

query (str | QueryBuilder) – The semantic query string or a QueryBuilder instance.
**params (Any) – Additional query parameters.

Return type:

dict[str, Any]

Returns:

The query results as a dictionary.

query_category(category, printouts=None, **params)

Query pages in a specific category.

This is a convenience method that builds and executes a query for a given category.

Parameters:

category (str) – The name of the category to query.
printouts (list[str] | None) – A list of properties to retrieve for each page.
**params (Any) – Additional query parameters.

Return type:

dict[str, Any]

Returns:

The query results as a dictionary.

class smw_reader.HTTPClient

Abstract interface for HTTP clients to enable dependency injection.

abstractmethod get(url, params=None, **kwargs)

Make a GET request.

Parameters:

url (str) – The URL to request.
params (dict[str, Any] | None) – Query parameters.
**kwargs (Any) – Additional request parameters.

Return type:

dict[str, Any]

Returns:

The response data.

abstractmethod post(url, data=None, **kwargs)

Make a POST request.

Parameters:

url (str) – The URL to request.
data (dict[str, Any] | None) – Request body data.
**kwargs (Any) – Additional request parameters.

Return type:

dict[str, Any]

Returns:

The response data.

class smw_reader.QueryBuilder

A fluent interface for building complex SMW queries.

This class allows for the programmatic construction of query strings by chaining methods to add conditions and printouts.

conditions: A list of query conditions (e.g., “[[Category:Person]]”).

printouts: A list of properties to print (e.g., “?Name”).

add_conditions(*conditions)

Add one or more conditions to the query.

Parameters:: *conditions (str | dict[str, str]) – A list of conditions to add. Each condition can be a string or a dictionary. A string is treated as a raw condition, e.g. “Category:Test”. A dict must contain ‘key’ and ‘value’, and optionally ‘operator’. e.g. {“key”: “Intro-Date”, “operator”: “>”, “value”: “2020-10-10”}
Return type:: Self
Returns:: The QueryBuilder instance for method chaining.

add_printouts(*printouts)

Add one or more printouts to the query.

Parameters:: *printouts (str) – A list of printouts to add.
Return type:: Self
Returns:: The QueryBuilder instance for method chaining.

build()

Build the final query string by joining conditions and printouts.

Return type:: str
Returns:: The formatted SMW query string.

class smw_reader.RequestsHTTPClient(timeout=30.0, user_agent='SMW-Reader/0.1.0')

HTTP client implementation using urllib (no external dependencies).

This implementation uses only standard library modules to avoid external dependencies while providing robust HTTP functionality.

get(url, params=None, **kwargs)

Make a GET request.

Parameters:

url (str) – The URL to request.
params (dict[str, Any] | None) – Query parameters.
**kwargs (Any) – Additional request parameters.

Return type:

dict[str, Any]

Returns:

The response data as a dictionary.

Raises:

SMWConnectionError – If the connection fails.
SMWServerError – If the server returns an error.

post(url, data=None, **kwargs)

Make a POST request.

Parameters:

url (str) – The URL to request.
data (dict[str, Any] | None) – Request body data.
**kwargs (Any) – Additional request parameters.

Return type:

dict[str, Any]

Returns:

The response data as a dictionary.

Raises:

SMWConnectionError – If the connection fails.
SMWServerError – If the server returns an error.

exception smw_reader.SMWAPIError(message, status_code=None, response_data=None): Base exception for SMW API errors.

exception smw_reader.SMWAuthenticationError(message, status_code=None, response_data=None): Exception raised when authentication fails.

class smw_reader.SMWClient(base_url, http_client=None, api_path='api.php')

Main client for accessing Semantic MediaWiki API.

This client provides a modular interface to various SMW API endpoints following dependency injection and open/closed principles.

get_endpoint(name)

Get a registered endpoint by name.

Parameters:: name (str) – The endpoint name.
Return type:: APIEndpoint
Returns:: The endpoint instance.
Raises:: SMWValidationError – If the endpoint is not registered.

make_request(action, params=None, method='GET')

Make a request to the SMW API.

Parameters:

action (str) – The API action/module name.
params (dict[str, Any] | None) – Additional parameters for the request.
method (str) – HTTP method to use.

Return type:

dict[str, Any]

Returns:

The API response as a dictionary.

Raises:

SMWAPIError – If the API request fails.

register_endpoint(endpoint)

Register an API endpoint with the client.

Parameters:: endpoint (APIEndpoint) – The endpoint instance to register.
Return type:: None

exception smw_reader.SMWConnectionError(message, status_code=None, response_data=None): Exception raised when there’s a connection error to the SMW API.

exception smw_reader.SMWServerError(message, status_code=None, response_data=None): Exception raised when the SMW server returns an error.

exception smw_reader.SMWValidationError(message, status_code=None, response_data=None): Exception raised when request parameters are invalid.