Documentation for ceterach

Ceterach is an interface for interacting with MediaWiki.

Contents

api module

Ceterach is an interface for interacting with MediaWiki.

class ceterach.api.MediaWiki(api_url='http://en.wikipedia.org/w/api.php', config=None)

Bases: object

call(params=None, **more_params)

Sends an API query to the wiki. params is a dict representing the query parameters.

If the use_defaults parameter (accepted only as a kwarg) is True, the parameters specified in MediaWiki.config[‘defaults’] will be added to params if they are not already specified.

Next, if more_params is specified, it will be used to update params.

If the same key appears in params, Mediawiki.config[‘defaults’], and more_params, then the keys of more_params take precedence over the keys of params and the keys of params take precedence over the keys of Mediawiki.config[‘defaults’].

If the action is not specified it defaults to ‘query’. The format key will be set to ‘json’.

To illustrate this, suppose that api = MediaWiki() and api.config["defaults"] = {"default": 1}. The call method, given these arguments, will send the dict in the comment to the API:

api.call({"p": 1}) # p=1, format='json', action='query', default=1
api.call({"action": "edit", "p": 1}) # p=1, format='json', action='edit', default=1
api.call({"p": 1}, use_defaults=False) # p=1, action='query', format='json'
api.call({"p": 1, 'default': 0}) # p=1, format='json', action='query', default=0
api.call({"p": 1}, default=100) # p=1, format='json', action='query', default=100
api.call({"p": 1, 'default': 0}, default=1000) # p=1, format='json', action='query', default=1000

If everything succeeded, we return the JSON data.

category(identity, follow_redirects=False) → ceterach.category.Category

Returns a Category object for identity, which represents either a title or pageid.

This method does not follow redirects, or check if the title is invalid. Those checks will be done when the Category’s attributes are loaded.

expand_templates(title, text, include_comments=False) → str

Evaluate the templates in text and return the processed result.

For more information, see MediaWiki docs.

Parameters:
  • title (str) – Act like the wikicode is on this page (default: "API"). This only really matters when parsing links to the page itself or links to subpages, or when using magic words like {{PAGENAME}}.
  • text (str) – Wikicode to process.
  • include_comments (bool) – Whether to include HTML comments in the output. Defaults to False.
Returns:

Text with templates expanded.

file(identity, follow_redirects=False) → ceterach.file.File

Returns a File object for identity, which represents either a title or pageid.

This method does not follow redirects, or check if the title is invalid. Those checks will be done when the Category’s attributes are loaded.

iterator(params=None, limit=inf, **more_params)
Iterates over an API query, so you no longer have to use something like: ::
>>> res = api.call(action="query", ...)
>>> res["query"]["pages"][tuple(res["query"]["pages"].keys())[0]][...]
Parameters:
  • params (dict) – Parameters to the query.
  • limit (numbers.Real) – The maximum number of items the iterator will yield. Defaults to infinity.
  • more_params – Parameters to the query, which will be added to params. See .call() for similar behaviour.
Returns:

A generator that probably contains dicts.

Example usage:

>>> for s in api.iterator(list="allpages", apnamespace=0, aplimit=1, limit=3):
...     print(s)
...
{'ns': 0, 'pageid': 5878274, 'title': '!'}
{'ns': 0, 'pageid': 3632887, 'title': '!!'}
{'ns': 0, 'pageid': 600744, 'title': '!!!'}
login(username, password)

Try to log in with the given username and password.

Parameters:
  • username (str) – Username to log in as.
  • password (str) – Password that corresponds to the username.
Returns:

True if the login succeeded, False if not.

logout()

Log the bot out.

Returns:True
namespaces

A mapping of the namespace number to the namespace name.

