diff --git a/mwclient/client.py b/mwclient/client.py
index 4c868098912debd8f53d1f685739340a9ac4b41e..9349d70d5620d5636c6dd0a9064cf2c579327607 100644
--- a/mwclient/client.py
+++ b/mwclient/client.py
@@ -30,8 +30,7 @@ log = logging.getLogger(__name__)
class Site(object):
- """
- A MediaWiki site identified by its hostname.
+ """A MediaWiki site identified by its hostname.
>>> import mwclient
>>> site = mwclient.Site('en.wikipedia.org')
@@ -40,7 +39,9 @@ class Site(object):
Mwclient assumes that the script path (where index.php and api.php are located)
is '/w/'. If the site uses a different script path, you must specify this
- (path must end in a '/'). Examples:
+ (path must end in a '/').
+
+ Examples:
>>> site = mwclient.Site('vim.wikia.com', path='/')
>>> site = mwclient.Site('sourceforge.net', path='/apps/mediawiki/mwclient/')
@@ -164,9 +165,11 @@ class Site(object):
def version_tuple_from_generator(string, prefix='MediaWiki '):
"""Return a version tuple from a MediaWiki Generator string
- Example: "MediaWiki 1.5.1" → (1, 5, 1)
+ Example:
+ "MediaWiki 1.5.1" → (1, 5, 1)
- :param prefix: the expected prefix of the string
+ Args:
+ prefix (str): The expected prefix of the string
"""
if not string.startswith(prefix):
raise errors.MediaWikiVersionError('Unknown generator {}'.format(string))
@@ -176,8 +179,9 @@ class Site(object):
def split_num(s):
"""Split the string on the first non-digit character.
- :return: a tuple of the digit part as int and, if
- available, the rest of the string.
+ Returns:
+ A tuple of the digit part as int and, if available,
+ the rest of the string.
"""
i = 0
while i < len(s):
@@ -209,8 +213,9 @@ class Site(object):
return "<Site object '%s%s'>" % (self.host, self.path)
def api(self, action, *args, **kwargs):
- """
- Perform a generic API call and handle errors. All arguments will be passed on.
+ """Perform a generic API call and handle errors.
+
+ All arguments will be passed on.
Example:
To get coordinates from the GeoData MediaWiki extension at English Wikipedia:
@@ -487,32 +492,37 @@ class Site(object):
return self.tokens[type]
- def upload(self, file=None, filename=None, description='', ignore=False, file_size=None,
- url=None, filekey=None, comment=None):
- """
- Uploads a file to the site. Returns JSON result from the API.
- Can raise `errors.InsufficientPermission` and `requests.exceptions.HTTPError`.
-
- : Parameters :
- - file : File object or stream to upload.
- - filename : Destination filename, don't include namespace
- prefix like 'File:'
- - description : Wikitext for the file description page.
- - ignore : True to upload despite any warnings.
- - file_size : Deprecated in mwclient 0.7
- - url : URL to fetch the file from.
- - filekey : Key that identifies a previous upload that was
+ def upload(self, file=None, filename=None, description='', ignore=False,
+ file_size=None, url=None, filekey=None, comment=None):
+ """Uploads a file to the site.
+
+ Note that one of `file`, `filekey` and `url` must be specified, but not
+ more than one. For normal uploads, you specify `file`.
+
+ Args:
+ file (str): File object or stream to upload.
+ filename (str): Destination filename, don't include namespace
+ prefix like 'File:'
+ description (str): Wikitext for the file description page.
+ ignore (bool): True to upload despite any warnings.
+ file_size (int): Deprecated in mwclient 0.7
+ url (str): URL to fetch the file from.
+ filekey (str): Key that identifies a previous upload that was
stashed temporarily.
- - comment : Upload comment. Also used as the initial page text
+ comment (str): Upload comment. Also used as the initial page text
for new files if `description` is not specified.
- Note that one of `file`, `filekey` and `url` must be specified, but not more
- than one. For normal uploads, you specify `file`.
-
Example:
- >>> client.upload(open('somefile', 'rb'), filename='somefile.jpg',
- description='Some description')
+ >>> client.upload(open('somefile', 'rb'), filename='somefile.jpg',
+ description='Some description')
+
+ Returns:
+ JSON result from the API.
+
+ Raises:
+ errors.InsufficientPermission
+ requests.exceptions.HTTPError
"""
if file_size is not None:
@@ -675,6 +685,7 @@ class Site(object):
"""Retrieve blocks as a generator.
Each block is a dictionary containing:
+
- user: the username or IP address of the user
- id: the ID of the block
- timestamp: when the block was added
@@ -755,8 +766,7 @@ class Site(object):
def recentchanges(self, start=None, end=None, dir='older', namespace=None,
prop=None, show=None, limit=None, type=None, toponly=None):
- """
- List recent changes to the wiki, Ã la Special:Recentchanges.
+ """List recent changes to the wiki, Ã la Special:Recentchanges.
"""
kwargs = dict(listing.List.generate_kwargs('rc', start=start, end=end, dir=dir,
namespace=namespace, prop=prop,
@@ -766,9 +776,10 @@ class Site(object):
def revisions(self, revids, prop='ids|timestamp|flags|comment|user',
expandtemplates=False, diffto='prev'):
- """
- Get data about a list of revisions. See also the `Page.revisions()`
- method.
+ """Get data about a list of revisions.
+
+ See also the `Page.revisions()` method.
+
API doc: https://www.mediawiki.org/wiki/API:Revisions
Example: Get revision text for two revisions:
@@ -808,10 +819,11 @@ class Site(object):
return revisions
def search(self, search, namespace='0', what=None, redirects=False, limit=None):
- """
- Perform a full text search.
+ """Perform a full text search.
+
API doc: https://www.mediawiki.org/wiki/API:Search
+ Example:
>>> for result in site.search('prefix:Template:Citation/'):
... print(result.get('title'))
diff --git a/mwclient/listing.py b/mwclient/listing.py
index 2e626e710b90384966d49d0bc09e58087bb72604..421837e687770de4fe7619fac7914b70e7e991d3 100644
--- a/mwclient/listing.py
+++ b/mwclient/listing.py
@@ -225,8 +225,8 @@ class PageList(GeneratorList):
page name, otherwise guess the namespace from the name using
`self.guess_namespace`.
- :rtype: One of Category, Image, or Page (default), according
- to the namespace.
+ Returns:
+ One of Category, Image or Page (default), according to namespace.
"""
if self.namespace != 0:
full_page_name = u"{namespace}:{name}".format(
@@ -255,8 +255,11 @@ class PageList(GeneratorList):
If name starts with any of the site's namespaces' names or
default_namespaces, use that. Else, return zero.
- :param name: The pagename as a string (having `.startswith`)
- :return: the id of the guessed namespace or zero.
+ Args:
+ name (str): The pagename as a string (having `.startswith`)
+
+ Returns:
+ The id of the guessed namespace or zero.
"""
for ns in self.site.namespaces:
if ns == 0:
diff --git a/mwclient/page.py b/mwclient/page.py
index dba423b7290385d3349011ae70762dd68ea4e50a..dbba7d573c90a9cb83e156a3826326b93302b33e 100644
--- a/mwclient/page.py
+++ b/mwclient/page.py
@@ -103,9 +103,10 @@ class Page(object):
return title
def can(self, action):
- """
- Check if the current user has the right to carry out some action with the current page.
+ """Check if the current user has the right to carry out some action
+ with the current page.
+ Example:
>>> page.can('edit')
True
@@ -136,8 +137,8 @@ class Page(object):
return self.text(*args, **kwargs)
def text(self, section=None, expandtemplates=False, cache=True):
- """
- Get the current wikitext of the page, or of a specific section.
+ """Get the current wikitext of the page, or of a specific section.
+
If the page does not exist, an empty string is returned. By
default, results will be cached and if you call text() again
with the same section and expandtemplates the result will come
@@ -178,8 +179,7 @@ class Page(object):
return text
def save(self, text, summary=u'', minor=False, bot=True, section=None, **kwargs):
- """
- Update the text of a section or the whole page by performing an edit operation.
+ """Update the text of a section or the whole page by performing an edit operation.
"""
if not self.site.logged_in and self.site.force_login:
# Should we really check for this?
@@ -314,8 +314,7 @@ class Page(object):
# Properties
def backlinks(self, namespace=None, filterredir='all', redirect=False,
limit=None, generator=True):
- """
- List pages that link to the current page, similar to Special:Whatlinkshere.
+ """List pages that link to the current page, similar to Special:Whatlinkshere.
API doc: https://www.mediawiki.org/wiki/API:Backlinks
@@ -334,8 +333,7 @@ class Page(object):
)
def categories(self, generator=True):
- """
- List categories used on the current page.
+ """List categories used on the current page.
API doc: https://www.mediawiki.org/wiki/API:Categories
@@ -348,8 +346,7 @@ class Page(object):
return_values='title')
def embeddedin(self, namespace=None, filterredir='all', limit=None, generator=True):
- """
- List pages that transclude the current page.
+ """List pages that transclude the current page.
API doc: https://www.mediawiki.org/wiki/API:Embeddedin
@@ -374,8 +371,7 @@ class Page(object):
)
def extlinks(self):
- """
- List external links from the current page.
+ """List external links from the current page.
API doc: https://www.mediawiki.org/wiki/API:Extlinks
@@ -383,8 +379,7 @@ class Page(object):
return mwclient.listing.PageProperty(self, 'extlinks', 'el', return_values='*')
def images(self, generator=True):
- """
- List files/images embedded in the current page.
+ """List files/images embedded in the current page.
API doc: https://www.mediawiki.org/wiki/API:Images
@@ -396,8 +391,7 @@ class Page(object):
return_values='title')
def iwlinks(self):
- """
- List interwiki links from the current page.
+ """List interwiki links from the current page.
API doc: https://www.mediawiki.org/wiki/API:Iwlinks
@@ -406,8 +400,7 @@ class Page(object):
return_values=('prefix', '*'))
def langlinks(self, **kwargs):
- """
- List interlanguage links from the current page.
+ """List interlanguage links from the current page.
API doc: https://www.mediawiki.org/wiki/API:Langlinks
@@ -417,8 +410,7 @@ class Page(object):
**kwargs)
def links(self, namespace=None, generator=True, redirects=False):
- """
- List links to other pages from the current page.
+ """List links to other pages from the current page.
API doc: https://www.mediawiki.org/wiki/API:Links
@@ -439,8 +431,7 @@ class Page(object):
prop='ids|timestamp|flags|comment|user',
expandtemplates=False, section=None,
diffto=None):
- """
- List revisions of the current page.
+ """List revisions of the current page.
API doc: https://www.mediawiki.org/wiki/API:Revisions
@@ -478,8 +469,7 @@ class Page(object):
**kwargs)
def templates(self, namespace=None, generator=True):
- """
- List templates used on the current page.
+ """List templates used on the current page.
API doc: https://www.mediawiki.org/wiki/API:Templates