-
Notifications
You must be signed in to change notification settings - Fork 51
api.py is a module used for communication with the wiki. It is essentially always used, though not always necessary to import directly, as the objects available in other modules provide a simpler interface for common queries and actions. As APIRequest is generally the only part of this that user code will ever call directly, examples and more complete documentation are at api.APIRequest.
api.py defines 3 objects
The APIRequest object is used to handle communication with the wiki. All functions that interact with the wiki use one or more APIRequests. Each object is designed to handle one API query. All HTTP requests are done via POST.
See api.APIRequest for full documentation and examples.
An APIResult object is returned by most calls to APIRequest.query. It is a subtype of the Python dict type and is identical in almost all ways. See the Python documentation for full documentation. APIResult also includes a response member variable that includes HTTP response headers for debugging purposes.
In general, there is no reason to ever need to create an APIResult object in your own code (they're created automatically when needed), and they can, for all intents and purposes, be treated as a dict.
The format of the actual data in the object is dependent on the API module being queried; see the MediaWiki API documentation for information on the structure of results of different API calls.
An APIListResult object is returned by calls to APIRequest.query that don't return a JSON object in the result (an array instead). It is a subtype of the Python list type and is identical in almost all ways. See the Python documentation for full documentation. APIListResult also includes a response member variable that includes HTTP response headers for debugging purposes.
This is very rarely used, as only one API module is known to behave this way, the OpenSearch module.
api.py defines 2 exceptions
APIError is an exception raised in the api module. It is the base class for all other API-related exceptions, which is currently only APIDisabled. APIError extends Exception.
APIError (not including subclasses) is currently raised in the following situations: *If a multipart request is made and the poster module is not available *When trying to change the result format using APIRequest.changeParam *When the MediaWiki API returns an error
APIDisabled is raised in only one situation, when a request is made to a site that has disabled the MediaWiki API.
api.py also contains a resultCombine() function. This is used by the now-deprecated old method for "continued" queries and will likely be removed in the future.