newiterator(params=None, limit=inf, **more_params)
Iterates over an API query, so you no longer have to use something like: ::
>>> res = api.call(action="query", ...)
>>> res["query"]["pages"][tuple(res["query"]["pages"].keys())[0]][...]
Parameters:
  • params (dict) – Parameters to the query.
  • limit (numbers.Real) – The maximum number of items the iterator will yield. Defaults to infinity.
  • more_params – Parameters to the query, which will be added to params. See .call() for similar behaviour.
Returns:

A generator that probably contains dicts.

Example usage:

>>> for s in api.iterator(list="allpages", apnamespace=0, aplimit=1, limit=3):
...     print(s)
...
{'ns': 0, 'pageid': 5878274, 'title': '!'}
{'ns': 0, 'pageid': 3632887, 'title': '!!'}
{'ns': 0, 'pageid': 600744, 'title': '!!!'}
olditerator(params=None, limit=inf, **more_params)
Iterates over an API query, so you no longer have to use something like: ::
>>> res = api.call(action="query", ...)
>>> res["query"]["pages"][tuple(res["query"]["pages"].keys())[0]][...]
Parameters:
  • params (dict) – Parameters to the query.
  • limit (numbers.Real) – The maximum number of items the iterator will yield. Defaults to infinity.
  • more_params – Parameters to the query, which will be added to params. See .call() for similar behaviour.
Returns:

A generator that probably contains dicts.

Example usage:

>>> for s in api.iterator(list="allpages", apnamespace=0, aplimit=1, limit=3):
...     print(s)
...
{'ns': 0, 'pageid': 5878274, 'title': '!'}
{'ns': 0, 'pageid': 3632887, 'title': '!!'}
{'ns': 0, 'pageid': 600744, 'title': '!!!'}
page(identity, follow_redirects=False) → ceterach.page.Page

Returns a Page object for identity, which represents either a title or pageid.

This method does not follow redirects, or check if the title is invalid. Those will be done when the Page’s attributes are loaded.

revision(identity) → ceterach.revision.Revision

Returns a Revision object for identity, which represents the revid.

This method does not check if the revid is valid. That will be done when the Revision’s attributes are loaded.

set_token(*args)

Sets the Wiki’s tokens attribute with the tokens specified in the args.

If args are not specified, they will default to 'edit'.

Parameters:args – Strings that represent token names
tokens

A mapping of the token name to the token.

user(identity) → ceterach.user.User

Returns a User object for identity, which represents the username.

page module

Ceterach is an interface for interacting with MediaWiki.

class ceterach.page.Page(api, title='', pageid=0, follow_redirects=False)

Bases: object

This represents a page on a wiki, and has attributes that ease the process of getting information about the page.

append(content, summary='', minor=False, bot=False, force=False)

Add content to the bottom of the page. summary is the edit summary used for the edit. The edit will be marked as minor if minor is True, and if bot is True and the logged-in user has the bot flag, it will also be marked as a bot edit.

Set force to True in order to make the edit in spite of edit conflicts or nonexistence.

Parameters:
  • content (str) – The text with which to append to the page’s original content.
  • summary (str) – The comment to use for the modification, also known as the edit summary.
  • minor (bool) – Mark the edit as minor, if set to True.
  • bot (bool) – Mark the edit as a bot edit, if the logged in user has the bot flag and the parameter is set to True.
  • force (bool) – If set to True, ignore edit conflicts and create the page if it doesn’t already exist.
Returns:

A dictionary containing the API query result.

categories

A tuple containing the categories that the page can be found in.

content

Returns the page content, which is cached if you try to get this attribute again.

If the page does not exist, the method raises a NonexistentPageError.

Returns:The page content
Raises:NonexistentPageError
create(content, summary='', minor=False, bot=False, force=False)

Create the page with content as the content. summary is the edit summary used for the edit. The edit will be marked as minor if minor is True, and if bot is True and the logged-in user has the bot flag, it will also be marked as a bot edit.

Set force to True in order to make the edit in spite of edit conflicts.

