Add help on magic numbers; fix AST funcs; misc

* Add help on magic numbers
* Reorganise AST functions
* Fix bugs in AST functions esp regarding negative numbers
* Improve and refactor layout function
* Add more doc strings
* Fix minor error in quotation

Author: grantps

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.11
+version number: 1.0.12
 author: Grant Paton-Simpson
 
 ## Overview

setup.py

@@ -2,7 +2,7 @@
 from codecs import open
 from os import path
 
-__version__ = '1.0.11'
+__version__ = '1.0.12'
 
 here = path.abspath(path.dirname(__file__))
 

superhelp/ast_funcs/__init__.py

@@ -0,0 +1,62 @@
+"""
+Specialised functions for working with the AST. Copes with different ASTs
+created prior to Python 3.8. Handles odd things like positive numbers being
+under value but negative being under value/UnaryOp/operand/Constant etc.
+
+When backward compatibility with 3.6 can be dropped use def __getattr__(name):
+https://stackoverflow.com/questions/2447353/getattr-on-a-module
+"""
+from .. import conf, gen_utils
+from . import versioned_gen as gen, versioned_nums as nums
+
+python_version = gen_utils.get_python_version()
+
+if python_version in (conf.PY3_6, conf.PY3_7):
+
+    val_dets = gen.val_dets_3_7
+
+    assigned_num_els_from_block = nums.assigned_num_els_from_block_3_7
+    num_str_from_parent_el = nums.num_str_from_parent_el_3_7
+    num_str_from_el = nums.num_str_from_el_3_7
+
+    assigned_str_els_from_block = gen.assigned_str_els_from_block_3_7
+    str_from_el = gen.str_from_el_3_7
+    str_els_from_block = gen.str_els_from_block_3_7
+
+    dict_key_from_subscript = gen.dict_key_from_subscript_3_7
+
+    _get_var_plus_equalled = gen._get_var_plus_equalled_3_7
+    _get_var_equal_plussed = gen._get_var_equal_plussed_3_7
+    get_danger_status = gen.get_danger_status_3_7
+
+    get_docstring_from_value = gen.get_docstring_from_value_3_7
+    get_slice_dets = gen.get_slice_dets_3_7
+    get_nt_lbl_flds = gen.get_nt_lbl_flds_3_7
+    get_slice_n = gen.get_slice_n_3_7
+    get_str_els_being_combined = gen.get_str_els_being_combined_3_7
+
+elif python_version == conf.PY3_8:
+
+    val_dets = gen.val_dets_3_8
+
+    assigned_num_els_from_block = nums.assigned_num_els_from_block_3_8
+    num_str_from_parent_el = nums.num_str_from_parent_el_3_8
+    num_str_from_el = nums.num_str_from_el_3_8
+
+    assigned_str_els_from_block = gen.assigned_str_els_from_block_3_8
+    str_from_el = gen.str_from_el_3_8
+    str_els_from_block = gen.str_els_from_block_3_8
+
+    dict_key_from_subscript = gen.dict_key_from_subscript_3_8
+
+    _get_var_plus_equalled = gen._get_var_plus_equalled_3_8
+    _get_var_equal_plussed = gen._get_var_equal_plussed_3_8
+    get_danger_status = gen.get_danger_status_3_8
+    get_docstring_from_value = gen.get_docstring_from_value_3_8
+    get_slice_dets = gen.get_slice_dets_3_8
+    get_nt_lbl_flds = gen.get_nt_lbl_flds_3_8
+    get_slice_n = gen.get_slice_n_3_8
+    get_str_els_being_combined = gen.get_str_els_being_combined_3_8
+
+else:
+    raise Exception(f"Unexpected Python version {python_version}")

superhelp/ast_funcs.py renamed to superhelp/ast_funcs/general.py

@@ -1,8 +1,7 @@
 import logging
 
-from . import conf
-from . import ast_versioned_funcs as avf
-from . import gen_utils
+from .. import conf
+from .. import gen_utils
 
 def get_el_lines_dets(el, *, ignore_trailing_lines=False):
     """
@@ -99,57 +98,3 @@ def get_standardised_el_dict(el):
     std_el_dict = {key: value for key, value in el.items()
         if key not in conf.NON_STD_EL_KEYS}
     return std_el_dict
-
-## when backward compatibility with 3.6 can be dropped use def __getattr__(name):
-## https://stackoverflow.com/questions/2447353/getattr-on-a-module
-python_version = gen_utils.get_python_version()
-
-if python_version in (conf.PY3_6, conf.PY3_7):
-
-    val_dets = avf.val_dets_3_7
-
-    assigned_num_els_from_block = avf.assigned_num_els_from_block_3_7
-    num_str_from_val = avf.num_str_from_val_3_7
-    num_str_from_el = avf.num_str_from_el_3_7
-
-    assigned_str_els_from_block = avf.assigned_str_els_from_block_3_7
-    str_from_el = avf.str_from_el_3_7
-    str_els_from_block = avf.str_els_from_block_3_7
-
-    dict_key_from_subscript = avf.dict_key_from_subscript_3_7
-
-    _get_var_plus_equalled = avf._get_var_plus_equalled_3_7
-    _get_var_equal_plussed = avf._get_var_equal_plussed_3_7
-    get_danger_status = avf.get_danger_status_3_7
-
-    get_docstring_from_value = avf.get_docstring_from_value_3_7
-    get_slice_dets = avf.get_slice_dets_3_7
-    get_nt_lbl_flds = avf.get_nt_lbl_flds_3_7
-    get_slice_n = avf.get_slice_n_3_7
-    get_str_els_being_combined = avf.get_str_els_being_combined_3_7
-
-elif python_version == conf.PY3_8:
-
-    val_dets = avf.val_dets_3_8
-
-    assigned_num_els_from_block = avf.assigned_num_els_from_block_3_8
-    num_str_from_val = avf.num_str_from_val_3_8
-    num_str_from_el = avf.num_str_from_el_3_8
-
-    assigned_str_els_from_block = avf.assigned_str_els_from_block_3_8
-    str_from_el = avf.str_from_el_3_8
-    str_els_from_block = avf.str_els_from_block_3_8
-
-    dict_key_from_subscript = avf.dict_key_from_subscript_3_8
-
-    _get_var_plus_equalled = avf._get_var_plus_equalled_3_8
-    _get_var_equal_plussed = avf._get_var_equal_plussed_3_8
-    get_danger_status = avf.get_danger_status_3_8
-    get_docstring_from_value = avf.get_docstring_from_value_3_8
-    get_slice_dets = avf.get_slice_dets_3_8
-    get_nt_lbl_flds = avf.get_nt_lbl_flds_3_8
-    get_slice_n = avf.get_slice_n_3_8
-    get_str_els_being_combined = avf.get_str_els_being_combined_3_8
-
-else:
-    raise Exception(f"Unexpected Python version {python_version}")

superhelp/ast_versioned_funcs.py renamed to superhelp/ast_funcs/versioned_gen.py

@@ -1,4 +1,6 @@
 
+from . import versioned_nums as nums
+
 def val_dets_3_7(val_el):
     """
     val_el is the element under value e.g. Constant (3.8+) or Str, Num (<3.8)
