Misc fixes:

grantps · grantps · commit c2bd89e3e2a2 · 2020-06-03T18:59:05.000+12:00
* Improve HTML links
* Fix shelp CLI option
* Reduce false positives identifying internal imports
* Improve line spacing of HTML links in CLI output
* Improve layout of links in CLI output
* Add comment about cross-platform benefits of pathlib
* Fix bug identifying list items when applying layout_comment
* Add tests for layout_comment
* Bump version
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 ![Example HTML output](https://github.com/grantps/superhelp/raw/master/superhelp_logo_padded_small.png)
 
-version number: 1.0.10
+version number: 1.0.11
 author: Grant Paton-Simpson
 
 ## Overview
diff --git a/setup.py b/setup.py
@@ -2,7 +2,7 @@
 from codecs import open
 from os import path
 
-__version__ = '1.0.10'
+__version__ = '1.0.11'
 
 here = path.abspath(path.dirname(__file__))
 
@@ -50,7 +50,7 @@
     python_requires='>=3.6',
     entry_points = {
         'console_scripts': [
-            'shelp=superhelp:shelp',  ## using argparse to allow arguments
+            'shelp=superhelp.helper:shelp',  ## using argparse to allow arguments
         ]
     },
 )
diff --git a/superhelp/conf.py b/superhelp/conf.py
@@ -184,7 +184,12 @@
 'uu', 'uuid', 'venv', 'warnings', 'wave', 'weakref', 'webbrowser', 'winreg',
 'winsound', 'wsgiref', 'xdrlib', 'xml', 'xmlrpc', 'zipapp', 'zipfile',
 'zipimport', 'zlib']
-POPULAR_LIBS = ['requests', 'flask', 'django', ]
+POPULAR_LIBS = ['urllib3', 'six', 'botocore', 'requests', 's3transfer', 'idna',
+    'certifi', 'python-dateutil', 'docutils', 'chardet', 'pyyaml', 'pip',
+    'jmespath', 'setuptools', 'boto3', 'rsa', 'pyasn1', 'numpy', 'wheel',
+    'pytz', 'markupsafe', 'flask', 'django', 'pandas', 'geopandas', 'bs4',
+    'requests_html', 'pipenv', 'poetry', 'scikit_learn', 'matplotlib',
+    'openpyxl', 'psycopg2', 'scrapy', 'twisted', ]
 
 SUPERHELP_PROJECT_OUTPUT = 'superhelp_project_output'
 SUPERHELP_GEN_OUTPUT = 'superhelp_output'
diff --git a/superhelp/displayers/cli_extras/ansi_printer.py b/superhelp/displayers/cli_extras/ansi_printer.py
@@ -258,7 +258,7 @@ def formatter(el, out, nesting_level=0, prefix='', parent=None):
             if links_list:
                 for i, l in enumerate(links_list, 1):
                     out.append(cli_colour.colourise_low_vis(
-                        f"{indent}[{i}] {l}"))
+                        f"{indent}[{i}] {l}\n"))
 
         if is_txt_and_inline_markup:
             if el.tag == 'li':
diff --git a/superhelp/displayers/cli_extras/cli_utils.py b/superhelp/displayers/cli_extras/cli_utils.py
@@ -262,21 +262,22 @@ def get_text_if_inline_markup(el):
 def replace_links(el, html, link_display_type='it'):
     """
     Digging through inline "<a href=..."
+
     :return: links_list, and tag
     """
     parts = html.split('<a ')
     if len(parts) == 1:
         links_list = None
         return links_list, html
     links_list, cur_link = [], 0
-    links = [l for l in el.getchildren() if "href" in l.keys()]
+    links = [l for l in el.getchildren() if 'href' in l.keys()]
     if not len(parts) == len(links) + 1:
         ## contains an html element we don't support e.g. blockquote
         links_list = None
         return links_list, html
     cur = ''
     while parts:
-        cur += parts.pop(0).rsplit("</a>")[-1]
+        cur += parts.pop(0).rsplit('</a>')[-1]
         if not parts:
             break
         