Parameters:
  • content (str) – The text with which to create the page.
  • summary (str) – The comment to use for the modification, also known as the edit summary.
  • minor (bool) – Mark the edit as minor, if set to True.
  • bot (bool) – Mark the edit as a bot edit, if the logged in user has the bot flag and the parameter is set to True.
  • force (bool) – If set to True, ignore edit conflicts and create the page if it doesn’t already exist.
Returns:

A dictionary containing the API query result.

delete(reason='')

Delete the page.

Parameters:reason (str) – The reason for the deletion.
Returns:A dictionary containing the API query result
edit(content, summary='', minor=False, bot=False, force=False)

Replace the page’s content with content. summary is the edit summary used for the edit. The edit will be marked as minor if minor is True, and if bot is True and the logged-in user has the bot flag, it will also be marked as a bot edit.

Set force to True in order to make the edit in spite of edit conflicts and nonexistence.

Parameters:
  • content (str) – The text with which to replace the page’s original content.
  • summary (str) – The comment to use for the modification, also known as the edit summary.
  • minor (bool) – Mark the edit as minor, if set to True.
  • bot (bool) – Mark the edit as a bot edit, if the logged in user has the bot flag and the parameter is set to True.
  • force (bool) – If set to True, ignore edit conflicts and create the page if it doesn’t already exist.
Returns:

A dictionary containing the API query result.

exists

Check the existence of the page.

Returns:True if the page exists, False otherwise
from_revid(revid)

Returns a Page object by extracting information from the given revid.

This method does not follow redirects, and the very process of calling the method makes an API query.

Parameters:revid (int) – The revision ID corresponding to the page being requested.
Returns:A page.
get_redirect_target()

Gets the Page object for the target this Page redirects to.

If this Page doesn’t exist, or is invalid, it will raise a NonexistentPageError, or InvalidPageError respectively. If the page isn’t a redirect, it will raise a RedirectError.

Returns:Page object that represents the redirect target.
Raises:NonexistentPageError, InvalidPageError, RedirectError
identity()

Return a {key: value} that can be used in API queries.

It should probably return None or raise an exception if nothing useful could be found. One day, it will.

Returns:{"pageids": ...}, {"titles": ...}, or {"revids": ...}
is_redirect
Returns:True if the page is a redirect, False if the Page isn’t or doesn’t exist.
is_talkpage

Check if this page is in a talk namespace.

Returns:True if the page is in a talk namespace, False otherwise
load_attributes(res=None)

Call this to load self.__title, ._is_redirect, ._pageid, ._exists, ._namespace, ._creator, and ._revid.

This method also resolves redirects if follow_redirects=True was passed to the constructor. If the page is a redirect, the method will make a grand total of 2 API queries.

If the res parameter was supplied, the method will pretend that was what the first query returned. As such, if redirects are followed, a single API query will be made.

Parameters:res (dict) – The result of an earlier API request (optional). If you are planning to set this parameter to a value other than None, the minimal API request parameters needed for this method to function correctly are: {'inprop': 'protection', 'prop': ('info', 'revisions', 'categories'), 'rvprop': ('user', 'content')}
load_revisions(num=inf)

Call this to populate self.revisions. Specify the num parameter to limit it to num revisions, in reverse chronological order.

The revision at index n will be closer to the current day than the revision at index n+1.

move(target, reason, talk=False, subpages=False, redirect=True)

Move the page to a new title, target.

Parameters:
  • target (str) – Title you want to rename the page to.
  • reason (str) – The reason for the move.
  • talk (bool) – Move the talk page too, if set to True.
  • subpages (bool) – Move subpages too, if set to True.
  • redirect (bool) – Leave a redirect behind, if set to True.
Returns:

A dictionary containing the API query result.

namespace
Returns:An integer representing the Page’s namespace.
pageid

An integer ID representing the page.

Returns:The page’s ID.
prepend(content, summary='', minor=False, bot=False, force=False)

