Preparation for PyPI and other fixes

.github/workflows/python-package.yml

@@ -9,6 +9,12 @@ on:
             - '*'
     pull_request:
 
+
+# 2025-01-07
+# NERSC has Python 3.10, Numpy 1.22.4, Scipy 1.8.1, matplotlib 3.8.4, astropy 6.0.1, healpy 1.16.6, PyYAML 6.0.1
+# PyPI has Python 3.13, Numpy 2.2.1, Scipy 1.15.0, matplotlib 3.10.0, astropy 7.0.0, healpy 1.18.0, PyYAML 6.0.2
+# Numpy 1.26.4 was the last pre-2.0 Numpy.
+#
 jobs:
     tests:
         name: Unit tests
@@ -17,9 +23,20 @@ jobs:
             fail-fast: true
             matrix:
                 os: [ubuntu-latest]
-                python-version: ['3.10']  # There are still issues with Numpy <1.23 and 3.11.
-                numpy-version: ['<1.23', '<1.24', '<2.0']
-                astropy-version: ['<6.0', '<6.1', '<7.0']
+                python-version: ['3.11', '3.12']
+                numpy-version: ['<2.0', '<2.1', '<2.2', '<3']
+                astropy-version: ['<6.1', '<7.0']  # , '<7.1'] 7 has an IERS issue
+                include:
+                    # Close to current NERSC configuration.
+                    - os: ubuntu-latest
+                      python-version: '3.10'
+                      numpy-version: '<1.23'
+                      astropy-version: '<6.1'
+                    # Stable, yet close to bleeding-edge.
+                    - os: ubuntu-latest
+                      python-version: '3.13'
+                      numpy-version: '<3'
+                      astropy-version: '<7.0'  # not <7.1 yet, see above
 
         steps:
             - name: Checkout code
@@ -33,8 +50,8 @@ jobs:
             - name: Install Python dependencies
               run: |
                 python -m pip install --upgrade pip setuptools wheel
-                python -m pip install --upgrade "numpy${{ matrix.numpy-version }}"
-                python -m pip install --upgrade "astropy${{ matrix.astropy-version }}"
+                python -m pip install --upgrade --upgrade-strategy only-if-needed "numpy${{ matrix.numpy-version }}"
+                python -m pip install --upgrade --upgrade-strategy only-if-needed "astropy${{ matrix.astropy-version }}"
                 python -m pip install --editable .[test]
             - name: Run the test
               run: pytest
@@ -47,7 +64,8 @@ jobs:
             matrix:
                 os: [ubuntu-latest]
                 python-version: ['3.10']
-                # astropy-version: ['<5.1'] not used at this time.
+                numpy-version: ['<1.23']
+                astropy-version: ['<6.1']
 
         steps:
             - name: Checkout code
@@ -61,6 +79,8 @@ jobs:
             - name: Install Python dependencies
               run: |
                 python -m pip install --upgrade pip setuptools wheel
+                python -m pip install --upgrade --upgrade-strategy only-if-needed "numpy${{ matrix.numpy-version }}"
+                python -m pip install --upgrade --upgrade-strategy only-if-needed "astropy${{ matrix.astropy-version }}"
                 python -m pip install --editable .[coverage]
             - name: Run the test with coverage
               run: pytest --cov
@@ -76,8 +96,10 @@ jobs:
         strategy:
             fail-fast: false
             matrix:
-                os: [ubuntu-latest]
-                python-version: ['3.10']
+                os:
+                    - ubuntu-latest
+                python-version:
+                    - '3.13'
 
         steps:
             - name: Checkout code
@@ -89,7 +111,9 @@ jobs:
               with:
                 python-version: ${{ matrix.python-version }}
             - name: Install Python dependencies
-              run: python -m pip install --upgrade pip setuptools wheel Sphinx sphinx-rtd-theme
+              run: |
+                python -m pip install --upgrade pip setuptools wheel
+                python -m pip install --editable .[doc]
             - name: Test the documentation
               run: sphinx-build -W --keep-going -b html doc doc/_build/html
 
