rda-python-miscs 2.0.15__py3-none-any.whl → 3.0.1__py3-none-any.whl

rda_python_miscs/bashqsub.py

@@ -7,7 +7,7 @@
 #            https://github.com/NCAR/rda-utility-programs.git
 #            2025-12-29 convert to class BashQsub
 #   Purpose: python script to submit a batch job on PBS node via bash script
-#    Github: https://github.com/NCAR/rda-pythn-miscs.git
+#    Github: https://github.com/NCAR/rda-python-miscs.git
 ##################################################################################
 import os
 import sys
@@ -16,8 +16,14 @@ from os import path as op
 from rda_python_common.pg_log import PgLOG
 
 class BashQsub(PgLOG):
+   """Submit a PBS batch job via a dynamically generated bash script using qsub.
+
+   Builds a bash script with PBS directives, module loads, and conda environment
+   activation, then submits it through the PBS qsub command.
+   """
 
    def __init__(self):
+      """Initialize BashQsub with default PBS resource settings and options."""
       super().__init__()
       self.DEFMODS = {
          'default': "ncarenv,netcdf,ncl,nco,cdo,conda,grib-util,wgrib2"
@@ -42,8 +48,15 @@ class BashQsub(PgLOG):
       self.gdexsub = self.BCHCMDS['PBS']
       self.args = None
 
-   # function to readparameters
+   # function to read parameters
    def read_parameters(self):
+      """Parse command-line arguments and populate PBS options and customized options.
+
+      Handles single-dash qsub options (e.g. -q, -A, -l) and long custom options
+      (-cmd, -cwd, -env, -mod, -res). Validates that the qsub command is available
+      and that a -cmd value is provided. Sets default log paths and job name if not
+      specified, and changes the working directory if -cwd is given.
+      """
       aname = 'bashqsub'
       pname = 'gdexqsub'
       self.set_help_path(__file__)
@@ -88,11 +101,12 @@ class BashQsub(PgLOG):
       if not self.SOPTIONS['e']: self.SOPTIONS['e'] = "{}/{}/".format(self.PGLOG['LOGPATH'], pname)
       if 'N' not in self.SOPTIONS: self.SOPTIONS['N'] = op.basename(self.coptions['cmd'])
       if self.coptions['cwd']:
-         if 's' in self.coptions['cwd']: self.coptions['cwd'] = self.replace_environments(self.coptions['cwd'], '', self.LGWNEX)
+         if '$' in self.coptions['cwd']: self.coptions['cwd'] = self.replace_environments(self.coptions['cwd'], '', self.LGWNEX)
          os.chdir(self.coptions['cwd'])
 
    # function to start actions
    def start_actions(self):
+      """Resolve the command path, build the bash script, and submit it via qsub."""
       cmd = self.valid_command(self.coptions['cmd'])
       if not cmd and not re.match(r'^/', self.coptions['cmd']): cmd = self.valid_command('./' + self.coptions['cmd'])
       if not cmd: self.pglog(self.coptions['cmd'] + ": Cannot find given command to run", self.LGWNEX)
@@ -105,6 +119,17 @@ class BashQsub(PgLOG):
    
    # build bash script to submit a PBS batch job
    def build_bash_script(self, cmd):
+      """Build and return a bash script string with PBS directives for the given command.
+
+      Sets HOME, sources system and conda profile scripts and the user's .bashrc,
+      loads modules, activates the conda environment, then runs the command.
+
+      Args:
+         cmd (str): The fully-resolved command (with arguments) to execute in the job.
+
+      Returns:
+         str: The complete bash batch script content.
+      """
       buf = "#!/usr/bin/bash\n\n"   # qsub starting bash script
       if 'l' in self.SOPTIONS: self.add_resources()
       # add options to bash script for qsub
@@ -128,8 +153,13 @@ class BashQsub(PgLOG):
       buf += "\necho {}\n{}\n\ndate\n".format(cmd, cmd)
       return buf
 
-   # check and add resource options 
+   # check and add resource options
    def add_resources(self):
+      """Parse -l option value into the RESOURCES dict and remove the raw -l entry.
+
+      Expects comma-separated name=value pairs (e.g. 'walltime=2:00:00,select=1:ncpus=4').
+      Logs an error if a token does not contain '='.
+      """
       for res in re.split(',', self.SOPTIONS['l']):
          ms = re.match(r'^([^=]+)=(.+)$', res)
          if ms:
@@ -140,6 +170,20 @@ class BashQsub(PgLOG):
 
    # add module loads for modules provided
    def add_modules(self, res, mods):
+      """Build and return module load/unload commands for the bash script.
+
+      Loads the default module set for the given reservation (or the 'default' set).
+      Additional modules in ``mods`` are appended; path-style entries (starting with
+      '/') use 'module use' instead of 'module load'.  Modules already in the default
+      set are skipped.  SWAPMODS entries trigger an unload before the new load.
+
+      Args:
+         res (str): Reservation name used to look up DEFMODS; falls back to 'default'.
+         mods (str): Comma-separated list of extra modules (or None).
+
+      Returns:
+         str: Shell commands to load/unload modules.
+      """
       mbuf = "\n"
       defmods = self.DEFMODS[res] if res in self.DEFMODS else self.DEFMODS['default']
       dmods = re.split(',', defmods)
@@ -163,6 +207,16 @@ class BashQsub(PgLOG):
 
    # set virtual machine libraries
    def set_vm_libs(self, res):
+      """Build and return conda/VM library activation commands for the bash script.
+
+      Looks up DEFLIBS for the given reservation (falls back to 'default').
+
+      Args:
+         res (str): Reservation name used to look up DEFLIBS; falls back to 'default'.
+
+      Returns:
+         str: Shell commands to activate virtual environment libraries, or '' if none.
+      """
       deflibs = self.DEFLIBS[res] if res in self.DEFLIBS else self.DEFLIBS['default']
       if not deflibs: return ''
       dlibs = re.split(',', deflibs)
@@ -171,8 +225,9 @@ class BashQsub(PgLOG):
          libbuf += dlib + "\n"
       return libbuf
 
-# main function to excecute this script
+# main function to execute this script
 def main():
+   """Entry point: instantiate BashQsub, parse arguments, run, and exit."""
    object = BashQsub()
    object.read_parameters()
    object.start_actions()

rda_python_miscs/bashqsub.usg

@@ -10,9 +10,9 @@
             -o LOGPATH/gdexqsub/
             -e LOGPATH/gdexqsub/
             -A P43713000
-            -m a
-            -q gdex
-            -l walltime=6:00:00,select=1:node=1:mem=1gb
+            -m n
+            -q gdex@casper-pbs
+            -l walltime=6:00:00,select=1:ncpus=1:mem=1gb
 
       - Option -cwd, set the working directory for the Command to be executed. If
           it is not specified, it defaults to the current directory where qsub
@@ -33,18 +33,18 @@
 A bash script example:
 #!/usr/bin/bash
 
-#PBS -o /gpfs/u/home/gdexdata/dssdb/log/gdexqsub/
-#PBS -e /gpfs/u/home/gdexdata/dssdb/log/gdexqsub/
+#PBS -o /glade/u/home/gdexdata/dssdb/log/gdexqsub/
+#PBS -e /glade/u/home/gdexdata/dssdb/log/gdexqsub/
 #PBS -A P43713000
 #PBS -q gdex@casper-pbs
 #PBS -m n
 #PBS -N dsrqst
 #PBS -l walltime=1:00:00
 #PBS -l select=1:ncpus=1:mem=1gb
-export HOME=/gpfs/u/home/zji
+export HOME=/glade/u/home/zji
 source /etc/profile.d/z00_modules.sh
 source /glade/u/apps/opt/conda/etc/profile.d/conda.sh
-source /gpfs/u/home/zji/.bashrc
+source /glade/u/home/zji/.bashrc
 pwd; hostname; date
 
 module load ncarenv

rda_python_miscs/gdexls.py

@@ -18,8 +18,16 @@ from os import path as op
 from rda_python_common.pg_split import PgSplit
 
 class GdexLs(PgSplit):
+   """List local files/directories and display matching metadata from GDEXDB.
+
+   For each path, queries the GDEX database for dataset, group, or file records
+   and prints them in aligned columns: type-prefixed name, size, file count (or
+   format), and description.  A leading letter on each output line indicates the
+   item type: 'D' for a dataset root, 'G' for a sub-group, 'F' for a data file.
+   """
 
    def __init__(self):
+      """Initialize display constants, CLI option flags, and listing state."""
       super().__init__()
       # define some constants for gdexls actions
       self.DIDX = 3   # description column index
@@ -49,6 +57,13 @@ class GdexLs(PgSplit):
 
    # function to read parameters
    def read_parameters(self):
+      """Parse command-line arguments into GDEXLS option flags and the file/directory list.
+
+      Recognises boolean flags -d, -f, -N, -r and value options -R, -D.
+      Positional arguments are resolved to real paths and appended to LINFO['files'].
+      Exits with usage if -h/--help/? is given; errors on unknown options or
+      values without a preceding option.
+      """
       self.set_help_path(__file__)
       self.PGLOG['LOGFILE'] = "gdexls.log"   # set different log file
       self.LINFO['curdir'] = self.get_real_path(os.getcwd())
@@ -61,7 +76,7 @@ class GdexLs(PgSplit):
          if ms:
             option = ms.group(1)
             if option not in self.GDEXLS: self.pglog(arg + ": Unknown Option", self.LGEREX)
-            if 'dfNr'.find(option) > -1:
+            if option in 'dfNr':
                self.GDEXLS[option] = 1
                option = defopt
             continue
@@ -76,8 +91,15 @@ class GdexLs(PgSplit):
                self.GDEXLS[option] = arg
             option = defopt
 
-   # functio to start actions
-   def start_actions(self):   
+   # function to start actions
+   def start_actions(self):
+      """Fetch DB connection info, resolve the default file list, and drive display.
+
+      If no paths were given, lists all entries in the current directory.
+      Defaults both -d and -f flags when neither is explicitly set.
+      Prints a summary count of datasets, groups, and files at the end,
+      or exits with an error if nothing matched in the database.
+      """
       self.view_dbinfo()
       if not self.LINFO['files']:
          self.LINFO['files'] = sorted(glob.glob('*'))   # view all files in current directory
@@ -112,6 +134,15 @@ class GdexLs(PgSplit):
 
    # display the top level list
    def display_top_list(self, files):
+      """Process and display each top-level path, expanding directories as needed.
+
+      A path ending with '/' suppresses display of the directory entry itself and
+      always recurses into it.  Paths not starting with '/' are joined to curdir.
+      Flushes the cached formatted list when it exceeds CLMT entries.
+
+      Args:
+         files (list[str]): Top-level paths provided on the command line (or cwd glob).
+      """
       for file in files:
          if not op.exists(file):
             sys.stderr.write(file + ": NOT exists\n")
@@ -131,6 +162,14 @@ class GdexLs(PgSplit):
 
    # recursively display directory/file info
    def display_list(self, files, level):
+      """Recursively display metadata for each path up to the configured depth limit.
+
+      Flushes the formatted cache when it exceeds CLMT entries to keep memory bounded.
+
+      Args:
+         files (list[str]): Glob-expanded paths at the current recursion level.
+         level (int): Current recursion depth (1-based); stops when >= GDEXLS['R'].
+      """
       for file in files:
          isdir = 1 if op.isdir(file) else 0
          self.display_line(file, isdir)
@@ -141,6 +180,17 @@ class GdexLs(PgSplit):
 
    # find dataset/group info; display or cache file
    def display_line(self, file, isdir):
+      """Look up GDEX metadata for a path and pass a formatted record to display_record.
+
+      Resolves the dataset ID and home path on first call, then reuses cached values
+      for subsequent paths under the same dataset.  Skips paths with no matching
+      dataset ID.  Dispatches to the dataset, group, or file branch based on whether
+      the path is the dataset root, a subdirectory, or a regular file.
+
+      Args:
+         file (str): Absolute path to the file or directory.
+         isdir (int): 1 if the path is a directory, 0 otherwise.
+      """
       getwfile = 1
       if self.LINFO['dsid'] and self.LINFO['dhome']:
          ms = re.match(r'^{}/(.*)$'.format(self.LINFO['dhome']), file)
@@ -151,7 +201,7 @@ class GdexLs(PgSplit):
          self.LINFO['dsid'] = self.find_dataset_id(file)
          if self.LINFO['dsid'] is None: return     # skip for missing dsid
          pgrec = self.pgget("dataset", "title, (dwebcnt + nwebcnt) nc, (dweb_size + nweb_size) ns", "dsid = '{}'".format(self.LINFO['dsid']), self.LGEREX)
-         if not pgrec: return None
+         if not pgrec: return
          self.LINFO['dhome'] = "{}/{}".format(self.PGLOG['DSDHOME'], self.LINFO['dsid'])
          if self.LINFO['dhome'] == file:
             file = re.sub(r'^{}'.format(self.LINFO['tpath']), '', file, 1)
@@ -183,8 +233,17 @@ class GdexLs(PgSplit):
             self.display_record(["F" + file, pgrec['data_size'], pgrec['data_format'], note])
             self.LINFO['fcnt'] += 1
 
-   # display one file info
+   # display one record
    def display_record(self, disp):
+      """Format the size field and either print immediately or cache for aligned output.
+
+      In unformatted mode (-N) the columns are joined by the delimiter and printed
+      directly.  Otherwise the record is appended to pgrecs and the per-column
+      maximum widths are updated for later aligned rendering by display_format_list.
+
+      Args:
+         disp (list[str]): Four-element list: [name, size, count/format, description].
+      """
       disp[1] = self.get_float_string(disp[1])
       if self.GDEXLS['N']:
          print(self.GDEXLS['D'].join(disp))
@@ -197,6 +256,12 @@ class GdexLs(PgSplit):
 
    # display cached list with format
    def display_format_list(self):
+      """Flush the cached record list with column-aligned formatting and reset the cache.
+
+      Applies left or right alignment to each of the first DIDX columns based on
+      ALIGNS, padding to the maximum observed width, then joins with the delimiter.
+      Resets pcnt to 0 after printing (pgrecs entries are left but ignored).
+      """
       for j in range(self.LINFO['pcnt']):
          disp = self.LINFO['pgrecs'][j]
          for i in range(self.DIDX):
@@ -207,9 +272,20 @@ class GdexLs(PgSplit):
          print(self.GDEXLS['D'].join(disp))
       self.LINFO['pcnt'] = 0
 
-   # change size to floating point value with unit
+   # convert size to floating point value with unit
    @staticmethod
    def get_float_string(val):
+      """Convert a numeric byte count to a human-readable string with a unit suffix.
+
+      Divides by 1000 repeatedly until the value is <= 1000 or the largest unit
+      (Petabytes) is reached.  Values >= 1K are formatted to two decimal places.
+
+      Args:
+         val (int|float): Size in bytes.
+
+      Returns:
+         str: Formatted string such as '1.50M' or '512B'.
+      """
       units = ['B', 'K', 'M', 'G', 'T', 'P']
       idx = 0
       while val > 1000 and idx < 5:
@@ -220,17 +296,32 @@ class GdexLs(PgSplit):
       else:
          return "{}{}".format(val, units[idx])
 
-   # replace /gpfs to the path /glade
+   # normalize /gpfs paths to /glade equivalents and resolve symlinks
    @staticmethod
    def get_real_path(path):
+      """Translate legacy /gpfs mount-point prefixes to their /glade equivalents.
+
+      Handles two mappings:
+        - /gpfs/u/...       → /glade/...
+        - /gpfs/csfs1/...   → /glade/campaign/...
+
+      Then calls os.path.realpath to resolve any symlinks.
+
+      Args:
+         path (str): Filesystem path, possibly using a /gpfs prefix.
+
+      Returns:
+         str: Canonicalized absolute path under the /glade hierarchy.
+      """
       if re.match(r'^/gpfs/u', path):
          path = re.sub(r'^/gpfs', '/glade', path, 1)
       elif re.match(r'^/gpfs/csfs1/', path):
          path = re.sub(r'^/gpfs/csfs1', '/glade/campaign', path, 1)
       return op.realpath(path)
 
-# main function to excecute this script
+# main function to execute this script
 def main():
+   """Entry point: instantiate GdexLs, parse arguments, run, and exit."""
    object = GdexLs()
    object.read_parameters()
    object.start_actions()

rda_python_miscs/gdexls.usg

@@ -1,60 +1,74 @@
 
- List directory and file information of the current or specified directories
- with metadata information if matched. Four columns are listed, they are Directory
- Name, Data Volume, File Count, and Brief Description if the listed item is a
- directory, and they are File Name, Data Size, Data Format, and Brief Description
- if the listed item is a file.
- 
- A leading letter is displayed on each line to indicate what type item is listed;
- including 'D' for a whole dataset, 'G' for a group or subgroup in a dataset,
- and 'F' for a data file.
- 
- The output of directory/file list is formatted as default with double spaces
- as delimiter and each column lined up vertically at least for the files under each
- directory. Provide Option -N to display list without format. A delimiter symbol '|'
- is defaulted if Option -N is present.
- 
+ List local files and directories with matching metadata from the GDEX database.
+ Each output line has four columns:
+
+   For a dataset root (D) or group (G):
+     Name  |  Total Data Volume  |  File Count  |  Description
+
+   For a data file (F):
+     Name  |  File Size  |  Data Format  |  Note
+
+ A leading letter on each line indicates the item type:
+   D - dataset root directory
+   G - group or sub-group directory within a dataset
+   F - individual data file
+
+ Output is column-aligned by default using double spaces as the delimiter.
+ Use -N to disable formatting; the delimiter then defaults to '|'.
+ Nothing is displayed if no matching GDEX metadata is found for the given paths.
+
  Usage: gdexls [-d] [-f] [-N] [-h] [-r] [-D DelimitSymbols] [-R RecursiveLevel] [Directory/File List]
 
-      - Option -d, list directory information only. Directory information
-        is included as default. Add this option to exclude file information;
+      - Option -d, list dataset/group (directory) information only.
+        Both directories and files are listed by default; this option
+        suppresses file output;
 
-      - Option -f, list file information only. File information
-        is included as default. Add this option to exclude directory information;
+      - Option -f, list file information only.
+        Both directories and files are listed by default; this option
+        suppresses directory output;
 
-      - Option -N, list files unformatted;
+      - Option -N, display output without column alignment;
 
       - Option -h, display this help document;
 
-      - Option -r, list directories and files recursively;
+      - Option -r, list directories and files recursively (no depth limit);
+
+      - Option -R RecursiveLevel, list recursively up to the specified depth.
+        -R 1 lists only the immediate contents of each given directory;
+
+      - Option -D DelimitSymbols, specify the column delimiter string.
+        Defaults to "  " (two spaces) for formatted output and '|' for
+        unformatted (-N) output. Quote the string if it contains shell
+        metacharacters, e.g. -D '<:>';
+
+      - Directory/File List is optional. Without it, all entries in the
+        current directory are listed. Shell wildcards are supported.
+
+  This utility can be run from any directory. It searches the GDEX database
+  using the resolved absolute path of each argument, so both absolute and
+  relative paths are accepted.
+
+  Examples for dataset d277006:
+
+     1. Change into the dataset home directory and run gdexls:
 
-      - Option -R, list directories and files recursively up to the level 
-        provided with this Option;
+           cd /PathTo/d277006
+           gdexls
 
-      - Option -D, specify delimiting symbols for dividing the columns.
-        It defaults to "  " for formatted output and '|' for unformatted output.
-        Make sure quote the symbols if any character in the symbols has Unix
-        meaning, for example -D '<:>';
+        Add -r to recurse into sub-directories, or cd into a sub-directory
+        first to list only its contents.
 
-      - Directory/file List is optional; without specification, all directories
-        and files in the current directory are listed. Unix command line
-        wildcards are supported.
+     2. Pass an absolute path directly:
 
-  This utility program can be executed anywhere. Nothing is displayed if neither
-  directory nor file information pre-gathered in database.
+           gdexls /PathTo/d277006/      # list contents of the dataset directory
+           gdexls /PathTo/d277006/*     # same effect via shell glob expansion
 
-  For examples, to check directories and files of d277006, you can
+        Without a trailing '/' or wildcard, the dataset entry itself is listed
+        unless -r or -R is given:
 
-     1. Change into the dataset home data directory as 'cd /PathTo/d277006' and
-        execute 'gdexls'; add recursive option '-r' to check directories and files
-        further into the sub-directories, or change directory into a sub-directory
-        to check files inside of it.
+           gdexls /PathTo/d277006       # shows the D-line for the dataset root
 
-     2. Pass an absolute path to gdexls as 'gdexls /PathTo/d277006/' or as
-        'gdexls /PathTo/d277006/*'; without the ending by '/' or an appended
-        wildcard symbol '*' information of the dataset itself is check unless
-        the recursive option '-r' or '-R RecursiveLevel' is present
+     3. Use a relative path from a neighbouring directory:
 
-     3. If the current directory is in another dataset home data directory,
-        such as /PathTo/d277006, you can pass a relative path to gdexls
-        as  'gdexls ../d277006/' or as 'gdexls ../d277006/*'
+           gdexls ../d277006/
+           gdexls ../d277006/*

rda_python_miscs/pg_rst.py

@@ -1237,6 +1237,11 @@ class PgRST(PgFile, PgUtil):
 
 def main():
     """Entry point for command-line usage of pg_rst.py."""
+    import sys
+    if len(sys.argv) == 1 or any(a in sys.argv[1:] for a in ('-h', '--help', '-?')):
+        pg = PgRST()
+        pg.show_usage("pg_rst")
+
     parser = argparse.ArgumentParser(
         description=(
             "Convert a .usg help document to reStructuredText (.rst) using RST templates. "

rda_python_miscs/pg_rst.usg

@@ -0,0 +1,60 @@
+ Convert a text-based program usage document (.usg file) into reStructuredText
+ (.rst) files using RST template files, for publication to readthedocs.io via
+ a gdex-docs-* GitHub repository.
+
+ OPTS and ALIAS are loaded from rda_python_<docname>/<docname>.py (or from
+ --pyfile if given): the module is searched first for a class that carries
+ both as class attributes, then for module-level OPTS/ALIAS variables.
+
+ Usage: pgrst [docname] [-u FILE] [-p FILE] [-d DIR] [-h]
+
+      - docname
+          Short document name, e.g. 'dsarch' or 'dsupdt'.  Required unless
+          --usgfile is given, in which case the name is derived from the .usg
+          filename by removing the extension.
+
+      - Option -u or --usgfile FILE
+          Path to the .usg source document.  When given, docname is derived
+          from the filename by removing the .usg extension, and the source
+          directory is set to the directory containing the file.
+
+      - Option -p or --pyfile FILE
+          Path to a Python file that defines OPTS (and optionally ALIAS) either
+          at module level or as class attributes.  When given, the default
+          module-import convention (rda_python_<docname>/<docname>.py) is
+          bypassed.
+
+      - Option -d or --docdir DIR
+          Root directory under which the per-document RST output is written.
+          Defaults to the current working directory.
+
+      - Option -h, display this help document.
+
+ The .usg source document must be structured with a summary paragraph at the
+ top, followed by option descriptions and an examples section.  OPTS defines
+ the option types (mode, single-value, multi-value, or action) used to
+ categorise each option in the RST output.
+
+ Output files are written to DOCDIR using RST template files bundled with
+ this package under rda_python_miscs/rst_templates/.
+
+ Examples:
+
+   1. Convert dsarch.usg to RST using the default module-import convention.
+      OPTS and ALIAS are loaded from rda_python_dsarch/dsarch.py.
+      RST output is written under the current directory:
+
+         pgrst dsarch
+
+   2. Convert dsarch.usg from a specific path, writing RST to /tmp/docs/:
+
+         pgrst dsarch -u /path/to/dsarch.usg -d /tmp/docs/
+
+   3. Convert using a custom Python file for OPTS/ALIAS instead of the
+      installed package module:
+
+         pgrst dsarch -p /path/to/dsarch.py
+
+   4. Derive the document name from the .usg filename (no positional arg):
+
+         pgrst -u /path/to/dsupdt.usg -d /tmp/docs/

rda_python_miscs/pg_wget.py

@@ -34,9 +34,10 @@ OPTIONS = {
 }
 
 #
-# main function to excecute this script
+# main function to execute this script
 #
 def main():
+   """Parse command-line options, validate inputs, and run the wildcard download."""
 
    option = None
    JCS = ['cat', 'tar', 'first', 'last']
@@ -89,9 +90,21 @@ def main():
    sys.exit(0)
 
 #
-# download one or multiple remote files via wget; concat files to a single one if multiple
+# download one or multiple remote files via wget; join files to a single one if multiple
 #
 def download_wildcard_files():
+   """Download remote files matching the wildcard pattern and combine into one output file.
+
+   Skips the download if the local output file already exists and -CN is not set.
+   Runs wget only when -CN is set or fewer than FC files are already present locally.
+   Compares timestamps and file metadata to decide whether a rebuild is needed.
+   Combines downloaded parts using the strategy selected by -JC (cat/tar/first/last).
+   Removes intermediate part-files when -CR is set.
+
+   Returns:
+      int: 1 if the output file was built or rebuilt, 0 if all parts were already
+           up-to-date, or None (implicitly) when a warning/error caused early return.
+   """
 
    deleted = 0
    if OPTIONS['FN']:
@@ -102,7 +115,7 @@ def download_wildcard_files():
 
    dinfo = PgFile.check_local_file(dfile, 1)
    if dinfo and not OPTIONS['CN']:
-      return PgLOG.pglog("{}: file dowloaded already ({} {})".format(dfile, dinfo['date_modified'], dinfo['time_modified']), PgLOG.LOGWRN)
+      return PgLOG.pglog("{}: file downloaded already ({} {})".format(dfile, dinfo['date_modified'], dinfo['time_modified']), PgLOG.LOGWRN)
 
    build = 0 if dinfo else 1
    wfile = OPTIONS['RN'] + "*"
@@ -127,11 +140,11 @@ def download_wildcard_files():
 
    if ncnt == 0:
       if deleted:
-         return PgLOG.pglog("{}: File dowloaded on {}".format(dfile, OPTIONS['UL']), PgLOG.LOGWRN)
+         return PgLOG.pglog("{}: File downloaded on {}".format(dfile, OPTIONS['UL']), PgLOG.LOGWRN)
       else:
-         return PgLOG.pglog("{}: NO file to dowload on {}".format(dfile, OPTIONS['UL']), PgLOG.LOGWRN)
+         return PgLOG.pglog("{}: NO file to download on {}".format(dfile, OPTIONS['UL']), PgLOG.LOGWRN)
    elif ncnt < OPTIONS['MC']:
-      return PgLOG.pglog("{}: NOT ready, only {} of {} files dowloaded".format(dfile, ncnt, OPTIONS['MC']), PgLOG.LOGWRN)
+      return PgLOG.pglog("{}: NOT ready, only {} of {} files downloaded".format(dfile, ncnt, OPTIONS['MC']), PgLOG.LOGWRN)
 
    rfiles = sorted(nlist)
    size = skip = 0
@@ -145,10 +158,10 @@ def download_wildcard_files():
       elif rfile not in dlist:
          build = 1
       elif PgFile.compare_file_info(dlist[rfile], rinfo) > 0:
-         PgLOG.pglog("{}: Newer file dowloaded from {}".format(rfile, OPTIONS['UL']), PgLOG.LOGWRN)
+         PgLOG.pglog("{}: Newer file downloaded from {}".format(rfile, OPTIONS['UL']), PgLOG.LOGWRN)
          build = 1
       else:
-         PgLOG.pglog("{}: No newer file found on ".format(rfile, OPTIONS['UL']), PgLOG.LOGWRN)
+         PgLOG.pglog("{}: No newer file found on {}".format(rfile, OPTIONS['UL']), PgLOG.LOGWRN)
 
    if skip == ncnt: return 0