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

Change subject: Epydoc syntax issues ......................................................................

Epydoc syntax issues

Change-Id: I368c3588e022900c494008f98e33df4fc876feed --- M pywikibot/__init__.py M pywikibot/bot.py M pywikibot/comms/http.py M pywikibot/comms/threadedhttp.py M pywikibot/config2.py M pywikibot/data/api.py M pywikibot/data/wikidataquery.py M pywikibot/date.py M pywikibot/diff.py M pywikibot/editor.py M pywikibot/exceptions.py M pywikibot/family.py M pywikibot/i18n.py M pywikibot/logentries.py M pywikibot/page.py M pywikibot/pagegenerators.py M pywikibot/site.py M pywikibot/textlib.py M pywikibot/tools.py M pywikibot/userinterfaces/gui.py M pywikibot/userinterfaces/terminal_interface_base.py M pywikibot/weblib.py 22 files changed, 331 insertions(+), 287 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/__init__.py b/pywikibot/__init__.py index c1e0e79..e20d7c4 100644 --- a/pywikibot/__init__.py +++ b/pywikibot/__init__.py @@ -271,13 +271,13 @@

In small angle approximation (and thus in radians):

- Δλ ≈ Δpos / r_φ, where r_φ is the radius of earth at the given latitude. + M{Δλ ≈ Δpos / r_φ}, where r_φ is the radius of earth at the given latitude. Δλ is the error in longitude.

- r_φ = r cos φ, where r is the radius of earth, φ the latitude + M{r_φ = r cos φ}, where r is the radius of earth, φ the latitude

- Therefore: - precision = math.degrees(self._dim/(radius*math.cos(math.radians(self.lat)))) + Therefore:: + precision = math.degrees(self._dim/(radius*math.cos(math.radians(self.lat)))) """ if not self._precision: radius = 6378137 # TODO: Support other globes diff --git a/pywikibot/bot.py b/pywikibot/bot.py index caafaca..7b100e1 100644 --- a/pywikibot/bot.py +++ b/pywikibot/bot.py @@ -122,12 +122,12 @@ r""" Convert exception trace to unicode if necessary.

- Make sure that the exception trace is converted to unicode: - * our pywikibot.Error traces are encoded in our - console encoding, which is needed for plainly printing them. - * but when it comes to logging using logging.exception, - the Python logging module will try to use these traces, - and it will fail if they are console encoded strings. + Make sure that the exception trace is converted to unicode. + + L{exceptions.Error} traces are encoded in our console encoding, which + is needed for plainly printing them. However, when logging them + using logging.exception, the Python logging module will try to use + these traces, and it will fail if they are console encoded strings.

Formatter.formatException also strips the trailing \n, which we need. """ @@ -165,9 +165,6 @@ This function must be called before using pywikibot.output(); and must be called again if the destination stream is changed.

- @param strm: Output stream. If None, re-uses the last stream if one - was defined, otherwise uses sys.stderr - Note: this function is called by handleArgs(), so it should normally not need to be called explicitly

@@ -175,18 +172,24 @@ Each type of output is handled by an appropriate handler object. This structure is used to permit eventual development of other user interfaces (GUIs) without modifying the core bot code. + The following output levels are defined: - DEBUG - only for file logging; debugging messages - STDOUT - output that must be sent to sys.stdout (for bots that may - have their output redirected to a file or other destination) - VERBOSE - optional progress information for display to user - INFO - normal (non-optional) progress information for display to user - INPUT - prompts requiring user response - WARN - user warning messages - ERROR - user error messages - CRITICAL - fatal error messages + - DEBUG: only for file logging; debugging messages. + - STDOUT: output that must be sent to sys.stdout (for bots that may + have their output redirected to a file or other destination). + - VERBOSE: optional progress information for display to user. + - INFO: normal (non-optional) progress information for display to user. + - INPUT: prompts requiring user response. + - WARN: user warning messages. + - ERROR: user error messages. + - CRITICAL: fatal error messages. + Accordingly, do ''not'' use print statements in bot code; instead, use pywikibot.output function. + + @param strm: Output stream. If None, re-uses the last stream if one + was defined, otherwise uses sys.stderr + """ global _handlers_initialized

@@ -464,18 +467,21 @@ def exception(msg=None, decoder=None, newline=True, tb=False, **kwargs): """Output an error traceback to the user via the userinterface.

- @param tb: Set to True in order to output traceback also. + Use directly after an 'except' statement::

- Use directly after an 'except' statement: - ... - except: - pywikibot.exception() - ... - or alternatively: - ... - except Exception as e: - pywikibot.exception(e) - ... + ... + except: + pywikibot.exception() + ... + + or alternatively:: + + ... + except Exception as e: + pywikibot.exception(e) + ... + + @param tb: Set to True in order to output traceback also. """ if isinstance(msg, BaseException): exc_info = 1 @@ -494,14 +500,12 @@ def input(question, password=False): """Ask the user a question, return the user's answer.

- Parameters: - * question - a unicode string that will be shown to the user. Don't add a - space after the question mark/colon, this method will do this - for you. - * password - if True, hides the user's input (for password entry). - - Returns a unicode string. - + @param question: a string that will be shown to the user. Don't add a + space after the question mark/colon, this method will do this for you. + @type question: unicode + @param password: if True, hides the user's input (for password entry). + @type password: bool + @rtype: unicode """ # make sure logging system has been initialized if not _handlers_initialized: @@ -517,7 +521,7 @@ Ask the user the question and return one of the valid answers.

