`pywikibot` — Base Classes and Functions#

The initialization file for the Pywikibot framework.

Imports from bot module

The following classes and functions are inported from bot module but can also be used as pywikibot members:

Imports from i18n module

The following function is inported from i18n module but can also be used as pywikibot members:

pywikibot.translate()

Imports from logging module

The following functions are inported from logging module but can also be used as pywikibot members:

Imports from page module

The following classes and function are inported from page module but can also be used as pywikibot members:

Imports from time module

The following class is inported from time module but can also be used as pywikibot members:

pywikibot.Timestamp

class pywikibot.Coordinate(lat, lon, alt=None, precision=None, globe=None, typ='', name='', dim=None, site=None, globe_item=None, primary=False)[source]#

Bases: WbRepresentation

Class for handling and storing Coordinates.

Represent a geo coordinate.

Parameters:

lat (float) – Latitude
lon (float) – Longitude
alt (float | None) – Altitude
precision (float | None) – precision
globe (str | None) – Which globe the point is on
typ (str) – The type of coordinate point
name (str) – The name
dim (int | None) – Dimension (in meters)
site (DataSite | None) – The Wikibase site
globe_item (ItemPageStrNoneType) – The Wikibase item for the globe, or the entity URI of this Wikibase item. Takes precedence over ‘globe’ if present.
primary (bool) – True for a primary set of coordinates

property entity: str#: Return the entity uri of the globe.

classmethod fromWikibase(data, site=None)[source]#

Constructor to create an object from Wikibase’s JSON output.

Parameters:

data (dict[str, Any]) – Wikibase JSON
site (DataSite | None) – The Wikibase site

Return type:

Coordinate

get_globe_item(repo=None, lazy_load=False)[source]#

Return the ItemPage corresponding to the globe.

Note that the globe need not be in the same data repository as the Coordinate itself.

A successful lookup is stored as an internal value to avoid the need for repeated lookups.

Parameters:

repo (DataSite | None) – the Wikibase site for the globe, if different from that provided with the Coordinate.
lazy_load (bool) – Do not raise NoPage if ItemPage does not exist.

Returns:

pywikibot.ItemPage

Return type:

pywikibot.ItemPage

property precision: float | None#

Return the precision of the geo coordinate.

The precision is calculated if the Coordinate does not have a precision, and self._dim is set.

When no precision and no self._dim exists, None is returned.

The biggest error (in degrees) will be given by the longitudinal error; the same error in meters becomes larger (in degrees) further up north. We can thus ignore the latitudinal error.

The longitudinal can be derived as follows:

In small angle approximation (and thus in radians):

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

\(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))))

precisionToDim()[source]#

Convert precision from Wikibase to GeoData’s dim and return the latter.

dim is calculated if the Coordinate doesn’t have a dimension, and precision is set. When neither dim nor precision are set, ValueError is thrown.

Carrying on from the earlier derivation of precision, since

precision = math.degrees(
    dim / (radius * math.cos(math.radians(self.lat))))

we get:

dim = math.radians(
    precision) * radius * math.cos(math.radians(self.lat))

But this is not valid, since it returns a float value for dim which is an integer. We must round it off to the nearest integer.

Therefore:

dim = int(round(math.radians(
    precision)*radius*math.cos(math.radians(self.lat))))

Return type:: int | None

toWikibase()[source]#

Export the data to a JSON object for the Wikibase API.

FIXME: Should this be in the DataSite object?

Returns:: Wikibase JSON
Return type:: dict[str, Any]

pywikibot.Site(code=None, fam=None, user=None, *, interface=None, url=None)[source]#

A factory method to obtain a Site object.

Site objects are cached and reused by this method.

By default rely on config settings. These defaults may all be overridden using the method parameters.

Creating the default site using config.mylang and config.family:

site = pywikibot.Site()

Override default site code:

site = pywikibot.Site('fr')

Override default family:

site = pywikibot.Site(fam='wikisource')

Setting a specific site:

site = pywikibot.Site('fr', 'wikisource')

which is equal to:

site = pywikibot.Site('wikisource:fr')

Note

An already created site is cached an a new variable points to the same object if interface, family, code and user are equal:

>>> import pywikibot
>>> site_1 = pywikibot.Site('wikisource:fr')
>>> site_2 = pywikibot.Site('fr', 'wikisource')
>>> site_1 is site_2
True
>>> site_1
APISite("fr", "wikisource")

APISite is the default interface. Refer pywikibot.site for other interface types.

Warning

Never create a site object via interface class directly. Always use this factory method.

