jenkins-bot has submitted this change. (
https://gerrit.wikimedia.org/r/c/pywikibot/core/+/860985 )
Change subject: [doc] Update documentation about protection
......................................................................
[doc] Update documentation about protection
Change-Id: Id92c696f68e83376db7f09b1346046d9596bbfa1
---
M pywikibot/site/_apisite.py
M pywikibot/page/_page.py
2 files changed, 106 insertions(+), 29 deletions(-)
Approvals:
Bináris: Looks good to me, but someone else must approve
Xqt: Looks good to me, approved
jenkins-bot: Verified
diff --git a/pywikibot/page/_page.py b/pywikibot/page/_page.py
index bd2283a..1b424ed 100644
--- a/pywikibot/page/_page.py
+++ b/pywikibot/page/_page.py
@@ -31,7 +31,15 @@
import pywikibot
from pywikibot import Timestamp, config, date, i18n, textlib
-from pywikibot.backports import Generator, Iterable, Iterator, List, Set
+from pywikibot.backports import (
+ Dict,
+ Generator,
+ Iterable,
+ Iterator,
+ List,
+ Set,
+ Tuple,
+)
from pywikibot.cosmetic_changes import CANCEL, CosmeticChangesToolkit
from pywikibot.exceptions import (
Error,
@@ -1049,12 +1057,38 @@
content=content,
)
- def protection(self) -> dict:
- """Return a dictionary reflecting page protections."""
+ def protection(self) -> Dict[str, Tuple[str, str]]:
+ """Return a dictionary reflecting page protections.
+
+ **Example:**
+
+ >>> site = pywikibot.Site('wikipedia:test')
+ >>> page = pywikibot.Page(site, 'Main Page')
+ >>> page.protection()
+ {'edit': ('sysop', 'infinity'), 'move': ('sysop', 'infinity')}
+
+ .. seealso::
+ - :meth:`Site.page_restrictions()
+ <pywikibot.site._apisite.APISite.page_restrictions>`
+ - :meth:`applicable_protections`
+ - :meth:`protect`
+ """
return self.site.page_restrictions(self)
def applicable_protections(self) -> Set[str]:
- """Return the protection types allowed for that page."""
+ """Return the protection types allowed for that page.
+
+ **Example:**
+
+ >>> site = pywikibot.Site('wikipedia:test')
+ >>> page = pywikibot.Page(site, 'Main Page')
+ >>> sorted(page.applicable_protections())
+ ['edit', 'move']
+
+ .. seealso::
+ - :meth:`protect`
+ - :meth:`protection`
+ """
self.site.loadpageinfo(self)
return self._applicable_protections
@@ -2008,27 +2042,35 @@
def protect(self,
reason: Optional[str] = None,
- protections: Optional[dict] = None,
+ protections: Optional[Dict[str, Optional[str]]] = None,
**kwargs) -> None:
- """
- Protect or unprotect a wiki page. Requires administrator status.
+ """Protect or unprotect a wiki page. Requires *protect* right.
- Valid protection levels are '' (equivalent to 'none'),
- 'autoconfirmed', 'sysop' and 'all'. 'all' means 'everyone is allowed',
- i.e. that protection type will be unprotected.
+ Valid protection levels are ``''`` (equivalent to ``None``),
+ ``'autoconfirmed'``, ``'sysop'`` and ``'all'``. ``'all'`` means
+ everyone is allowed, i.e. that protection type will be
+ unprotected.
- In order to unprotect a type of permission, the protection level shall
- be either set to 'all' or '' or skipped in the protections dictionary.
+ In order to unprotect a type of permission, the protection level
+ shall be either set to ``'all'`` or ``''`` or skipped in the
+ protections dictionary.
- Expiry of protections can be set via kwargs, see Site.protect() for
+ Expiry of protections can be set via *kwargs*, see
+ :meth:`Site.protect()<pywikibot.site._apisite.APISite.protect>` for
details. By default there is no expiry for the protection types.
- :param protections: A dict mapping type of protection to protection
- level of that type. Allowed protection types for a page can be
- retrieved by Page.self.applicable_protections()
+ .. seealso::
+ - :meth:`Site.protect()
+ <pywikibot.site._apisite.APISite.protect>`
+ - :meth:`applicable_protections`
+
+ :param protections: A dict mapping type of protection to
+ protection level of that type. Allowed protection types for
+ a page can be retrieved by :meth:`applicable_protections`.
Defaults to protections is None, which means unprotect all
protection types.
- Example: {'move': 'sysop', 'edit': 'autoconfirmed'}
+
+ Example: ``{'move': 'sysop', 'edit': 'autoconfirmed'}``
:param reason: Reason for the action, default is None and will set an
empty string.
diff --git a/pywikibot/site/_apisite.py b/pywikibot/site/_apisite.py
index c892912..da2b051 100644
--- a/pywikibot/site/_apisite.py
+++ b/pywikibot/site/_apisite.py
@@ -55,7 +55,7 @@
)
from pywikibot.login import LoginStatus as _LoginStatus
from pywikibot.site._basesite import BaseSite
-from pywikibot.site._decorators import need_right
+from pywikibot.site._decorators import need_right, need_version
from pywikibot.site._extensions import (
EchoMixin,
FlowMixin,
@@ -1393,7 +1393,17 @@
self,
page: 'pywikibot.page.BasePage'
) -> Dict[str, Tuple[str, str]]:
- """Return a dictionary reflecting page protections."""
+ """Return a dictionary reflecting page protections.
+
+ **Example:**
+
+ >>> site = pywikibot.Site('wikipedia:test')
+ >>> page = pywikibot.Page(site, 'Main Page')
+ >>> site.page_restrictions(page)
+ {'edit': ('sysop', 'infinity'), 'move': ('sysop', 'infinity')}
+
+ .. seealso:: :meth:`page.BasePage.protection` (should be preferred)
+ """
if not hasattr(page, '_protection'):
self.loadpageinfo(page)
return page._protection
@@ -2523,21 +2533,33 @@
"""
Return the protection types available on this site.
+ **Example:**
+
+ >>> site = pywikibot.Site('wikipedia:test')
+ >>> sorted(site.protection_types())
+ ['create', 'edit', 'move', 'upload']
+
.. seealso:: :py:obj:`Siteinfo._get_default()`
:return: protection types available
"""
return set(self.siteinfo.get('restrictions')['types'])
+ @need_version('1.27.3')
def protection_levels(self) -> Set[str]:
"""
Return the protection levels available on this site.
+ **Example:**
+
+ >>> site = pywikibot.Site('wikipedia:test')
+ >>> sorted(site.protection_levels())
+ ['', 'autoconfirmed', ... 'sysop', 'templateeditor']
+
.. seealso:: :py:obj:`Siteinfo._get_default()`
:return: protection types available
"""
- # implemented in b73b5883d486db0e9278ef16733551f28d9e096d
return set(self.siteinfo.get('restrictions')['levels'])
@need_right('protect')
@@ -2549,19 +2571,23 @@
expiry: Union[datetime.datetime, str, None] = None,
**kwargs: Any
) -> None:
- """(Un)protect a wiki page. Requires administrator status.
+ """(Un)protect a wiki page. Requires *protect* right.
- .. seealso:: :api:`Protect`
+ .. seealso::
+ - :api:`Protect`
+ - :meth:`protection_types`
+ - :meth:`protection_levels`
- :param protections: A dict mapping type of protection to protection
- level of that type. Valid restriction types are 'edit', 'create',
- 'move' and 'upload'. Valid restriction levels are '' (equivalent
- to 'none' or 'all'), 'autoconfirmed', and 'sysop'.
- If None is given, however, that protection will be skipped.
+ :param protections: A dict mapping type of protection to
+ protection level of that type. Refer :meth:`protection_types`
+ for valid restriction types and :meth:`protection_levels`
+ for valid restriction levels. If None is given, however,
+ that protection will be skipped.
:param reason: Reason for the action
:param expiry: When the block should expire. This expiry will be
- applied to all protections. If None, 'infinite', 'indefinite',
- 'never', or '' is given, there is no expiry.
+ applied to all protections. If ``None``, ``'infinite'``,
+ ``'indefinite'``, ``'never'``, or ``''`` is given, there is
+ no expiry.
"""
token = self.tokens['csrf']
self.lock_page(page)
--
To view, visit https://gerrit.wikimedia.org/r/c/pywikibot/core/+/860985
To unsubscribe, or for help writing mail filters, visit
https://gerrit.wikimedia.org/r/settings
Gerrit-Project: pywikibot/core
Gerrit-Branch: master
Gerrit-Change-Id: Id92c696f68e83376db7f09b1346046d9596bbfa1
Gerrit-Change-Number: 860985
Gerrit-PatchSet: 3
Gerrit-Owner: Xqt <i...@gno.de>
Gerrit-Reviewer: Bináris <wikipo...@gmail.com>
Gerrit-Reviewer: Dalba <dalba.w...@gmail.com>
Gerrit-Reviewer: Xqt <i...@gno.de>
Gerrit-Reviewer: jenkins-bot
Gerrit-MessageType: merged
_______________________________________________
Pywikibot-commits mailing list -- pywikibot-commits@lists.wikimedia.org
To unsubscribe send an email to pywikibot-commits-le...@lists.wikimedia.org
