jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/910824 )
Change subject: [doc] Update documentation for tools ......................................................................
[doc] Update documentation for tools
- add some examples for chars.string_to_ascii_html() and chars.string2html() which can be tested via docstring tests - ignore some tools code from coverage
Change-Id: I9811c0c1a7166933051825d30efa053345e22905 --- M pywikibot/tools/__init__.py M pywikibot/tools/chars.py M pywikibot/tools/_deprecate.py 3 files changed, 44 insertions(+), 13 deletions(-)
Approvals: Xqt: Looks good to me, approved jenkins-bot: Verified
diff --git a/pywikibot/tools/__init__.py b/pywikibot/tools/__init__.py index 1c06290..74d15ae 100644 --- a/pywikibot/tools/__init__.py +++ b/pywikibot/tools/__init__.py @@ -1,6 +1,6 @@ """Miscellaneous helper functions (not wiki-dependent).""" # -# (C) Pywikibot team, 2008-2022 +# (C) Pywikibot team, 2008-2023 # # Distributed under the terms of the MIT license. # @@ -116,7 +116,7 @@ return False if version: if not hasattr(m, '__version__'): - return False + return False # pragma: no cover
required_version = pkg_resources.parse_version(version) module_version = pkg_resources.parse_version(m.__version__) diff --git a/pywikibot/tools/_deprecate.py b/pywikibot/tools/_deprecate.py index 8995c86..1cb2fd9 100644 --- a/pywikibot/tools/_deprecate.py +++ b/pywikibot/tools/_deprecate.py @@ -19,7 +19,7 @@ deprecation decorators moved to _deprecate submodule """ # -# (C) Pywikibot team, 2008-2022 +# (C) Pywikibot team, 2008-2023 # # Distributed under the terms of the MIT license. # @@ -157,7 +157,7 @@ return inner_wrapper
if not __debug__: - return obj + return obj # pragma: no cover
return outer_wrapper
@@ -254,7 +254,7 @@ else: wrapper.__doc__ = deprecation_notice
- if not __debug__: + if not __debug__: # pragma: no cover return obj
manage_wrapping(wrapper, obj) @@ -290,7 +290,7 @@ # When called as @deprecated, return a replacement function if without_parameters: if not __debug__: - return args[0] + return args[0] # pragma: no cover
return decorator(args[0])
@@ -396,7 +396,7 @@ return obj(*__args, **__kw)
if not __debug__: - return obj + return obj # pragma: no cover
manage_wrapping(wrapper, obj)
diff --git a/pywikibot/tools/chars.py b/pywikibot/tools/chars.py index 06e85ea..6421628 100644 --- a/pywikibot/tools/chars.py +++ b/pywikibot/tools/chars.py @@ -1,6 +1,6 @@ """Character based helper functions (not wiki-dependent).""" # -# (C) Pywikibot team, 2015-2022 +# (C) Pywikibot team, 2015-2023 # # Distributed under the terms of the MIT license. # @@ -10,7 +10,7 @@ from typing import Union from urllib.parse import unquote_to_bytes
-from pywikibot.backports import List, Tuple +from pywikibot.backports import Iterable from pywikibot.tools._unidata import _category_cf
@@ -45,6 +45,15 @@ def string_to_ascii_html(string: str) -> str: """Convert unicode chars of str to HTML entities if chars are not ASCII.
+ **Example:** + + >>> string_to_ascii_html('Python') + 'Python' + >>> string_to_ascii_html("Pywikibot's API") + "Pywikibot's API" + >>> string_to_ascii_html('Eetße Joohunndot füür Kreůßtůß') + 'Eetße Joohunndot füür Kreůßtůß' + :param string: String to update """ html = [] @@ -64,6 +73,17 @@ return it unchanged. Otherwise encode the non-ASCII characters into HTML &#; entities.
+ **Example:** + + >>> string2html('Referências', 'utf-8') + 'Referências' + >>> string2html('Referências', 'ascii') + 'Referências' + >>> string2html('脚注', 'euc_jp') + '脚注' + >>> string2html('脚注', 'iso-8859-1') + '脚注' + :param string: String to update :param encoding: Encoding to use """ @@ -74,10 +94,8 @@ return string_to_ascii_html(string)
-def url2string( - title: str, - encodings: Union[str, List[str], Tuple[str, ...]] = 'utf-8' -) -> str: +def url2string(title: str, + encodings: Union[str, Iterable[str]] = 'utf-8') -> str: """Convert URL-encoded text to unicode using several encoding.
Uses the first encoding that doesn't cause an error.