Revision: 4465
Author: russblau
Date: 2007-10-17 21:25:20 +0000 (Wed, 17 Oct 2007)
Log Message:
-----------
Finished docstring cleanup at last!
Modified Paths:
--------------
trunk/pywikipedia/wikipedia.py
Modified: trunk/pywikipedia/wikipedia.py
===================================================================
--- trunk/pywikipedia/wikipedia.py 2007-10-17 20:04:39 UTC (rev 4464)
+++ trunk/pywikipedia/wikipedia.py 2007-10-17 21:25:20 UTC (rev 4465)
@@ -38,29 +38,30 @@
Other functions:
getall(): Load a group of pages via Special:Export
-
- handleArgs(): Process all standard command line arguments (such as -family,
- -lang, -log and others)
-
- translate(xx, dict): dict is a dictionary, giving text depending on language,
- xx is a language. Returns the text in the most applicable language for
- the xx: wiki
-
+ handleArgs(): Process all standard command line arguments (such as
+ -family, -lang, -log and others)
+ translate(xx, dict): dict is a dictionary, giving text depending on
+ language, xx is a language. Returns the text in the most applicable
+ language for the xx: wiki
setAction(text): Use 'text' instead of "Wikipedia python library" in
edit summaries
setUserAgent(text): Sets the string being passed to the HTTP server as
the User-agent: header. Defaults to 'Pywikipediabot/1.0'.
output(text): Prints the text 'text' in the encoding of the user's
- console.
+ console. **Use this instead of "print" statements**
input(text): Asks input from the user, printing the text 'text' first.
+ inputChoice: Shows user a list of choices and returns user's selection.
+
showDiff(oldtext, newtext): Prints the differences between oldtext and
newtext on the screen
- url2link: Convert urlname of a wiki page into interwiki link format.
-
+ datafilepath: Return an absolute path to a data file in a standard
+ location.
+ shortpath: Return a relative form of the data file pathname.
+
Wikitext manipulation functions: each of these takes a unicode string
- containing wiki text as its first argument, and returns a modified
- version of the text unless otherwise noted --
+containing wiki text as its first argument, and returns a modified version
+of the text unless otherwise noted --
replaceExcept: replace all instances of 'old' by 'new', skipping any
instances of 'old' within comments and other special text blocks
@@ -71,7 +72,8 @@
encodeEsperantoX: convert wikitext to the Esperanto x-encoding.
sectionencode: encode text for use as a section title in wiki-links.
-Wikitext maniupulation functions for interlanguage links:
+Wikitext manipulation functions for interlanguage links:
+
getLanguageLinks(text,xx): extract interlanguage links from text and
return in a dict
removeLanguageLinks(text): remove all interlanguage links from text
@@ -80,8 +82,10 @@
getLanguageLinks
interwikiFormat(links): convert a dict of interlanguage links to text
(using same dict format as getLanguageLinks)
+ url2link: Convert urlname of a wiki page into interwiki link format.
Wikitext manipulation functions for category links:
+
getCategoryLinks(text): return list of Category objects corresponding
to links in text
removeCategoryLinks(text): remove all category links from text
@@ -3404,6 +3408,13 @@
Methods:
+ language: This Site's language code.
+ family: This Site's Family object.
+ sitename: A string representing this Site.
+ languages: A list of all languages contained in this site's Family.
+ validLanguageLinks: A list of language codes that can be used in interwiki
+ links.
+
loggedInAs: return current username, or None if not logged in.
forceLogin: require the user to log in to the site
messages: return True if there are new messages on the site
@@ -3413,6 +3424,13 @@
urlEncode: Encode a query to be sent using an http POST request.
postForm: Post form data to an address at this site.
postData: Post encoded form data to an http address at this site.
+
+ namespace(num): Return local name of namespace 'num'.
+ normalizeNamespace(value): Return preferred name for namespace 'value' in
+ this Site's language.
+ namespaces: Return list of canonical namespace names for this Site.
+ getNamespaceIndex(name): Return the int index of namespace 'name', or None
+ if invalid.
redirect: Return the localized redirect tag for the site.
redirectRegex: Return compiled regular expression matching on redirect
@@ -3420,6 +3438,7 @@
mediawiki_message: Retrieve the text of a specified MediaWiki message
has_mediawiki_message: True if this site defines specified MediaWiki
message
+
shared_image_repository: Return tuple of image repositories used by this
site.
category_on_one_line: Return True if this site wants all category links
@@ -3429,11 +3448,16 @@
linkto(title): Return string in the form of a wikilink to 'title'
isInterwikiLink(s): Return True if 's' is in the form of an interwiki
link.
+ getSite(lang): Return Site object for wiki in same family, language
+ 'lang'.
version: Return MediaWiki version string from Family file.
versionnumber: Return int identifying the MediaWiki version.
live_version: Return version number read from Special:Version.
checkCharset(charset): Warn if charset doesn't match family file.
+ linktrail: Return regex for trailing chars displayed as part of a link.
+ disambcategory: Category in which disambiguation pages are listed.
+
Methods that yield Page objects derived from a wiki's Special: pages
(note, some methods yield other information in a tuple along with the
Pages; see method docs for details) --
@@ -3927,7 +3951,7 @@
return self._mediawiki_messages[key]
def has_mediawiki_message(self, key):
- """Return True iff this site defines a MediaWiki message for key "key" """
+ """Return True iff this site defines a MediaWiki message for 'key'."""
try:
v = self.mediawiki_message(key)
return True
@@ -4788,9 +4812,12 @@
def normalizeNamespace(self, value):
"""Return canonical name for namespace 'value' in this Site's language.
+ 'Value' should be a string or unicode.
If no match, return 'value' unmodified.
"""
+ if not self.nocapitalize and value[0].islower():
+ value = value[0].upper() + value[1:]
return self.family.normalizeNamespace(self.lang, value)
def namespaces(self):
@@ -4817,27 +4844,35 @@
return nslist
def getNamespaceIndex(self, namespace):
+ """Given a namespace name, return its int index, or None if invalid."""
return self.family.getNamespaceIndex(self.lang, namespace)
def linktrail(self):
+ """Return regex for trailing chars displayed as part of a link."""
return self.family.linktrail(self.lang)
def language(self):
+ """Return Site's language code."""
return self.lang
def fam(self):
+ """Return Family object for this Site."""
return self.family
def sitename(self):
+ """Return string representing this Site's name and language."""
return self.family.name+':'+self.lang
def languages(self):
+ """Return list of all valid language codes for this site's Family."""
return self.family.langs.keys()
def validLanguageLinks(self):
+ """Return list of language codes that can be used in interwiki links."""
return self._validlanguages
def disambcategory(self):
+ """Return Category in which disambig pages are listed."""
import catlib
try:
return catlib.Category(self,
@@ -4866,7 +4901,7 @@
else:
return self._token
- def putToken(self,value, sysop = False):
+ def putToken(self, value, sysop = False):
if sysop:
self._sysoptoken = value
else:
@@ -5131,7 +5166,8 @@
return []
def translate(code, xdict):
- """
+ """Return the most appropriate translation from a translation dict.
+
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 Wikipedia in
@@ -5236,9 +5272,7 @@
colorTagR = re.compile('\03{.*?}', re.UNICODE)
def log(text):
- """
- Writes the given text to the logfile.
- """
+ """Write the given text to the logfile."""
if logfile:
# remove all color markup
# TODO: consider pre-compiling this regex for speed improvements
@@ -5251,7 +5285,8 @@
input_lock = threading.Lock()
output_cache = []
def output(text, decoder = None, newline = True, toStdout = False):
- """
+ """Output a message to the user via the userinterface.
+
Works like print, but uses the encoding used by the user's console
(console_encoding in the configuration file) instead of ASCII.
If decoder is None, text should be a unicode string. Otherwise it
@@ -5266,6 +5301,7 @@
text can contain special sequences to create colored output. These
consist of the escape character \03 and the color name in curly braces,
e. g. \03{lightpurple}. \03{default} resets the color.
+
"""
output_lock.acquire()
try:
@@ -5299,8 +5335,7 @@
ui.output(*args, **kwargs)
def input(question, password = False):
- """
- Asks the user a question, then returns the user's answer.
+ """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
@@ -5309,6 +5344,7 @@
* password - if True, hides the user's input (for password entry).
Returns a unicode string.
+
"""
input_lock.acquire()
try:
@@ -5320,11 +5356,11 @@
return data
def inputChoice(question, answers, hotkeys, default = None):
- """
- Asks the user a question and offers several options, then returns the
- user's choice. The user's input will be case-insensitive, so the hotkeys
- should be distinctive case-insensitively.
+ """Ask the user a question with several options, return the user's choice.
+ 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
@@ -5335,6 +5371,7 @@
be returned when the user just presses Enter.
Returns a one-letter string in lowercase.
+
"""
input_lock.acquire()
try: