jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1037926?usp=email )
Change subject: [doc] Update documentation
......................................................................
[doc] Update documentation
- remove 4th level sections in changelog to prevent sphinx section warnings
- remove "Roadmap" section and level up "Current release" and "Deprecations"
- add a new exlinks role ":source:" to link to Pywikibot's source on phab.
- use :source: in tests/README.rst to avoid references to recently removed
test documentations.
Change-Id: Ic40ef5e8d875a7fa3046b52d47ee755d92201b4c
---
M HISTORY.rst
M ROADMAP.rst
M docs/changelog.rst
M docs/conf.py
M docs/tests_ref/index.rst
M tests/README.rst
M tox.ini
7 files changed, 81 insertions(+), 103 deletions(-)
Approvals:
jenkins-bot: Verified
Xqt: Looks good to me, approved
diff --git a/HISTORY.rst b/HISTORY.rst
index 3135942..472eddc 100644
--- a/HISTORY.rst
+++ b/HISTORY.rst
@@ -1,4 +1,4 @@
-Release history
+Release History
===============
9.1.3
@@ -51,8 +51,7 @@
-----
*08 March 2024*
-Improvements
-^^^^^^^^^^^^
+**Improvements**
* Python 3.13 is supported
* Update :mod:`tools`._unidata._category_cf from Unicodedata version 15.1.0
@@ -74,8 +73,7 @@
* L10N and i18n updates
* Add :class:`pagegenerators.PagePilePageGenerator` (:phab:`T353086`)
-Bugfixes
-^^^^^^^^
+**Bugfixes**
* :meth:`Timestamp.now()<pywikibot.time.Timestamp.now>` and
:meth:`Timestamp.fromtimestamp()<pywikibot.time.Timestamp.fromtimestamp>` also returns a
@@ -93,8 +91,7 @@
* :func:`pywikibot.input_choice` validates *default* parameter (:phab:`T353097`)
* Remove typing imports from user-config.py file (:phab:`T352965`)
-Breaking changes and code cleanups
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+**Breaking changes and code cleanups**
* Cache directory was renamed from ``apicache-py3`` to ``apicache`` due to timestamp changes. (:phab:`T337748`)
**Warning:** Do not use Pywikibot 9+ together with Pywikibot 3.0.20181203 and below.
@@ -350,8 +347,7 @@
-----
*21 January 2023*
-Improvements
-^^^^^^^^^^^^
+**Improvements**
* Allow copying timezone from timestamp in :class:`pywikibot.WbTime` (:phab:`T325864`)
* Support federated Wikibase (:phab:`T173195`)
@@ -390,8 +386,7 @@
* Adjust subprocess args in :mod:`tools.djvu`
* Short site value can be given if site code is equal to family like ``-site:meta`` or ``-site:commons``
-Documentation improvements
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+**Documentation improvements**
* Add highlighting to targeted code snippet within documentation (:phab:`T323800`)
* Add previous, next, index, and modules links to documentation sidebar (:phab:`T323803`)
@@ -400,8 +395,7 @@
* Use ``Furo`` sphinx theme instead of ``Natural`` and improve documentation look and feel (:phab:`T322212`)
* MediaWiki API cross reference was added to the documentation
-Bugfixes
-^^^^^^^^
+**Bugfixes**
* Fix representation string for :class:`page.Claim` stub instances (:phab:`T326453`)
* Don't raise StopIteration in :meth:`login.LoginManager.check_user_exists`
@@ -413,8 +407,7 @@
* Fix disolving script_paths for site-package (:phab:`T320530`)
* Respect limit argument with Board.topics() (:phab:`T138215`, :phab:`T138307`)
-Breaking changes
-^^^^^^^^^^^^^^^^
+**Breaking changes**
* ``mwparserfromhell`` package is mandatory (:phab:`T326498`)
* Several package dependencies were updated
@@ -430,8 +423,7 @@
* Python 3.5 support was dropped (:phab:`T301908`)
* *See also Code cleanups below*
-Code cleanups
-^^^^^^^^^^^^^
+**Code cleanups**
* ``maintenance/sorting_order`` script was removed (:phab:`T325426`)
* ``alphabetic_sv`` and ``interwiki_putfirst`` attributes of
@@ -649,8 +641,7 @@
-----
*26 February 2022*
-Improvements
-^^^^^^^^^^^^
+**Improvements**
* i18n updates for date.py
* Add number transliteration of 'lo', 'ml', 'pa', 'te' to NON_LATIN_DIGITS
@@ -695,8 +686,7 @@
* Adjust groupsize within pagegenerators.PreloadingGenerator (:phab:`T291770`)
* New "maxlimit" property was added to APISite (:phab:`T291770`)
-Bugfixes
-^^^^^^^^
+**Bugfixes**
* Don't raise an exception if BlockEntry initializer found a hidden title (:phab:`T78152`)
* Fix KeyError in create_warnings_list (:phab:`T301610`)
@@ -716,16 +706,14 @@
* Make site parameter of textlib.replace_links() mandatory (:phab:`T294649`)
* Raise a generic ServerError if the http status code is unofficial (:phab:`T293208`)
-Breaking changes
-^^^^^^^^^^^^^^^^
+**Breaking changes**
* Support of Python 3.5.0 - 3.5.2 has been dropped (:phab:`T286867`)
* generate_user_files.py, generate_user_files.py, shell.py and version.py were moved to pywikibot/scripts and must be
used with pwb wrapper script
* *See also Code cleanups below*
-Code cleanups
-^^^^^^^^^^^^^
+**Code cleanups**
* Deprecated http.get_fake_user_agent() function was removed
* FilePage.fileIsShared() was removed in favour of FilePage.file_is_shared()
@@ -894,8 +882,7 @@
-----
*28 May 2021*
-Improvements and Bugfixes
-^^^^^^^^^^^^^^^^^^^^^^^^^
+**Improvements and Bugfixes**
* Use different logfiles for multiple processes of the same script (:phab:`T56685`)
* throttle.pip will be reused as soon as possbile
@@ -910,8 +897,7 @@
* Fix __getattr__ for WikibaseEntity (:phab:`T281389`)
* Handle abusefilter-{disallow,warning} codes (:phab:`T85656`)
-Code cleanups
-^^^^^^^^^^^^^
+**Code cleanups**
* MultipleSitesBot.site attribute was removed (:phab:`T283209`)
* Deprecated BaseSite.category_namespaces() method was removed
@@ -939,8 +925,7 @@
-----
*17 April 2021*
-Improvements and Bugfixes
-^^^^^^^^^^^^^^^^^^^^^^^^^
+**Improvements and Bugfixes**
* interwiki_graph module was restored (:phab:`T223826`)
* proofreadpage: search for "new" class after purge (:phab:`T280357`)
@@ -954,8 +939,7 @@
* L10N updates
* Family files can be collected from a zip folder (:phab:`T278076`)
-Dependencies
-^^^^^^^^^^^^
+**Dependencies**
* **mwparserfromhell** or **wikitextparser** are strictly recommended (:phab:`T106763`)
* Require **Pillow**>=8.1.1 due to vulnerability found (:phab:`T278743`)
@@ -963,8 +947,7 @@
* Enable textlib.extract_templates_and_params with **wikitextparser** package
* Add support for **PyMySQL** 1.0.0+
-Code cleanups
-^^^^^^^^^^^^^
+**Code cleanups**
* APISite.resolvemagicwords(), BaseSite.ns_index() and remove BaseSite.getNamespaceIndex() were removed
* Deprecated MoveEntry.new_ns() and new_title() methods were removed
@@ -986,8 +969,7 @@
-----
*16 March 2021*
-Breaking changes
-^^^^^^^^^^^^^^^^
+**Breaking changes**
* interwiki_graph module was removed (:phab:`T223826`)
* Require setuptools >= 20.2 due to :pep:`440`
@@ -996,8 +978,7 @@
* Return requests.Response with http.request() instead of plain text (:phab:`T265206`)
* config.db_hostname has been renamed to db_hostname_format
-Code cleanups
-^^^^^^^^^^^^^
+**Code cleanups**
* tools.PY2 was removed (:phab:`T213287`)
* Site.language() method was removed in favour of Site.lang property
@@ -1014,8 +995,7 @@
* Unused comms.threadedhttp module was removed; threadedhttp.HttpRequest was already replaced with requests.Response
(:phab:`T265206`)
-Other changes
-^^^^^^^^^^^^^
+**Other changes**
* Raise a SiteDefinitionError if api request response is Non-JSON and site is AutoFamily (:phab:`T272911`)
* Support deleting and undeleting specific file versions (:phab:`T276725`)
@@ -1798,8 +1778,8 @@
* Localisation updates
* CODE_OF_CONDUCT included
-Bugfixes
-^^^^^^^^
+**Bugfixes**
+
* Manage temporary readonly error (:phab:`T154011`)
* Unbreak wbGeoShape and WbTabularData (:phab:`T166362`)
* Clean up issue with _WbDataPage (:phab:`T166362`)
@@ -1809,8 +1789,8 @@
* Add colon when replacing category and file weblink (:phab:`T127745`)
* API Request: set uiprop only when ensuring 'userinfo' in meta (:phab:`T169202`)
-Improvements
-^^^^^^^^^^^^
+**Improvements**
+
* Introduce the new WbUnknown data type for Wikibase (:phab:`T165961`)
* djvu.py: add replace_page() and delete_page()
* Build GeoShape and TabularData from shared base class
@@ -1833,8 +1813,8 @@
* Allow pywikibot to authenticate against a private wiki (:phab:`T153903`)
* Make WbRepresentations hashable (:phab:`T167827`)
-Updates
-^^^^^^^
+**Updates**
+
* Update linktails
* Update languages_by_size
* Update cross_allowed (global bot wikis group)
@@ -1855,8 +1835,8 @@
* Bugfixes and improvements
* Localisation updates
-Bugfixes
-^^^^^^^^
+**Bugfixes**
+
* Increase the default socket_timeout to 75 seconds (:phab:`T163635`)
* use repr() of exceptions to prevent UnicodeDecodeErrors (:phab:`T120222`)
* Handle offset mismatches during chunked upload (:phab:`T156402`)
@@ -1868,8 +1848,8 @@
* getInternetArchiveURL: Retry http.fetch if there is a ConnectionError (:phab:`T164208`)
* Remove wikidataquery from pywikibot (:phab:`T162585`)
-Improvements
-^^^^^^^^^^^^
+**Improvements**
+
* Introduce user_add_claim and allow asynchronous ItemPage.addClaim (:phab:`T87493`)
* Enable private edit summary in specialbots (:phab:`T162527`)
* Make a decorator for asynchronous methods
@@ -1895,8 +1875,8 @@
* Add support for tabular-data Wikibase data type (:phab:`T163981`)
* Get thumburl information in FilePage() (:phab:`T137011`)
-Updates
-^^^^^^^
+**Updates**
+
* Update languages_by_size in family files
* wikisource_family.py: Add "pa" to languages_by_size
* Config2: limit the number of retries to 15 (:phab:`T165898`)
@@ -1910,8 +1890,8 @@
* requests package is mandatory
* Deprecate previous 2.0 branches and tags
-Bugfixes
-^^^^^^^^
+**Bugfixes**
+
* Use default summary when summary value does not contain a string (:phab:`T160823`)
* Enable specialbots.py for PY3 (:phab:`T161457`)
* Change tw(n)translate from Site.code to Site.lang dependency (:phab:`T140624`)
@@ -1932,8 +1912,8 @@
* Fix for positional_arg behavior of GeneratorFactory (:phab:`T155227`)
* Fix broken LDAP based login (:phab:`T90149`)
-Improvements
-^^^^^^^^^^^^
+**Improvements**
+
* Simplify User class
* Renamed isImage and isCategory
* Add -property option to pagegenerators.py
@@ -1951,8 +1931,8 @@
* GeneratorFactory: make getCategory respect self.site (:phab:`T155687`)
* Fix and improve default regexes
-Updates
-^^^^^^^
+**Updates**
+
* Update linktrails
* Update languages_by_size
* Updating global bot wikis, closed wikis and deleted wikis
@@ -1973,8 +1953,8 @@
* Last stable 2.0 branch
-Bugfixes
-^^^^^^^^
+**Bugfixes**
+
* Establish the project's name, once and for all
* setup.py: Add Python 3.4 and 3.5 to pypi classifiers
* Remove item count output in page generators
@@ -2008,8 +1988,8 @@
*15 December 2015*
-Bugfixes
-^^^^^^^^
+**Bugfixes**
+
* Remove dependency on pYsearch
* Require google>=0.7
* Desupport Python 2.6 for Pywikibot 2.0 release branch
@@ -2042,8 +2022,8 @@
*30 September 2015*
-Bugfixes
-^^^^^^^^
+**Bugfixes**
+
* New Wikipedia site: azb
* Indexes in str.format
* MediaWikiVersion: Accept new wmf style
@@ -2058,19 +2038,19 @@
*9 July 2015*
-Configuration updates
-^^^^^^^^^^^^^^^^^^^^^
+**Configuration updates**
+
* Changing the sandbox content template on Fa WP
-Family file updates
-^^^^^^^^^^^^^^^^^^^
+**Family file updates**
+
* Remove broken wikis from battlestarwiki family
* Adding euskara and sicilianu languages to Vikidia family
* WOW Wiki subdomains hr, ro & sr deleted
* Add new Wikipedia languages gom and lrc
-Bugfixes
-^^^^^^^^
+**Bugfixes**
+
* fix UnicodeDecodeError on api error
* pwb.py now correctly passes arguments to generate_family_file
* Fix Win32 config.editor detection
@@ -2091,7 +2071,7 @@
*25 May 2015*
-Major improvements include:
+**Major improvements**
* Sphinx documentation at https://doc.wikimedia.org/pywikibot/
* Initial ProofreadPage support
@@ -2101,7 +2081,7 @@
* isbn.py now supports wikibase
* RecentChanges stream (rcstream) support
-Pywikibot API improvements include:
+**Pywikibot API improvements**
* Python 3 ipaddress support
* Support for Python warning system
@@ -2119,7 +2099,7 @@
* FilePage.latest_file_info and FilePage.oldest_file_info added
* ItemClaimFilterPageGenerator added
-Low-level changes include:
+**Low-level changes**
* Switch to JSON-based i18n data format
* Unicode_literals used throughout source code
@@ -2130,7 +2110,7 @@
* PageNotFound exception is no longer used
* UserActionRefuse exception was replaced by UserRightsError and NotEmailableError
-Other changes include:
+**Other changes**
* Python 3 support fixes
* Daemonize support
diff --git a/ROADMAP.rst b/ROADMAP.rst
index 30a077d..8450056 100644
--- a/ROADMAP.rst
+++ b/ROADMAP.rst
@@ -1,11 +1,11 @@
-Current release
----------------
+Current Release Changes
+=======================
* Raise :exc:`exceptions.SectionError` if a section does not exists on a page (:phab:`T107141`)
* Retry api request on ServerError (:phab:`T364275`, :phab:`T364393`)
-Deprecations
-------------
+New Deprecations
+================
* 9.2.0: *total* argument in ``-logevents`` pagegenerators option is deprecated;
use ``-limit`` instead (:phab:`T128981`)
@@ -55,8 +55,8 @@
:attr:`Page.latest_revision.timestamp<page.BasePage.latest_revision>`
-Will be removed in Pywikibot 10
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Pending removal in Pywikibot 10
+-------------------------------
* 9.1.0: :func:`version.svn_rev_info` and :func:`version.getversion_svn` will be removed. SVN is no longer supported.
(:phab:`T362484`)
diff --git a/docs/changelog.rst b/docs/changelog.rst
index b12b4ac..de64526 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -4,9 +4,6 @@
What is new with Pywikibot |release|? What are the main changes of older version?
-Roadmap
-=======
-
.. include:: ../ROADMAP.rst
.. include:: ../HISTORY.rst
diff --git a/docs/conf.py b/docs/conf.py
index c3e10fe..e5b0360 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -503,6 +503,10 @@
'pylib': ('https://docs.python.org/3/library/%s', 'Python Library %s'),
# Generic Python link; should be used with explicit title
'python': ('https://docs.python.org/3/%s', None),
+ # Pywikibot source (on Phabricator)
+ 'source': (
+ 'https://phabricator.wikimedia.org/diffusion/PWBC/browse/master/%s.py',
+ '%s'),
}
diff --git a/docs/tests_ref/index.rst b/docs/tests_ref/index.rst
index 7f069a9..4c782e3 100644
--- a/docs/tests_ref/index.rst
+++ b/docs/tests_ref/index.rst
@@ -9,11 +9,9 @@
Test utilities
**************
-Tests in this project:
-
.. toctree::
- :maxdepth: 1
+ :titlesonly:
- aspects
- basepage
- utils
+ aspects
+ basepage
+ utils
diff --git a/tests/README.rst b/tests/README.rst
index a6f1265..e72ecd7 100644
--- a/tests/README.rst
+++ b/tests/README.rst
@@ -17,8 +17,8 @@
Running tests
=============
-All tests
----------
+Run all tests
+-------------
The entire suite of tests may be run in the following ways from the root directory:
@@ -41,8 +41,8 @@
tox
-Specific tests
---------------
+Run specific tests
+------------------
Individual test components can be run using unittest, pytest or pwb.
With -lang and -family or -site options pwb can be used to specify a site.
@@ -99,7 +99,7 @@
=====================
**PYWIKIBOT_TEST_GUI**
- Enable :mod:`tests.gui_tests`. Used for AppVeyor tests. GitHub actions would
+ Enable :source:`tests/gui_tests`. Used for AppVeyor tests. GitHub actions would
fail due to ``couldn't connect to display ":1.0"`` error. Set this environment
variable to run this test locally::
@@ -107,7 +107,7 @@
**PYWIKIBOT_TEST_LOGOUT**
Used when a test is logging out the test user. This environment variable
- enables :mod:`tests.site_login_logout_tests`. The environment setting is
+ enables :source:`tests/site_login_logout_tests`. The environment setting is
needed to ensure that these tests run in their own test action and does not
interfere with other tests. Otherwise they could fail if the test user is
logged out by the test. Only one instance must run this test script. Set this
@@ -117,10 +117,9 @@
**PYWIKIBOT_TEST_MODULES**
Only run tests given with this environment variable. Multiple tests must be
- separated by a ``,`` without any white space. Available library tests are
- listed in :ref:`Library tests` and script tests can be found in
- :ref:`Script tests`. To enable only :mod:`tests.site_tests` and
- :mod:`tests.wikibase_tests` set the environment variable as::
+ separated by a ``,`` without any white space. For example to enable only
+ :source:`tests/site_tests` and :source:`tests/wikibase_tests` set the
+ environment variable as::
PYWIKIBOT_TEST_MODULES=site,wikibase
@@ -135,7 +134,7 @@
**PYWIKIBOT_TEST_OAUTH**
This environment variable holds the Oauth token. It is set by
``oauth_tests-ci.yml`` CI config file and is solely used by
- :mod:`tests.oauth_tests`. You can use it for your private tests. The
+ :source:`tests/oauth_tests`. You can use it for your private tests. The
environment variable must contain consumer key and secret and access
key and secret delimited by ``:`` as::
@@ -151,7 +150,7 @@
**PYWIKIBOT_TEST_RUNNING**
This environment variable skips tests instead of raising
:exc:`exceptions.MaxlagTimeoutError` when maximum retries attempted due to
- maxlag without success. It is also used by :mod:`tests.script_tests` for code
+ maxlag without success. It is also used by :source:`tests/script_tests` for code
coverage. GitHub actions and AppVeyor tests activate this variable::
PYWIKIBOT_TEST_RUNNING=1
diff --git a/tox.ini b/tox.ini
index 2ca9de4..c254410 100644
--- a/tox.ini
+++ b/tox.ini
@@ -100,7 +100,7 @@
basepython = python3.9
commands =
rstcheck --version
- rstcheck -r --report-level WARNING --ignore-roles api,phab .
+ rstcheck -r --report-level WARNING --ignore-roles api,phab,source .
deps =
-rrequirements.txt
-rdocs/requirements.txt
--
To view, visit https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1037926?usp=email
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: Ic40ef5e8d875a7fa3046b52d47ee755d92201b4c
Gerrit-Change-Number: 1037926
Gerrit-PatchSet: 3
Gerrit-Owner: Xqt <info(a)gno.de>
Gerrit-Reviewer: Xqt <info(a)gno.de>
Gerrit-Reviewer: jenkins-bot
Gerrit-MessageType: merged
jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1033691?usp=email )
Change subject: [Fix] Add namespaces parameter to BasePage.templates and itertemplates
......................................................................
[Fix] Add namespaces parameter to BasePage.templates and itertemplates
- add namespaces parameter to BasePage.templates() and require
keyworded arguments. Retrieve all pages from API:Templates and filter
namespace on return. Update documentation.
- add namespaces parameter to BasePage.itertemplates() and require
keyworded arguments except for total (otherwise the positional
arguments cannot be deprecated if the total will be the last argument
later like in APISite.pagetemplates().
- only use pages in TEMPLATE namespaces within BasePage.isDisambig()
because the other pages are also in that namespace. Use tempates()
instead of itertemplates() here to cache. Use site method disambig()
instead of Family.disambig(). Update documentations.
- Update documentation in APISite.pagetemplates(), reorder keyword
parameters which are keyword only.
- use TEMPLATE namespace to get templates in Page.templatesWithParams
because the namespace of the links to be compared is TEMPLATE too.
Use itertemplates here because the result can be cached by the
calling method. This solves T365199.
- use TEMPLATE namespace to get templates in commonscat.py and
solve_disambiguation.py scripts because "real" templates are
requuired here.
- update utils.DryParamInfo class for pg tests
Bug: T365199
Change-Id: I0e82e889039f3e9cbf36f5faf038331d8a17d3fe
---
M docs/api_ref/pywikibot.site.rst
M pywikibot/family.py
M pywikibot/page/_basepage.py
M pywikibot/page/_page.py
M pywikibot/site/_generators.py
M scripts/commonscat.py
M scripts/solve_disambiguation.py
M tests/utils.py
8 files changed, 129 insertions(+), 58 deletions(-)
Approvals:
Xqt: Looks good to me, approved
jenkins-bot: Verified
diff --git a/docs/api_ref/pywikibot.site.rst b/docs/api_ref/pywikibot.site.rst
index 1380d73..347430b 100644
--- a/docs/api_ref/pywikibot.site.rst
+++ b/docs/api_ref/pywikibot.site.rst
@@ -61,12 +61,15 @@
:rtype: tuple[str, ...]
- .. method:: disambig(fallback: str = '_default')
+ .. method:: disambig(fallback = '_default')
Return list of disambiguation templates.
.. seealso:: :meth:`family.Family.disambig`
+ :param str | None fallback:
+ :rtype: list[str]
+
.. method:: protocol()
diff --git a/pywikibot/family.py b/pywikibot/family.py
index 79042e7..22961fd 100644
--- a/pywikibot/family.py
+++ b/pywikibot/family.py
@@ -453,8 +453,11 @@
"""
return self.archived_page_templates.get(code, ())
- def disambig(self, code, fallback: str = '_default'):
- """Return list of disambiguation templates."""
+ def disambig(self, code, fallback: str | None = '_default') -> list[str]:
+ """Return list of disambiguation templates.
+
+ :raises KeyError: unknown title for disambig template
+ """
if code in self.disambiguationTemplates:
return self.disambiguationTemplates[code]
diff --git a/pywikibot/page/_basepage.py b/pywikibot/page/_basepage.py
index 61623b6..de45151 100644
--- a/pywikibot/page/_basepage.py
+++ b/pywikibot/page/_basepage.py
@@ -39,6 +39,7 @@
ComparableMixin,
cached,
deprecated,
+ deprecate_positionals,
first_upper,
issue_deprecation_warning,
remove_last_args,
@@ -900,18 +901,19 @@
return self.namespace() == Namespace.FILE
def isDisambig(self) -> bool:
- """
- Return True if this is a disambiguation page, False otherwise.
+ """Return True if this is a disambiguation page, False otherwise.
By default, it uses the Disambiguator extension's result. The
- identification relies on the presence of the __DISAMBIG__ magic word
- which may also be transcluded.
+ identification relies on the presence of the ``__DISAMBIG__``
+ magic word which may also be transcluded.
- If the Disambiguator extension isn't activated for the given site,
- the identification relies on the presence of specific templates.
- First load a list of template names from the Family file;
- if the value in the Family file is None or no entry was made, look for
- the list on [[MediaWiki:Disambiguationspage]]. If this page does not
+ If the Disambiguator extension isn't activated for the given
+ site, the identification relies on the presence of specific
+ templates. First load a list of template names from the
+ :class:`Family<family.Family>` file via :meth:`BaseSite.disambig()
+ <pywikibot.site._basesite.BaseSite.disambig>`; if the value in
+ the Family file not found, look for the list on
+ ``[[MediaWiki:Disambiguationspage]]``. If this page does not
exist, take the MediaWiki message. 'Template:Disambig' is always
assumed to be default, and will be appended regardless of its
existence.
@@ -925,19 +927,25 @@
default = set(self.site.family.disambig('_default'))
except KeyError:
default = {'Disambig'}
+
try:
- distl = self.site.family.disambig(self.site.code,
- fallback=False)
+ distl = self.site.disambig(fallback=False)
except KeyError:
distl = None
- if distl is None:
+
+ if distl:
+ # Normalize template capitalization
+ self.site._disambigtemplates = {first_upper(t) for t in distl}
+ else:
+ # look for the list on [[MediaWiki:Disambiguationspage]]
disambigpages = pywikibot.Page(self.site,
'MediaWiki:Disambiguationspage')
if disambigpages.exists():
disambigs = {link.title(with_ns=False)
for link in disambigpages.linkedPages()
- if link.namespace() == 10}
+ if link.namespace() == Namespace.TEMPLATE}
elif self.site.has_mediawiki_message('disambiguationspage'):
+ # take the MediaWiki message
message = self.site.mediawiki_message(
'disambiguationspage').split(':', 1)[1]
# add the default template(s) for default mw message
@@ -946,16 +954,16 @@
else:
disambigs = default
self.site._disambigtemplates = disambigs
- else:
- # Normalize template capitalization
- self.site._disambigtemplates = {first_upper(t) for t in distl}
- templates = {tl.title(with_ns=False) for tl in self.templates()}
+
+ templates = {tl.title(with_ns=False)
+ for tl in self.templates(namespaces=Namespace.TEMPLATE)}
disambigs = set()
# always use cached disambig templates
disambigs.update(self.site._disambigtemplates)
# see if any template on this page is in the set of disambigs
disambig_in_page = disambigs.intersection(templates)
- return self.namespace() != 10 and bool(disambig_in_page)
+ return (self.namespace() != Namespace.TEMPLATE
+ and bool(disambig_in_page))
def getReferences(self,
follow_redirects: bool = True,
@@ -1601,17 +1609,33 @@
"""Convenience function to get the Wikibase item of a page."""
return pywikibot.ItemPage.fromPage(self)
- def templates(self, content: bool = False) -> list[pywikibot.Page]:
- """
- Return a list of Page objects for templates used on this Page.
+ @deprecate_positionals(since='9.2')
+ def templates(self,
+ *,
+ content: bool = False,
+ namespaces: NamespaceArgType = None) -> list[pywikibot.Page]:
+ """Return a list of Page objects for templates used on this Page.
- Template parameters are ignored. This method only returns embedded
- templates, not template pages that happen to be referenced through
- a normal link.
+ This method returns a list of pages which are embedded as
+ templates even they are not in the TEMPLATE: namespace. This
+ method caches the result. If *namespaces* is used, all pages are
+ retrieved and cached but the result is filtered.
+
+ .. versionchanged:: 2.0
+ a list of :class:`pywikibot.Page` is returned instead of a
+ list of template titles. The given pages may have namespaces
+ different from TEMPLATE namespace. *get_redirect* parameter
+ was removed.
+ .. versionchanged:: 9.2
+ *namespaces* parameter was added; all parameters must be given
+ as keyword arguments.
+
+ .. seealso::
+ - :meth:`itertemplates`
:param content: if True, retrieve the content of the current version
of each template (default False)
- :param content: bool
+ :param namespaces: Only iterate pages in these namespaces
"""
# Data might have been preloaded
# Delete cache if content is needed and elements have no content
@@ -1620,32 +1644,53 @@
and not all(t.has_content() for t in self._templates)):
del self._templates
+ # retrieve all pages in _templates and filter namespaces later
if not hasattr(self, '_templates'):
self._templates = set(self.itertemplates(content=content))
+ if namespaces is not None:
+ ns = self.site.namespaces.resolve(namespaces)
+ return [t for t in self._templates if t.namespace() in ns]
+
return list(self._templates)
+ @deprecate_positionals(since='9.2')
def itertemplates(
self,
total: int | None = None,
+ *,
content: bool = False,
+ namespaces: NamespaceArgType = None
) -> Iterable[pywikibot.Page]:
- """
- Iterate Page objects for templates used on this Page.
+ """Iterate Page objects for templates used on this Page.
- Template parameters are ignored. This method only returns embedded
- templates, not template pages that happen to be referenced through
- a normal link.
+ This method yield pages embedded as templates even they are not
+ in the TEMPLATE: namespace. The retrieved pages are not cached
+ but they can be yielded from the cache of a previous
+ :meth:`templates` call.
+
+ .. versionadded:: 2.0
+ .. versionchanged:: 9.2
+ *namespaces* parameter was added; all parameters except
+ *total* must be given as keyword arguments.
+
+ .. seealso::
+ - :meth:`site.APISite.pagetemplates()
+ <pywikibot.site._generators.GeneratorsMixin.pagetemplates>`
+ - :meth:`templates`
+ - :meth:`getReferences`
:param total: iterate no more than this number of pages in total
:param content: if True, retrieve the content of the current version
of each template (default False)
- :param content: bool
+ :param namespaces: Only iterate pages in these namespaces
"""
if hasattr(self, '_templates'):
- return itertools.islice(self.templates(content=content), total)
+ return itertools.islice(self.templates(
+ content=content, namespaces=namespaces), total)
- return self.site.pagetemplates(self, total=total, content=content)
+ return self.site.pagetemplates(
+ self, content=content, namespaces=namespaces, total=total)
def imagelinks(
self,
diff --git a/pywikibot/page/_page.py b/pywikibot/page/_page.py
index 60573f6..8dcda60 100644
--- a/pywikibot/page/_page.py
+++ b/pywikibot/page/_page.py
@@ -9,7 +9,7 @@
itself, including its contents.
"""
#
-# (C) Pywikibot team, 2008-2023
+# (C) Pywikibot team, 2008-2024
#
# Distributed under the terms of the MIT license.
#
@@ -27,6 +27,7 @@
)
from pywikibot.page._basepage import BasePage
from pywikibot.page._toolforge import WikiBlameMixin
+from pywikibot.site import Namespace
from pywikibot.tools import cached
@@ -58,7 +59,9 @@
"""
return textlib.extract_templates_and_params(self.text, True, True)
- def templatesWithParams(self): # noqa: N802
+ def templatesWithParams( # noqa: N802
+ self,
+ ) -> list[tuple[pywikibot.Page, list[str]]]:
"""Return templates used on this Page.
The templates are extracted by :meth:`raw_extracted_templates`,
@@ -68,14 +71,14 @@
All parameter keys and values for each template are stripped of
whitespace.
- :return: a list of tuples with one tuple for each template invocation
- in the page, with the template Page as the first entry and a list
- of parameters as the second entry.
- :rtype: list of (pywikibot.page.Page, list)
+ :return: a list of tuples with one tuple for each template
+ invocation in the page, with the template Page as the first
+ entry and a list of parameters as the second entry.
"""
# WARNING: may not return all templates used in particularly
# intricate cases such as template substitution
- titles = {t.title() for t in self.templates()}
+ titles = {t.title()
+ for t in self.itertemplates(namespaces=Namespace.TEMPLATE)}
templates = self.raw_extracted_templates
# backwards-compatibility: convert the dict returned as the second
# element into a list in the format used by old scripts
@@ -83,7 +86,7 @@
for template in templates:
try:
link = pywikibot.Link(template[0], self.site,
- default_namespace=10)
+ default_namespace=Namespace.TEMPLATE)
if link.canonical_title() not in titles:
continue
except Error:
diff --git a/pywikibot/site/_generators.py b/pywikibot/site/_generators.py
index 1ee5a29..af2aa43 100644
--- a/pywikibot/site/_generators.py
+++ b/pywikibot/site/_generators.py
@@ -504,21 +504,29 @@
self,
page: pywikibot.Page,
*,
+ content: bool = False,
namespaces: NamespaceArgType = None,
total: int | None = None,
- content: bool = False,
) -> Iterable[pywikibot.Page]:
- """Iterate templates transcluded (not just linked) on the page.
+ """Iterate pages transcluded (not just linked) on the page.
- .. seealso:: :api:`Templates`
+ .. note: You should not use this method directly; use
+ :meth:`pywikibot.Page.itertemplates` instead.
+ .. seealso::
+ - :api:`Templates`
+ - :meth:`page.BasePage.itertemplates`
+
+ :param content: if True, load the current content of each
+ iterated page (default False)
:param namespaces: Only iterate pages in these namespaces
- :param content: if True, load the current content of each iterated page
- (default False)
+ :param total: maximum number of pages to retrieve in total
:raises KeyError: a namespace identifier was not resolved
:raises TypeError: a namespace identifier has an inappropriate
type such as NoneType or bool
+ :raises UnsupportedPageError: a Page object is not supported due
+ to namespace restriction
"""
tltitle = page.title(with_section=False).encode(self.encoding())
return self._generator(api.PageGenerator, type_arg='templates',
diff --git a/scripts/commonscat.py b/scripts/commonscat.py
index e1f3191..bbfc466 100755
--- a/scripts/commonscat.py
+++ b/scripts/commonscat.py
@@ -38,7 +38,7 @@
# *Found one template. Add this template
# *Found more templates. Ask the user <- still have to implement this
#
-# (C) Pywikibot team, 2008-2023
+# (C) Pywikibot team, 2008-2024
#
# Distributed under the terms of the MIT license.
#
@@ -50,6 +50,7 @@
from pywikibot import i18n, pagegenerators
from pywikibot.bot import ConfigParserBot, ExistingPageBot
from pywikibot.exceptions import InvalidTitleError
+from pywikibot.site import Namespace
from pywikibot.textlib import add_text
@@ -264,8 +265,9 @@
for template in templates_to_ignore:
if not isinstance(template, tuple):
- for pageTemplate in page.templates():
- if pageTemplate.title(with_ns=False) == template:
+ for page_template in page.itertemplates(
+ namespaces=Namespace.TEMPLATE):
+ if page_template.title(with_ns=False) == template:
return True
else:
for inPageTemplate, params in page.templatesWithParams():
@@ -512,7 +514,7 @@
commonsPage.getRedirectTarget().title(with_ns=False))
if (pywikibot.Page(commonsPage.site, 'Template:Category redirect')
- in commonsPage.templates()):
+ in commonsPage.itertemplates(namespaces=Namespace.TEMPLATE)):
pywikibot.log(
'getCommonscat: The category is a category redirect')
for template, param in commonsPage.templatesWithParams():
diff --git a/scripts/solve_disambiguation.py b/scripts/solve_disambiguation.py
index 26c1dae..878e048 100755
--- a/scripts/solve_disambiguation.py
+++ b/scripts/solve_disambiguation.py
@@ -107,6 +107,7 @@
NoPageError,
PageSaveRelatedError,
)
+from pywikibot.site import Namespace
from pywikibot.tools import first_lower, first_upper
from pywikibot.tools.formatter import SequenceOutputter
@@ -1037,7 +1038,8 @@
if primary:
primary_page = pywikibot.Page(page.site,
'Template:' + primary)
- if primary and primary_page in page.templates():
+ if primary and primary_page in page.itertemplates(
+ namespaces=Namespace.TEMPLATE):
baseTerm = page.title()
for template, params in page.templatesWithParams():
if params and template == primary_page:
diff --git a/tests/utils.py b/tests/utils.py
index 7ea74d1..209ac34 100644
--- a/tests/utils.py
+++ b/tests/utils.py
@@ -11,7 +11,7 @@
import sys
import unittest
import warnings
-from contextlib import contextmanager
+from contextlib import contextmanager, suppress
from subprocess import PIPE, Popen, TimeoutExpired
from typing import Any
@@ -239,10 +239,15 @@
def __getitem__(self, name):
"""Return dry data or a dummy parameter block."""
- try:
+ with suppress(KeyError):
return super().__getitem__(name)
- except KeyError:
- return {'name': name, 'limit': None}
+
+ result = {'name': name, 'prefix': '', 'limit': {}}
+
+ if name == 'query+templates':
+ result['limit'] = {'max': 1}
+
+ return result
class DummySiteinfo:
--
To view, visit https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1033691?usp=email
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: I0e82e889039f3e9cbf36f5faf038331d8a17d3fe
Gerrit-Change-Number: 1033691
Gerrit-PatchSet: 7
Gerrit-Owner: Xqt <info(a)gno.de>
Gerrit-Reviewer: Xqt <info(a)gno.de>
Gerrit-Reviewer: jenkins-bot
Gerrit-MessageType: merged