Add content to the top of the page. summary is the edit summary used for the edit. The edit will be marked as minor if minor is True, and if bot is True and the logged-in user has the bot flag, it will also be marked as a bot edit.

Set force to True in order to make the edit in spite of edit conflicts or nonexistence.

Parameters:
  • content (str) – The text with which to prepend to the page’s original content.
  • summary (str) – The comment to use for the modification, also known as the edit summary.
  • minor (bool) – Mark the edit as minor, if set to True.
  • bot (bool) – Mark the edit as a bot edit, if the logged in user has the bot flag and the parameter is set to True.
  • force (bool) – If set to True, ignore edit conflicts and create the page if it doesn’t already exist.
Returns:

A dictionary containing the API query result.

protection

Get the protection levels on the page.

Returns:A dict representing the page’s protection level. The keys are, by default, ‘edit’, ‘create’, and ‘move’. If the wiki is configured to have other protection types, those types will also be included in the keys. The values can be (None, None) (no restriction for that action) or (level, expiry):
  • level is the userright needed to perform the action ("autoconfirmed", for example)
  • expiry is the expiration time of the restriction. This will either be None, or a datetime at which the protection will expire.
revid
Returns:An integer representing the Page’s current revision ID.
revision_user

Returns the last user to edit the page.

Returns:A User object
Raises:NonexistentPageError, if the page doesn’t exist or is invalid.
revisions

A tuple containing the page’s revisions, from newest to oldest.

title

Returns the page’s title. If self.load_attributes() was not called prior to the execution of this method, the result will be equal to the title parameter passed to the constructor. Otherwise, it will be normalised.

Returns:The page’s title.
toggle_talk(follow_redirects=None)

Return a page with its namespace switched to or from the talk namespace.

Parameters:follow_redirects (bool) – If set to anything other than None (the default), this will be passed to the new Page object’s constructor. Otherwise, it will be set to the one passed to its own constructor.
Returns:The page that’s either the talk or non-talk version of the current page.
Raises:exc.InvalidPageError
undelete(reason='')

Undelete the page.

Parameters:reason (str) – The reason for the undeletion.
Returns:A dictionary containing the API query result

user module

Ceterach is an interface for interacting with MediaWiki.

class ceterach.user.User(api, name)

Bases: object

blockinfo

Information on the user’s current block status.

This will always return a dict with the keys {'by', 'reason', 'expiry'}. If the user is not currently blocked, all the values will be None.

create(password, email='', realname='', logout=True)

Try to create a new account on the wiki with the already-specified username.

Parameters:
  • password (str) – the password that the new account should have.
  • email (str) – the email address that the new account should be associated with.
  • realname (str) – the real name that the new account should be associated with.
  • logout (bool) – whether to log the user out right after creating it.
editcount

The number of edits this user has made.

email(subject, text, cc=True)

Send an email to the user.

Parameters:
  • subject (str) – sSubject of the email
  • text (str) – (plain text) content of the email.
  • cc (bool) – Whether you wish to send yourself a copy of the email.
Returns:

The result of the API query.

exists

Whether this user account exists.

gender

The gender of the user.

groups

The user groups that this user is in. This is different from the user rights that this user has, which can be obtained with .rights.

is_emailable

Whether this user can be emailed.

is_ip

Whether this user is an IP user.

load_attributes(res=None)

Call this to load self.__title, ._is_redirect, ._pageid, ._exists, ._namespace, ._creator, and ._revid.

This method also resolves redirects if follow_redirects=True was passed to the constructor. If the page is a redirect, the method will make a grand total of 2 API queries.

If the res parameter was supplied, the method will pretend that was what the first query returned. As such, if redirects are followed, a single API query will be made.

Parameters:res (dict) – The result of an earlier API request (optional). If you are planning to set this parameter to a value other than None, the minimal API request parameters needed for this method to function correctly are: {'usprop': ('blockinfo', 'groups', 'rights', 'editcount', 'registration', 'emailable', 'gender'), 'list': 'users'}
name

