rda-python-common 2.1.7__py3-none-any.whl → 2.1.9__py3-none-any.whl

rda_python_common/__init__.py

@@ -0,0 +1,38 @@
+"""rda_python_common: shared utility package for RDA Python tools.
+
+This package exposes two parallel APIs:
+
+1. Legacy module-based API (back-compat). Import the capitalized submodules
+   and call their module-level functions, e.g.::
+
+       from rda_python_common import PgLOG
+       PgLOG.pglog("message", PgLOG.LOGWRN)
+
+2. Class-based API (preferred for new code). Import the class from the
+   lower-case module and either instantiate or subclass it, e.g.::
+
+       from rda_python_common.pg_log import PgLOG
+       log = PgLOG()
+       log.pglog("message", log.LOGWRN)
+
+The legacy submodules are eagerly imported below so that
+``from rda_python_common import PgLOG`` continues to return the module
+object that existing callers expect.
+"""
+
+from . import PgLOG, PgUtil, PgDBI, PgFile, PgLock, PgCMD, PgSIG, PgOPT, PgSplit
+
+__version__ = "2.1.9"
+
+__all__ = [
+   "PgLOG",
+   "PgUtil",
+   "PgDBI",
+   "PgFile",
+   "PgLock",
+   "PgCMD",
+   "PgSIG",
+   "PgOPT",
+   "PgSplit",
+   "__version__",
+]

rda_python_common/pg_dbi.py

@@ -62,12 +62,12 @@ class PgDBI(PgLOG):
       super().__init__()  # initialize parent class
 
       #  PostgreSQL specified query timestamp format
-      self.fmtyr = lambda fn=self: "extract(year from {})::int".format(fn)
-      self.fmtqt = lambda fn=self: "extract(quarter from {})::int".format(fn)
-      self.fmtmn = lambda fn=self: "extract(month from {})::int".format(fn)
-      self.fmtdt = lambda fn=self: "date({})".format(fn)
-      self.fmtym = lambda fn=self: "to_char({}, 'yyyy-mm')".format(fn)
-      self.fmthr = lambda fn=self: "extract(hour from {})::int".format(fn)
+      self.fmtyr = lambda fn: "extract(year from {})::int".format(fn)
+      self.fmtqt = lambda fn: "extract(quarter from {})::int".format(fn)
+      self.fmtmn = lambda fn: "extract(month from {})::int".format(fn)
+      self.fmtdt = lambda fn: "date({})".format(fn)
+      self.fmtym = lambda fn: "to_char({}, 'yyyy-mm')".format(fn)
+      self.fmthr = lambda fn: "extract(hour from {})::int".format(fn)
 
       self.pgdb = None    # reference to a connected database object
       self.curtran = 0    # 0 - no transaction, 1 - in transaction
@@ -577,7 +577,7 @@ class PgDBI(PgLOG):
             self.qelog(dberror, 0, "Retry Connecting", ary, pgcnt, self.LOGWRN)
             self.pgconnect(1, pgcnt + 1)
             return (self.FAILURE if not self.pgdb else self.SUCCESS)
-         elif re.match(r'^55', pgcode):  #  try to lock again
+         elif pgcode.startswith('55'):  #  try to lock again
             self.qelog(dberror, 10, "Retry Locking", ary, pgcnt, self.LOGWRN)
             return self.SUCCESS
          elif pgcode == '25P02':   #  try to add table

rda_python_common/pg_file.py

@@ -2595,7 +2595,7 @@ class PgFile(PgUtil, PgSIG):
       if opt&17:
          dy = int(items[6])
          mn = self.get_month(items[5])
-         if re.match(r'^\d+$', items[7]):
+         if items[7].isdigit():
             yr = int(items[7])
             mtime = "00:00:00"
          else:
@@ -2972,7 +2972,7 @@ class PgFile(PgUtil, PgSIG):
       if dir is None:
          if isinstance(val, int):
             self.DIRLVLS = val
-         elif re.match(r'^\d+$', val):
+         elif val.isdigit():
             self.DIRLVLS = int(val)
       elif dir and not re.match(r'^(\.|\./|/)$', dir) and dir not in self.DELDIRS:
          self.DELDIRS[dir] = val

rda_python_common/pg_lock.py

@@ -1,7 +1,7 @@
 ###############################################################################
 #     Title: pg_lock.py
 #    Author: Zaihua Ji,  zji@ucar.edu
-#      Date: 08/118/2020
+#      Date: 08/18/2020
 #             2025-01-10 transferred to package rda_python_common from
 #             https://github.com/NCAR/rda-shared-libraries.git
 #             2025-12-01 convert to class PgLock

rda_python_common/pg_log.py

@@ -252,7 +252,7 @@ class PgLOG:
                msg = self.PGLOG['PRGMSG'] + "\n" + msg
                self.PGLOG['PRGMSG'] = ""
             if self.PGLOG['ERRCNT'] == 0:
-               if not re.search(r'\n$', msg): msg += "!\n"
+               if not msg.endswith('\n'): msg += "!\n"
             else:
                if self.PGLOG['ERRCNT'] == 1:
                   msg += " with 1 Error:\n"
@@ -1423,7 +1423,7 @@ class PgLOG:
       try:
          self.PGLOG['RDAUID'] = self.PGLOG['GDEXUID'] = pwd.getpwnam(self.PGLOG['GDEXUSER']).pw_uid
          self.PGLOG['RDAGID'] = self.PGLOG['GDEXGID'] = grp.getgrnam(self.PGLOG['GDEXGRP']).gr_gid