Changed in version 7.3: Short creation if site code is equal to family name like Site('commons'), Site('meta') or Site('wikidata').

Parameters:

code (str | None) – language code (override config.mylang) code may also be a sitename like ‘wikipedia:test’
fam (str | Family | None) – family name or object (override config.family)
user (str | None) – bot user name to use on this site (override config.usernames)
interface (str | _BaseSite | None) – site class or name of class in pywikibot.site (override config.site_interface)
url (str | None) – Instead of code and fam, does try to get a Site based on the URL. Still requires that the family supporting that URL exists.

Raises:

ValueError – URL and pair of code and family given
ValueError – Invalid interface name
ValueError – Missing Site code
ValueError – Missing Site family

Return type:

_BaseSite

class pywikibot.WbGeoShape(page, site=None)[source]#

Bases: WbDataPage

A Wikibase geo-shape representation.

Create a new WbDataPage object.

Parameters:

page (pywikibot.Page) – page containing the data
site (DataSite | None) – The Wikibase site

class pywikibot.WbMonolingualText(text, language)[source]#

Bases: WbRepresentation

A Wikibase monolingual text representation.

Create a new WbMonolingualText object.

Parameters:

text (str) – text string
language (str) – language code of the string

classmethod fromWikibase(data, site=None)[source]#

Create a WbMonolingualText from the JSON data given by Wikibase API.

Parameters:

data (dict[str, Any]) – Wikibase JSON
site (DataSite | None) – The Wikibase site

Return type:

WbMonolingualText

toWikibase()[source]#

Convert the data to a JSON object for the Wikibase API.

Returns:: Wikibase JSON
Return type:: dict[str, Any]

class pywikibot.WbQuantity(amount, unit=None, error=None, site=None)[source]#

Bases: WbRepresentation

A Wikibase quantity representation.

Create a new WbQuantity object.

Parameters:

amount (ToDecimalType) – number representing this quantity
unit (ItemPageStrNoneType) – the Wikibase item for the unit or the entity URI of this Wikibase item.
error (ToDecimalType | tuple[ToDecimalType, ToDecimalType]) – the uncertainty of the amount (e.g. ±1)
site (DataSite | None) – The Wikibase site

classmethod fromWikibase(data, site=None)[source]#

Create a WbQuantity from the JSON data given by the Wikibase API.

Parameters:

data (dict[str, Any]) – Wikibase JSON
site (DataSite | None) – The Wikibase site

Return type:

WbQuantity

get_unit_item(repo=None, lazy_load=False)[source]#

Return the ItemPage corresponding to the unit.

Note that the unit need not be in the same data repository as the WbQuantity itself.

A successful lookup is stored as an internal value to avoid the need for repeated lookups.

Parameters:

repo (DataSite | None) – the Wikibase site for the unit, if different from that provided with the WbQuantity.
lazy_load (bool) – Do not raise NoPage if ItemPage does not exist.

Returns:

pywikibot.ItemPage

Return type:

pywikibot.ItemPage

toWikibase()[source]#

Convert the data to a JSON object for the Wikibase API.

Returns:: Wikibase JSON
Return type:: dict[str, Any]

property unit: str#: Return _unit’s entity uri or ‘1’ if _unit is None.

class pywikibot.WbTabularData(page, site=None)[source]#

Bases: WbDataPage

A Wikibase tabular-data representation.

Create a new WbDataPage object.

Parameters:

page (pywikibot.Page) – page containing the data
site (DataSite | None) – The Wikibase site

class pywikibot.WbTime(year=None, month=None, day=None, hour=None, minute=None, second=None, precision=None, before=0, after=0, timezone=0, calendarmodel=None, site=None)[source]#

Bases: WbRepresentation

A Wikibase time representation.

Make a WbTime object from the current time:

current_ts = pywikibot.Timestamp.now()
wbtime = pywikibot.WbTime.fromTimestamp(current_ts)

For converting python datetime objects to WbTime objects, see pywikibot.Timestamp and fromTimestamp().

Create a new WbTime object.

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.

Note

Comparison information: When using the greater than or equal to operator, or the less than or equal to operator, two different time objects with the same UTC time after factoring in timezones are considered equal. However, the equality operator will return false if the timezone is different.

Parameters:

