Skip to content

Commit

Permalink
[doc] Fix docstrings
Browse files Browse the repository at this point in the history 
- [203] Add blank line before class docstring
- [212] Start Multi-line docstring summary at the first line

Change-Id: I06485009d487b356975c9873dffbc54f32aefb58
  • Loading branch information
@xqt
xqt committed Nov 1, 2024
1 parent f95f22c commit 2124a48
Show file tree
Hide file tree
Showing 163 changed files with 786 additions and 1,445 deletions.
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ ignore_missing_imports = true

[tool.ruff.lint]
select = ["D"]
ignore = ["D105", "D203", "D211", "D212", "D213", "D214", "D401", "D404", "D406", "D407", "D412", "D413", "D416", "D417"]
ignore = ["D105", "D211", "D213", "D214", "D401", "D404", "D406", "D407", "D412", "D413", "D416", "D417"]

[tool.ruff.lint.per-file-ignores]
"pywikibot/families/*" = ["D102"]
Expand Down
3 changes: 1 addition & 2 deletions pywikibot/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -272,8 +272,7 @@ def Site(code: str | None = None, # noqa: N802
def showDiff(oldtext: str, # noqa: N802
newtext: str,
context: int = 0) -> None:
"""
Output a string showing the differences between oldtext and newtext.
"""Output a string showing the differences between oldtext and newtext.
The differences are highlighted (only on compatible systems) to show which
changes were made.
Expand Down
86 changes: 32 additions & 54 deletions pywikibot/_wbtypes.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,8 +101,7 @@ def __init__(self, lat: float, lon: float, alt: float | None = None,
site: DataSite | None = None,
globe_item: ItemPageStrNoneType = None,
primary: bool = False) -> None:
"""
Represent a geo coordinate.
"""Represent a geo coordinate.
:param lat: Latitude
:param lon: Longitude
Expand Down Expand Up @@ -150,8 +149,7 @@ def entity(self) -> str:
return self._entity

def toWikibase(self) -> dict[str, Any]:
"""
Export the data to a JSON object for the Wikibase API.
"""Export the data to a JSON object for the Wikibase API.
FIXME: Should this be in the DataSite object?
Expand All @@ -167,8 +165,7 @@ def toWikibase(self) -> dict[str, Any]:
@classmethod
def fromWikibase(cls, data: dict[str, Any],
site: DataSite | None = None) -> Coordinate:
"""
Constructor to create an object from Wikibase's JSON output.
"""Constructor to create an object from Wikibase's JSON output.
:param data: Wikibase JSON
:param site: The Wikibase site
Expand Down Expand Up @@ -230,8 +227,7 @@ def precision(self, value: float) -> None:
self._precision = value

def precisionToDim(self) -> int | None:
"""
Convert precision from Wikibase to GeoData's dim and return the latter.
"""Convert precision from Wikibase to GeoData's dim.
dim is calculated if the Coordinate doesn't have a dimension, and
precision is set. When neither dim nor precision are set, ValueError
Expand Down Expand Up @@ -273,8 +269,7 @@ def precisionToDim(self) -> int | None:

def get_globe_item(self, repo: DataSite | None = None,
lazy_load: bool = False) -> pywikibot.ItemPage:
"""
Return the ItemPage corresponding to the globe.
"""Return the ItemPage corresponding to the globe.
Note that the globe need not be in the same data repository as the
Coordinate itself.
Expand Down Expand Up @@ -720,8 +715,7 @@ def toTimestr(self, force_iso: bool = False) -> str:
self.hour, self.minute, self.second)

def toTimestamp(self, timezone_aware: bool = False) -> Timestamp:
"""
Convert the data to a pywikibot.Timestamp.
"""Convert the data to a pywikibot.Timestamp.
.. versionchanged:: 8.0.1
*timezone_aware* parameter was added.
Expand Down Expand Up @@ -764,8 +758,7 @@ def toWikibase(self) -> dict[str, Any]:
@classmethod
def fromWikibase(cls, data: dict[str, Any],
site: DataSite | None = None) -> WbTime:
"""
Create a WbTime from the JSON data given by the Wikibase API.
"""Create a WbTime from the JSON data given by the Wikibase API.
:param data: Wikibase JSON
:param site: The Wikibase site. If not provided, retrieves the data
Expand All @@ -784,8 +777,7 @@ class WbQuantity(WbRepresentation):