-      except:
+      except KeyError:
          self.PGLOG['RDAUID'] = self.PGLOG['GDEXUID'] = 0
          self.PGLOG['RDAGID'] = self.PGLOG['GDEXGID'] = 0
       if self.PGLOG['CURUID'] == self.PGLOG['GDEXUSER']: self.PGLOG['SETUID'] = self.PGLOG['GDEXUSER']   
@@ -1624,8 +1624,8 @@ class PgLOG:
       missthen = 0
       try:
          rf = open(resource, 'r')
-      except:
-         return   # skip if cannot open   
+      except OSError:
+         return   # skip if cannot open
       nline = rf.readline()
       while nline:
          line = self.pgtrim(nline)
@@ -1638,12 +1638,12 @@ class PgLOG:
             missthen = 0
             if re.match(r'^then$', line): continue   # then on next line
             checkif = 0   # end of inline if
-         elif re.match(r'^endif', line):
+         elif line.startswith('endif'):
             checkif = 0   # end of if
             continue
          elif checkif == -1:   # skip the line
             continue
-         elif checkif == 2 and re.match(r'^else', line):
+         elif checkif == 2 and line.startswith('else'):
             checkif = -1   # done check envs in if
             continue
          if checkif == 1:

rda_python_common/pg_opt.py

@@ -1158,7 +1158,7 @@ class PgOPT(PgFile):
          if self.OPTS[opt][2]&16:
             if not val:
                val = 0
-            elif re.match(r'^\d+$', val):
+            elif val.isdigit():
                val = int(val)
          elif val and (opt == 'DS' or opt == 'OD'):
             val = self.format_dataset_id(val)

rda_python_common/pg_sig.py

@@ -961,7 +961,7 @@ class PgSIG(PgDBI):
       lines = buf.split('\n')
       for line in lines:
          if chkt:
-            if re.match(r'^Job', line):
+            if line.startswith('Job'):
                line = re.sub(r'^Job ID', 'JobID', line, 1)
                line = re.sub(r'Finish Time', 'FinishTime', line, 1)
                line = re.sub(r'Req Mem', 'ReqMem', line, 1)

rda_python_common/pg_split.py

@@ -1,7 +1,7 @@
 ###############################################################################
 #     Title: pg_split.py  -- PostgreSQL DataBase Interface foe table wfile
 #    Author: Zaihua Ji,  zji@ucar.edu
-#      Date: 09/010/2024
+#      Date: 09/10/2024
 #             2025-01-10 transferred to package rda_python_common from
 #             https://github.com/NCAR/rda-shared-libraries.git
 #             2025-12-01 convert to class PgSplit
@@ -12,8 +12,9 @@ import os
 import re
 from os import path as op
 from .pg_util import PgUtil
+from .pg_dbi import PgDBI
 
-class PgSplit(PgUtil):
+class PgSplit(PgUtil, PgDBI):
    """Manages synchronisation of wfile records between shared and per-dataset tables.
 
    Handles compare, add, update, and delete operations between the shared

rda_python_common/pg_util.py

@@ -93,22 +93,22 @@ class PgUtil(PgLOG):
          int | str: Numeric month (1-12) when fmt is None; formatted string otherwise.
       """
       if not isinstance(mn, int):
-         if re.match(r'^\d+$', mn):
+         if mn.isdigit():
             mn = int(mn)
          else:
             for m in range(12):
                if re.match(mn, self.MONTHS[m], re.I):
                   mn = m + 1
                   break
-      if fmt and mn > 0 and mn < 13:
+      if fmt and 0 < mn < 13:
          slen = len(fmt)
          if slen == 2:
             smn = "{:02}".format(mn)
-         elif re.match(r'^mon', fmt, re.I):
+         elif fmt[:3].lower() == 'mon':
             smn = self.MNS[mn-1] if slen == 3 else self.MONTHS[mn-1]
-            if re.match(r'^Mon', fmt):
+            if fmt.startswith('Mon'):
                smn = smn.capitalize()
-            elif re.match(r'^MON', fmt):
+            elif fmt.startswith('MON'):
                smn = smn.upper()
          else:
             smn = str(mn)
@@ -131,26 +131,26 @@ class PgUtil(PgLOG):
                     formatted string otherwise.
       """
       if not isinstance(wday, int):
-         if re.match(r'^\d+$', wday):
+         if wday.isdigit():
             wday = int(wday)
          else:
             for w in range(7):
                if re.match(wday, self.WDAYS[w], re.I):
                   wday = w
                   break
-      if fmt and wday >= 0 and wday <= 6:
+      if fmt and 0 <= wday <= 6:
          slen = len(fmt)
          if slen == 4:
             swday = self.WDAYS[wday]
-            if re.match(r'^We', fmt):
+            if fmt.startswith('We'):
                swday = swday.capitalize()
-            elif re.match(r'^WE', fmt):
+            elif fmt.startswith('WE'):
                swday = swday.upper()
          elif slen == 3:
             swday = self.WDS[wday]
-            if re.match(r'^Ww', fmt):
+            if fmt.startswith('Ww'):
                swday = swday.capitalize()
-            elif re.match(r'^WW', fmt):
+            elif fmt.startswith('WW'):
                swday = swday.upper()
          else:
             swday = str(wday)
@@ -179,7 +179,7 @@ class PgUtil(PgLOG):
       if exists is None or exists:
          if not op.exists(file): return ''    # file does not exist
       bname = op.basename(file)
-      if re.match(r'^,.*', bname): return ''       # hidden file
+      if bname.startswith(','): return ''       # hidden file
       if re.search(r'index\.(htm|html|shtml)$', bname, re.I): return ''   # index file
       if  type and type != 'D': return type
       if re.search(r'\.(doc|php|html|shtml)(\.|$)', bname, re.I): return ''    # file with special extention
@@ -314,7 +314,7 @@ class PgUtil(PgLOG):
       """
       if not date: return default
       if not isinstance(date, str): date = str(date)