year (int | None) – The year as a signed integer of between 1 and 16 digits.
month (int | None) – Month of the timestamp, if it exists.
day (int | None) – Day of the timestamp, if it exists.
hour (int | None) – Hour of the timestamp, if it exists.
minute (int | None) – Minute of the timestamp, if it exists.
second (int | None) – Second of the timestamp, if it exists.
precision (int | str | None) – The unit of the precision of the time.
before (int) – Number of units after the given time it could be, if uncertain. The unit is given by the precision.
after (int) – Number of units before the given time it could be, if uncertain. The unit is given by the precision.
timezone (int) – Timezone information in minutes.
calendarmodel (str | None) – URI identifying the calendar model.
site (DataSite | None) – The Wikibase site. If not provided, retrieves the data repository from the default site from user-config.py. Only used if calendarmodel is not given.

FORMATSTR = '{0:+012d}-{1:02d}-{2:02d}T{3:02d}:{4:02d}:{5:02d}Z'#

PRECISION = {'10000': 5, '100000': 4, '1000000': 3, '10000000': 2, '100000000': 1, '1000000000': 0, 'century': 7, 'day': 11, 'decade': 8, 'hour': 12, 'millenia': 6, 'minute': 13, 'month': 10, 'second': 14, 'year': 9}#

equal_instant(other)[source]#

Checks if the two times represent the same instant in time.

This is different from the equality operator, which will return false for two times that are the same number of UTC seconds, but with different timezone information.

For example, a time with at 10:00 UTC-5 would return false if checked with == with a time at 15:00 UTC, but would return true with this method.

Added in version 9.0.

Parameters:: other (WbTime)
Return type:: bool

classmethod fromTimestamp(timestamp, precision=14, before=0, after=0, timezone=0, calendarmodel=None, site=None, copy_timezone=False)[source]#

Create a new WbTime object from a pywikibot.Timestamp.

Changed in version 8.0: Added copy_timezone parameter.

Parameters:

timestamp (Timestamp) – Timestamp
precision (int | str) – The unit of the precision of the time. Defaults to 14 (second).
before (int) – Number of units after the given time it could be, if uncertain. The unit is given by the precision.
after (int) – Number of units before the given time it could be, if uncertain. The unit is given by the precision.
timezone (int) – Timezone information in minutes.
calendarmodel (str | None) – URI identifying the calendar model.
site (DataSite | None) – The Wikibase site. If not provided, retrieves the data repository from the default site from user-config.py. Only used if calendarmodel is not given.
copy_timezone (bool) – Whether to copy the timezone from the timestamp if it has timezone information. Defaults to False to maintain backwards compatibility. If a timezone is given, timezone information is discarded.

Return type:

WbTime

classmethod fromTimestr(datetimestr, precision=14, before=0, after=0, timezone=0, calendarmodel=None, site=None)[source]#

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.

Parameters:

datetimestr (str) – Timestamp in a format resembling ISO 8601, e.g. +2013-01-01T00:00:00Z
precision (int | str) – The unit of the precision of the time. Defaults to 14 (second).
before (int) – Number of units after the given time it could be, if uncertain. The unit is given by the precision.
after (int) – Number of units before the given time it could be, if uncertain. The unit is given by the precision.
timezone (int) – Timezone information in minutes.
calendarmodel (str | None) – URI identifying the calendar model.
site (DataSite | None) – The Wikibase site. If not provided, retrieves the data repository from the default site from user-config.py. Only used if calendarmodel is not given.

Return type:

WbTime

classmethod fromWikibase(data, site=None)[source]#

Create a WbTime from the JSON data given by the Wikibase API.

Parameters:

data (dict[str, Any]) – Wikibase JSON
site (DataSite | None) – The Wikibase site. If not provided, retrieves the data repository from the default site from user-config.py.

Return type:

WbTime

normalize()[source]#

Normalizes the WbTime object to account for precision.

Normalization is needed because WbTime objects can have hidden values that affect naive comparisons, such as an object set to a precision of YEAR but containing a month and day value.

This function returns a new normalized object and does not do any modification in place.

Normalization will delete timezone information if the precision is less than or equal to DAY.

Note: Normalized WbTime objects can only be compared to other normalized WbTime objects of the same precision. Normalization might make a WbTime object that was less than another WbTime object before normalization, greater than it after normalization, or vice versa.

Return type:: WbTime

toTimestamp(timezone_aware=False)[source]#

Convert the data to a pywikibot.Timestamp.

Changed in version 8.0.1: timezone_aware parameter was added.

Parameters:: timezone_aware (bool) – Whether the timezone should be passed to the Timestamp object.
Raises:: ValueError – instance value cannot be represented using Timestamp
Return type:: Timestamp

toTimestr(force_iso=False)[source]#

Convert the data to a UTC date/time string.

pywikibot — Base Classes and Functions#

`pywikibot` — Base Classes and Functions#