jenkins-bot has submitted this change and it was merged.

Change subject: Fix docstrings and PEP257 ......................................................................

Fix docstrings and PEP257

Change-Id: I3406bee8df5c244703f744b9dd83b953af983517 --- M pywikibot/data/api.py 1 file changed, 42 insertions(+), 20 deletions(-)

Approvals: John Vandenberg: Looks good to me, but someone else must approve Xqt: Looks good to me, approved jenkins-bot: Verified

diff --git a/pywikibot/data/api.py b/pywikibot/data/api.py index 2bdb78a..efe88b3 100644 --- a/pywikibot/data/api.py +++ b/pywikibot/data/api.py @@ -47,7 +47,9 @@

class APIError(pywikibot.Error): + """The wiki site returned an error message.""" + def __init__(self, code, info, **kwargs): """Save error dict returned by MW API.""" self.code = code @@ -67,6 +69,7 @@

class Request(MutableMapping): + """A request to a Site's api.php interface.

Attributes of this object (except for the special parameters listed @@ -121,6 +124,7 @@ @param format: (optional) Defaults to "json"

""" + def __init__(self, **kwargs): try: self.site = kwargs.pop("site") @@ -277,7 +281,7 @@ def submit(self): """Submit a query and parse the response.

- @return: The data retrieved from api.php (a dict) + @return: a dict containing data retrieved from api.php

""" while True: @@ -469,7 +473,10 @@

class CachedRequest(Request): def __init__(self, expiry, *args, **kwargs): - """ expiry should be either a number of days or a datetime.timedelta object """ + """Construct a CachedRequest object. + + @param expiry: either a number of days or a datetime.timedelta object + """ super(CachedRequest, self).__init__(*args, **kwargs) if not isinstance(expiry, datetime.timedelta): expiry = datetime.timedelta(expiry) @@ -479,7 +486,7 @@

@staticmethod def _get_cache_dir(): - """The base directory path for cache entries. + """Return the base directory path for cache entries.

The directory will be created if it does not already exist.

@@ -508,11 +515,12 @@ return dir

def _uniquedescriptionstr(self): - """ Unique description for the cache entry. + """Return unique description for the cache entry.

If this is modified, please also update scripts/maintenance/cache.py to support - the new key and all previous keys. """ + the new key and all previous keys. + """

login_status = self.site._loginstatus

@@ -544,7 +552,7 @@ return dt + self.expiry < datetime.datetime.now()

def _load_cache(self): - """ Return whether the cache can be used """ + """Return whether the cache can be used.""" try: with open(self._cachefile_path(), 'rb') as f: uniquedescr, self._data, self._cachetime = pickle.load(f) @@ -561,7 +569,7 @@ return False

def _write_cache(self, data): - """ writes data to self._cachefile_path() """ + """Write data to self._cachefile_path().""" data = [self._uniquedescriptionstr(), data, datetime.datetime.now()] with open(self._cachefile_path(), 'wb') as f: pickle.dump(data, f) @@ -575,6 +583,7 @@

class QueryGenerator(object): + """Base class for iterators that handle responses to API action=query.

By default, the iterator will iterate each item in the query response, @@ -590,11 +599,12 @@ links. See the API documentation for specific query options.

""" + def __init__(self, **kwargs): - """ - Constructor: kwargs are used to create a Request object; - see that object's documentation for values. 'action'='query' is - assumed. + """Construct a QueryGenerator object. + + kwargs are used to create a Request object; see that object's + documentation for values. 'action'='query' is assumed.

""" if "action" in kwargs and kwargs["action"] != "query": @@ -644,7 +654,7 @@ def __modules(self): """ Instance cache: hold the query data for paraminfo on - querymodule=self.module at self.site + querymodule=self.module at self.site.

""" if not hasattr(self.site, "_modules"): @@ -653,13 +663,13 @@

@__modules.deleter def __modules(self): - """Delete the instance cache - maybe we don't need it""" + """Delete the instance cache - maybe we don't need it.""" if hasattr(self.site, "_modules"): del self.site._modules

@property def _modules(self): - """Query api on self.site for paraminfo on querymodule=self.module""" + """Query api on self.site for paraminfo on querymodule=self.module.""" if not set(self.module.split('|')) <= set(self.__modules.keys()): paramreq = CachedRequest(expiry=config.API_config_expiry, site=self.site, action="paraminfo", @@ -711,7 +721,7 @@ self.limit = int(value)

def update_limit(self): - """Set query limit for self.module based on api response""" + """Set query limit for self.module based on api response."""

for mod in self.module.split('|'): for param in self._modules[mod].get("parameters", []): @@ -745,7 +755,7 @@ return

def __iter__(self): - """Submit request and iterate the response based on self.resultkey + """Submit request and iterate the response based on self.resultkey.

Continues response as needed until limit (if any) is reached.

@@ -857,13 +867,15 @@

class PageGenerator(QueryGenerator): + """Iterator for response to a request of type action=query&generator=foo.

This class can be used for any of the query types that are listed in the - API documentation as being able to be used as a generator. Instances of + API documentation as being able to be used as a generator. Instances of this class iterate Page objects.

""" + def __init__(self, generator, g_content=False, **kwargs): """ Required and optional parameters are as for C{Request}, except that @@ -905,6 +917,7 @@

class CategoryPageGenerator(PageGenerator): + """Like PageGenerator, but yields Category objects instead of Pages."""

def result(self, pagedata): @@ -913,6 +926,7 @@

class ImagePageGenerator(PageGenerator): + """Like PageGenerator, but yields ImagePage objects instead of Pages."""

def result(self, pagedata): @@ -924,7 +938,8 @@

class PropertyGenerator(QueryGenerator): - """Iterator for queries of type action=query&property=... + + """Iterator for queries of type action=query&prop=...

See the API documentation for types of page properties that can be queried. @@ -936,12 +951,13 @@ be supplied when instantiating this class).

""" + def __init__(self, prop, **kwargs): """ Required and optional parameters are as for C{Request}, except that action=query is assumed and prop is required.

- @param prop: the "property=" type from api.php + @param prop: the "prop=" type from api.php @type prop: str

""" @@ -950,6 +966,7 @@

class ListGenerator(QueryGenerator): + """Iterator for queries of type action=query&list=...

See the API documentation for types of lists that can be queried. Lists @@ -963,6 +980,7 @@ returned information into a Page object.

""" + def __init__(self, listaction, **kwargs): """ Required and optional parameters are as for C{Request}, except that @@ -976,10 +994,12 @@

class LogEntryListGenerator(ListGenerator): + """ Like ListGenerator, but specialized for listaction="logevents" : yields LogEntry objects instead of dicts. """ + def __init__(self, logtype=None, **kwargs): ListGenerator.__init__(self, "logevents", **kwargs)

@@ -991,13 +1011,15 @@

class LoginManager(login.LoginManager): + """Supply getCookie() method to use API interface.""" + def getCookie(self, remember=True, captchaId=None, captchaAnswer=None): """Login to the site.

Parameters are all ignored.

- Returns cookie data if successful, None otherwise. + @return: cookie data if successful, None otherwise.

""" if hasattr(self, '_waituntil'):