jenkins-bot has submitted this change and it was merged.
Change subject: [IMPROV] Add additional documentation ......................................................................
[IMPROV] Add additional documentation
This adds a few missing docstrings, so that some files are now not failing the non-voting jenkins test.
Repurposed the tests so that the normal flake8 test is now also doing the docstring tests because the docstrings-mandatory test was doing the normal flake8 tests anyway. The docstrings-mandatory test now contains all files which already pass the non-voting docstrings test.
Change-Id: I213f1d05235a7f242a0776e44d37f8f89a8437c9 --- M pywikibot/site.py M pywikibot/textlib.py M pywikibot/tools.py M pywikibot/userinterfaces/terminal_interface_base.py M pywikibot/userinterfaces/terminal_interface_unix.py M pywikibot/xmlreader.py M tox.ini 7 files changed, 150 insertions(+), 5 deletions(-)
Approvals: John Vandenberg: Looks good to me, approved jenkins-bot: Verified
diff --git a/pywikibot/site.py b/pywikibot/site.py index 8f82568..6e1fbc4 100644 --- a/pywikibot/site.py +++ b/pywikibot/site.py @@ -100,6 +100,7 @@
@classmethod def name(cls, search_value): + """Return the name of a LoginStatus by it's value.""" for key, value in cls.__dict__.items(): if key == key.upper() and value == search_value: return key @@ -107,9 +108,11 @@ % search_value)
def __init__(self, state): + """Constructor.""" self.state = state
def __repr__(self): + """Return internal representation.""" return 'LoginStatus(%s)' % (LoginStatus.name(self.state))
@@ -301,12 +304,15 @@ return Namespace._colons(self.id, self.custom_name)
def __int__(self): + """Return the namespace id.""" return self.id
def __index__(self): + """Return the namespace id.""" return self.id
def __hash__(self): + """Return the namespace id.""" return self.id
def __eq__(self, other): @@ -325,12 +331,15 @@ return not self.__eq__(other)
def __mod__(self, other): + """Apply modulo on the namespace id.""" return self.id.__mod__(other)
def __sub__(self, other): + """Apply subtraction on the namespace id.""" return -(other) + self.id
def __add__(self, other): + """Apply addition on the namespace id.""" return other + self.id
def _cmpkey(self): @@ -560,6 +569,7 @@ return self._username[False]
def username(self, sysop=False): + """Return the username/sysopname used for the site.""" return self._username[sysop]
def __getattr__(self, attr): @@ -853,21 +863,27 @@ # namespace shortcuts for backwards-compatibility
def special_namespace(self): + """Return local name for the Special: namespace.""" return self.namespace(-1)
def image_namespace(self): + """Return local name for the File namespace.""" return self.namespace(6)
def mediawiki_namespace(self): + """Return local name for the MediaWiki namespace.""" return self.namespace(8)
def template_namespace(self): + """Return local name for the Template namespace.""" return self.namespace(10)
def category_namespace(self): + """Return local name for the Category namespace.""" return self.namespace(14)
def category_namespaces(self): + """Return names for the Category namespace.""" return self.namespace(14, all=True)
# site-specific formatting preferences @@ -1300,6 +1316,7 @@ """Container for tokens."""
def __init__(self, site): + """Constructor.""" self.site = site self._tokens = {} self.failed_cache = set() # cache unavailable tokens. @@ -1329,6 +1346,7 @@ self.failed_cache.add((self.site.user(), key))
def __getitem__(self, key): + """Get token value for the given key.""" assert(self.site.user())
user_tokens = self._tokens.setdefault(self.site.user(), {}) @@ -1357,12 +1375,15 @@ .format(key, self.site.user(), self.site))
def __contains__(self, key): + """Return True if the given token name is cached.""" return key in self._tokens.setdefault(self.site.user(), {})
def __str__(self): + """Return a str representation of the internal tokens dictionary.""" return self._tokens.__str__()
def __repr__(self): + """Return a representation of the internal tokens dictionary.""" return self._tokens.__repr__()
@@ -2272,6 +2293,7 @@ self._update_page(page, query, 'loadcoordinfo')
def loadpageprops(self, page): + """Load page props for the given page.""" title = page.title(withSection=False) query = self._generator(api.PropertyGenerator, type_arg="pageprops", @@ -3744,6 +3766,11 @@
@deprecated("Site.randompages()") def randomredirectpage(self): + """ + DEPRECATED: Use Site.randompages() instead. + + @return: Return a random redirect page + """ return self.randompages(total=1, redirects=True)
def randompages(self, step=None, total=10, namespaces=None, @@ -4345,7 +4372,14 @@
@must_be(group='sysop') def unblockuser(self, user, reason): + """ + Remove the block for the user.
+ @param user: The username/IP without a namespace. + @type user: User + @param reason: Reason for the unblock. + @type reason: basestring + """ token = self.tokens['block'] req = api.Request(site=self, action='unblock', user=user.username, reason=reason, token=token) @@ -4691,6 +4725,11 @@ @deprecated("Site().newfiles()") @deprecated_args(number=None, repeat=None) def newimages(self, *args, **kwargs): + """ + Yield information about newly uploaded files. + + DEPRECATED: Use newfiles() instead. + """ return self.newfiles(*args, **kwargs)
@deprecated_args(number=None, repeat=None) @@ -4885,6 +4924,10 @@ @deprecated("Site().unusedfiles()") @deprecated_args(number=None, repeat=None) def unusedimages(self, *args, **kwargs): + """Yield FilePage objects from Special:Unusedimages. + + DEPRECATED: Use L{APISite.unusedfiles} instead. + """ return self.unusedfiles(*args, **kwargs)
@deprecated_args(number=None, repeat=None) diff --git a/pywikibot/textlib.py b/pywikibot/textlib.py index d37f654..530dc70 100644 --- a/pywikibot/textlib.py +++ b/pywikibot/textlib.py @@ -379,7 +379,7 @@
def findmarker(text, startwith=u'@@', append=None): - # find a string which is not part of text + """Find a string which is not part of text.""" if not append: append = u'@' mymarker = startwith @@ -653,8 +653,8 @@ return s
-# Sort sites according to local interwiki sort logic def interwikiSort(sites, insite=None): + """Sort sites according to local interwiki sort logic.""" if not sites: return [] if insite is None: @@ -1241,19 +1241,24 @@ """
def __init__(self, offset, name): + """Constructor.""" self.__offset = datetime.timedelta(minutes=offset) self.__name = name
def utcoffset(self, dt): + """Return the offset to UTC.""" return self.__offset
def tzname(self, dt): + """Return the name of the timezone.""" return self.__name
def dst(self, dt): + """Return no daylight savings time.""" return datetime.timedelta(0)
def __repr__(self): + """Return the internal representation of the timezone.""" return "%s(%s, %s)" % ( self.__class__.__name__, self.__offset.days * 86400 + self.__offset.seconds, @@ -1266,6 +1271,7 @@ """Find timestamp in page and return it as timezone aware datetime object."""
def __init__(self, site=None): + """Constructor.""" if site is None: self.site = pywikibot.Site() else: diff --git a/pywikibot/tools.py b/pywikibot/tools.py index d3112cb..3eaae65 100644 --- a/pywikibot/tools.py +++ b/pywikibot/tools.py @@ -43,9 +43,11 @@
if sys.version_info[0] > 2: def __str__(self): + """Return the unicode representation as the str representation.""" return self.__unicode__() else: def __str__(self): + """Return the str representation of the UTF-8 encoded Unicode.""" return self.__unicode__().encode('utf8')
@@ -55,21 +57,27 @@ """Mixin class to allow comparing to other objects which are comparable."""
def __lt__(self, other): + """Compare if other is less than self.""" return other >= self._cmpkey()
def __le__(self, other): + """Compare if other is less equals self.""" return other > self._cmpkey()
def __eq__(self, other): + """Compare if other is equal to self.""" return other == self._cmpkey()
def __ge__(self, other): + """Compare if other is greater equals self.""" return other < self._cmpkey()
def __gt__(self, other): + """Compare if other is greater than self.""" return other <= self._cmpkey()
def __ne__(self, other): + """Compare if other is not equal to self.""" return other != self._cmpkey()
diff --git a/pywikibot/userinterfaces/terminal_interface_base.py b/pywikibot/userinterfaces/terminal_interface_base.py index 3336392..bc6fc08 100755 --- a/pywikibot/userinterfaces/terminal_interface_base.py +++ b/pywikibot/userinterfaces/terminal_interface_base.py @@ -46,6 +46,12 @@ """Base for terminal user interfaces."""
def __init__(self): + """ + Initialize the UI. + + This caches the std-streams locally so any attempts to monkey-patch the + streams later will not work. + """ self.stdin = sys.stdin self.stdout = sys.stdout self.stderr = sys.stderr @@ -98,7 +104,11 @@ root_logger.addHandler(warning_handler)
def printNonColorized(self, text, targetStream): - # We add *** after the text as a whole if anything needed to be colorized. + """ + Write the text non colorized to the target stream. + + To each line which contains a color tag a ' ***' is added at the end. + """ lines = text.split('\n') for i, line in enumerate(lines): if i > 0: @@ -349,6 +359,7 @@ u'What is the solution of the CAPTCHA at this url ?')
def argvu(self): + """Return the decoded arguments from argv.""" try: return [s.decode(self.encoding) for s in self.argv] except AttributeError: # in python 3, self.argv is unicode and thus cannot be decoded @@ -393,6 +404,7 @@ self.stream.flush()
def emit(self, record): + """Emit the record formatted to the output and return it.""" text = self.format(record) return self.UI.output(text, targetStream=self.stream)
@@ -414,9 +426,11 @@ """
def __init__(self, level=None): + """Constructor.""" self.level = level
def filter(self, record): + """Return true if the level is below or equal to the set level.""" if self.level: return record.levelno <= self.level else: diff --git a/pywikibot/userinterfaces/terminal_interface_unix.py b/pywikibot/userinterfaces/terminal_interface_unix.py index bb6384d..b980cf6 100755 --- a/pywikibot/userinterfaces/terminal_interface_unix.py +++ b/pywikibot/userinterfaces/terminal_interface_unix.py @@ -36,6 +36,7 @@ """User interface for unix terminals."""
def printColorized(self, text, targetStream): + """Print the text colorized using the Unix colors.""" totalcount = 0 for key, value in unixColors.items(): ckey = '\03{%s}' % key diff --git a/pywikibot/xmlreader.py b/pywikibot/xmlreader.py index dceeb4b..bf5eee3 100644 --- a/pywikibot/xmlreader.py +++ b/pywikibot/xmlreader.py @@ -52,6 +52,7 @@ def __init__(self, title, ns, id, text, username, ipedit, timestamp, editRestriction, moveRestriction, revisionid, comment, redirect): + """Constructor.""" # TODO: there are more tags we can read. self.title = title self.ns = ns @@ -80,11 +81,13 @@ """
def __init__(self, filename, handler): + """Constructor.""" threading.Thread.__init__(self) self.filename = filename self.handler = handler
def run(self): + """Parse the file in a single thread.""" xml.sax.parse(self.filename, self.handler)
@@ -102,6 +105,7 @@ """
def __init__(self, filename, allrevisions=False): + """Constructor.""" self.filename = filename if allrevisions: self._parse = self._parse_all diff --git a/tox.ini b/tox.ini index 20b989d..2bb2ebe 100644 --- a/tox.ini +++ b/tox.ini @@ -10,8 +10,9 @@ install_command = pip install --process-dependency-links --pre {opts} {packages}
[testenv:flake8] -commands = flake8 {posargs} +commands = flake8 --ignore=D102,D103,E122,E127,E241 {posargs} deps = flake8 + flake8-docstrings
[testenv:flake8-docstrings] commands = flake8 {posargs} @@ -19,7 +20,75 @@ flake8-docstrings
[testenv:flake8-docstrings-mandatory] -commands = flake8 --ignore=D102,D103,E122,E127,E241 +commands = flake8 \ + ez_setup.py \ + generate_user_files.py \ + pwb.py \ + pywikibot/__init__.py \ + pywikibot/backports.py \ + pywikibot/bot.py \ + pywikibot/comms/__init__.py \ + pywikibot/comms/http.py \ + pywikibot/compat/ \ + pywikibot/config2.py \ + pywikibot/data/__init__.py \ + pywikibot/data/wikistats.py \ + pywikibot/date.py \ + pywikibot/diff.py \ + pywikibot/echo.py \ + pywikibot/editor.py \ + pywikibot/exceptions.py \ + pywikibot/families/ \ + pywikibot/fixes.py \ + pywikibot/i18n.py \ + pywikibot/pagegenerators.py \ + pywikibot/plural.py \ + pywikibot/throttle.py \ + pywikibot/userinterfaces/__init__.py \ + pywikibot/userinterfaces/terminal_interface.py \ + pywikibot/weblib.py \ + scripts/__init__.py \ + scripts/add_text.py \ + scripts/basic.py \ + scripts/category_redirect.py \ + scripts/claimit.py \ + scripts/clean_sandbox.py \ + scripts/commonscat.py \ + scripts/coordinate_import.py \ + scripts/delete.py \ + scripts/flickrripper.py \ + scripts/harvest_template.py \ + scripts/illustrate_wikidata.py \ + scripts/image.py \ + scripts/imagerecat.py \ + scripts/imageuncat.py \ + scripts/listpages.py \ + scripts/login.py \ + scripts/maintenance/__init__.py \ + scripts/newitem.py \ + scripts/pagefromfile.py \ + scripts/protect.py \ + scripts/shell.py \ + scripts/spamremove.py \ + scripts/states_redirect.py \ + scripts/template.py \ + scripts/transferbot.py \ + scripts/upload.py \ + scripts/watchlist.py \ + setup.py \ + tests/__init__.py \ + tests/archivebot_tests.py \ + tests/category_tests.py \ + tests/date_tests.py \ + tests/edit_failure_tests.py \ + tests/exceptions_tests.py \ + tests/family_tests.py \ + tests/i18n/ \ + tests/pwb/ \ + tests/pwb_tests.py \ + tests/script_tests.py \ + tests/upload_tests.py \ + tests/wikidataquery_tests.py
deps = flake8>=2.2.5 flake8-docstrings