@@ -99,8 +123,10 @@ jobs:
         strategy:
             fail-fast: false
             matrix:
-                os: [ubuntu-latest]
-                python-version: ['3.10']
+                os:
+                    - ubuntu-latest
+                python-version:
+                    - '3.13'
 
         steps:
             - name: Checkout code
@@ -120,14 +146,39 @@ jobs:
             - name: Compare generated api.rst to checked-in version
               run: diff --ignore-space-change --ignore-blank-lines ./api.rst ./doc/api.rst
 
+    scripts:
+        name: Script definition completeness test
+        runs-on: ${{ matrix.os }}
+        strategy:
+            fail-fast: false
+            matrix:
+                os:
+                    - ubuntu-latest
+                python-version:
+                    - '3.13'
+
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+            - name: Set up Python ${{ matrix.python-version }}
+              uses: actions/setup-python@v5
+              with:
+                  python-version: ${{ matrix.python-version }}
+            - name: Compare contents of bin/ to options.scripts in setup.cfg
+              run: python -c 'import os; import sys; from configparser import ConfigParser; conf = ConfigParser(); foo = conf.read(["setup.cfg"]); scripts = [os.path.basename(s) for s in conf["options"]["scripts"].strip().split("\n")]; sys.exit(int(set(os.listdir("bin")) != set(scripts)))'
+
     style:
         name: Style check
         runs-on: ${{ matrix.os }}
         strategy:
             fail-fast: false
             matrix:
-                os: [ubuntu-latest]
-                python-version: ['3.10']
+                os:
+                    - ubuntu-latest
+                python-version:
+                    - '3.13'
 
         steps:
             - name: Checkout code

README.rst

@@ -19,13 +19,14 @@ desiutil
 Introduction
 ============
 
-This is the place for general purpose tools for use by
-everyone.
+`desiutil` contains general purpose tools for use by any and all other `DESI packages`_.
+
+.. _`DESI packages`: https://github.com/desihub
 
 Full Documentation
 ==================
 
-Please visit `desiutil on Read the Docs`_
+Please visit `desiutil on Read the Docs`_.
 
 .. _`desiutil on Read the Docs`: https://desiutil.readthedocs.io/en/latest/
 

bin/update_iers_frozen

@@ -1,9 +1,9 @@
 #!/usr/bin/env python
 """Update the iers_frozen file.
 """
-from pkg_resources import resource_filename
+from importlib.resources import files
 from desiutil.iers import update_iers
 
-frozen = resource_filename('desiutil', 'data/iers_frozen.ecsv')
-print("Updating {0}".format(frozen))
+frozen = str(files('desiutil') / 'data' / 'iers_frozen.ecsv')
+print(f"Updating {frozen}.")
 update_iers(frozen)

doc/changes.rst

@@ -11,10 +11,16 @@ Change Log
 * Remove deprecated module :mod:`desiutil.census`.
 * Remove deprecated top-level ``setup.py``.
 
-3.4.4 (unreleased)
+3.5.0 (unreleased)
 ------------------
 
-* No changes yet.
+* Fix bug in :func:`~desiutil.names.radec_to_desiname` for values very close to zero;
+  don't issue warnings in :func:`~desiutil.annotate.annotate_fits` if the units
+  are not actually changing; general package clean-up in preparation for
+  deployment to PyPI_ (PR `#212`_).
+
+.. _PyPI: https://pypi.org
+.. _`#212`: https://github.com/desihub/desiutil/pull/212
 
 3.4.3 (2024-08-15)
 ------------------
@@ -397,7 +403,7 @@ remains compatible with 2.x.x
 * Fix :command:`desiInstall` on cori.
 * Add :mod:`desiutil.census` to calculate DESI disk space use.
 
-.. _basemap: http://matplotlib.org/basemap/
+.. _basemap: https://matplotlib.org/basemap/stable/
 .. _`#61`: https://github.com/desihub/desiutil/pull/61
 .. _`#63`: https://github.com/desihub/desiutil/pull/63
 .. _`#70`: https://github.com/desihub/desiutil/pull/70