@@ -293,7 +294,7 @@ def replace_links(el, html, link_display_type='it'):
             cur += cli_colour.colourise_low_vis(f"({link_str})")
         elif link_display_type != "h":  # inline table (it)
             # we build a link list, add the number like ① :
-            cur += f"{chr(cli_conf.LINK_START_ORD + cur_link)} "
+            cur += f" {chr(cli_conf.LINK_START_ORD + cur_link)} "
             links_list.append(link_str)
         else:
             pass  ## apparently we ignore h
diff --git a/superhelp/gen_utils.py b/superhelp/gen_utils.py
@@ -97,7 +97,8 @@ def convert_to_xml(node, omit_docstrings=False, node_mappings=None):
 
 starting_num_space_pattern = r"""(?x)
     ^      ## start
-    \d{1}  ## one digit
+    \d+  ## one or more digits
+    \.?    ## optional dot
     \s{1}  ## one whitespace
     \S+    ## at least one non-whitespace
     """
@@ -511,6 +512,23 @@ def int2first_etc(num):
     }
     return nice.get(num, num)
 
+def _is_special_line(one_line_paragraph):
+    """
+    Special lines are ones we shouldn't break into sub-lines. Title, list items,
+    links etc.
+
+    :rtype: bool
+    """
+    res = starting_num_space_prog.match(one_line_paragraph)
+    if res is not None:
+        return True
+    if one_line_paragraph.startswith((
+            '#',  ## could be one hash or multiple depending on heading level
+            '* '  ## trying to detect bulleted (unordered) lists
+        )):
+        return True
+    return False
+
 def layout_comment(raw_comment, *, is_code=False):
     """
     Layout comment ready for MD. Handles dedenting and code.
@@ -548,15 +566,7 @@ def layout_comment(raw_comment, *, is_code=False):
                 len(raw_paragraph) - len(raw_paragraph.rstrip('\n')))
             paragraph = raw_paragraph.strip()
             one_line_paragraph = paragraph.replace('\n', ' ')  ## actually continuations of same line so no need to put on separate lines
-            special_line = False
-            res = starting_num_space_prog.match(one_line_paragraph)
-            if res is not None:
-                special_line = True
-            if one_line_paragraph.startswith((
-                    '#',  ## could be one hash or multiple depending on heading level
-                    '* '  ## trying to detect bulleted (unordered) lists
-                )):
-                special_line = True
+            special_line = _is_special_line(one_line_paragraph)
             if special_line:
                 wrapped_paragraph_lines = [one_line_paragraph, ]
             else:
diff --git a/superhelp/helpers/class_help.py b/superhelp/helpers/class_help.py
@@ -60,7 +60,7 @@ def getters_setters(block_dets, *, repeat=False, **_kwargs):
         why_getters_etc = layout(f"""\
 
         A good discussion of getters, setters, and properties can be found at