@staticmethod
def _require_errors(site: DataSite | None) -> bool:
"""
Check if Wikibase site is so old it requires error bounds to be given.
"""Check if Wikibase site is old and requires error bounds to be given.
If no site item is supplied it raises a warning and returns True.
Expand All @@ -800,8 +792,7 @@ def _require_errors(site: DataSite | None) -> bool:

@staticmethod
def _todecimal(value: ToDecimalType) -> Decimal | None:
"""
Convert a string to a Decimal for use in WbQuantity.
"""Convert a string to a Decimal for use in WbQuantity.
None value is returned as is.
Expand All @@ -815,8 +806,7 @@ def _todecimal(value: ToDecimalType) -> Decimal | None:

@staticmethod
def _fromdecimal(value: Decimal | None) -> str | None:
"""
Convert a Decimal to a string representation suitable for WikiBase.
"""Convert a Decimal to a string representation suitable for WikiBase.
None value is returned as is.
Expand All @@ -830,8 +820,7 @@ def __init__(
error: ToDecimalType | tuple[ToDecimalType, ToDecimalType] = None,
site: DataSite | None = None,
) -> None:
"""
Create a new WbQuantity object.
"""Create a new WbQuantity object.
:param amount: number representing this quantity
:param unit: the Wikibase item for the unit or the entity URI of this
Expand Down Expand Up @@ -878,8 +867,7 @@ def unit(self) -> str:

def get_unit_item(self, repo: DataSite | None = None,
lazy_load: bool = False) -> pywikibot.ItemPage:
"""
Return the ItemPage corresponding to the unit.
"""Return the ItemPage corresponding to the unit.
Note that the unit need not be in the same data repository as the
WbQuantity itself.
Expand All @@ -901,8 +889,7 @@ def get_unit_item(self, repo: DataSite | None = None,
return self._unit

def toWikibase(self) -> dict[str, Any]:
"""
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
"""
Expand All @@ -916,8 +903,7 @@ def toWikibase(self) -> dict[str, Any]:
@classmethod
def fromWikibase(cls, data: dict[str, Any],
site: DataSite | None = None) -> WbQuantity:
"""
Create a WbQuantity from the JSON data given by the Wikibase API.
"""Create a WbQuantity from the JSON data given by the Wikibase API.
:param data: Wikibase JSON
:param site: The Wikibase site
Expand All @@ -934,13 +920,13 @@ def fromWikibase(cls, data: dict[str, Any],


class WbMonolingualText(WbRepresentation):

"""A Wikibase monolingual text representation."""

_items = ('text', 'language')

def __init__(self, text: str, language: str) -> None:
"""
Create a new WbMonolingualText object.
"""Create a new WbMonolingualText object.
:param text: text string
:param language: language code of the string
Expand All @@ -951,8 +937,7 @@ def __init__(self, text: str, language: str) -> None:
self.language = language

def toWikibase(self) -> dict[str, Any]:
"""
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
"""
Expand All @@ -964,8 +949,7 @@ def toWikibase(self) -> dict[str, Any]:
@classmethod
def fromWikibase(cls, data: dict[str, Any],
site: DataSite | None = None) -> WbMonolingualText:
"""
Create a WbMonolingualText from the JSON data given by Wikibase API.
"""Create a WbMonolingualText from the JSON data given by Wikibase API.
:param data: Wikibase JSON
:param site: The Wikibase site
Expand All @@ -974,6 +958,7 @@ def fromWikibase(cls, data: dict[str, Any],


class WbDataPage(WbRepresentation):

"""An abstract Wikibase representation for data pages.
.. warning:: Perhaps a temporary implementation until :phab:`T162336`
Expand All @@ -986,8 +971,7 @@ class WbDataPage(WbRepresentation):
@classmethod
@abc.abstractmethod
def _get_data_site(cls, repo_site: DataSite) -> APISite:
"""
Return the site serving as a repository for a given data type.
"""Return the site serving as a repository for a given data type.
.. note:: implemented in the extended class.
Expand All @@ -998,8 +982,7 @@ def _get_data_site(cls, repo_site: DataSite) -> APISite:
@classmethod
@abc.abstractmethod
def _get_type_specifics(cls, site: DataSite) -> dict[str, Any]:
"""
Return the specifics for a given data type.
"""Return the specifics for a given data type.
.. note:: Must be implemented in the extended class.
Expand All @@ -1017,8 +1000,7 @@ def _get_type_specifics(cls, site: DataSite) -> dict[str, Any]:
@staticmethod
def _validate(page: pywikibot.Page, data_site: BaseSite, ending: str,
label: str) -> None:
"""
Validate the provided page against general and type specific rules.
"""Validate the provided page against general and type specific rules.
:param page: Page containing the data.
:param data_site: The site serving as a repository for the given
Expand Down Expand Up @@ -1073,8 +1055,7 @@ def __hash__(self) -> int:
return hash(self.toWikibase())

def toWikibase(self) -> str:
"""
Convert the data to the value required by the Wikibase API.
"""Convert the data to the value required by the Wikibase API.
:return: title of the data page incl. namespace
"""
Expand All @@ -1097,21 +1078,20 @@ def fromWikibase(cls, page_name: str, site: DataSite | None) -> WbDataPage:


class WbGeoShape(WbDataPage):

"""A Wikibase geo-shape representation."""

@classmethod
def _get_data_site(cls, site: DataSite) -> APISite:
"""
Return the site serving as a geo-shape repository.
"""Return the site serving as a geo-shape repository.
:param site: The Wikibase site
"""
return site.geo_shape_repository()

@classmethod
def _get_type_specifics(cls, site: DataSite) -> dict[str, Any]:
"""
Return the specifics for WbGeoShape.
"""Return the specifics for WbGeoShape.
:param site: The Wikibase site
"""
Expand All @@ -1124,21 +1104,20 @@ def _get_type_specifics(cls, site: DataSite) -> dict[str, Any]:


class WbTabularData(WbDataPage):

"""A Wikibase tabular-data representation."""

@classmethod
def _get_data_site(cls, site: DataSite) -> APISite:
"""
Return the site serving as a tabular-data repository.
"""Return the site serving as a tabular-data repository.
:param site: The Wikibase site
"""
return site.tabular_data_repository()

@classmethod
def _get_type_specifics(cls, site: DataSite) -> dict[str, Any]:
"""
Return the specifics for WbTabularData.
"""Return the specifics for WbTabularData.
:param site: The Wikibase site
"""
Expand All @@ -1151,6 +1130,7 @@ def _get_type_specifics(cls, site: DataSite) -> dict[str, Any]:


class WbUnknown(WbRepresentation):

"""A Wikibase representation for unknown data type.
This will prevent the bot from breaking completely when a new type
Expand All @@ -1166,8 +1146,7 @@ class WbUnknown(WbRepresentation):
_items = ('json',)

def __init__(self, json: dict[str, Any], warning: str = '') -> None:
"""
Create a new WbUnknown object.
"""Create a new WbUnknown object.
:param json: Wikibase JSON
:param warning: a warning message which is shown once if
Expand All @@ -1192,8 +1171,7 @@ def toWikibase(self) -> dict[str, Any]:
@classmethod
def fromWikibase(cls, data: dict[str, Any],
site: DataSite | None = None) -> WbUnknown:
"""
Create a WbUnknown from the JSON data given by the Wikibase API.
"""Create a WbUnknown from the JSON data given by the Wikibase API.
:param data: Wikibase JSON
:param site: The Wikibase site
Expand Down
Loading

0 comments on commit 2124a48

Please sign in to comment.