@param question: The question asked without trailing spaces. - @type answers: basestring + @type question: basestring @param answers: The valid answers each containing a full length answer and a shortcut. Each value must be unique. @type answers: Iterable containing an iterable of length two @@ -549,7 +553,7 @@ Ask the user a yes/no question and returns the answer as a bool.

@param question: The question asked without trailing spaces. - @type answers: basestring + @type question: basestring @param default: The result if no answer was entered. It must be a bool or 'y' or 'n' and can be disabled by setting it to None. @type default: basestring or bool @@ -581,17 +585,16 @@ The user's input will be case-insensitive, so the hotkeys should be distinctive case-insensitively.

- Parameters: - * question - a unicode string that will be shown to the user. Don't add a - space after the question mark, this method will do this - for you. - * answers - a list of strings that represent the options. - * hotkeys - a list of one-letter strings, one for each answer. - * default - an element of hotkeys, or None. The default choice that will + @param question: a string that will be shown to the user. Don't add a + space after the question mark/colon, this method will do this for you. + @type question: basestring + @param answers: a list of strings that represent the options. + @type answers: list of basestring + @param hotkeys: a list of one-letter strings, one for each answer. + @param default: an element of hotkeys, or None. The default choice that will be returned when the user just presses Enter. - - Returns a one-letter string in lowercase. - + @return: a one-letter string in lowercase. + @rtype: str """ # make sure logging system has been initialized if not _handlers_initialized: @@ -609,6 +612,7 @@ This is required because the -help option loads the module's docstring and because the module name will be used for the filename of the log.

+ @rtype: unicode """ # get commandline arguments called = pywikibot.argvu[0].strip() @@ -986,14 +990,14 @@ and puts the page if needed.

Option used: - * 'always' + * 'always'

Keyword args used: - * 'async' - passed to page.save - * 'comment' - passed to page.save - * 'show_diff' - show changes between oldtext and newtext (enabled) - * 'ignore_save_related_errors' - report and ignore (disabled) - * 'ignore_server_errors' - report and ignore (disabled) + * 'async' - passed to page.save + * 'comment' - passed to page.save + * 'show_diff' - show changes between oldtext and newtext (enabled) + * 'ignore_save_related_errors' - report and ignore (disabled) + * 'ignore_server_errors' - report and ignore (disabled) """ if oldtext == newtext: pywikibot.output(u'No changes were needed on %s' diff --git a/pywikibot/comms/http.py b/pywikibot/comms/http.py index 92eeb5d..660e597 100644 --- a/pywikibot/comms/http.py +++ b/pywikibot/comms/http.py @@ -219,7 +219,7 @@ used for requests to non wiki pages.

@param site: The Site to connect to - @type site: L{pywikibot.site.Site} + @type site: L{pywikibot.site.BaseSite} @param uri: the URI to retrieve @type uri: str @return: The received data (a unicode string). diff --git a/pywikibot/comms/threadedhttp.py b/pywikibot/comms/threadedhttp.py index a34de00..32e55bd 100644 --- a/pywikibot/comms/threadedhttp.py +++ b/pywikibot/comms/threadedhttp.py @@ -140,13 +140,13 @@ """ Constructor.

- @param cookiejar: (optional) CookieJar to use. A new one will be + @kwarg cookiejar: (optional) CookieJar to use. A new one will be used when not supplied. - @param connection_pool: (optional) Connection pool to use. A new one + @kwarg connection_pool: (optional) Connection pool to use. A new one will be used when not supplied. - @param max_redirects: (optional) The maximum number of redirects to + @kwarg max_redirects: (optional) The maximum number of redirects to follow. 5 is default. - @param timeout: (optional) Socket timeout in seconds. Default is + @kwarg timeout: (optional) Socket timeout in seconds. Default is config.socket_timeout. Disable with None.

""" diff --git a/pywikibot/config2.py b/pywikibot/config2.py index 7316d9f..18ea59c 100644 --- a/pywikibot/config2.py +++ b/pywikibot/config2.py @@ -4,14 +4,14 @@

Provides two family class methods which can be used in the user-config: -- register_family_file -- register_families_folder + - register_family_file + - register_families_folder

Sets module global base_dir and provides utility methods to build paths relative to base_dir: -- makepath -- datafilepath -- shortpath + - makepath + - datafilepath + - shortpath """ # # (C) Rob W.W. Hooft, 2003 @@ -136,16 +136,16 @@ def get_base_dir(test_directory=None): r"""Return the directory in which user-specific information is stored.

- This is determined in the following order - - 1. If the script was called with a -dir: argument, use the directory - provided in this argument - 2. If the user has a PYWIKIBOT2_DIR environment variable, use the value - of it - 3. If user-config presents in current directory, use the current directory - 4. Use (and if necessary create) a 'pywikibot' folder under - 'Application Data' or 'AppData\Roaming' (Windows) or - '.pywikibot' directory (Unix and similar) under the user's home - directory. + This is determined in the following order: + 1. If the script was called with a -dir: argument, use the directory + provided in this argument + 2. If the user has a PYWIKIBOT2_DIR environment variable, use the value + of it + 3. If user-config presents in current directory, use the current directory + 4. Use (and if necessary create) a 'pywikibot' folder under + 'Application Data' or 'AppData\Roaming' (Windows) or + '.pywikibot' directory (Unix and similar) under the user's home + directory.