The displayed username or IP address of this user.

registration

The time that this user registered at.

rights

The user rights that this user has. This is different from the user groups that this user is in, which can be obtained with .groups.

userid

This user’s user id, for internal MediaWiki use.

userpage

A Page object that represents this user’s userpage.

revision module

Ceterach is an interface for interacting with MediaWiki.

class ceterach.revision.Revision(api, revid)

Bases: object

content

The content of the page described by this revision.

is_deleted

True if the revision is deleted, otherwise False.

is_minor

True if this revision was a minor edit, otherwise False.

load_attributes(res=None)
page

The page to which this revision was made.

prev_revision

The revision made before this one, which was made to the same page.

restore(summary='', minor=False, bot=True, force=False)

Replace the page’s content with the content found in this revision. summary is the edit summary used for the edit. The edit will be marked as minor if minor is True, and if bot is True and the logged-in user has the bot flag, it will also be marked as a bot edit.

Set force to True in order to make the edit in spite of edit conflicts and nonexistence.

Parameters:
  • summary (str) – The comment to use for the modification, also known as the edit summary.
  • minor (bool) – Mark the edit as minor, if set to True.
  • bot (bool) – Mark the edit as a bot edit, if the logged in user has the bot flag and the parameter is set to True.
  • force (bool) – If set to True, ignore edit conflicts and create the page if it doesn’t already exist.
Returns:

A dictionary containing the API query result.

revid

The revision id of the revision.

rollback(summary='', bot=False)

Undo edits in reverse chronological order, and stop when the edit about to be undone is made by a user different from the one who had most recently edited the page.

Parameters:
  • summary (str) – The edit summary to revert the edits.
  • bot (bool) – If set to true, mark the edit as a bot edit, if the user has the bot flag.
Returns:

A dictionary containing the API query result.

rvtoken
summary

The edit summary that describes this revision.

timestamp

The time at which this revision was made.

user

The user who made this revision.

ceterach.revision.decorate(meth)

file module

Ceterach is an interface for interacting with MediaWiki.

class ceterach.file.File(api, title='', pageid=0, follow_redirects=False)

Bases: ceterach.page.Page

dimensions

A tuple of integers, in the format of (width, height).

hash

The SHA1 hash of the file content.

load_attributes(res=None)

Call this to load self.__title, ._is_redirect, ._pageid, ._exists, ._namespace, ._creator, and ._revid.

This method also resolves redirects if follow_redirects=True was passed to the constructor. If the page is a redirect, the method will make a grand total of 2 API queries.

If the res parameter was supplied, the method will pretend that was what the first query returned. As such, if redirects are followed, a single API query will be made.

Parameters:res (dict) – The result of an earlier API request (optional). If you are planning to set this parameter to a value other than None, the minimal API request parameters needed for this method to function correctly are: {'inprop': 'protection', 'prop': ('info', 'revisions', 'categories'), 'rvprop': ('user', 'content')}
mime

The mime type of the file.

size

The file size in bytes.

upload(fileobj, text, summary, watch=False, key='')

Upload an arbitrary file object to this file page.

Parameters:
  • fileobj (file) – The file that will be uploaded.
  • text (str) – The description page for the file page.
  • summary (str) – The upload summary to be used.
  • watch (bool) – Set this to True in order to put this page on the watchlist when this file is uploaded, otherwise False.
  • key (str) – Session key returned by a previous upload that failed due to warnings.
uploader
Returns:A User object representing the user who uploaded the most recent revision of the file.
url(width=None, height=None) → str

Returns a direct link to the file.

You may specify either the width or the height, but not both.

Parameters:
  • width (int) – The desired width of the image.
  • height (int) – The desired height of the image.

category module

Ceterach is an interface for interacting with MediaWiki.

class ceterach.category.Category(api, title='', pageid=0, follow_redirects=False)

Bases: ceterach.page.Page

load_attributes(res=None)

Call this to load self.__title, ._is_redirect, ._pageid, ._exists, ._namespace, ._creator, and ._revid.

This method also resolves redirects if follow_redirects=True was passed to the constructor. If the page is a redirect, the method will make a grand total of 2 API queries.

If the res parameter was supplied, the method will pretend that was what the first query returned. As such, if redirects are followed, a single API query will be made.

Parameters:res (dict) – The result of an earlier API request (optional). If you are planning to set this parameter to a value other than None, the minimal API request parameters needed for this method to function correctly are: {'inprop': 'protection', 'prop': ('info', 'revisions', 'categories'), 'rvprop': ('user', 'content')}
members

Iterate over Pages in the category.

populate(res=None)

Get the pages that are contained by this category, and subcategories. This data is stored in ._members and ._subcats.

If the res parameter was supplied, the method will pretend that was what the query returned.

Parameters:res (list) – The result of an earlier API request (optional). If you are planning to set this parameter to a value other than None, the minimal API request parameters to correctly form this are: {"prop": ('revisions', 'info'), "gcmtitle": category_title, "generator": "categorymembers", "rvprop": 'content'}
subcats

Iterate over Categories in the category.

exceptions module

Ceterach is an interface for interacting with MediaWiki.

exception ceterach.exceptions.ApiError(message, code=None)

Bases: ceterach.exceptions.CeterachError

Could not connect to the API and process the response correctly. Perhaps the URL was malformed, the site does not exist, the API does not support format=json, or the internet connection died.

exception ceterach.exceptions.CeterachError(message, code=None)

Bases: Exception

This is the base exception class for exceptions in Ceterach.

Parameters:
  • message – The message, stored in self.msg
  • code – The error code, stored in self.code
code = 'py'
exception ceterach.exceptions.EditConflictError(message, code=None)

Bases: ceterach.exceptions.EditError

You got an edit conflict while editing a page.

This exception will also be raised in the case of delete/recreate conflicts.

exception ceterach.exceptions.EditError(message, code=None)

Bases: ceterach.exceptions.CeterachError

An error occurred while editing or doing something else that ‘wrote’ to the API.

exception ceterach.exceptions.EditFilterError(message, code=None)

Bases: ceterach.exceptions.FilterError

MediaWiki edit filter blocked the edit.

exception ceterach.exceptions.FilterError(message, code=None)

Bases: ceterach.exceptions.EditError

Base class for edits that are blocked by filters and blacklists.

exception ceterach.exceptions.InvalidPageError(message, code=None)

Bases: ceterach.exceptions.CeterachError

Attempted to get information about a page whose title is invalid.

exception ceterach.exceptions.NonexistentPageError(message, code=None)

Bases: ceterach.exceptions.CeterachError

Attempted to get information about a page that does not exist.

exception ceterach.exceptions.NonexistentRevisionError(message, code=None)

Bases: ceterach.exceptions.CeterachError

Attempted to get information about a revision that does not exist.

exception ceterach.exceptions.NonexistentUserError(message, code=None)

Bases: ceterach.exceptions.CeterachError

Attempted to get information about a user that does not exist.

exception ceterach.exceptions.PermissionsError(message, code=None)

Bases: ceterach.exceptions.EditError

Attempted to do something that requires rights you don’t have. For instance, a non-admin tried to edit a full-protected page.

exception ceterach.exceptions.RedirectError(message, code=None)

Bases: ceterach.exceptions.CeterachError

Attempted to do something to the page under the assumption that it was a redirect, but it is not a redirect, so it didn’t work.

exception ceterach.exceptions.SpamFilterError(message, code=None)

Bases: ceterach.exceptions.FilterError

MediaWiki spam filter blocked the edit.

Indices and tables