rda-python-miscs 2.0.2__tar.gz → 2.0.3__tar.gz

{rda_python_miscs-2.0.2 → rda_python_miscs-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rda_python_miscs
-Version: 2.0.2
+Version: 2.0.3
 Summary: RDA Python package to hold RDA miscellaneous utility programs
 Author-email: Zaihua Ji <zji@ucar.edu>
 Project-URL: Homepage, https://github.com/NCAR/rda-python-miscs

{rda_python_miscs-2.0.2 → rda_python_miscs-2.0.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rda_python_miscs"
-version = "2.0.2"
+version = "2.0.3"
 authors = [
   { name="Zaihua Ji", email="zji@ucar.edu" },
 ]

{rda_python_miscs-2.0.2 → rda_python_miscs-2.0.3}/src/rda_python_miscs/pg_rst.py

@@ -19,7 +19,6 @@ import inspect
 import argparse
 import importlib
 from os import path as op
-import PgLOG
 from rda_python_common.pg_file import PgFile
 from rda_python_common.pg_util import PgUtil
 
@@ -142,17 +141,17 @@ class PgRST(PgFile, PgUtil):
       self.ALIAS = alias
 
       self.parse_docs(docname)
-      if not self.sections: PgLOG.pglog(docname + ": empty document", PgLOG.LGWNEX)
+      if not self.sections: self.pglog(docname + ": empty document", self.LGWNEX)
 
       self.DOCS['DOCNAM'] = docname
       if docname in self.LINKS: self.LINKS.remove(docname)
       self.DOCS['DOCLNK'] = r"({})".format('|'.join(self.LINKS))
       self.DOCS['DOCTIT'] = docname.upper()
-      self.change_local_directory(self.DOCS['DOCDIR'], PgLOG.LGWNEX)
-      PgLOG.pglog("Write rst document '{}' under {}".format(docname, self.DOCS['DOCDIR']), PgLOG.LOGWRN)
+      self.change_local_directory(self.DOCS['DOCDIR'], self.LGWNEX)
+      self.pglog("Write rst document '{}' under {}".format(docname, self.DOCS['DOCDIR']), self.LOGWRN)
 
       if op.exists("index.rst"):  # write index file once
-         PgLOG.pglog("index.rst exists already, delete first if needs to be regenerated", PgLOG.LOGWRN)
+         self.pglog("index.rst exists already, delete first if needs to be regenerated", self.LOGWRN)
       else:
          self.write_index(self.sections[0])
 
@@ -169,69 +168,70 @@ class PgRST(PgFile, PgUtil):
 
       Lines beginning with ``#`` are treated as comments and skipped.  Inline
       trailing comments are also stripped.  Angle-bracketed uppercase tokens
-      (e.g. ``<FILENAME>``) are temporarily escaped to ``&lt;FILENAME&gt;``
-      so they are not misidentified as option markers later in processing.
+      (e.g. ``<FILENAME>``) are temporarily escaped to ``&ltFILENAME&gt``
+      so they are not misidentified as option markers (``<:>``, ``<=>``,
+      ``<!>``) later in processing.  They are unescaped back to ``<FILENAME>``
+      in :meth:`replace_option_link` before appearing in RST output.
 
       Args:
          docname (str): Short document name used to locate ``<ORIGIN>/<docname>.usg``.
       """
       docfile = "{}/{}.usg".format(self.DOCS['ORIGIN'], docname)
-      PgLOG.pglog("Parsing info for Document '{}'".format(docname), PgLOG.LOGWRN)
+      self.pglog("Parsing info for Document '{}'".format(docname), self.LOGWRN)
       section = self.init_section('0', "Preface")
       option = example = None
-      fh = open(docfile, 'r')
-      line = fh.readline()
-      while line:
-         if re.match(r'\s*#', line):
-            line = fh.readline()
-            continue   # skip comment lines
-         ms = re.match(r'^(.*\S)\s+#', line)
-         if ms:
-            line = ms.group(1)     # remove comments
-         else:
-            line = line.rstrip()   # remove trailing white spaces
-
-         # Temporarily escape <UPPERCASE> tokens so they are not confused
-         # with special markers like <:>, <=>, <!> used in option parsing.
-         while True:
-            ms = re.search(r'(<([A-Z/\-\.]+)>)', line)
+      with open(docfile, 'r') as fh:
+         line = fh.readline()
+         while line:
+            if re.match(r'\s*#', line):
+               line = fh.readline()
+               continue   # skip comment lines
+            ms = re.match(r'^(.*\S)\s+#', line)
             if ms:
-               line = line.replace(ms.group(1), "&lt{}&gt".format(ms.group(2)))
+               line = ms.group(1)     # remove comments
             else:
-               break
-         ms = re.match(r'^([\d\.]+)\s+(.+)$', line)
-         if ms:   # start new section
-            section = self.record_section(section, option, example, ms.group(1), ms.group(2))
-            option = example = None
-         else:
-            ms = re.match(r'^  -([A-Z]{2}) or -\w+(.*)$', line)
-            if ms:    # found new option
-               option = self.record_option(section, option, example, ms.group(1), ms.group(2))
-               example = None
-            elif option:
-               ms = re.match(r'^  For( | another )example, (.*)$', line)
-               if ms:    # found example
-                  example = self.record_example(option, example, ms.group(2))
-               elif example:
-                  example['desc'] += line + "\n"
+               line = line.rstrip()   # remove trailing white spaces
+
+            # Temporarily escape <UPPERCASE> tokens so they are not confused
+            # with special markers like <:>, <=>, <!> used in option parsing.
+            while True:
+               ms = re.search(r'(<([A-Z/\-\.]+)>)', line)
+               if ms:
+                  line = line.replace(ms.group(1), "&lt{}&gt".format(ms.group(2)))
                else:
-                  option['desc'] += line + "\n"
+                  break
+            ms = re.match(r'^([\d\.]+)\s+(.+)$', line)
+            if ms:   # start new section
+               section = self.record_section(section, option, example, ms.group(1), ms.group(2))
+               option = example = None
             else:
-               section['desc'] += line + "\n"
+               ms = re.match(r'^  -([A-Z]{2}) or -\w+(.*)$', line)
+               if ms:    # found new option
+                  option = self.record_option(section, option, example, ms.group(1), ms.group(2))
+                  example = None
+               elif option:
+                  ms = re.match(r'^  For( | another )example, (.*)$', line)
+                  if ms:    # found example
+                     example = self.record_example(option, example, ms.group(2))
+                  elif example:
+                     example['desc'] += line + "\n"
+                  else:
+                     option['desc'] += line + "\n"
+               else:
+                  section['desc'] += line + "\n"
 
-         line = fh.readline()
-      fh.close()
+            line = fh.readline()
 
       self.record_section(section, option, example)
 
       # check completion of options
       for opt in self.OPTS:
          if opt not in self.options:
-            PgLOG.pglog("Missing option Entry -{} (-{}) in Document '{}'".format(opt, self.OPTS[opt][1], docname), PgLOG.LOGWRN)
+            self.pglog("Missing option Entry -{} (-{}) in Document '{}'".format(opt, self.OPTS[opt][1], docname), self.LOGWRN)
       if self.sections:
          cnt = len(self.sections)
          s = 's' if cnt > 1 else ''
-         PgLOG.pglog("{} Section{} gathered for '{}'".format(cnt, s, docname), PgLOG.LOGWRN)
+         self.pglog("{} Section{} gathered for '{}'".format(cnt, s, docname), self.LOGWRN)
 
    #
    # cache section information
@@ -323,15 +323,14 @@ class PgRST(PgFile, PgUtil):
          dict: New section dict with keys ``secid``, ``title``, ``desc``,
                ``level``, and ``opts``.
       """
+      level = secid.count('.') + 1
       section = {
          'secid' : secid,
          'title' : title,
           'desc' : "",
-         'level' : 0,
+         'level' : level,
           'opts' : []
       }
-      level = len(re.split(r'\.', secid))
-      section['level'] = level
       if level == 1:
          if re.match(r'^ACTION', section['title']):
             self.SECIDS['Action'] = secid
@@ -369,7 +368,7 @@ class PgRST(PgFile, PgUtil):
       types = ("Mode", "Info", "Info", "Action")
 
       if opt not in self.OPTS:
-         PgLOG.pglog("{} -- option not defined for {}".format(opt, self.DOCS['DOCNAM']), PgLOG.LGWNEX)
+         self.pglog("{} -- option not defined for {}".format(opt, self.DOCS['DOCNAM']), self.LGWNEX)
       option['secid'] = secid
       option['opt'] = opt
       ms = re.match(r'^(, | \(Alias: .*\), )(.*)', desc)
@@ -397,9 +396,7 @@ class PgRST(PgFile, PgUtil):
       Returns:
          dict: New example dict with keys ``opt``, ``title``, and ``desc``.
       """
-      example = {'opt' : opt, 'title' : "", 'desc' : desc.title() + "\n"}
-
-      return example
+      return {'opt' : opt, 'title' : "", 'desc' : desc.title() + "\n"}
 
    #
    # write the entry file: index.rst
@@ -471,33 +468,29 @@ class PgRST(PgFile, PgUtil):
       if extra is None: extra = ""
       rstfile = "{}/{}{}.rst".format(self.DOCS['DOCDIR'], template, extra)
 
-      tf = open(tempfile, 'r')
-      rf = open(rstfile, 'w')
-      idx = 0
-      line = tf.readline()
-      while line:
-         idx += 1
-         if re.match(r'\s*#', line):
-            line = tf.readline()
-            continue   # skip comment lines
-         ms = re.match(r'^(.*\S)\s+#', line)
-         if ms:
-            line = ms.group(1)     # remove comments
-         else:
-            line = line.rstrip()   # remove trailing white spaces
-
-         matches = re.findall(r'__([A-Z]+)__', line)
-         if matches:
-            for key in matches:
-               if key not in hash: PgLOG.pglog("{}: not defined at {}({}) {}".format(key, line, idx, tempfile), PgLOG.LGWNEX)
-               if not hash[key]: PgLOG.pglog(key + ": empty content", PgLOG.LGWNEX)
-               line = line.replace("__{}__".format(key), hash[key])
-         rf.write(line + "\n")
+      with open(tempfile, 'r') as tf, open(rstfile, 'w') as rf:
+         idx = 0
          line = tf.readline()
-
-      tf.close()
-      rf.close()
-      PgLOG.pglog("{}{}.rst created from {}.rst.temp".format(template, extra, template), PgLOG.LOGWRN)
+         while line:
+            idx += 1
+            if re.match(r'\s*#', line):
+               line = tf.readline()
+               continue   # skip comment lines
+            ms = re.match(r'^(.*\S)\s+#', line)
+            if ms:
+               line = ms.group(1)     # remove comments
+            else:
+               line = line.rstrip()   # remove trailing white spaces
+
+            matches = re.findall(r'__([A-Z]+)__', line)
+            if matches:
+               for key in matches:
+                  if key not in hash: self.pglog("{}: not defined at {}({}) {}".format(key, line, idx, tempfile), self.LGWNEX)
+                  if not hash[key]: self.pglog(key + ": empty content", self.LGWNEX)
+                  line = line.replace("__{}__".format(key), hash[key])
+            rf.write(line + "\n")
+            line = tf.readline()
+      self.pglog("{}{}.rst created from {}.rst.temp".format(template, extra, template), self.LOGWRN)
 
    #
    # create rst content for table of contents
@@ -685,12 +678,10 @@ class PgRST(PgFile, PgUtil):
       elif ptype == 2:
          opts = re.findall(r'(-\(*)([a-zA-Z]{2,})(\W|$)', line)
          ms = re.match(r'^\s*%s(\s+[\w\.]+\s+|\s+)([a-zA-Z]{2})(\s)' % self.DOCS['DOCNAM'], line)
-         # list.insert() returns None; prepend the match groups explicitly.
          if ms: opts = [ms.groups()] + opts
       else:
          opts = re.findall(r'(^-\(*|\W-\(*)([a-zA-Z]{2,})(\W|$)', line)
 
-      if opts is None: opts = []
       for optary in opts:
          opt = self.get_short_option(optary[1])
          pre = optary[0]
@@ -712,7 +703,6 @@ class PgRST(PgFile, PgUtil):
             after = ')'
 
          replace = pre + opt + after
-         if re.search(r'<!>', after): after = after.replace(r'<!>', '<&#33;>')
          link = "{}`{} <{}>`_{}".format(pre, opt, link, after)
          line = line.replace(replace, link)
 
@@ -753,6 +743,10 @@ class PgRST(PgFile, PgUtil):
             link = self.Q1 + opt + self.Q2
          line = line.replace(replace, link)
 
+      # Unescape <UPPERCASE> tokens that were temporarily escaped during
+      # parsing to avoid confusion with option markers (<:>, <=>, <!>).
+      line = line.replace('&lt', '<').replace('&gt', '>')
+
       return line
 
    #
@@ -778,10 +772,10 @@ class PgRST(PgFile, PgUtil):
          str: RST-formatted description content.
       """
       if desc == "\n": return ''
-      ptype = 0   # paragraph type: 0 - normal, 1 - table, 2 - synopsis
+      ptype = 0   # paragraph type: 0 - normal, 1 - table, 2 = synopsis
       content = ''
       cnt = 0
-      alllines = re.split(r'\n', desc)
+      alllines = desc.split('\n')
       lines = []
       for line in alllines:
          if re.match(r'^\s*\S', line):
@@ -1078,9 +1072,9 @@ class PgRST(PgFile, PgUtil):
 
       for opt in self.ALIAS:
          for alias in self.ALIAS[opt]:
-             if re.match(r'^{}$'.format(alias), p, re.I): return opt
+            if re.match(r'^{}$'.format(alias), p, re.I): return opt
 
-      PgLOG.pglog("{} - unknown option for {}".format(p, self.DOCS['DOCNAM']), PgLOG.LGWNEX)
+      self.pglog("{} - unknown option for {}".format(p, self.DOCS['DOCNAM']), self.LGWNEX)
 
    #
    # replace with rst link for a given section title
@@ -1118,118 +1112,121 @@ class PgRST(PgFile, PgUtil):
       for section in self.sections:
          if section['secid'] == secid: return section
 
-      PgLOG.pglog("Unknown Section ID {}".format(secid), PgLOG.LGWNEX)
+      self.pglog("Unknown Section ID {}".format(secid), self.LGWNEX)
 
+   def load_opts_alias(self, docname):
+      """Import ``rda_python_<docname>.<docname>`` and return its ``(OPTS, ALIAS, origin)`` triple.
 
-# ---------------------------------------------------------------------------
-# Command-line entry point
-# ---------------------------------------------------------------------------
+      Resolution order for OPTS / ALIAS:
 
-def _load_opts_alias(docname):
-   """Import ``rda_python_<docname>.<docname>`` and return its ``(OPTS, ALIAS, origin)`` triple.
+      1. Module-level ``OPTS`` / ``ALIAS`` attributes.
+      2. The first class *defined in that module* that carries both ``OPTS``
+         and ``ALIAS`` as class-level attributes.
 
-   Resolution order for OPTS / ALIAS:
+      ``ALIAS`` is optional; an empty dict is returned when not found.
 
-   1. Module-level ``OPTS`` / ``ALIAS`` attributes.
-   2. The first class *defined in that module* that carries both ``OPTS``
-      and ``ALIAS`` as class-level attributes.
+      The ``origin`` value is the absolute path of the directory that contains
+      ``<docname>.py`` (i.e. ``rda_python_<docname>/``), derived from
+      ``mod.__file__``.  It is intended to be assigned to
+      ``PgRST.DOCS['ORIGIN']`` so that :meth:`PgRST.parse_docs` looks for the
+      ``.usg`` source file in the same location as the document module.
 
-   ``ALIAS`` is optional; an empty dict is returned when not found.
+      Args:
+         docname (str): Short document name used to build the module path
+                        ``rda_python_<docname>.<docname>``.
 
-   The ``origin`` value is the absolute path of the directory that contains
-   ``<docname>.py`` (i.e. ``rda_python_<docname>/``), derived from
-   ``mod.__file__``.  It is intended to be assigned to
-   ``PgRST.DOCS['ORIGIN']`` so that :meth:`PgRST.parse_docs` looks for the
-   ``.usg`` source file in the same location as the document module.
+      Returns:
+         tuple[dict, dict, str]: ``(OPTS, ALIAS, origin)`` where *origin* is
+         the absolute directory path of the imported module file.
 
-   Args:
-      docname (str): Short document name used to build the module path
-                     ``rda_python_<docname>.<docname>``.
+      Raises:
+         SystemExit: via :func:`PgLOG.pglog` (``LGWNEX``) if the module
+                     cannot be imported or ``OPTS`` cannot be found.
+      """
+      modname = "rda_python_{}.{}".format(docname, docname)
+      try:
+         mod = importlib.import_module(modname)
+      except ImportError as exc:
+         self.pglog(
+            "Cannot import module '{}': {}".format(modname, exc),
+            self.LGWNEX,
+         )
+
+      # Derive ORIGIN from the module's own file path.
+      origin = op.dirname(op.abspath(mod.__file__))
+
+      # 1. Try module-level attributes first.
+      opts  = getattr(mod, 'OPTS',  None)
+      alias = getattr(mod, 'ALIAS', None)
+
+      # 2. Fall back to the first class in the module that owns both.
+      if opts is None or alias is None:
+         for _, obj in inspect.getmembers(mod, inspect.isclass):
+            if obj.__module__ == modname:
+               cls_opts  = getattr(obj, 'OPTS',  None)
+               cls_alias = getattr(obj, 'ALIAS', None)
+               if cls_opts is not None:
+                  if opts  is None: opts  = cls_opts
+                  if alias is None: alias = cls_alias
+                  break
+
+      if opts is None:
+         self.pglog(
+            "Module '{}' does not define OPTS (checked module level and "
+            "all classes defined in the module)".format(modname),
+            self.LGWNEX,
+         )
+
+      # ALIAS is optional; default to empty dict.
+      if alias is None:
+         alias = {}
+
+      return opts, alias, origin
 
-   Returns:
-      tuple[dict, dict, str]: ``(OPTS, ALIAS, origin)`` where *origin* is
-      the absolute directory path of the imported module file.
 
-   Raises:
-      SystemExit: via :func:`PgLOG.pglog` (``LGWNEX``) if the module
-                  cannot be imported or ``OPTS`` cannot be found.
-   """
-   modname = "rda_python_{}.{}".format(docname, docname)
-   try:
-      mod = importlib.import_module(modname)
-   except ImportError as exc:
-      PgLOG.pglog(
-         "Cannot import module '{}': {}".format(modname, exc),
-         PgLOG.LGWNEX,
-      )
-
-   # Derive ORIGIN from the module's own file path.
-   origin = op.dirname(op.abspath(mod.__file__))
-
-   # 1. Try module-level attributes first.
-   opts  = getattr(mod, 'OPTS',  None)
-   alias = getattr(mod, 'ALIAS', None)
-
-   # 2. Fall back to the first class in the module that owns both.
-   if opts is None or alias is None:
-      for _, obj in inspect.getmembers(mod, inspect.isclass):
-         if obj.__module__ == modname:
-            cls_opts  = getattr(obj, 'OPTS',  None)
-            cls_alias = getattr(obj, 'ALIAS', None)
-            if cls_opts is not None:
-               if opts  is None: opts  = cls_opts
-               if alias is None: alias = cls_alias
-               break
-
-   if opts is None:
-      PgLOG.pglog(
-         "Module '{}' does not define OPTS (checked module level and "
-         "all classes defined in the module)".format(modname),
-         PgLOG.LGWNEX,
-      )
-
-   # ALIAS is optional; default to empty dict.
-   if alias is None:
-      alias = {}
-
-   return opts, alias, origin
-
-
-if __name__ == '__main__':
-   parser = argparse.ArgumentParser(
-      description=(
-         "Generate RST documentation from a structured .usg source document.\n\n"
-         "OPTS and ALIAS are loaded from rda_python_<docname>/<docname>.py: "
-         "the module is searched first for module-level OPTS/ALIAS variables, "
-         "then for a class defined in that module that carries both as class "
-         "attributes."
-      ),
-      formatter_class=argparse.RawDescriptionHelpFormatter,
-   )
-   parser.add_argument(
-      'docname',
-      help=(
-         "Short document name, e.g. 'dsarch' or 'dsupdt'.  "
-         "The module rda_python_<docname>/<docname>.py must be importable "
-         "and must define OPTS (and optionally ALIAS) either at module "
-         "level or as class attributes."
-      ),
-   )
-   parser.add_argument(
-      '--docdir',
-      default=None,
-      metavar='DIR',
-      help=(
-         "Root directory under which the per-document RST output directory "
-         "is created (default: current working directory).  "
-         "The final output lands in <docdir>/<docname>/."
-      ),
-   )
-   args = parser.parse_args()
-
-   opts, alias, origin = _load_opts_alias(args.docname)
-   pg = PgRST()
-   pg.DOCS['ORIGIN'] = origin
-   if args.docdir is not None:
-      pg.DOCS['DOCDIR'] = args.docdir
-   pg.process_docs(args.docname, opts, alias)
+# ---------------------------------------------------------------------------
+# Command-line entry point
+# ---------------------------------------------------------------------------
+
+def main():
+    """Entry point for command-line usage of pg_rst.py."""
+    parser = argparse.ArgumentParser(
+        description=(
+            "Convert a .usg help document to reStructuredText (.rst) using RST templates. "
+            "OPTS and ALIAS are loaded from rda_python_<docname>/<docname>.py: "
+            "the module is searched first for module-level OPTS/ALIAS variables, "
+            "then for a class defined in that module that carries both as class "
+            "attributes."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        'docname',
+        help=(
+            "Short document name, e.g. 'dsarch' or 'dsupdt'.  "
+            "The module rda_python_<docname>/<docname>.py must be importable "
+            "and must define OPTS (and optionally ALIAS) either at module "
+            "level or as class attributes."
+        ),
+    )
+    parser.add_argument(
+        '--docdir',
+        default=None,
+        metavar='DIR',
+        help=(
+            "Root directory under which the per-document RST output directory "
+            "is created (default: current working directory).  "
+            "The final output lands in <docdir>/<docname>/."
+        ),
+    )
+    args = parser.parse_args()
+
+    pg = PgRST()
+    opts, alias, origin = pg.load_opts_alias(args.docname)
+    pg.DOCS['ORIGIN'] = origin
+    if args.docdir is not None:
+        pg.DOCS['DOCDIR'] = args.docdir
+    pg.process_docs(args.docname, opts, alias)
+
+if __name__ == "__main__":
+    main()

{rda_python_miscs-2.0.2 → rda_python_miscs-2.0.3}/src/rda_python_miscs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rda_python_miscs
-Version: 2.0.2
+Version: 2.0.3
 Summary: RDA Python package to hold RDA miscellaneous utility programs
 Author-email: Zaihua Ji <zji@ucar.edu>
 Project-URL: Homepage, https://github.com/NCAR/rda-python-miscs