Xqt has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1069698?usp=email )
Change subject: [doc] update ROADMAP.rst and datasite documentation
......................................................................
[doc] update ROADMAP.rst and datasite documentation
Change-Id: Ia84970b146e69e44b258abc6f859d650842097dc
---
M ROADMAP.rst
M pywikibot/site/_datasite.py
2 files changed, 149 insertions(+), 97 deletions(-)
Approvals:
Xqt: Verified; Looks good to me, approved
diff --git a/ROADMAP.rst b/ROADMAP.rst
index b781176..b1e6268 100644
--- a/ROADMAP.rst
+++ b/ROADMAP.rst
@@ -1,6 +1,7 @@
Current Release Changes
=======================
+* Add tags to the wikibase functions (:phab:`T372513`)
* :func:`diff.get_close_matches_ratio()` function was added
* Initialize super classes of :exc:`EditReplacementError` (:phab:`T212740`)
* Add a hint to import missing module in :mod:`wrapper<pywikibot.scripts.wrapper>` script
diff --git a/pywikibot/site/_datasite.py b/pywikibot/site/_datasite.py
index de02a74..a5f8a31 100644
--- a/pywikibot/site/_datasite.py
+++ b/pywikibot/site/_datasite.py
@@ -280,21 +280,38 @@
return entity['datatype']
@need_right('edit')
- def editEntity(self, entity, data, bot: bool = True, **kwargs):
+ def editEntity(self,
+ entity: pywikibot.page.WikibaseEntity | dict,
+ data: dict,
+ bot: bool = True,
+ **kwargs) -> dict:
"""Edit entity.
.. note:: This method is unable to create entities other than
- 'item' if dict with API parameters was passed to 'entity'
+ ``item`` if dict with API parameters was passed to *entity*
parameter.
+ .. versionchanged:: 9.4
+ *tags* keyword argument was added
+
:param entity: Page to edit, or dict with API parameters
- to use for entity identification
- :type entity: WikibaseEntity or dict
+ to use for entity identification.
:param data: data updates
- :type data: dict
- :param bot: Whether to mark the edit as a bot edit
+ :param bot: Whether to mark the edit as a bot edit.
+
+ :keyword int baserevid: The numeric identifier for the revision
+ to base the modification on. This is used for detecting
+ conflicts during save.
+ :keyword bool clear: If set, the complete entity is emptied
+ before proceeding. The entity will not be saved before it is
+ filled with the *data*, possibly with parts excluded.
+ :keyword str summary: Summary for the edit. Will be prepended by
+ an automatically generated comment. The length limit of the
+ autocomment together with the summary is 260 characters. Be
+ aware that everything above that limit will be cut off.
+ :keyword Iterable[str] | str tags: Change tags to apply to the
+ revision.
:return: New entity data
- :rtype: dict
"""
# this changes the reference to a new object
data = dict(data)
@@ -313,9 +330,7 @@
if not params: # If no identification was provided
params['new'] = 'item'
- params['action'] = 'wbeditentity'
- if bot:
- params['bot'] = 1
+ params.update(action='wbeditentity', bot=bot)
if kwargs.get('baserevid'):
params['baserevid'] = kwargs['baserevid']
@@ -340,8 +355,10 @@
bot: bool = True,
summary: str | None = None,
tags: str | None = None) -> None:
- """
- Add a claim.
+ """Add a claim.
+
+ .. versionchanged:: 9.4
+ *tags* parameter was added
:param entity: Entity to modify
:param claim: Claim to be added
@@ -350,14 +367,15 @@
:param tags: Change tags to apply to the revision
"""
claim.snak = entity.getID() + '$' + str(uuid.uuid4())
- params = {'action': 'wbsetclaim',
- 'claim': json.dumps(claim.toJSON()),
- 'baserevid': entity.latest_revision_id,
- 'summary': summary,
- 'tags': tags,
- 'bot': bot,
- 'token': self.tokens['csrf'],
- }
+ params = {
+ 'action': 'wbsetclaim',
+ 'claim': json.dumps(claim.toJSON()),
+ 'baserevid': entity.latest_revision_id,
+ 'summary': summary,
+ 'tags': tags,
+ 'bot': bot,
+ 'token': self.tokens['csrf'],
+ }
req = self.simple_request(**params)
data = req.submit()
# Update the item
@@ -369,16 +387,17 @@
@need_right('edit')
def changeClaimTarget(self,
- claim,
+ claim: pywikibot.Claim,
snaktype: str = 'value',
bot: bool = True,
summary: str | None = None,
tags: str | None = None):
- """
- Set the claim target to the value of the provided claim target.
+ """Set the claim target to the value of the provided claim target.
+
+ .. versionchanged:: 9.4
+ *tags* parameter was added
:param claim: The source of the claim target value
- :type claim: pywikibot.Claim
:param snaktype: An optional snaktype ('value', 'novalue' or
'somevalue'). Default: 'value'
:param bot: Whether to mark the edit as a bot edit
@@ -387,17 +406,20 @@
"""
if claim.isReference or claim.isQualifier:
raise NotImplementedError
+
if not claim.snak:
# We need to already have the snak value
raise NoPageError(claim)
- params = {'action': 'wbsetclaimvalue',
- 'claim': claim.snak,
- 'snaktype': snaktype,
- 'summary': summary,
- 'tags': tags,
- 'bot': bot,
- 'token': self.tokens['csrf'],
- }
+
+ params = {
+ 'action': 'wbsetclaimvalue',
+ 'claim': claim.snak,
+ 'snaktype': snaktype,
+ 'summary': summary,
+ 'tags': tags,
+ 'bot': bot,
+ 'token': self.tokens['csrf'],
+ }
if snaktype == 'value':
params['value'] = json.dumps(claim._formatValue())
@@ -407,31 +429,41 @@
return req.submit()
@need_right('edit')
- def save_claim(self, claim: pywikibot.page.Claim,
+ def save_claim(self,
+ claim: pywikibot.page.Claim,
summary: str | None = None,
bot: bool = True,
tags: str | None = None):
"""
Save the whole claim to the wikibase site.
+ .. versionchanged:: 9.4
+ *tags* parameter was added
+
:param claim: The claim to save
:param bot: Whether to mark the edit as a bot edit
:param summary: Edit summary
:param tags: Change tags to apply to the revision
+ :raises NoPageError: missing the the snak value
+ :raises NotImplementedError: ``claim.isReference`` or
+ ``claim.isQualifier`` is given
"""
if claim.isReference or claim.isQualifier:
raise NotImplementedError
+
if not claim.snak:
# We need to already have the snak value
raise NoPageError(claim)
- params = {'action': 'wbsetclaim',
- 'claim': json.dumps(claim.toJSON()),
- 'baserevid': claim.on_item.latest_revision_id,
- 'summary': summary,
- 'tags': tags,
- 'bot': bot,
- 'token': self.tokens['csrf'],
- }
+
+ params = {
+ 'action': 'wbsetclaim',
+ 'claim': json.dumps(claim.toJSON()),
+ 'baserevid': claim.on_item.latest_revision_id,
+ 'summary': summary,
+ 'tags': tags,
+ 'bot': bot,
+ 'token': self.tokens['csrf'],
+ }
req = self.simple_request(**params)
data = req.submit()
@@ -440,7 +472,9 @@
@need_right('edit')
@remove_last_args(['baserevid']) # since 7.0.0
- def editSource(self, claim, source,
+ def editSource(self,
+ claim: pywikibot.Claim,
+ source: pywikibot.Claim,
new: bool = False,
bot: bool = True,
summary: str | None = None,
@@ -448,27 +482,31 @@
"""Create/Edit a source.
.. versionchanged:: 7.0
- deprecated `baserevid` parameter was removed
+ deprecated *baserevid* parameter was removed
+ .. versionchanged:: 9.4
+ *tags* parameter was added
- :param claim: A Claim object to add the source to
- :type claim: pywikibot.Claim
- :param source: A Claim object to be used as a source
- :type source: pywikibot.Claim
- :param new: Whether to create a new one if the "source" already exists
- :param bot: Whether to mark the edit as a bot edit
- :param summary: Edit summary
- :param tags: Change tags to apply to the revision
+ :param claim: A Claim object to add the source to.
+ :param source: A Claim object to be used as a source.
+ :param new: Whether to create a new one if the "source" already
+ exists.
+ :param bot: Whether to mark the edit as a bot edit.
+ :param summary: Edit summary.
+ :param tags: Change tags to apply to the revision.
+ :raises ValueError: The claim cannot have a source.
"""
if claim.isReference or claim.isQualifier:
raise ValueError('The claim cannot have a source.')
- params = {'action': 'wbsetreference',
- 'statement': claim.snak,
- 'baserevid': claim.on_item.latest_revision_id,
- 'summary': summary,
- 'tags': tags,
- 'bot': bot,
- 'token': self.tokens['csrf'],
- }
+
+ params = {
+ 'action': 'wbsetreference',
+ 'statement': claim.snak,
+ 'baserevid': claim.on_item.latest_revision_id,
+ 'summary': summary,
+ 'tags': tags,
+ 'bot': bot,
+ 'token': self.tokens['csrf'],
+ }
# build up the snak
sources = source if isinstance(source, list) else [source]
@@ -495,7 +533,9 @@
@need_right('edit')
@remove_last_args(['baserevid']) # since 7.0.0
- def editQualifier(self, claim, qualifier,
+ def editQualifier(self,
+ claim: pywikibot.Claim,
+ qualifier: pywikibot.Claim,
new: bool = False,
bot: bool = True,
summary: str | None = None,
@@ -503,35 +543,40 @@
"""Create/Edit a qualifier.
.. versionchanged:: 7.0
- deprecated `baserevid` parameter was removed
+ deprecated *baserevid* parameter was removed
+ .. versionchanged:: 9.4
+ *tags* parameter was added
:param claim: A Claim object to add the qualifier to
- :type claim: pywikibot.Claim
:param qualifier: A Claim object to be used as a qualifier
- :type qualifier: pywikibot.Claim
- :param new: Whether to create a new one if the "qualifier"
+ :param new: Whether to create a new one if the qualifier
already exists
:param bot: Whether to mark the edit as a bot edit
:param summary: Edit summary
:param tags: Change tags to apply to the revision
+ :raises ValueError: The claim cannot have a qualifier.
"""
if claim.isReference or claim.isQualifier:
raise ValueError('The claim cannot have a qualifier.')
- params = {'action': 'wbsetqualifier',
- 'claim': claim.snak,
- 'baserevid': claim.on_item.latest_revision_id,
- 'summary': summary,
- 'tags': tags,
- 'bot': bot,
- 'token': self.tokens['csrf'],
- }
+
+ params = {
+ 'action': 'wbsetqualifier',
+ 'claim': claim.snak,
+ 'baserevid': claim.on_item.latest_revision_id,
+ 'summary': summary,
+ 'tags': tags,
+ 'bot': bot,
+ 'token': self.tokens['csrf'],
+ }
if (not new and hasattr(qualifier, 'hash')
and qualifier.hash is not None):
params['snakhash'] = qualifier.hash
+
# build up the snak
if qualifier.getSnakType() == 'value':
params['value'] = json.dumps(qualifier._formatValue())
+
params['snaktype'] = qualifier.getSnakType()
params['property'] = qualifier.getID()
@@ -540,17 +585,19 @@
@need_right('edit')
@remove_last_args(['baserevid']) # since 7.0.0
- def removeClaims(self, claims,
+ def removeClaims(self,
+ claims: list[pywikibot.Claim],
bot: bool = True,
summary: str | None = None,
tags: str | None = None):
"""Remove claims.
.. versionchanged:: 7.0
- deprecated `baserevid` parameter was removed
+ deprecated *baserevid* parameter was removed
+ .. versionchanged:: 9.4
+ *tags* parameter was added
:param claims: Claims to be removed
- :type claims: list[pywikibot.Claim]
:param bot: Whether to mark the edit as a bot edit
:param summary: Edit summary
:param tags: Change tags to apply to the revision
@@ -575,7 +622,9 @@
@need_right('edit')
@remove_last_args(['baserevid']) # since 7.0.0
- def removeSources(self, claim, sources,
+ def removeSources(self,
+ claim: pywikibot.Claim,
+ sources: list[pywikibot.Claim],
bot: bool = True,
summary: str | None = None,
tags: str | None = None):
@@ -583,11 +632,11 @@
.. versionchanged:: 7.0
deprecated `baserevid` parameter was removed
+ .. versionchanged:: 9.4
+ *tags* parameter was added
:param claim: A Claim object to remove the sources from
- :type claim: pywikibot.Claim
:param sources: A list of Claim objects that are sources
- :type sources: list
:param bot: Whether to mark the edit as a bot edit
:param summary: Edit summary
:param tags: Change tags to apply to the revision
@@ -608,7 +657,9 @@
@need_right('edit')
@remove_last_args(['baserevid']) # since 7.0.0
- def remove_qualifiers(self, claim, qualifiers,
+ def remove_qualifiers(self,
+ claim: pywikibot.Claim,
+ qualifiers: list[pywikibot.Claim],
bot: bool = True,
summary: str | None = None,
tags: str | None = None):
@@ -616,11 +667,11 @@
.. versionchanged:: 7.0
deprecated `baserevid` parameter was removed
+ .. versionchanged:: 9.4
+ *tags* parameter was added
:param claim: A Claim object to remove the qualifier from
- :type claim: pywikibot.Claim
:param qualifiers: Claim objects currently used as a qualifiers
- :type qualifiers: list[pywikibot.Claim]
:param bot: Whether to mark the edit as a bot edit
:param summary: Edit summary
:param tags: Change tags to apply to the revision
@@ -640,17 +691,19 @@
return req.submit()
@need_right('edit')
- def linkTitles(self, page1, page2, bot: bool = True):
- """
- Link two pages together.
+ def linkTitles(self,
+ page1: pywikibot.Page,
+ page2: pywikibot.Page,
+ bot: bool = True) -> dict:
+ """Link two pages together.
+
+ .. versionchanged:: 9.4
+ *tags* parameter was added
:param page1: First page to link
- :type page1: pywikibot.Page
:param page2: Second page to link
- :type page2: pywikibot.Page
:param bot: Whether to mark the edit as a bot edit
:return: dict API output
- :rtype: dict
"""
params = {
'action': 'wblinktitles',
@@ -667,28 +720,26 @@
@need_right('item-merge')
def mergeItems(self,
- from_item,
- to_item,
- ignore_conflicts=None,
+ from_item: pywikibot.ItemPage,
+ to_item: pywikibot.ItemPage,
+ ignore_conflicts: list[str] | None = None,
summary: str | None = None,
bot: bool = True,
- tags: str | None = None):
- """
- Merge two items together.
+ tags: str | None = None) -> dict:
+ """Merge two items together.
+
+ .. versionchanged:: 9.4
+ *tags* parameter was added
:param from_item: Item to merge from
- :type from_item: pywikibot.ItemPage
:param to_item: Item to merge into
- :type to_item: pywikibot.ItemPage
:param ignore_conflicts: Which type of conflicts
('description', 'sitelink', and 'statement')
should be ignored
- :type ignore_conflicts: list of str
:param summary: Edit summary
:param bot: Whether to mark the edit as a bot edit
:param tags: Change tags to apply to the revision
:return: dict API output
- :rtype: dict
"""
params = {
'action': 'wbmergeitems',
--
To view, visit https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1069698?usp=email
To unsubscribe, or for help writing mail filters, visit https://gerrit.wikimedia.org/r/settings?usp=email
Gerrit-MessageType: merged
Gerrit-Project: pywikibot/core
Gerrit-Branch: master
Gerrit-Change-Id: Ia84970b146e69e44b258abc6f859d650842097dc
Gerrit-Change-Number: 1069698
Gerrit-PatchSet: 2
Gerrit-Owner: Xqt <info(a)gno.de>
Gerrit-Reviewer: Xqt <info(a)gno.de>
Gerrit-Reviewer: jenkins-bot