-        <https://www.python-course.eu/python3_properties.php>.
+        [Properties vs. Getters and Setters](https://www.python-course.eu/python3_properties.php)
 
         Getters and setters are usually added in other languages such as Java
         because direct attribute access doesn't give the ability to calculate
diff --git a/superhelp/helpers/dict_help.py b/superhelp/helpers/dict_help.py
@@ -155,9 +155,10 @@ def dict_overview(block_dets, *, repeat=False, execute_code=True, **_kwargs):
         They are also super-efficient and fast. The two presentations to watch
         are by the mighty Brandon Rhodes:
 
-        1. The Dictionary Even Mightier -
-        <https://www.youtube.com/watch?v=66P5FMkWoVU>
-        2. The Mighty Dictionary - <https://www.youtube.com/watch?v=oMyy4Sm0uBs>
+        1. [The Dictionary Even Mightier](https://www.youtube.com/watch?v=66P5FMkWoVU)
+
+
+        2. [The Mighty Dictionary](https://www.youtube.com/watch?v=oMyy4Sm0uBs)
         """)
     else:
         dict_def = ''
diff --git a/superhelp/helpers/for_help.py b/superhelp/helpers/for_help.py
@@ -247,7 +247,7 @@ def for_else(block_dets, *, repeat=False, **_kwargs):
         extra_msg = layout("""\
         #### Interesting discussion on `for`-`else`
 
-        <https://nedbatchelder.com/blog/201110/forelse.html>
+        [For/else](https://nedbatchelder.com/blog/201110/forelse.html)
         One comment noted that the construct violates the principle of Least
         Astonishment.
         """)
diff --git a/superhelp/helpers/import_help.py b/superhelp/helpers/import_help.py
@@ -122,6 +122,8 @@ def internal_imports(blocks_dets, *, repeat=False, **_kwargs):
     Note – other modules you don’t want to run directly can continue to use
     relative importing – even if they are imported (absolutely) from modules you
     will be running directly as scripts.
+
+    [Python Modules and Packages – An Introduction](https://realpython.com/python-modules-packages/)
     """)
 
     message = {
diff --git a/superhelp/helpers/lambda_help.py b/superhelp/helpers/lambda_help.py
@@ -18,9 +18,9 @@ def lambda_advice(snippet, *, repeat=False, **_kwargs):
     brief_msg = layout("""\
 
     Lambdas are commonly overused so it is worth reading
-    <https://treyhunner.com/2018/09/stop-writing-lambda-expressions/>. Having
-    said this, lambdas used appropriately in sorting as key are idiomatic and
-    readable as a result.
+    [Overusing lambda expressions in Python](https://treyhunner.com/2018/09/stop-writing-lambda-expressions/).
+    Having said this, lambdas used appropriately in sorting as key are idiomatic
+    and readable as a result.
     """)
     main_msg = (
         layout("""\
@@ -153,8 +153,7 @@ def water_quality(vals):
     )
     extra = layout("""\
 
-    Trey Hunner's "Overusing lambda expressions in Python"
-    <https://treyhunner.com/2018/09/stop-writing-lambda-expressions/> is well
+    Trey Hunner's [Overusing lambda expressions in Python](https://treyhunner.com/2018/09/stop-writing-lambda-expressions/) is well
     worth reading. The position taken in SuperHELP differs in some regards but
     has been influenced by Trey's thinking.
 
diff --git a/superhelp/helpers/name_help.py b/superhelp/helpers/name_help.py
@@ -142,8 +142,8 @@ def _get_names_and_values_msg(name2name_pairs_dets):
     brief_summary = layout("""\
 
     To get a better understanding of what that means in Python see / read
-    <https://nedbatchelder.com/text/names1.html>. Or look at this advice at a
-    higher level of detail e.g. 'Main'.
+    [Python Names and Values](https://nedbatchelder.com/text/names1.html). Or
+    look at this advice at a higher level of detail e.g. 'Main'.
     """)
     main_summary = (
         layout(f"""\
@@ -226,10 +226,10 @@ def _get_names_and_values_msg(name2name_pairs_dets):
     )
     ned_talk_etc = layout("""\
     The talk to watch / read on the topic is:
-    <https://nedbatchelder.com/text/names1.html>
+    [Python Names and Values](https://nedbatchelder.com/text/names1.html)
 
-    <https://lerner.co.il/2019/06/18/understanding-python-assignment/> is also
-    helpful.
+    [Understanding Python assignment](https://lerner.co.il/2019/06/18/understanding-python-assignment/)
+    is also helpful.
 
     A note about using the verb 'assign'? I recommend saying that we assign
     names to values rather than the other way around because it better fits how
@@ -239,7 +239,7 @@ def _get_names_and_values_msg(name2name_pairs_dets):
 
     In technical terms, Python is not pass-by-value or pass-by-reference but
     pass-by-object-reference. See
-    <https://robertheaton.com/2014/02/09/pythons-pass-by-object-reference-as-explained-by-philip-k-dick/>
+    [Is Python pass-by-reference or pass-by-value?](https://robertheaton.com/2014/02/09/pythons-pass-by-object-reference-as-explained-by-philip-k-dick/)
     """)
 
     message = {
diff --git a/superhelp/helpers/num_help.py b/superhelp/helpers/num_help.py
@@ -99,8 +99,8 @@ def num_overview(block_dets, *, execute_code=True, repeat=False, **_kwargs):
             general, the decimal floating-point numbers you enter are only
             approximated by the binary floating-point numbers actually stored in
             the machine." For more information, read the rest of
-            <https://docs.python.org/3/tutorial/floatingpoint.html>. It is
-            really interesting - honest!
+            [Floating Point Arithmetic: Issues and Limitations](https://docs.python.org/3/tutorial/floatingpoint.html).
+            It is really interesting - honest!
             """)
         else:
             floats = ''
diff --git a/superhelp/helpers/operator_help.py b/superhelp/helpers/operator_help.py
@@ -98,7 +98,7 @@ def compound_operator_possible(block_dets, *, repeat=False, **_kwargs):
             """, is_code=True)
             + layout("""\
             See more details here:
-            <https://www.programiz.com/python-programming/operators>
+            [Python Operators](https://www.programiz.com/python-programming/operators)
 
             `+=` and `-+` are probably the most readable but other compound
             operators become more useful when names used are longer. For example
diff --git a/superhelp/helpers/pathlib_help.py b/superhelp/helpers/pathlib_help.py
@@ -168,10 +168,10 @@ def using_os(blocks_dets, *, repeat=False, **_kwargs):
         main_msg = (
             layout("""\
 
-            The `pathlib` library often provides a superior way of working with
-            paths than `os` and `os.path`. Instead of manipulating strings,
-            `pathlib` has semantic methods and operators. Consider the following
-            alternatives:
+            The `pathlib` library often provides a better way of working with
+            paths than `os` and `os.path`, especially when code needs to run
+            cross-platform. Instead of manipulating strings, `pathlib` has
+            semantic methods and operators. Consider the following alternatives:
             """)
             +
             layout("""\
@@ -215,9 +215,9 @@ def using_os(blocks_dets, *, repeat=False, **_kwargs):
         extra_msg =layout("""\
         Further advocacy can be found at:
 
-        * <https://treyhunner.com/2019/01/no-really-pathlib-is-great/>
+        * [No really, pathlib is great](https://treyhunner.com/2019/01/no-really-pathlib-is-great/)
 
-        * <https://treyhunner.com/2018/12/why-you-should-be-using-pathlib/>
+        * [Why you should be using pathlib](https://treyhunner.com/2018/12/why-you-should-be-using-pathlib/)
         """)
     else:
         brief_msg = ''
diff --git a/tests/test_misc.py b/tests/test_misc.py
@@ -0,0 +1,29 @@
+from textwrap import dedent
+
+from nose.tools import assert_equal, assert_not_equal, assert_true, assert_false  # @UnusedImport @UnresolvedImport
+
+from superhelp.gen_utils import layout_comment as layout
+
+def test_layout():
+    tests = [
+        ("Hi", "\nHi"),
+
+        ("""\
+        1. [The Dictionary Even Mightier](https://www.youtube.com/watch?v=66P5FMkWoVU)
+
+        2. [The Mighty Dictionary](https://www.youtube.com/watch?v=oMyy4Sm0uBs)
+        """,
+        dedent("""\
+
+        1. [The Dictionary Even Mightier](https://www.youtube.com/watch?v=66P5FMkWoVU)
+
+        2. [The Mighty Dictionary](https://www.youtube.com/watch?v=oMyy4Sm0uBs)
+
+        """)),
+
+    ]
+    for raw, expected_res in tests:
+        actual_res = layout(raw, is_code=False)
+        assert_equal(actual_res, expected_res, f"'{actual_res}'")
+
+# test_layout()

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@`
`2`	`2`	`from codecs import open`
`3`	`3`	`from os import path`
`4`	`4`
`5`		`-__version__ = '1.0.10'`
	`5`	`+__version__ = '1.0.11'`
`6`	`6`
`7`	`7`	`here = path.abspath(path.dirname(__file__))`
`8`	`8`
`@@ -50,7 +50,7 @@`
`50`	`50`	`python_requires='>=3.6',`
`51`	`51`	`entry_points = {`
`52`	`52`	`'console_scripts': [`
`53`		`- 'shelp=superhelp:shelp', ## using argparse to allow arguments`
	`53`	`+ 'shelp=superhelp.helper:shelp', ## using argparse to allow arguments`
`54`	`54`	`]`
`55`	`55`	`},`
`56`	`56`	`)`