-      if re.match(r'^0000', date): return default
+      if date.startswith('0000'): return default
       return date
 
    #    fmt: date format, default to "YYYY-MM-DD"
@@ -422,7 +422,7 @@ class PgUtil(PgLOG):
       adt = re.split(sep, sdt)
       acnt = len(adt)
       for i in range(acnt):
-         if re.match(r'^\d+$', adt[i]): adt[i] = int(adt[i])
+         if adt[i].isdigit(): adt[i] = int(adt[i])
       return adt
 
    #    date: given date in format of fromfmt
@@ -490,19 +490,20 @@ class PgUtil(PgLOG):
          if i >= mcnt: break
          fmt = formats[k]
          val = ms[0][i]
-         if re.match(r'^Y', fmt, re.I):
+         head = fmt[:1].upper()
+         if head == 'Y':
             dates[0] = int(val)
             if len(fmt) == 3: dates[0] *= 10
-         elif re.match(r'^C', fmt, re.I):
+         elif head == 'C':
             dates[0] = 100 * int(val)      # year at end of century
-         elif re.match(r'^M', fmt, re.I):
-            if re.match(r'^Mon', fmt, re.I):
+         elif head == 'M':
+            if fmt[:3].upper() == 'MON':
                dates[1] = self.get_month(val)
             else:
                dates[1] = int(val)
-         elif re.match(r'^Q', fmt, re.I):
+         elif head == 'Q':
             dates[1] = 3 * int(val)        # month at end of quarter
-         elif re.match(r'^H', fmt, re.I):  # hour
+         elif head == 'H':  # hour
             dates.append(int(val))
          else:    # day
             dates[2] = int(val)
@@ -653,11 +654,11 @@ class PgUtil(PgLOG):
             slen = len(fmt)
             if slen == 2:
                smn = "{:02}".format(m)
-            elif re.match(r'^mon', fmt, re.I):
+            elif fmt[:3].lower() == 'mon':
                smn = self.MNS[m-1] if slen == 3 else self.MONTHS[m-1]
-               if re.match(r'^Mo', fmt):
+               if fmt.startswith('Mo'):
                   smn = smn.capitalize()
-               elif re.match(r'^MO', fmt):
+               elif fmt.startswith('MO'):
                   smn = smn.upper()
             else:
                smn = str(m)

rda_python_common/pgpassword.py

@@ -4,17 +4,42 @@
 #    Author: Zaihua Ji, zji@ucar.edu
 #      Date: 2025-10-27
 #            2025-12-02 convert to class PgPassword
-#   Purpose: python script to retrieve passwords for postgrsql login to connect a
+#   Purpose: python script to retrieve passwords for postgresql login to connect a
 #            gdex database from inside an python application
 #    Github: https://github.com/NCAR/rda-python-common.git
 ##################################################################################
+"""
+pgpassword.py - Command-line helper that retrieves a PostgreSQL password.
+
+Provides the PgPassword class and a ``main`` entry point used by the
+``pgpassword`` console script. The password is looked up first from
+OpenBao (using the URL/token configured in PgDBI) and, if not found,
+from the user's ``.pgpass`` file. The result is printed to stdout so
+that shell wrappers and other RDA utilities can capture it.
+"""
 import sys
 import re
 from .pg_dbi import PgDBI
 
 class PgPassword(PgDBI):
+   """
+   Command-line helper for retrieving a PostgreSQL login password.
+
+   Inherits from PgDBI to reuse its database-connection metadata
+   (PGDBI), default schema handling, and password-lookup methods
+   (``get_baopassword`` / ``get_pgpassword``).
+
+   Instance attributes set in __init__:
+      DBFLDS    -- mapping of CLI option letters to PGDBI field names
+      DBINFO    -- per-invocation overrides for dbname/scname/lnname/
+                   dbhost/dbport supplied via CLI options
+      dbopt     -- True once at least one DB-override option is seen,
+                   triggering ``default_scinfo`` before lookup
+      password  -- the retrieved password (set by ``start_actions``)
+   """
 
    def __init__(self):