@@ -37,101 +39,6 @@ def val_dets_3_8(val_el):
         return None
     return val, needs_quoting
 
-## nums ******************************
-
-def assigned_num_els_from_block_3_7(block_el):
-    num_els = block_el.xpath('descendant-or-self::Assign/value/Num')
-    return num_els
-
-def assigned_num_els_from_block_3_8(block_el):
-    val_els = block_el.xpath('descendant-or-self::Assign/value')
-    num_els = []
-    for val_el in val_els:
-        constant_els = val_el.xpath('Constant')
-        if len(constant_els) != 1:
-            continue
-        constant_el = constant_els[0]
-        if constant_el.get('type') in ('int', 'float'):
-            num_els.append(constant_el)
-    return num_els
-
-def num_str_from_val_3_7(val_el):
-    """
-    As for 3_8 version but Num / Str instead of Constant etc.
-    """
-    positive_num_els = val_el.xpath('Num')
-    if len(positive_num_els) == 1:
-        num = positive_num_els[0].get('n')
-    else:
-        sub_els = val_el.xpath('UnaryOp/op/USub')
-        if not sub_els:
-            return None
-        negative_num_els = val_el.xpath('UnaryOp/operand/Num')
-        if len(negative_num_els) != 1:
-            return None
-        pos_num = negative_num_els[0].get('n')
-        num = f'-{pos_num}'
-    return num
-
-def num_str_from_val_3_8(val_el):
-    """
-    ## a positive number
-    <Assign lineno="1" col_offset="0">
-      ...
-      <value>
-        <Constant lineno="1" col_offset="4" type="int" value="0"/>
-      </value>
-    </Assign>
-
-    ## a negative number
-    <Assign lineno="1" col_offset="0">
-      ...
-      <value>
-        <UnaryOp lineno="1" col_offset="4">
-          <op>
-            <USub/>
-          </op>
-          <operand>
-            <Constant lineno="1" col_offset="5" type="int" value="1"/>
-          </operand>
-        </UnaryOp>
-      </value>
-    </Assign>
-    """
-    positive_num_els = val_el.xpath('Constant')
-    if len(positive_num_els) == 1:
-        positive_num_el = positive_num_els[0]
-        val = positive_num_el.get('value')
-        if positive_num_el.get('type') not in ('int', 'float'):
-            return None
-        num = val
-    else:
-        sub_els = val_el.xpath('UnaryOp/op/USub')
-        if not sub_els:
-            return None
-        negative_num_els = val_el.xpath('UnaryOp/operand/Constant')
-        if len(negative_num_els) != 1:
-            return None
-        negative_num_el = negative_num_els[0]
-        val = negative_num_el.get('value')
-        if negative_num_el.get('type') not in ('int', 'float'):
-            return None
-        num = f'-{val}'
-    return num
-
-def num_str_from_el_3_7(comparison_el):
-    num = comparison_el.get('n')
-    if not num:
-        return None
-    return num
-
-def num_str_from_el_3_8(comparison_el):
-    val = comparison_el.get('value')
-    if comparison_el.get('type') in ('int', 'float'):
-        num = val
-    else:
-        num = None
-    return num
 
 ## strs ******************************
 
@@ -405,7 +312,7 @@ def get_slice_dets_3_7(assign_subscript_el):
     if len(val_els) != 1:
         return None
     val_el = val_els[0]
-    num_str = num_str_from_val_3_7(val_el)
+    num_str = nums.num_str_from_parent_el_3_7(val_el)
     if num_str:
         slice_dets = slice_dets = f'[{num_str}]'
     else:
@@ -425,7 +332,7 @@ def get_slice_dets_3_8(assign_subscript_el):
     if len(val_els) != 1:
         return None
     val_el = val_els[0]
-    num_str = num_str_from_val_3_8(val_el)
+    num_str = nums.num_str_from_parent_el_3_8(val_el)
     if num_str:
         slice_dets = slice_dets = f'[{num_str}]'
     else: