Further fix/improve setup.py, add RELEASE.md, update README and CHANGELOG, and final cleanup for release (#62)

* Improve handling of USE_CYTHON and Numpy/Cython not being availible

* Add build requirements to pyproject.toml

* Rename USE_CYTHON to CSURT_F2PY to avoid conflicts and be cleaner

* Major updates to README and conform to proper Markdown format

* Centralize version handling and make top-level setup constants caps

* Add release instructions

* Update CHANGELOG with new changes since Github release

Author: CAM-Gerlach

.gitignore

@@ -40,3 +40,4 @@ spyder_crash.log
 *.tmp
 *.temp
 *.bak
+pip-wheel-metadata/

.travis.yml

@@ -1,8 +1,8 @@
 sudo: false
 env:
   matrix:
-  - USE_CYTHON=true
-  - USE_CYTHON=false
+  - CSURT_F2PY=false
+  - CSURT_F2PY=true
   global:
   - LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libgfortran.so.3
 

CHANGELOG.md

@@ -1,4 +1,40 @@
-# Change Log
+# CSU_RadarTools Changelog
+
+
+## 1.3
+
+First release packaged for PyPI and Conda-Forge.
+
+### Beta_Functions
+
+* Changed membership beta functions for vertical ice and ice crystals.
+* Removed executable portion (when running as main script) that was never used.
+
+
+### Under the Hood
+
+* Conform project to modern, best practice standards.
+* Add basic Travis CI tests.
+* Fix and enhance setup script and prepare for proper packaging.
+* Drop support for EoL Python 2.7 and add it for 3.7.
+* Add CHANGELOG and RELEASE instructions and update/improve README.
+
+
+
+## 1.2
+
+Version bump; no non-trivial changes.
+
+
+
+## 1.0
+
+Initial Github release.
+
+### Examples
+
+* Updates to the example Jupyter notebooks.
+
 
 
 ## 2016-11

README.md

@@ -1,48 +1,61 @@
-CSU_RadarTools README
----------------------
+# CSU_RadarTools
+
 Python tools for polarimetric radar retrievals.
 
-This codebase was developed at Colorado State University by numerous people,
-including Brenda Dolan, Brody Fuchs, Kyle Wiens, Rob Cifelli, Larry Carey, Timothy Lang,
-and others.
+This codebase was developed at Colorado State University by numerous people, including Brenda Dolan, Brody Fuchs, Kyle Wiens, Rob Cifelli, Larry Carey, Timothy Lang, and others.
 
 Currently, fuzzy-logic-based hydrometeor identification, blended rainfall,
-DSD retrievals, and liquid/ice mass calculations are supported. There is also an
-algorithm that uses a finite impulse response (FIR) filter to process differential phase
-and calculate specific differential phase.
+DSD retrievals, and liquid/ice mass calculations are supported.
+There is also an algorithm that uses a finite impulse response (FIR) filter to process differential phase and calculate specific differential phase.
 Finally, there are some tools to do rudimentary QC on the data.
 
-These are supplied as standalone functions that take polarimetric radar data
-as arguments. Scalars and arrays are supported as function inputs. The main exception
-is `csu_kdp.calc_kdp_bringi()` which requires individual rays, sweeps, or volumes of
-radar data.
-
-CSU_RadarTools Installation
----------------------------
-To install:
-`python setup.py install`
-(you may need to have sudo privileges, depending on your setup)
-
-There is a parameter in the setup.py file called `USE_CYTHON`. By default it is set to `True`.
-This will cause the program to compile using Cython to speed up the KDP other routines.
-This enables the widest cross-platform support. However, if you are able to compile programs
-using `f2py`, you may want to try `USE_CYTHON = False` in setup.py. This will provide a modest
-performance improvement. Under Windows, `f2py` will be difficult to get working, but we've been
-successful using it under Mac and Linux.
-
-<b>Note: If you have previously installed `csu_radartools` you may have to completely remove it
-from its installation location to get the latest version to work right, since the KDP
-routines have been substantially altered.</b>
+These are supplied as standalone functions that take polarimetric radar data as arguments.
+Scalars and arrays are supported as function inputs. The main exception is `csu_kdp.calc_kdp_bringi()` which requires individual rays, sweeps, or volumes of radar data.
+
+
+## CSU_RadarTools Installation
+
+If using Anaconda/Miniconda, CSU_RadarTools can be installed from `conda-forge` (in progress) with:
 
-To access, use the following in your analysis code:
 ```
-from csu_radartools import (csu_fhc, csu_liquid_ice_mass, csu_blended_rain, csu_dsd,
-                            csu_kdp, csu_misc, fundamentals)
+conda install -c defaults -c conda-forge csu_radartools
+```
+
+We suggest you do so in a dedicated conda environment (e.g. shared with PyART and/or your other radar data manipulation tools) to avoid any chance of contaiminating your `base` environment.
+
+Alternatively, if not using Anaconda/Miniconda, you can install CSU_Radartools using `pip` (or `pip3`, if `pip` does not point to your Python 3 install on your system):
+
+```
+pip install csu_radartools
+```
+
+Again, we suggest using a proper `virtualenv`/`venv` for your radar analysis stack, *particularly* if using your system Python install.
+If are using your system Python or one installed for all users, you may need to have sudo privileges, depending on your setup.
+
+By default, if the `CSURT_F2PY` environment variable is not set (or set to a case-insensitive match for {`0`, `false`, `no`}, the package will be compiled using Cython to speed up KDP and other routines.
+This enables the widest cross-platform support.
+However, if you are able to compile programs using `f2py`, you may want to try setting `CSU_F2PY` to any non-falsy value (e.g. `1`).
+This should provide a modest performance improvement.
+Under Windows, `f2py` will be difficult to get working, but we've been successful using it under Mac and Linux.
+
+*Note:* If you have previously installed `CSU_Radartools` you may have to completely remove it
+from its installation location to get the latest version to work right, since the KDP
+routines have been substantially altered.
+
+To easily access all of the tools, you can use the following in your analysis code:
+
+```python
+from csu_radartools import (csu_fhc, csu_liquid_ice_mass, csu_blended_rain,
+                            csu_dsd, csu_kdp, csu_misc, fundamentals)
 ```
 
-For help information do help on individual modules. There is also a demonstration IPython notebook in the notebooks directory that covers all the modules.
+For help information do help on individual modules.
+There is also a demonstration IPython notebook in the notebooks directory that covers all the modules.
 
-CSU_RadarTools is known to work under Python 2.7 and 3.4. Other Python versions are untested.
+CSU_RadarTools is known to work under Python 2.7 and 3.4-3.7.
+Other Python versions are untested.
+Although we still fully support Python 2.7 at this time, we strongly recommend you move to Python >=3.6 as soon as practicable, given the Python 2 end of life date in less than a year, and the fact that many other scientific packages have dropped it already.
+For more information, please see e.g. [the Python 3 Statement](https://python3statement.org/).
 
-Latest release of CSU_RadarTools (v1.2):
+Latest release of CSU_RadarTools (v1.3):
 [![DOI](https://zenodo.org/badge/31606116.svg)](https://zenodo.org/badge/latestdoi/31606116)

RELEASE.md

@@ -0,0 +1,35 @@
+## CSU_RadarTools Release Instructions
+
+To release a new version of `csu_radartools` on PyPI:
+
+1. `git checkout master`
+
+2. `git fetch upstream && get merge upstream/master`
+
+3. `git clean -xfd`
+
+4. Ensure CHANGELOG is up to date
+
+5. Update `_version.py` (set release version, remove 'dev0')
+
+6. `git add . && git commit -m 'Release X.X.X'`
+
+7. `conda update pip wheel setuptools twine numpy cython` or `pip install -U pip` then `pip install -U wheel setuptools twine numpy cython`
+
+8. `python setup.py sdist bdist_wheel`
+
+9. `twine upload dist/*`
+
+10. `git tag -a vX.X.X -m 'Release X.X.X'`
+
+11. Update `_version.py` (add 'dev0' and increment minor)
+
+12. `git add . && git commit -m 'Increment to dev version'`
+
+13. `git checkout master`
+
+14. `git push upstream master`
+
+15. `git push upstream --tags`
+
+16. Publish release annoucement to Github Releases page

csu_radartools/csu_blended_rain_tropical.py

@@ -71,12 +71,12 @@ def calc_blended_rain_tropical(
     See Bringi and Chandrasekar textbook for more information
     See also Thompson et al. 2016 for more details of the Tropical Blended
     algorithm
-    
+
     Note
     ----
-    
+
     The coefficients are defined as Z=aR**b .
-    
+
     The T15 equations are defined as:
     R = a*Kdp*zeta_dr**c and R=a*Zh*zeta_dr**c
     where as the algorithm expects it in the form

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+# Minimum requirements for the build system to execute.
+requires = ["setuptools", "wheel", "cython", "numpy"]

setup.py

@@ -11,53 +11,82 @@
 """
 
 import os
-import numpy
+import ast
 import setuptools
 
+try:
+    import numpy
+except ImportError:
+    raise RuntimeError("Cannot find NumPy. Please install it first "
+                       "or use pip >= 10, which will do so automatically.")
 
-# Set to False to use f2py instead of Cython for csu_kdp, etc
-if os.environ.get('USE_CYTHON', False):
+
+# Set CSU_F2PY to True to use f2py instead of Cython for csu_kdp, etc
+if ('CSURT_F2PY' in os.environ
+        and os.environ.get('CSURT_F2PY').lower() not in {'0', 'false', 'no'}):
     USE_CYTHON = False
 else:
     USE_CYTHON = True
 
 if USE_CYTHON:
-    from setuptools import setup, Extension
-    from Cython.Build import cythonize
-    from Cython.Compiler import Options
+    from setuptools import setup, Extension  # analysis:ignore
+    try:
+        import Cython  # analysis:ignore
+    except ImportError:
+        raise RuntimeError("Cannot find Cython. Please install it first "
+                           "or use pip >= 10, which will do so automatically.")
+    from Cython.Build import cythonize  # analysis:ignore
+    from Cython.Compiler import Options  # analysis:ignore
     Options.language_level = '2'
 else:
-    from numpy.distutils.core import setup, Extension
+    from numpy.distutils.core import setup, Extension  # analysis:ignore
 
 
+# Get current location
+HERE = os.path.abspath(os.path.dirname(__file__))
 # Pull the header into a variable
-doclines = __doc__.split('\n')
+DOCLINES = __doc__.split('\n')
+# Get packages
+PACKAGES = setuptools.find_packages()
 
-VERSION = '1.2'
 
-# Set variables for setup
-PACKAGES = setuptools.find_packages()
+# Get package version
+def get_version(module=None):
+    """Get version string for package."""
+    if module is None:
+        module = setuptools.find_packages()[0]
+    with open(os.path.join(HERE, module, '_version.py'), 'r') as version_file:
+        data = version_file.read()
+    lines = data.split('\n')
+    for line in lines:
+        if line.startswith('VERSION_INFO'):
+            version_tuple = ast.literal_eval(line.split('=')[-1].strip())
+            version = '.'.join(map(str, version_tuple))
+            break
+    return version
+
 
 if USE_CYTHON:
     EXT = '.pyx'
 else:
     EXT = '.f'
 
-extensions = [Extension(PACKAGES[0] + '.calc_kdp_ray_fir',
+EXTENSIONS = [Extension(PACKAGES[0] + '.calc_kdp_ray_fir',
                         [PACKAGES[0] + '/calc_kdp_ray_fir' + EXT])]
+INCLUDE_DIRS = [numpy.get_include(), '.']
 
 if USE_CYTHON:
-    extensions = cythonize(extensions)
+    EXTENSIONS = cythonize(EXTENSIONS)
 
 
 # Run setup
 setup(name='csu_radartools',
-      version=VERSION,
+      version=get_version(),
       url='https://radarmet.atmos.colostate.edu',
       download_url='https://github.com/CSU-Radarmet/CSU_RadarTools/releases',
       author='Brenda Dolan, Brody Fuchs, Timothy Lang',
       author_email='bdolan@atmos.colostate.edu',
-      description=doclines[1],
+      description=DOCLINES[1],
       long_description=__doc__,
       keywords='radar precipitation meteorology weather',
       classifiers=[
@@ -80,8 +109,8 @@
           ],
       packages=PACKAGES,
       package_data={'csu_radartools': ['beta_function_parameters/*.csv']},
-      ext_modules=extensions,
-      include_dirs=[numpy.get_include(), '.'],
+      ext_modules=EXTENSIONS,
+      include_dirs=INCLUDE_DIRS,
       install_requires=['numpy', 'pandas', 'matplotlib', 'scipy', 'cython'],
       python_requires='>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, <4',
       )