@@ -569,7 +575,7 @@ remains compatible with 2.x.x
 * Update the list of NERSC hosts, including cori.
 * Code is now `PEP 8`_ compliant.
 
-.. _`PEP 8`: http://legacy.python.org/dev/peps/pep-0008/
+.. _`PEP 8`: https://legacy.python.org/dev/peps/pep-0008/
 
 1.1.0 (2015-11-06)
 ------------------
@@ -599,7 +605,7 @@ remains compatible with 2.x.x
 * fix_permissions.sh won't clobber executable bits.
 
 .. _`Travis build support`: https://travis-ci.org/desihub/desiutil
-.. _`Read the Docs support`: http://desiutil.readthedocs.org/en/latest/
+.. _`Read the Docs support`: https://desiutil.readthedocs.io/en/latest/
 
 0.6.0 (2015-10-13)
 ------------------

doc/conf.py

@@ -34,15 +34,16 @@
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon'
+    'sphinx.ext.napoleon',
+    'sphinx_rtd_theme',
 ]
 
 # Configuration for intersphinx, copied from astropy.
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
     'numpy': ('https://numpy.org/doc/stable/', None),
-    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
-    'matplotlib': ('https://matplotlib.org/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/', None),
+    'matplotlib': ('https://matplotlib.org/stable/', None),
     'astropy': ('https://docs.astropy.org/en/stable/', None),
     'h5py': ('https://docs.h5py.org/en/latest/', None)
     }
@@ -132,12 +133,7 @@
 # a list of builtin themes.
 #html_theme = 'default'
 #html_theme = 'haiku'
-try:
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-except ImportError:
-    pass
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

doc/index.rst

@@ -7,7 +7,7 @@ Introduction
 
 desiutil is a set of low-level utilities used by all DESI_ packages.
 
-.. _DESI: https://desi.lbl.gov
+.. _DESI: https://www.desi.lbl.gov
 
 Dependencies
 ============
@@ -17,25 +17,26 @@ Required Dependencies
 
 These packages must be installed for desiutil to work properly:
 
-* `pyyaml <https://pyyaml.org/>`_
-* `requests <https://requests.readthedocs.io/>`_
-* `astropy <https://www.astropy.org/>`_
+* `PyYAML <https://pyyaml.org/>`_
+* `Requests <https://requests.readthedocs.io/>`_
+* `Astropy <https://www.astropy.org/>`_
 
-  - This implies a dependency on `NumPy <https://numpy.org>`_
+  - This implies a dependency on `NumPy <https://numpy.org>`_.
 
 Optional Dependencies
 +++++++++++++++++++++
 
 If you want to use the plotting utilities in :mod:`desiutil.plots`, you will
 need:
 
-* `matplotlib <https://matplotlib.org/>`_
+* `Matplotlib <https://matplotlib.org/>`_
 * `healpy <https://healpy.readthedocs.io/en/latest/>`_
 
 If you want to work with the dust utilities in :mod:`desiutil.dust`, you will
 need:
 
-* `SciPy <https://scipy.org>`
+* `SciPy <https://scipy.org>`_
+* `speclite <https://speclite.readthedocs.io/en/latest/>`_
 
 Contents
 ========

py/desiutil/__init__.py

@@ -7,7 +7,7 @@
 
 This package provides low-level utilities for general use by DESI_.
 
