jenkins-bot submitted this change.

View Change

[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(-)

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.

To view, visit change 910824. To unsubscribe, or for help writing mail filters, visit settings.