Set PYWIKIBOT2_NO_USER_CONFIG=1 to disable loading user-config.py

@@ -153,6 +153,7 @@ directory. Used to test whether placing a user config file in this directory will cause it to be selected as the base directory. @type test_directory: str or None + @rtype: unicode """ def exists(directory): directory = os.path.abspath(directory) @@ -708,12 +709,11 @@ def makepath(path): """Return a normalized absolute version of the path argument.

- - if the given path already exists in the filesystem - the filesystem is not modified. - - - otherwise makepath creates directories along the given path - using the dirname() of the path. You may append - a '/' to the path if you want it to be a directory path. + - if the given path already exists in the filesystem + the filesystem is not modified. + - otherwise makepath creates directories along the given path + using the dirname() of the path. You may append + a '/' to the path if you want it to be a directory path.

from holger@trillke.net 2002/03/18

diff --git a/pywikibot/data/api.py b/pywikibot/data/api.py index eb97667..6389e5c 100644 --- a/pywikibot/data/api.py +++ b/pywikibot/data/api.py @@ -203,22 +203,24 @@ >>> sorted(data[u'query'].keys()) # doctest: +IGNORE_UNICODE ['namespaces', 'userinfo']

- @param site: The Site to which the request will be submitted. If not - supplied, uses the user's configured default Site. - @param mime: If true, send in "multipart/form-data" format (default False) - @param mime_params: A dictionary of parameter which should only be - transferred via mime mode. If not None sets mime to True. - @param max_retries: (optional) Maximum number of times to retry after - errors, defaults to 25 - @param retry_wait: (optional) Minimum time to wait after an error, - defaults to 5 seconds (doubles each retry until max of 120 is - reached) - @param format: (optional) Defaults to "json" - """

def __init__(self, **kwargs): - """Constructor.""" + """ + Constructor. + + @kwarg site: The Site to which the request will be submitted. If not + supplied, uses the user's configured default Site. + @kwarg mime: If true, send in "multipart/form-data" format (default False) + @kwarg mime_params: A dictionary of parameter which should only be + transferred via mime mode. If not None sets mime to True. + @kwarg max_retries: (optional) Maximum number of times to retry after + errors, defaults to 25 + @kwarg retry_wait: (optional) Minimum time to wait after an error, + defaults to 5 seconds (doubles each retry until max of 120 is + reached) + @kwarg format: (optional) Defaults to "json" + """ try: self.site = kwargs.pop("site") except KeyError: @@ -1402,11 +1404,11 @@ @type page: Page @param pagedict: the contents of a "page" element of a query response @type pagedict: dict - @param prop: the property names which resulted in pagedict. If a missing + @param props: the property names which resulted in pagedict. If a missing value in pagedict can indicate both 'false' and 'not present' the property which would make the value present must be in the props parameter. - @type prop: iterable of string + @type props: iterable of string """ if "pageid" in pagedict: page._pageid = int(pagedict['pageid']) diff --git a/pywikibot/data/wikidataquery.py b/pywikibot/data/wikidataquery.py index 7a0626b..c3eaf35 100644 --- a/pywikibot/data/wikidataquery.py +++ b/pywikibot/data/wikidataquery.py @@ -56,8 +56,8 @@ Add to this QuerySet using the given joiner.

If the given joiner is not the same as we used before in - this QuerySet, nest the current one in parens before joining - - this makes the implicit grouping of the API explicit. + this QuerySet, nest the current one in parens before joining. + This makes the implicit grouping of the API explicit.

@return: a new query set representing the joining of this one and the arguments @@ -208,10 +208,10 @@

The resulting IDs may be used in query strings.

- @param item A single item. One of ItemPages, PropertyPages, int - or anything that can be fed to int() + @param item: A single item. One of ItemPages, PropertyPages, int + or anything that can be fed to int()

- @return the int ID of the item + @return: the int ID of the item """ if isinstance(item, ItemPage) or isinstance(item, PropertyPage): return item.getID(numeric=True) @@ -307,9 +307,9 @@ """ Constructor.

- @param item The root item - @param forward List of forward properties, can be empty - @param reverse List of reverse properties, can be empty + @param item: The root item + @param forward: List of forward properties, can be empty + @param reverse: List of reverse properties, can be empty """ # check sensible things coming in, as we lose info once we do # type conversion @@ -367,9 +367,9 @@ You have to give prop and one of begin or end. Note that times have to be in UTC, timezones are not supported by the API

- @param prop the property - @param begin WbTime object representign the beginning of the period - @param end WbTime object representing the end of the period + @param prop: the property + @param begin: WbTime object representign the beginning of the period + @param end: WbTime object representing the end of the period """

queryType = "between" @@ -474,7 +474,7 @@ """ Get the query string for a given query or queryset.

- @return query string including labels and props + @return: string including labels and props """ qStr = "q=%s" % quote(str(q))

@@ -499,7 +499,7 @@ """ Load the query result from the cache, if possible.

- Returns None if the data is not there or if it is too old. + @return: None if the data is not there or if it is too old. """ if self.cacheMaxAge <= 0: return None @@ -527,7 +527,7 @@ """ Save data from a query to a cache file, if enabled.

- No return value. + @rtype: None """ if self.cacheMaxAge <= 0: return @@ -575,7 +575,7 @@ """ Actually run a query over the API.