-.. _DESI: http://desi.lbl.gov
+.. _DESI: https://www.desi.lbl.gov
 """
 #
 # Set version string.

py/desiutil/_version.py

@@ -1 +1 @@
-__version__ = '3.4.4.dev1122'
+__version__ = '3.5.0.dev1122'

py/desiutil/annotate.py

@@ -426,16 +426,19 @@ def annotate_fits(filename, extension, output, units=None, comments=None,
             for colname in column_index:
                 ttype = f"TTYPE{column_index[colname]:d}"
                 if colname in column_comments:
-                    if hdu.header.comments[ttype].strip():
+                    current_comment = hdu.header.comments[ttype].strip()
+                    if current_comment and column_comments[colname] != current_comment:
                         log.warning("Overriding comment on column '%s': '%s' -> '%s'.",
-                                    colname, hdu.header.comments[ttype].strip(), column_comments[colname])
+                                    colname, current_comment, column_comments[colname])
                     hdu.header[ttype] = (colname, column_comments[colname])
                     log.debug('Set %s comment to "%s"', colname, column_comments[colname])
                 if colname in column_units:
                     tunit = f"TUNIT{column_index[colname]:d}"
-                    if tunit in hdu.header and hdu.header[tunit].strip():
-                        log.warning("Overriding units for column '%s': '%s' -> '%s'.",
-                                    colname, hdu.header[tunit].strip(), column_units[colname])
+                    if tunit in hdu.header:
+                        current_unit = hdu.header[tunit].strip()
+                        if current_unit and column_units[colname] != current_unit:
+                            log.warning("Overriding units for column '%s': '%s' -> '%s'.",
+                                        colname, current_unit, column_units[colname])
                         hdu.header[tunit] = (column_units[colname], colname+' units')
                     else:
                         hdu.header.insert(f"TFORM{column_index[colname]:d}",
@@ -465,11 +468,13 @@ def _options():
     parser.add_argument('-D', '--disable-comments', action='store_true', dest='disable_comments',
                         help='Do not add comments, even if they are defined in one of the inputs.')
     parser.add_argument('-e', '--extension', dest='extension', action='store', metavar='EXT', default='1',
-                        help="Update FITS extension EXT, which can be a number or an EXTNAME. If not specified, HDU 1 will be updated, which is standard for simple binary tables.")
+                        help=("Update FITS extension EXT, which can be a number or an EXTNAME. " +
+                              "If not specified, HDU 1 will be updated, which is standard for simple binary tables."))
     parser.add_argument('-o', '--overwrite', dest='overwrite', action='store_true',
                         help='Overwrite the input FITS file.')
     parser.add_argument('-T', '--truncate-comments', dest='truncate', action='store_true',
-                        help='Allow any long comments to be truncated when written out. Without this option, long comments will raise an error.')
+                        help=('Allow any long comments to be truncated when written out. ' +
+                              'Without this option, long comments will raise an error.'))
     parser.add_argument('-u', '--units', action='store', dest='units', metavar='UNITS',
                         help="UNITS should have the form COLUMN='unit':COLUMN='unit'.")
     parser.add_argument('-v', '--verbose', dest='verbose', action='store_true',

py/desiutil/bitmask.py

@@ -57,8 +57,9 @@
 'Cosmic ray'
 
 
-.. _desispec: http://desispec.readthedocs.io
+.. _desispec: https://desispec.readthedocs.io/en/latest/
 """
+import numpy as np
 
 
 class _MaskBit(int):
@@ -222,7 +223,8 @@ def names(self, mask=None):
         ----------
         mask : :class:`int`, optional
             The mask integer to convert to names. If not supplied,
-            return names of all known bits.
+            return names of all known bits. `mask` can also be a numpy scalar
+            or a numpy array of length 1.
 
         Returns
         -------
@@ -236,7 +238,17 @@ def names(self, mask=None):
             for bitnum in sorted(bitnums):
                 names.append(self._bits[bitnum].name)
         else:
-            mask = int(mask)  # workaround numpy issue #2955 for uint64
+            if isinstance(mask, int) or isinstance(mask, np.integer):
+                pass
+            elif isinstance(mask, np.ndarray) and mask.shape == (1, ):
+                mask = mask[0]
+            else:
+                raise ValueError('Unknown type or invalid shape for mask!')
+            if mask < 0:
+                mask = np.int64(mask).astype(np.uint64)
+            # For Numpy < 2, the operation (int & np.uint64) was not defined.
+            # For Numpy >= 2, this operation should be harmless.
+            mask = int(mask)
             bitnum = 0
             while 2**bitnum <= mask:
                 if (2**bitnum & mask):