jenkins-bot has submitted this change and it was merged.
Change subject: [DOC] Add docstrings to __init__ where missing
......................................................................
[DOC] Add docstrings to __init__ where missing
Information largely based on
https://www.mediawiki.org/wiki/Wikibase/DataModel
Change-Id: Ide69b99a38bd2eeba7b76fae7b821cedffa93481
---
M pywikibot/__init__.py
1 file changed, 111 insertions(+), 9 deletions(-)
Approvals:
John Vandenberg: Looks good to me, approved
jenkins-bot: Verified
diff --git a/pywikibot/__init__.py b/pywikibot/__init__.py
index 609d4f8..c2f4dd5 100644
--- a/pywikibot/__init__.py
+++ b/pywikibot/__init__.py
@@ -242,7 +242,7 @@
@type lat: float
@param lon: Longitude
@type lon: float
- @param alt: Altitute? TODO FIXME
+ @param alt: Altitude? TODO FIXME
@param precision: precision
@type precision: float
@param globe: Which globe the point is on
@@ -253,6 +253,8 @@
@type name: str
@param dim: Dimension (in meters)
@type dim: int
+ @param site: The Wikibase site
+ @type site: pywikibot.site.DataSite
@param entity: The URL entity of a Wikibase item
@type entity: str
"""
@@ -283,6 +285,9 @@
Export the data to a JSON object for the Wikibase API.
FIXME: Should this be in the DataSite object?
+
+ @return: Wikibase JSON
+ @rtype: dict
"""
if self.globe not in self.site.globes():
raise CoordinateGlobeUnknownException(
@@ -297,7 +302,15 @@
@classmethod
def fromWikibase(cls, data, site):
- """Constructor to create an object from Wikibase's JSON
output."""
+ """
+ Constructor to create an object from Wikibase's JSON output.
+
+ @param data: Wikibase JSON
+ @type data: dict
+ @param site: The Wikibase site
+ @type site: pywikibot.site.DataSite
+ @rtype: pywikibot.Coordinate
+ """
globes = {}
for k in site.globes():
globes[site.globes()[k]] = k
@@ -381,6 +394,39 @@
The precision can be set by the Wikibase int value (0-14) or by a human
readable string, e.g., 'hour'. If no precision is given, it is set
according to the given time units.
+
+ Timezone information is given in three different ways depending on the time:
+ * Times after the implementation of UTC (1972): as an offset from UTC in
minutes;
+ * Times before the implementation of UTC: the offset of the time zone from
universal time;
+ * Before the implementation of time zones: The longitude of the place of
+ the event, in the range −180° to 180°, multiplied by 4 to convert to minutes.
+
+ @param year: The year as a signed integer of between 1 and 16 digits.
+ @type year: long
+ @param month: Month
+ @type month: int
+ @param day: Day
+ @type day: int
+ @param hour: Hour
+ @type hour: int
+ @param minute: Minute
+ @type minute: int
+ @param second: Second
+ @type second: int
+ @param precision: The unit of the precision of the time.
+ @type precision: int or str
+ @param before: Number of units after the given time it could be, if uncertain.
+ The unit is given by the precision.
+ @type before: int
+ @param after: Number of units before the given time it could be, if uncertain.
+ The unit is given by the precision.
+ @type after: int
+ @param timezone: Timezone information in minutes.
+ @type timezone: int
+ @param calendarmodel: URI identifying the calendar model
+ @type calendarmodel: str
+ @param site: The Wikibase site
+ @type site: pywikibot.site.DataSite
"""
if year is None:
raise ValueError('no year given')
@@ -428,6 +474,33 @@
@classmethod
def fromTimestr(cls, datetimestr, precision=14, before=0, after=0,
timezone=0, calendarmodel=None, site=None):
+ """
+ Create a new WbTime object from a UTC date/time string.
+
+ The timestamp differs from ISO 8601 in that:
+ * The year is always signed and having between 1 and 16 digits;
+ * The month, day and time are zero if they are unknown;
+ * The Z is discarded since time zone is determined from the timezone param.
+
+ @param datetimestr: Timestamp in a format resembling ISO 8601,
+ e.g. +2013-01-01T00:00:00Z
+ @type datetimestr: str
+ @param precision: The unit of the precision of the time.
+ @type precision: int or str
+ @param before: Number of units after the given time it could be, if uncertain.
+ The unit is given by the precision.
+ @type before: int
+ @param after: Number of units before the given time it could be, if uncertain.
+ The unit is given by the precision.
+ @type after: int
+ @param timezone: Timezone information in minutes.
+ @type timezone: int
+ @param calendarmodel: URI identifying the calendar model
+ @type calendarmodel: str
+ @param site: The Wikibase site
+ @type site: pywikibot.site.DataSite
+ @rtype: pywikibot.WbTime
+ """
match = re.match(r'([-+]?\d+)-(\d+)-(\d+)T(\d+):(\d+):(\d+)Z',
datetimestr)
if not match:
@@ -441,7 +514,8 @@
"""
Convert the data to a UTC date/time string.
- @return: str
+ @return: Timestamp in a format resembling ISO 8601
+ @rtype: str
"""
return self.FORMATSTR.format(self.year, self.month, self.day,
self.hour, self.minute, self.second)
@@ -450,7 +524,8 @@
"""
Convert the data to a JSON object for the Wikibase API.
- @return: dict
+ @return: Wikibase JSON
+ @rtype: dict
"""
json = {'time': self.toTimestr(),
'precision': self.precision,
@@ -463,6 +538,13 @@
@classmethod
def fromWikibase(cls, ts):
+ """
+ Create a WbTime from the JSON data given by the Wikibase API.
+
+ @param ts: Wikibase JSON
+ @type ts: dict
+ @rtype: pywikibot.WbTime
+ """
return cls.fromTimestr(ts[u'time'], ts[u'precision'],
ts[u'before'], ts[u'after'],
ts[u'timezone'], ts[u'calendarmodel'])
@@ -476,14 +558,26 @@
@staticmethod
def _todecimal(value):
- """Convert a string to a Decimal for use in
WbQuantity."""
+ """
+ Convert a string to a Decimal for use in WbQuantity.
+
+ @param value: decimal number to convert
+ @type value: str
+ @rtype: Decimal
+ """
if isinstance(value, Decimal):
return value
return Decimal(str(value))
@staticmethod
def _fromdecimal(value):
- """Convert a Decimal to a string representation suitable for
WikiBase."""
+ """
+ Convert a Decimal to a string representation suitable for WikiBase.
+
+ @param value: decimal number to convert
+ @type value: Decimal
+ @rtype: str
+ """
return format(value, "+g")
def __init__(self, amount, unit=None, error=None):
@@ -518,7 +612,12 @@
self.lowerBound = self.amount - lowerError
def toWikibase(self):
- """Convert the data to a JSON object for the Wikibase
API."""
+ """
+ Convert the data to a JSON object for the Wikibase API.
+
+ @return: Wikibase JSON
+ @rtype: dict
+ """
json = {'amount': self._fromdecimal(self.amount),
'upperBound': self._fromdecimal(self.upperBound),
'lowerBound': self._fromdecimal(self.lowerBound),
@@ -532,6 +631,8 @@
Create a WbQuanity from the JSON data given by the Wikibase API.
@param wb: Wikibase JSON
+ @type wb: dict
+ @rtype: pywikibot.WbQuanity
"""
amount = cls._todecimal(wb['amount'])
upperBound = cls._todecimal(wb['upperBound'])
@@ -574,6 +675,7 @@
@param wb: Wikibase JSON
@type wb: dict
+ @rtype: pywikibot.WbMonolingualText
"""
return cls(wb['text'], wb['language'])
@@ -724,11 +826,11 @@
def stopme():
- """Drop this process from the throttle log, after pending threads
finish.
+ """
+ Drop this process from the throttle log, after pending threads finish.
Can be called manually if desired, but if not, will be called automatically
at Python exit.
-
"""
global stopped
_logger = "wiki"
--
To view, visit
https://gerrit.wikimedia.org/r/264618
To unsubscribe, visit
https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: Ide69b99a38bd2eeba7b76fae7b821cedffa93481
Gerrit-PatchSet: 2
Gerrit-Project: pywikibot/core
Gerrit-Branch: master
Gerrit-Owner: Lokal Profil <lokal.profil(a)gmail.com>
Gerrit-Reviewer: John Vandenberg <jayvdb(a)gmail.com>
Gerrit-Reviewer: Lokal Profil <lokal.profil(a)gmail.com>
Gerrit-Reviewer: jenkins-bot <>