- @return Python dict of the interpreted JSON or None on failure + @return: dict of the interpreted JSON or None on failure """ fullQueryString = self.getQueryString(q, labels, props)

diff --git a/pywikibot/date.py b/pywikibot/date.py index 94f1dc7..350bdf7 100644 --- a/pywikibot/date.py +++ b/pywikibot/date.py @@ -188,13 +188,16 @@ """This function helps in simple list value matching.

!!!!! The index starts at 1, so 1st element has index 1, not 0 !!!!! - Usually it will be used as a lambda call in a map: - lambda v: slh(v, [u'January',u'February',...])

- Usage scenarios: - formats['MonthName']['en'](1) => u'January' - formats['MonthName']['en'](u'January') => 1 - formats['MonthName']['en'](u'anything else') => raise ValueError + Usually it will be used as a lambda call in a map:: + + lambda v: slh(v, [u'January',u'February',...]) + + Usage scenarios:: + + formats['MonthName']['en'](1) => u'January' + formats['MonthName']['en'](u'January') => 1 + formats['MonthName']['en'](u'anything else') => raise ValueError

""" if isinstance(value, basestring): @@ -400,23 +403,26 @@ def dh(value, pattern, encf, decf, filter=None): """This function helps in year parsing.

- Usually it will be used as a lambda call in a map: - lambda v: dh(v, u'pattern string', encodingFunc, decodingFunc) + Usually it will be used as a lambda call in a map::

- encodingFunc: + lambda v: dh(v, u'pattern string', encf, decf) + + @param encf: Converts from an integer parameter to another integer or a tuple of integers. Depending on the pattern, each integer will be converted to a proper string representation, and will be passed as a format argument - to the pattern: - pattern % encodingFunc(value) - This function is a complement of decodingFunc. + to the pattern::

- decodingFunc: + pattern % encf(value) + + This function is a complement of decf. + + @param decf: Converts a tuple/list of non-negative integers found in the original value string into a normalized value. The normalized value can be passed right back into dh() to produce the original string. This function is a complement - of encodingFunc. dh() interprets %d as a decimal and %s as a roman + of encf. dh() interprets %d as a decimal and %s as a roman numeral number.

""" diff --git a/pywikibot/diff.py b/pywikibot/diff.py index e7bffe2..7773b7e 100644 --- a/pywikibot/diff.py +++ b/pywikibot/diff.py @@ -22,10 +22,6 @@

"""One change hunk between a and b.

- a and b: two sequences of lines. - grouped_opcode: list of 5-tuples describing how to turn a into b. - it has the same format as returned by difflib.get_opcodes(). - Note: parts of this code are taken from by difflib.get_grouped_opcodes().

""" @@ -35,6 +31,15 @@ PENDING = 0

def __init__(self, a, b, grouped_opcode): + """ + Constructor. + + @param a: sequence of lines + @param b: sequence of lines + @param grouped_opcode: list of 5-tuples describing how to turn a into b. + it has the same format as returned by difflib.get_opcodes(). + + """ self.a = a self.b = b self.group = grouped_opcode @@ -203,7 +208,8 @@ def get_blocks(self): """Return list with blocks of indexes which compose a and, where applicable, b.

- Format of each block: + Format of each block:: + [-1, (i1, i2), (-1, -1)] -> block a[i1:i2] does not change from a to b then is there is no corresponding hunk. [hunk index, (i1, i2), (j1, j2)] -> block a[i1:i2] becomes b[j1:j2] diff --git a/pywikibot/editor.py b/pywikibot/editor.py index 0ab7de1..fd00b12 100644 --- a/pywikibot/editor.py +++ b/pywikibot/editor.py @@ -77,15 +77,17 @@ """ Call the editor and thus allows the user to change the text.

- Returns the modified text. Halts the thread's operation until the editor - is closed. + Halts the thread's operation until the editor is closed.

- Returns None if the user didn't save the text file in his text editor. - - Parameters: - * text - a Unicode string - * jumpIndex - an integer: position at which to put the caret - * highlight - a substring; each occurence will be highlighted + @param text: the text to be edited + @type text: unicode + @param jumpIndex: position at which to put the caret + @type jumpIndex: int + @param highlight: each occurence of this substring will be highlighted + @type highlight: unicode + @return: the modified text, or None if the user didn't save the text + file in his text editor + @rtype: unicode or None """ text = self.convertLinebreaks(text) if config.editor: diff --git a/pywikibot/exceptions.py b/pywikibot/exceptions.py index 90b2e5c..298ef6c 100644 --- a/pywikibot/exceptions.py +++ b/pywikibot/exceptions.py @@ -24,8 +24,8 @@ - CircularRedirect: Page is a circular redirect - SectionError: The section specified by # does not exist

-PageSaveRelatedError: page exceptions within the save operation on a Page. - (alias: PageNotSaved) +PageSaveRelatedError: page exceptions within the save operation on a Page +(alias: PageNotSaved). - SpamfilterError: MediaWiki spam filter detected a blacklisted URL - OtherPageSaveError: misc. other save related exception. - LockedPage: Page is locked diff --git a/pywikibot/family.py b/pywikibot/family.py index 645138a..9275f60 100644 --- a/pywikibot/family.py +++ b/pywikibot/family.py @@ -1030,10 +1030,10 @@ """ Return a regex matching the path after the domain.

- It is using L{Family.path} and L{Family.nicepath} with code set to - 'None'. If that returns a KeyError (L{Family.scriptpath} probably + It is using L{path} and L{nicepath} with code set to + 'None'. If that returns a KeyError (L{scriptpath} probably using the C{langs} dictionary) it retries it with the key from - L{Family.langs} if it only contains one entry and throws an Error + C{langs} if it only contains one entry and throws an Error otherwise. In that case the Family instance should overwrite this method or supply code independent methods.

diff --git a/pywikibot/i18n.py b/pywikibot/i18n.py index 7e5b2db..1e2fda9 100644 --- a/pywikibot/i18n.py +++ b/pywikibot/i18n.py @@ -33,10 +33,6 @@ def _altlang(code): """Define fallback languages for particular languages.

- @param code The language code - @type code string - @return a list of strings as language codes - If no translation is available to a specified language, translate() will try each of the specified fallback languages, in order, until it finds one with a translation, with 'en' and '_default' as a last resort. @@ -46,6 +42,10 @@

This code is used by other translating methods below.

+ @param code: The language code + @type code: string + @return: language codes + @rtype: list of str """ # Akan if code in ['ak', 'tw']: @@ -278,18 +278,6 @@ def translate(code, xdict, parameters=None, fallback=False): """Return the most appropriate translation from a translation dict.

- @param code The language code - @type code string or Site object - @param xdict dictionary with language codes as keys or extended dictionary - with family names as keys containing language dictionaries or - a single (unicode) string. May contain PLURAL tags as described - in twntranslate - @type xdict dict, string, unicode - @param parameters For passing (plural) parameters - @type parameters dict, string, unicode, int - @param fallback Try an alternate language code - @type fallback boolean - Given a language code and a dictionary, returns the dictionary's value for key 'code' if this key exists; otherwise tries to return a value for an alternative language that is most applicable to use on the wiki in @@ -301,6 +289,18 @@ list.

For PLURAL support have a look at the twntranslate method + + @param code: The language code + @type code: string or Site object + @param xdict: dictionary with language codes as keys or extended dictionary + with family names as keys containing language dictionaries or + a single (unicode) string. May contain PLURAL tags as + described in twntranslate + @type xdict: dict, string, unicode + @param parameters: For passing (plural) parameters + @type parameters: dict, string, unicode, int + @param fallback: Try an alternate language code + @type fallback: boolean

""" family = pywikibot.config.family @@ -405,32 +405,31 @@ def twntranslate(code, twtitle, parameters=None): r"""Translate a message with plural support.

- @param code: The language code - @param twtitle: The TranslateWiki string title, in <package>-<key> format - @param parameters: For passing (plural) parameters. - Support is implemented like in MediaWiki extension. If the TranslateWiki - message contains a plural tag inside which looks like - {{PLURAL:<number>|<variant1>|<variant2>[|<variantn>]}} + message contains a plural tag inside which looks like:: + + {{PLURAL:<number>|<variant1>|<variant2>[|<variantn>]}} + it takes that variant calculated by the plural_rules depending on the number value. Multiple plurals are allowed.

- Examples: - If we had a test dictionary in test.py like - msg = { - 'en': { - # number value as format sting is allowed - 'test-plural': u'Bot: Changing %(num)s {{PLURAL:%(num)d|page|pages}}.', - }, - 'nl': { - # format sting inside PLURAL tag is allowed - 'test-plural': u'Bot: Pas {{PLURAL:num|1 pagina|%(num)d pagina's}} aan.', - }, - 'fr': { - # additional sting inside or outside PLURAL tag is allowed - 'test-plural': u'Robot: Changer %(descr)s {{PLURAL:num|une page|quelques pages}}.', - }, - } + As an examples, if we had a test dictionary in test.py like:: + + msg = { + 'en': { + # number value as format sting is allowed + 'test-plural': u'Bot: Changing %(num)s {{PLURAL:%(num)d|page|pages}}.', + }, + 'nl': { + # format sting inside PLURAL tag is allowed + 'test-plural': u'Bot: Pas {{PLURAL:num|1 pagina|%(num)d pagina's}} aan.', + }, + 'fr': { + # additional sting inside or outside PLURAL tag is allowed + 'test-plural': u'Robot: Changer %(descr)s {{PLURAL:num|une page|quelques pages}}.', + }, + } + >>> from pywikibot import i18n >>> i18n.messages_package_name = 'tests.i18n' >>> # use a number @@ -452,6 +451,11 @@

The translations are retrieved from i18n.<package>, based on the callers import table. + + @param code: The language code + @param twtitle: The TranslateWiki string title, in <package>-<key> format + @param parameters: For passing (plural) parameters. + """ # If a site is given instead of a code, use its language if hasattr(code, 'code'): diff --git a/pywikibot/logentries.py b/pywikibot/logentries.py index cdfe41b..5a71ad9 100644 --- a/pywikibot/logentries.py +++ b/pywikibot/logentries.py @@ -103,9 +103,10 @@ """ Return the blocked account or IP.

- * Returns the Page object of username or IP - if this block action targets a username or IP. - * Returns the blockid if this log reflects the removal of an autoblock + @return: the Page object of username or IP if this block action + targets a username or IP, or the blockid if this log reflects + the removal of an autoblock + @rtype: Page or int """ # TODO what for IP ranges ? if self.isAutoblockRemoval: diff --git a/pywikibot/page.py b/pywikibot/page.py index 20519f0..9301a49 100644 --- a/pywikibot/page.py +++ b/pywikibot/page.py @@ -281,7 +281,7 @@ return hash(unicode(self))

def autoFormat(self): - """Return L{date.autoFormat} dictName and value, if any. + """Return L{date.getAutoFormat} dictName and value, if any.

Value can be a year, date, etc., and dictName is 'YearBC', 'Year_December', or another dictionary name. Please note that two @@ -310,12 +310,12 @@ retrieved yet, or if force is True. This can raise the following exceptions that should be caught by the calling code:

- @exception NoPage The page does not exist - @exception IsRedirectPage The page is a redirect. The argument of the - exception is the title of the page it - redirects to. - @exception SectionError The section does not exist on a page with - a # link + @exception NoPage: The page does not exist + @exception IsRedirectPage: The page is a redirect. The argument of the + exception is the title of the page it + redirects to. + @exception SectionError: The section does not exist on a page with + a # link

@param force: reload all page attributes, including errors. @param get_redirect: return the redirect text, do not follow the @@ -637,7 +637,7 @@ Character count ignores language links and category links. Can raise the same exceptions as get().

- @return bool + @rtype: bool """ txt = self.get() txt = textlib.removeLanguageLinks(txt, site=self.site) @@ -699,7 +699,7 @@ 'Template:Disambig' is always assumed to be default, and will be appended regardless of its existence.

- @return: bool + @rtype: bool """ if self.site.has_extension('Disambiguator'): # If the Disambiguator extension is loaded, use it @@ -823,7 +823,7 @@ total=None, content=False): """Return an iterator for pages that embed this page as a template.

- @param filterRedirects: if True, only iterate redirects; if False, + @param filter_redirects: if True, only iterate redirects; if False, omit redirects; if None, do not filter @param namespaces: only iterate pages in these namespaces @param step: limit each API call to this number of pages @@ -1563,19 +1563,21 @@ If no calls have been made since loadDeletedRevisions(), everything will be restored.

- Simplest case: + Simplest case:: + Page(...).undelete('This will restore all revisions')

- More complex: + More complex:: + pg = Page(...) - revs = pg.loadDeletedRevsions() + revs = pg.loadDeletedRevisions() for rev in revs: if ... #decide whether to undelete a revision pg.markDeletedRevision(rev) #mark for undeletion pg.undelete('This will restore only selected revisions.')

@param comment: The undeletion edit summary. - + @type comment: basestring """ if comment is None: pywikibot.output(u'Preparing to undelete %s.' @@ -1663,8 +1665,10 @@ """ Remove page from oldCat and add it to newCat.

- @param oldCat and newCat: should be Category objects. - If newCat is None, the category will be removed. + @param oldCat: category to be removed + @type oldCat: Category + @param newCat: category to be added, if any + @type newCat: Category or None

@param comment: string to use as an edit summary

@@ -1676,9 +1680,10 @@

@param include: list of tags not to be disabled by default in relevant textlib functions, where CategoryLinks can be searched. - @type: list + @type include: list

@return: True if page was saved changed, otherwise False. + @rtype: bool

""" # get list of Category objects the article is in and remove possible @@ -1906,7 +1911,8 @@ def getFileVersionHistory(self): """Return the file's version history.

- @return: A list of dictionaries with the following keys: + @return: A list of dictionaries with the following keys:: + [comment, sha1, url, timestamp, metadata, height, width, mime, user, descriptionurl, size]

@@ -2058,7 +2064,7 @@ @param total: iterate no more than this number of pages in total (at all levels) @param namespaces: only yield pages in the specified namespaces - @type namespace: int or list of ints + @type namespaces: int or list of ints @param content: if True, retrieve the content of the current version of each page (default False) @param sortby: determines the order in which results are generated, @@ -2636,9 +2642,9 @@ @type site: DataSite @param title: normalized title of the page @type title: unicode - @param ns: namespace + @kwarg ns: namespace @type ns: Namespace instance, or int - @param entity_type: Wikibase entity type + @kwarg entity_type: Wikibase entity type @type entity_type: str ('item' or 'property')

@raise TypeError: incorrect use of parameters @@ -2992,10 +2998,10 @@ Edit an entity using Wikibase wbeditentity API.

This function is wrapped around by: - *editLabels - *editDescriptions - *editAliases - *ItemPage.setSitelinks + - editLabels + - editDescriptions + - editAliases + - ItemPage.setSitelinks

@param data: Data to be saved @type data: dict (must be not None for python 2.6; bug 70707) @@ -3137,13 +3143,14 @@ """ Get the ItemPage for a Page that links to it.

- @exception NoPage There is no corresponding ItemPage for the page @param page: Page to look for corresponding data item @type page: pywikibot.Page @param lazy_load: Do not raise NoPage if either page or corresponding ItemPage does not exist. @type lazy_load: bool @return: ItemPage + + @exception NoPage: There is no corresponding ItemPage for the page """ if not page.site.has_transcluded_data: raise pywikibot.WikiBaseError(u'%s has no transcluded data' @@ -3463,7 +3470,8 @@ """ A Wikibase entity in the property namespace.

- Should be created as: + Should be created as:: + PropertyPage(DataSite, 'P21') """

@@ -3674,8 +3682,8 @@ @param value: The new target value. @type value: object

- Raises ValueError if value is not of the type - required for the Claim type. + @exception ValueError: if value is not of the type + required for the Claim type. """ value_class = self.types[self.type] if not isinstance(value, value_class): @@ -3690,7 +3698,7 @@ @param value: The new target value. @type value: object @param snaktype: The new snak type. - @type value: str ('value', 'somevalue', or 'novalue') + @type snaktype: str ('value', 'somevalue', or 'novalue') """ if value: self.setTarget(value) @@ -4298,7 +4306,7 @@ def __unicode__(self): """Return a unicode string representation.

- @return unicode + @return: unicode """ return self.astext()

@@ -4506,8 +4514,8 @@

Uses the first encoding that doesn't cause an error.

- @param data: URL-encoded character data to convert - @type data: str + @param title: URL-encoded character data to convert + @type title: str @param encodings: Encodings to attempt to use during conversion. @type encodings: str, list or Site @return: unicode diff --git a/pywikibot/pagegenerators.py b/pywikibot/pagegenerators.py index 940c630..a1eff4d 100644 --- a/pywikibot/pagegenerators.py +++ b/pywikibot/pagegenerators.py @@ -1098,12 +1098,12 @@ The provided generator must support parameter 'start', 'end', 'reverse', and 'total' such as site.recentchanges(), site.logevents().

- For example: + To fetch revisions in recentchanges in live time::

- To fetch revisions in recentchanges in live time, call gen = RepeatingGenerator(site.recentchanges, lambda x: x['revid'])

- To fetch new pages in live time, call + To fetch new pages in live time:: + gen = RepeatingGenerator(site.newpages, lambda x: x[0])

Note that other parameters not listed below will be passed @@ -1696,7 +1696,8 @@ Yield a list of pages based on a MySQL query.

Each query should provide the page namespace and page title. An example - query that yields all ns0 pages might look like: + query that yields all ns0 pages might look like:: + SELECT page_namespace, page_title, diff --git a/pywikibot/site.py b/pywikibot/site.py index 9cadefe..62a6e05 100644 --- a/pywikibot/site.py +++ b/pywikibot/site.py @@ -118,10 +118,11 @@ """ Namespace site data object.

This is backwards compatible with the structure of entries - in site._namespaces which were a list of - [customised namespace, - canonical namespace name?, - namespace alias*] + in site._namespaces which were a list of:: + + [customised namespace, + canonical namespace name?, + namespace alias*]

If the canonical_name is not provided for a namespace between -2 and 15, the MediaWiki 1.14+ built-in names are used. @@ -944,7 +945,8 @@ def need_version(version): """ Decorator to require a certain MediaWiki version number.

- @param number: the mw version number required + @param version: the mw version number required + @type version: str @return: a decorator to make sure the requirement is satisfied when the decorated function is called. """ @@ -993,10 +995,10 @@ Return the default value for different properties.

If the property is 'restrictions' it returns a dictionary with: - 'cascadinglevels': 'sysop' - 'semiprotectedlevels': 'autoconfirmed' - 'levels': '' (everybody), 'autoconfirmed', 'sysop' - 'types': 'create', 'edit', 'move', 'upload' + - 'cascadinglevels': 'sysop' + - 'semiprotectedlevels': 'autoconfirmed' + - 'levels': '' (everybody), 'autoconfirmed', 'sysop' + - 'types': 'create', 'edit', 'move', 'upload' Otherwise it returns L{pywikibot.tools.EMPTY_DEFAULT}.

@param key: The property name @@ -1943,7 +1945,7 @@ time. It requests to expand the text '{{CURRENTTIMESTAMP}}' for older wikis.

- @return the current server time + @return: the current server time @rtype: L{Timestamp} """ if LV(self.version()) >= LV("1.16"): @@ -2451,12 +2453,12 @@ Most of them were merged into the 'csrf' token. If the token type in the parameter is not known it will default to the 'csrf' token. The other token types available are: - - deleteglobalaccount - - patrol - - rollback - - setglobalaccountstatus - - userrights - - watch + - deleteglobalaccount + - patrol + - rollback + - setglobalaccountstatus + - userrights + - watch

@param types: the types of token (e.g., "edit", "move", "delete"); see API documentation for full list of types @@ -3714,7 +3716,7 @@ * unwatch: remove the page from the watchlist * preferences: use the preference settings (Default) * nochange: don't change the watchlist - @param botflag: if True, mark edit with bot flag + @param bot: if True, mark edit with bot flag @return: True if edit succeeded, False if it failed

""" @@ -4060,7 +4062,7 @@ """ Return the protection types available on this site.

- @return protection types available + @return: protection types available @rtype: set of unicode instances @see: L{Siteinfo._get_default()} """ @@ -4070,7 +4072,7 @@ """ Return the protection levels available on this site.

- @return protection types available + @return: protection types available @rtype: set of unicode instances @see: L{Siteinfo._get_default()} """ @@ -4136,9 +4138,6 @@ "notpatrollable": "The revision %(revid)s can't be patrolled as it's too old." }

- # test it with: - # python -m unittest tests.site_tests.SiteUserTestCase.testPatrol - def patrol(self, rcid=None, revid=None, revision=None): """Return a generator of patrolled pages.

@@ -4158,7 +4157,8 @@ of pages to be patrolled. @type revision: iterable/iterator which returns a Revision object; it also supports a single Revision. - @yield: dict with 'rcid', 'ns' and 'title' of the patrolled page. + @rtype: iterator of dict with 'rcid', 'ns' and 'title' + of the patrolled page.

""" # If patrol is not enabled, attr will be set the first time a diff --git a/pywikibot/textlib.py b/pywikibot/textlib.py index daa4a13..cd23724 100644 --- a/pywikibot/textlib.py +++ b/pywikibot/textlib.py @@ -89,18 +89,17 @@ regex matching. If allowoverlap is true, overlapping occurrences are all replaced (watch out when using this, it might lead to infinite loops!).

- Parameters: - text - a unicode string - old - a compiled or uncompiled regular expression - new - a unicode string (which can contain regular - expression references), or a function which takes - a match object as parameter. See parameter repl of - re.sub(). - exceptions - a list of strings which signal what to leave out, - e.g. ['math', 'table', 'template'] - caseInsensitive - a boolean - marker - a string that will be added to the last replacement; - if nothing is changed, it is added at the end + @type text: unicode + @param old: a compiled or uncompiled regular expression + @param new: a unicode string (which can contain regular + expression references), or a function which takes + a match object as parameter. See parameter repl of + re.sub(). + @param exceptions: a list of strings which signal what to leave out, + e.g. ['math', 'table', 'template'] + @type caseInsensitive: bool + @param marker: a string that will be added to the last replacement; + if nothing is changed, it is added at the end

""" if site is None: @@ -687,7 +686,7 @@

@param include: list of tags which should not be removed by removeDisabledParts() and where CategoryLinks can be searched. - @type: list + @type include: list

@return: all category links found @rtype: list of Category objects @@ -1170,16 +1169,18 @@ """ Determine whether the page text contains the given section title.

+ It does not care whether a section string may contain spaces or + underlines. Both will match. + + If a section parameter contains a internal link, it will match the + section with or without a preceding colon which is required for a + text link e.g. for categories and files. + @param pagetext: The wikitext of a page - @type text: unicode or string + @type pagetext: unicode or string @param section: a section of a page including wikitext markups @type section: unicode or string

- Note: It does not care whether a section string may contain spaces or - underlines. Both will match. - If a section parameter contains a internal link, it will match the - section with or without a preceding colon which is required for a - text link e.g. for categories and files. """ # match preceding colon for text links section = re.sub(r'\[\[(\:)?', '[[:?', re.escape(section)) diff --git a/pywikibot/tools.py b/pywikibot/tools.py index 39f31ca..26d43bd 100644 --- a/pywikibot/tools.py +++ b/pywikibot/tools.py @@ -445,7 +445,7 @@ def deprecated(*args, **kwargs): """Decorator to output a deprecation warning.

- @param instead: if provided, will be used to specify the replacement + @kwarg instead: if provided, will be used to specify the replacement @type instead: string """ def decorator(obj): diff --git a/pywikibot/userinterfaces/gui.py b/pywikibot/userinterfaces/gui.py index d29ac00..85bda15 100644 --- a/pywikibot/userinterfaces/gui.py +++ b/pywikibot/userinterfaces/gui.py @@ -332,10 +332,15 @@ """ Provide user with editor to modify text.

- Parameters: - * text - a Unicode string - * jumpIndex - an integer: position at which to put the caret - * highlight - a substring; each occurence will be highlighted + @param text: the text to be edited + @type text: unicode + @param jumpIndex: position at which to put the caret + @type jumpIndex: int + @param highlight: each occurence of this substring will be highlighted + @type highlight: unicode + @return: the modified text, or None if the user didn't save the text + file in his text editor + @rtype: unicode or None """ self.text = None # put given text into our textarea diff --git a/pywikibot/userinterfaces/terminal_interface_base.py b/pywikibot/userinterfaces/terminal_interface_base.py index e08c50b..5f37e69 100755 --- a/pywikibot/userinterfaces/terminal_interface_base.py +++ b/pywikibot/userinterfaces/terminal_interface_base.py @@ -310,11 +310,15 @@

Uses a Tkinter edit box because we don't have a console editor

- Parameters: - * text - a Unicode string - * jumpIndex - an integer: position at which to put the caret - * highlight - a substring; each occurrence will be highlighted - + @param text: the text to be edited + @type text: unicode + @param jumpIndex: position at which to put the caret + @type jumpIndex: int + @param highlight: each occurence of this substring will be highlighted + @type highlight: unicode + @return: the modified text, or None if the user didn't save the text + file in his text editor + @rtype: unicode or None """ try: import gui diff --git a/pywikibot/weblib.py b/pywikibot/weblib.py index b608e6d..f682fec 100644 --- a/pywikibot/weblib.py +++ b/pywikibot/weblib.py @@ -19,13 +19,13 @@ def getInternetArchiveURL(url, timestamp=None): """Return archived URL by Internet Archive.

- Parameters: - url - url to search an archived version for - timestamp - requested archive date. The version closest to that moment - is returned. Format: YYYYMMDDhhmmss or part thereof. - See [[:mw:Archived Pages]] and https://archive.org/help/wayback_api.php for more details. + + @param url: url to search an archived version for + @param timestamp: requested archive date. The version closest to that + moment is returned. Format: YYYYMMDDhhmmss or part thereof. + """ import json uri = u'https://archive.org/wayback/available?' @@ -47,13 +47,13 @@ def getWebCitationURL(url, timestamp=None): """Return archived URL by Web Citation.

- Parameters: - url - url to search an archived version for - timestamp - requested archive date. The version closest to that moment - is returned. Format: YYYYMMDDhhmmss or part thereof. - See http://www.webcitation.org/doc/WebCiteBestPracticesGuide.pdf for more details + + @param url: url to search an archived version for + @param timestamp: requested archive date. The version closest to that + moment is returned. Format: YYYYMMDDhhmmss or part thereof. + """ import xml.etree.ElementTree as ET uri = u'http://www.webcitation.org/query?'