+      """Initialize PgPassword with empty DB-override info and option maps."""
       super().__init__()  # initialize parent class
       self.DBFLDS = {
          'd': 'dbname',
@@ -34,12 +59,34 @@ class PgPassword(PgDBI):
       self.password = ''
 
    # read in command line parameters
-   def read_parameters(self):   
+   def read_parameters(self):
+      """
+      Parse ``sys.argv`` and apply CLI overrides.
+
+      Recognized options:
+         -? / --help -- show usage and exit
+         -l URL      -- OpenBao URL (stored in self.PGDBI['BAOURL'])
+         -k TOKEN    -- OpenBao token name (stored in self.PGDBI['BAOTOKEN'])
+         -d NAME     -- PostgreSQL database name
+         -c NAME     -- PostgreSQL schema name
+         -u NAME     -- PostgreSQL login user name
+         -h HOST     -- PostgreSQL server host name
+         -p PORT     -- PostgreSQL port number
+
+      With no arguments, all defaults inherited from PgDBI/PgLOG are
+      used and the password lookup proceeds. Unknown options, stray
+      values, or an option without its required value cause an
+      immediate error exit via ``self.pglog(..., LGEREX)``.
+      """
       argv = sys.argv[1:]
       opt = None
-      dohelp = True
       for arg in argv:
-         if re.match(r'^-\w+$', arg):
+         if arg in ('-?', '-help', '--help'):
+            self.set_help_path(__file__)
+            self.show_usage("pgpassword")
+         elif re.match(r'^-[a-zA-Z]$', arg):
+            if opt:
+               self.pglog("-" + opt + ": missing option value", self.LGEREX)
             opt = arg[1:]
          elif opt:
             if opt == 'l':
@@ -50,32 +97,31 @@ class PgPassword(PgDBI):
                self.dbopt = True
                self.DBINFO[self.DBFLDS[opt]] = arg
             else:
-               self.pglog(arg + ": Unknown option", self.LGEREX)
-            dohelp = False
+               self.pglog("-" + opt + ": Unknown option", self.LGEREX)
+            opt = None
          else:
-            self.pglog(arg + ": Value provided without option", self.LGEREX)
-      if dohelp:
-         print("Usage: pgpassword [-l OpenBaoURL] [-k TokenName] [-d DBNAME]  \\")
-         print("                  [-c SCHEMA] [-u USName] [-h DBHOST] [-p DBPORT]")
-         print("  -l OpenBao URL to retrieve passwords")
-         print("  -k OpenBao Token Name to retrieve passwords")
-         print("  -d PostgreSQL Database Name")
-         print("  -c PostgreSQL Schema Name")
-         print("  -u PostgreSQL Login User Name")
-         print("  -h PostgreSQL Server Host Name")
-         print("  -p PostgreSQL Port Number")
-         sys.exit(0)
+            self.pglog(arg + ": value provided without option", self.LGEREX)
+      if opt:
+         self.pglog("-" + opt + ": missing option value", self.LGEREX)
 
    # get the pgpassword
    def start_actions(self):
+      """
+      Look up the password and store it in ``self.password``.
+
+      Applies any CLI-supplied DB overrides via ``default_scinfo``, then
+      tries OpenBao first (``get_baopassword``) and falls back to the
+      ``.pgpass`` file (``get_pgpassword``) if OpenBao returns nothing.
+      """
       if self.dbopt:
          self.default_scinfo(self.DBINFO['dbname'], self.DBINFO['scname'], self.DBINFO['dbhost'],
                              self.DBINFO['lnname'], None, self.DBINFO['dbport'])   
       self.password = self.get_baopassword()
-      if not self.password: self.password = self.get_pg_pass()
+      if not self.password: self.password = self.get_pgpassword()
 
-# main function to excecute this script
+# main function to execute this script
 def main():
+   """Entry point for the ``pgpassword`` console script: print the retrieved password to stdout."""
    object = PgPassword()
    object.read_parameters()
    object.start_actions()   

rda_python_common/pgpassword.usg

@@ -0,0 +1,57 @@
+
+ Retrieve a PostgreSQL login password for use by RDA python applications.
+ The password is looked up first from OpenBao (using the URL and token
+ configured in PgDBI) and, if not found there, from the user's .pgpass
+ file.  The retrieved password is printed to stdout so that shell
+ wrappers and other RDA utilities can capture it.
+
+ Usage: pgpassword [-?] [-l OpenBaoURL] [-k TokenName] [-d DBNAME]   \
+                   [-c SCHEMA] [-u USName] [-h DBHOST] [-p DBPORT]
+
+ With no options, pgpassword retrieves the password using all defaults
+ inherited from PgDBI/PgLOG (see per-option defaults below).
+
+      - Option -?, show this usage information and exit (also -help
+          and --help);
+
+      - Option -l, OpenBao URL used to retrieve passwords. Overrides
+          the BAOURL value from the PgDBI configuration.
+          Default: https://bao.k8s.ucar.edu/
+
+      - Option -k, OpenBao token name used to authenticate the password
+          lookup. Overrides the BAOTOKEN value from the PgDBI
+          configuration.
+
+      - Option -d, PostgreSQL database name.
+          Default: rdadb
+
+      - Option -c, PostgreSQL schema name.
+          Default: dssdb
+
+      - Option -u, PostgreSQL login user name.
+          Default: dssdb (same as the -c default)
+
+      - Option -h, PostgreSQL server host name.
+          Default: value of the DSSDBHOST environment variable, or
+          rda-db.ucar.edu if DSSDBHOST is not set.
+
+      - Option -p, PostgreSQL server port number.
+          Default: 5432
+
+ If any of -d, -c, -u, -h, or -p is supplied, the values are applied
+ via default_scinfo() before the password lookup is performed.
+
+ Examples:
+
+   1. Retrieve the password for the default database/user configured
+      in PgDBI:
+
+         pgpassword
+
+   2. Retrieve the password for a specific database, schema and user:
+
+         pgpassword -d rdadb -c dssdb -u metauser
+
+   3. Retrieve the password from a custom OpenBao endpoint:
+
+         pgpassword -l https://bao.example.org -k my-token -d rdadb

rda_python_common-2.1.9.dist-info/METADATA

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: rda_python_common
+Version: 2.1.9
+Summary: RDA Python common library codes shared by other RDA python packages
+Author-email: Zaihua Ji <zji@ucar.edu>
+Project-URL: Homepage, https://github.com/NCAR/rda-python-common
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 5 - Production/Stable
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hvac
+Requires-Dist: psycopg2==2.9.10
+Requires-Dist: rda-python-globus
+Requires-Dist: unidecode
+Requires-Dist: hvac
+Dynamic: license-file
+
+# rda-python-common
+
+Python common library codes to be shared by other RDA python utility programs.
+
+## Installing and using in another RDA python repo
+
+`rda-python-common` is the foundation that every other `rda-python-*` repo
+builds on.  To consume it from a new or existing repo, follow these steps.
+
+### 1. Install the package
+
+For local development, clone this repo alongside your project and install it
+in editable mode so that changes are picked up without re-installing:
+
+```bash
+git clone https://github.com/NCAR/rda-python-common.git
+cd rda-python-common
+pip install -e .
+```
+
+For a regular (non-editable) install from a checkout:
+
+```bash
+pip install /path/to/rda-python-common
+```
+
+For a production install on a system that uses the published distribution:
+
+```bash
+pip install rda_python_common
+```
+
+The package brings in its own transitive dependencies (`psycopg2-binary`,
+`rda-python-globus`, `unidecode`, `hvac`).
+
+### 2. Declare it as a dependency in your project
+
+Add `rda_python_common` to the `dependencies` list of your project's
+`pyproject.toml` so that downstream installs pull it in automatically:
+
+```toml
+[project]
+name = "rda_python_yourtool"
+version = "0.1.0"
+dependencies = [
+  "rda_python_common",
+  # ... other deps
+]
+```
+
+This is the same pattern used by `rda-python-dsarch`, `rda-python-dsupdt`,
+`rda-python-dsrqst`, `rda-python-dscheck`, `rda-python-metrics`, and
+`rda-python-miscs`.
+
+### 3. Import the modules you need
+
+Two import styles are supported (see [Usage examples](#usage-examples) below):
+
+```python
+# Preferred for new code -- import the class from the lower-case module
+from rda_python_common.pg_log import PgLOG
+from rda_python_common.pg_dbi import PgDBI
+
+# Legacy module-style imports remain supported for back-compatibility
+from rda_python_common import PgLOG, PgDBI
+PgLOG.pglog("hello", PgLOG.LOGWRN)
+```
+
+### 4. Verify the install
+
+```bash
+python -c "import rda_python_common; print(rda_python_common.__version__)"
+```
+
+You should see the installed version (currently `2.1.9`).  If the import
+fails, double-check that the active Python environment is the one where you
+ran `pip install`.
+
+## Modules
+
+All shared functionality lives under `src/rda_python_common/` and is organised as
+a single-inheritance class hierarchy.  Each module defines exactly one class;
+later classes extend earlier ones, so an application that instantiates the
+top-of-chain class (typically `PgOPT` or `PgCMD`) gets every helper through one
+object.
+
+Inheritance tree (top-down; multi-inheritance shown as two arrows
+converging on the same child):
+
+```
+                          PgLOG
+                       ┌────┴────┐
+                       ▼         ▼
+                    PgUtil     PgDBI
+                     │ │        │ │ │
+                     │ └────┐ ┌─┘ │ └─► PgPassword
+                     │      ▼ ▼   │
+                     │    PgSplit │       (multi-inherits
+                     │            │        PgUtil + PgDBI)
+                     │            ▼
+                     │          PgSIG
+                     │            │
+                     │ ┌──────────┘
+                     ▼ ▼
+                   PgFile                 (multi-inherits
+                     │                     PgUtil + PgSIG)
+                     ├─► PgOPT
+                     │
+                     └─► PgLock
+                          │
+                          └─► PgCMD
+```
+
+The tree is single inheritance everywhere except at two join points:
+
+- **`PgFile(PgUtil, PgSIG)`** — combines date/record utilities (`PgUtil`
+  via `PgLOG`) with daemon/signal/DB control (`PgSIG` → `PgDBI` → `PgLOG`),
+  so its descendants `PgOPT`, `PgLock`, and `PgCMD` inherit logging, DB,
+  util, signal, and file facilities through one MRO.
+- **`PgSplit(PgUtil, PgDBI)`** — combines record-manipulation helpers
+  (`PgUtil`) with the `pgadd`/`pgget`/`pgmget`/`pgupdt`/`pgdel` DB
+  operations (`PgDBI`) it needs to keep the shared `wfile` table and the
+  per-dataset `wfile_<dsid>` partitions in sync.
+
+- **`pg_log.py`** — `PgLOG`.  Root of the hierarchy.  Provides the central
+  logging facility (bit-mask `logact` flags such as `MSGLOG`, `WARNLG`,
+  `ERRLOG`, `EXITLG`), e-mail dispatch, system-command execution, process
+  metadata lookup, and the global `PGLOG` settings dictionary used by every
+  other module.
+
+- **`pg_util.py`** — `PgUtil(PgLOG)`.  Miscellaneous date/time, dataset-ID,
+  and column-oriented record-manipulation helpers.  Holds the `DATEFMTS`
+  regex table, `MONTHS`/`MNS`/`WDAYS`/`WDS` lookup lists, and the `MDAYS`
+  days-per-month array used for date arithmetic, formatting, parsing, and
+  record sort/search/classification across all RDA tools.
+
+- **`pg_file.py`** — `PgFile(PgUtil, PgSIG)`.  Unified file-operation layer
+  spanning local file systems, remote hosts (rsync/ssh/scp), AWS S3 / object
+  store, and Globus endpoints.  Used by `rdacp`, `dsarch`, `dsupdt`, and
+  related tools whenever data is moved, listed, or stat-ed.
+
+- **`pg_lock.py`** — `PgLock(PgFile)`.  RDADB record-locking primitives for
+  the `dscheck`, `dsrqst`, `dlupdt`, `dcupdt`, `ptrqst`, and `dataset`
+  tables.  Acquires, refreshes, and releases per-record locks so that
+  long-running batch jobs coordinate cleanly.
+
+- **`pg_dbi.py`** — `PgDBI(PgLOG)`.  PostgreSQL database interface built on
+  `psycopg2`.  Wraps connection management, batch `INSERT`/`SELECT`/
+  `UPDATE`/`DELETE`, transaction control, and credential lookup from
+  `.pgpass` or OpenBao.  All RDA tools talk to the `rdadb` database through
+  this class.
+
+- **`pg_sig.py`** — `PgSIG(PgDBI)`.  Daemon process control, POSIX signal
+  handling, child/background-process management, and PBS/Torque batch-job
+  status queries.  Provides the `PGSIG` runtime dictionary plus `VUSERS`,
+  `CPIDS`, `CBIDS`, and `SDUMP` tables that drive RDA daemon programs.
+
+- **`pg_cmd.py`** — `PgCMD(PgLock)`.  Manages `dscheck` batch and delayed-
+  mode command tracking.  Records, updates, and reaps the per-command rows
+  that let RDA utilities resume or be monitored across PBS batch jobs.
+
+- **`pg_split.py`** — `PgSplit(PgUtil, PgDBI)`.  Synchronises `wfile` records
+  between the shared `wfile` table and the per-dataset `wfile_<dsid>`
+  partition tables.  Provides compare/add/update/delete helpers used when
+  archiving or reconciling dataset file inventories.
+
+- **`pg_opt.py`** — `PgOPT(PgFile)`.  Command-line option parsing and
+  application configuration framework for RDA tools (`dsarch`, `dsupdt`,
+  `dsrqst`, ...).  Holds the master `OPTS` definition table, parsed
+  `params`, command-line vs. input-file option tracking (`CMDOPTS`/
+  `INOPTS`), output formatting, dataset/help/media/storage/backup type
+  maps, and the global `PGOPT` settings.
+
+- **`pgpassword.py`** — `PgPassword(PgDBI)`.  Standalone CLI entry point
+  (`pgpassword`) that resolves a PostgreSQL login password from OpenBao
+  (`get_baopassword`) or `~/.pgpass` (`get_pgpassword()`) given database/schema/
+  host/port/user selectors via `-d`, `-c`, `-h`, `-p`, `-u`, `-l`, `-k`.
+  Prints the resolved password to stdout so shell scripts can capture it.
+
+## Usage examples
+
+Each class lives in its own submodule.  Import the class you need, then
+either instantiate it directly or subclass it to add application-specific
+state and methods.
+
+### 1. Direct instantiation — use the helpers as-is
+
+```python
+# Logging only
+from rda_python_common.pg_log import PgLOG
+
+log = PgLOG()
+log.pglog("dsarch started", log.LOGWRN)
+
+# Database access (PgDBI inherits PgLOG, so you get logging too)
+from rda_python_common.pg_dbi import PgDBI
+
+db = PgDBI()
+rec = db.pgget('dataset', 'dsid, title', "dsid = 'd633000'")
+print(rec)
+```
+
+### 2. Subclassing a single common class
+
+```python
+# A small utility that needs date/record helpers plus logging.
+from rda_python_common.pg_util import PgUtil
+
+class DateReport(PgUtil):
+   def __init__(self):
+      super().__init__()           # initialise PgUtil (and PgLOG)
+      self.today = self.curtime()  # method inherited from PgUtil
+
+   def run(self):
+      self.pglog(f"report date: {self.today}", self.LOGWRN)
+
+DateReport().run()
+```
+
+### 3. Subclassing one of the multi-inheriting joins
+
+```python
+# A worker that needs file I/O (PgFile) and dscheck command tracking (PgCMD).
+# PgCMD already extends PgFile via PgLock, so a single base is enough.
+from rda_python_common.pg_cmd import PgCMD
+
+class Worker(PgCMD):
+   def __init__(self):
+      super().__init__()
+      self.jobs = []
+
+   def archive_one(self, src, dst):
+      # PgFile method, available through the inheritance chain
+      self.local_copy_local(src, dst)
+      # PgDBI method, available through PgCMD -> PgLock -> PgFile -> PgSIG -> PgDBI
+      self.pgupdt('wfile', {'status': 'A'}, f"wfile = '{dst}'")
+
+Worker().archive_one('/in/file', '/out/file')
+```
+
+### 4. Combining multiple common classes (application action class)
+
+This mirrors how RDA tools such as `dsarch` are structured.  The leaf class
+multi-inherits several common classes so a single object exposes options,
+command tracking, and wfile splitting.
+
+```python
+# Excerpt of the pattern used by rda_python_dsarch/dsarch.py
+from rda_python_common.pg_opt   import PgOPT
+from rda_python_common.pg_cmd   import PgCMD
+from rda_python_common.pg_split import PgSplit
+
+class PgArch(PgOPT, PgCMD, PgSplit):
+   """Shared state + helpers for a CLI archiving tool."""
+   def __init__(self):
+      super().__init__()
+      self.RTPATH = {}          # runtime path cache
+      self.OPTS   = {}          # option table (populated by subclass)
+
+class DsArch(PgArch):
+   def __init__(self):
+      super().__init__()
+      self.ALLCNT = self.ADDCNT = self.MODCNT = 0
+
+   def main(self):
+      self.read_parameters()    # from PgOPT
+      self.start_actions()      # dispatch
+
+if __name__ == "__main__":
+   DsArch().main()
+```
+
+### 5. Reading a PostgreSQL password from OpenBao or ~/.pgpass
+
+```python
+from rda_python_common.pgpassword import PgPassword
+
+pw = PgPassword()
+pw.default_scinfo('rdadb', 'dssdb', 'rda-pgdb', 'gdexweb', None, 5432)
+password = pw.get_baopassword() or pw.get_pgpassword()
+```
+
+In every case `super().__init__()` cooperates correctly across the
+multi-inheriting joins (`PgFile` and `PgSplit`), so subclasses only need
+to call it once.

rda_python_common-2.1.9.dist-info/RECORD

@@ -0,0 +1,28 @@
+rda_python_common/PgCMD.py,sha256=EYjG2Z4zEnvsXE1z-jt5UaNoEKxnOYYiMMzvW6HrKA4,20597
+rda_python_common/PgDBI.py,sha256=sOKQmzF_qmLR_vnj-NnFEYbLI05t2bVbhqlqy46iluA,76424
+rda_python_common/PgFile.py,sha256=7hyDFm40_NjQ_tg5WviMw_waYPdyXCi0DRCf0Av8eNE,99370
+rda_python_common/PgLOG.py,sha256=43YVpMjWEOLpaMUb4YTEYlDTvp7FTmDQ8V3TAKQrC4M,55228
+rda_python_common/PgLock.py,sha256=12i84nsGBuifSyPnm8IR63LvHvRuVU573D5QKFlHdOI,22623
+rda_python_common/PgOPT.py,sha256=Kn4JYezZhZwAn2usiIYHoHiymGHRgsN299dxyXbKwkI,56244
+rda_python_common/PgSIG.py,sha256=eTJJ3XxutsQ3JSg6uYRpH26ZmrVUup3ShqDFLWXLruA,35803
+rda_python_common/PgSplit.py,sha256=SSg5_Qu5PqP44EkqebO-V_cErNcdE2QtORgFHQ7RqlQ,8822
+rda_python_common/PgUtil.py,sha256=OqESKCd72b9g8m8jwjPJhXDtPYlW6G8oSOhwChvz2Cg,48600
+rda_python_common/__init__.py,sha256=_zWhlp02qZlgMlsox5HGR_mmXRjyQSHIo__v_hTW2rY,994
+rda_python_common/pg_cmd.py,sha256=hQZaW80eFqEUoF0vZHtGuvBEWXbXdY0Nvj6rFIQGboo,32856
+rda_python_common/pg_dbi.py,sha256=q6LT4a4lwo-sM2LEqgrEVkAlh886xeKiz4feqRKw-7c,116238
+rda_python_common/pg_file.py,sha256=RzQTxnht4bFOVty4qoYPREawMCUsnFIbWm2pfEez1fE,161993
+rda_python_common/pg_lock.py,sha256=31EaVDjCkcx3-n8-KnzG18R8Pz7Z6KyFsEqcml6Iq5c,32702
+rda_python_common/pg_log.py,sha256=5kasi1aucWWhlGRlvOG9MT4eHmNsPqEb09rFn_kHPjg,80669
+rda_python_common/pg_opt.py,sha256=sXrlzFWpR2XMak6NlA0MPvErBuQnY6gHM5OsHtoeIPQ,82496
+rda_python_common/pg_password.py,sha256=X-eIDwdqBhtrhrbDTNWle-0JtWsyIVZdDOZaBu7cFHM,2343
+rda_python_common/pg_sig.py,sha256=wLKBmFNWAmxWJFC2L3SLsD4n464kzzHbIFFNBlCW6kI,52759
+rda_python_common/pg_split.py,sha256=aAWKUZPmZ-LQ_fJ3DSKzPKxJw0fMDJ2fgP8ZT629M30,16375
+rda_python_common/pg_util.py,sha256=bjp2civRIhqaBSR8oOtyRzYIZBdwB90SzmJLjRIA7fc,87280
+rda_python_common/pgpassword.py,sha256=aTQaO59QokWrv2EKom4TvKhNW2Mr6aFMMBVG4DCbcKI,5023
+rda_python_common/pgpassword.usg,sha256=Wrle6A8sdlMGx3ZEAmE6TNDPOlG84Whe0T3rCNFzPfY,2013
+rda_python_common-2.1.9.dist-info/licenses/LICENSE,sha256=1dck4EAQwv8QweDWCXDx-4Or0S8YwiCstaso_H57Pno,1097
+rda_python_common-2.1.9.dist-info/METADATA,sha256=RCXhbSP_OnuQyIUUa5h67nFYjzElGU2uDBMXoH5wFcY,11090
+rda_python_common-2.1.9.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rda_python_common-2.1.9.dist-info/entry_points.txt,sha256=pZgVNWspcK-F1TbPav7C3C9NdeHDZMm_25fW9weix00,65
+rda_python_common-2.1.9.dist-info/top_level.txt,sha256=KVQmx7D3DD-jsiheqL8HdTrRE14hpRnZY5_ioMArA5k,18
+rda_python_common-2.1.9.dist-info/RECORD,,

rda_python_common-2.1.7.dist-info/METADATA

@@ -1,21 +0,0 @@
-Metadata-Version: 2.4
-Name: rda_python_common
-Version: 2.1.7
-Summary: RDA Python common library codes shared by other RDA python packages
-Author-email: Zaihua Ji <zji@ucar.edu>
-Project-URL: Homepage, https://github.com/NCAR/rda-python-common
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 5 - Production/Stable
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: hvac
-Requires-Dist: psycopg2==2.9.10
-Requires-Dist: rda-python-globus
-Requires-Dist: unidecode
-Dynamic: license-file
-
-# rda-python-common
-Python common library codes to be shared by other RDA python utility programs.

rda_python_common-2.1.7.dist-info/RECORD

@@ -1,27 +0,0 @@
-rda_python_common/PgCMD.py,sha256=EYjG2Z4zEnvsXE1z-jt5UaNoEKxnOYYiMMzvW6HrKA4,20597
-rda_python_common/PgDBI.py,sha256=sOKQmzF_qmLR_vnj-NnFEYbLI05t2bVbhqlqy46iluA,76424
-rda_python_common/PgFile.py,sha256=7hyDFm40_NjQ_tg5WviMw_waYPdyXCi0DRCf0Av8eNE,99370
-rda_python_common/PgLOG.py,sha256=43YVpMjWEOLpaMUb4YTEYlDTvp7FTmDQ8V3TAKQrC4M,55228
-rda_python_common/PgLock.py,sha256=12i84nsGBuifSyPnm8IR63LvHvRuVU573D5QKFlHdOI,22623
-rda_python_common/PgOPT.py,sha256=Kn4JYezZhZwAn2usiIYHoHiymGHRgsN299dxyXbKwkI,56244
-rda_python_common/PgSIG.py,sha256=eTJJ3XxutsQ3JSg6uYRpH26ZmrVUup3ShqDFLWXLruA,35803
-rda_python_common/PgSplit.py,sha256=SSg5_Qu5PqP44EkqebO-V_cErNcdE2QtORgFHQ7RqlQ,8822
-rda_python_common/PgUtil.py,sha256=OqESKCd72b9g8m8jwjPJhXDtPYlW6G8oSOhwChvz2Cg,48600
-rda_python_common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-rda_python_common/pg_cmd.py,sha256=hQZaW80eFqEUoF0vZHtGuvBEWXbXdY0Nvj6rFIQGboo,32856
-rda_python_common/pg_dbi.py,sha256=R-ZzHUItAxma_rCTrelDakFQDl8yEtOTKo4IRfzKl_Q,116269
-rda_python_common/pg_file.py,sha256=doIXpl0I8gO1yiNofipjwZmHF6TYQkWIEj9XrMRz4XQ,162013
-rda_python_common/pg_lock.py,sha256=Il-pY81JtEDMWtwqW6lEM-EtKbhNI6rug8VMCdkGgNc,32703
-rda_python_common/pg_log.py,sha256=Zte9joy46hn2RsJPNpisHLjxZI-mDdcXY4aSiMNlIoY,80661
-rda_python_common/pg_opt.py,sha256=N45DIY2O3S7ogABOHUecfiKwQY1_O4X7WYYZGLdnhOI,82506
-rda_python_common/pg_password.py,sha256=X-eIDwdqBhtrhrbDTNWle-0JtWsyIVZdDOZaBu7cFHM,2343
-rda_python_common/pg_sig.py,sha256=Dz7QKOkwYchbhVZgQxQqFrUmGaxer2bm8D2K99ig5L0,52760
-rda_python_common/pg_split.py,sha256=yOeUSRzgQlwNGzv76ZLCZtsjzDQw0NeYXz0IV0RZgXQ,16343
-rda_python_common/pg_util.py,sha256=1f25D4xyPMerW55q42CQOD0WYAoFYL2A8Opl4rHA8N4,87393
-rda_python_common/pgpassword.py,sha256=WXEq88XgkQSmJ2j2MX0HSVEUFZOFu-gokRJYvEQj_u4,2900
-rda_python_common-2.1.7.dist-info/licenses/LICENSE,sha256=1dck4EAQwv8QweDWCXDx-4Or0S8YwiCstaso_H57Pno,1097
-rda_python_common-2.1.7.dist-info/METADATA,sha256=HBIupC4bHGhJ3H9tanrlZxjiw_SuDKChlvB7E06YfGs,761
-rda_python_common-2.1.7.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-rda_python_common-2.1.7.dist-info/entry_points.txt,sha256=pZgVNWspcK-F1TbPav7C3C9NdeHDZMm_25fW9weix00,65
-rda_python_common-2.1.7.dist-info/top_level.txt,sha256=KVQmx7D3DD-jsiheqL8HdTrRE14hpRnZY5_ioMArA5k,18
-rda_python_common-2.1.7.dist-info/RECORD,,