Merge pull request #14 from timcera/contribute

Added a setup.py, and README.rst to work with PyPI

HSP2/main.py

@@ -14,19 +14,35 @@
 
 import os
 import importlib
+from datetime import datetime as dt
+from collections import defaultdict
+
 import h5py
 import pandas as pd
 import numpy as np
-from datetime import datetime as dt
-from collections import defaultdict
+import mando
+from mando.rst_text_formatter import RSTHelpFormatter
 
 import HSP2
 
-
-def run(hdfname, saveall=False, reloadkeys= False):
-    ''' runs main HSP2 program
-     saveall    - (optional) saves all calculated data ignoring SAVE tables
-     reloadkeys - (optional) regenerates keys, used after adding new modules'''
+@mando.command(formatter_class=RSTHelpFormatter, doctype='numpy')
+def run(hdfname,
+        saveall=False,
+        reloadkeys=False):
+    '''Runs main HSP2 program.
+
+    Parameters
+    ----------
+    hdfname: str
+        HDF5 filename used for both input and
+        output.
+    saveall
+        [optional] Default is False.
+        Saves all calculated data ignoring SAVE tables.
+    reloadkeys
+        [optional] Default is False.
+        Regenerates keys, used after adding new modules.
+    '''
 
     if not os.path.exists(hdfname):
         print (hdfname + ' HDF5 File Not Found, QUITTING')
@@ -387,3 +403,11 @@ def initm(general, ui, ts, flag, monthly, name):
         ts[name] = transform(ui[monthly], general['tindex'], 'DAYVAL').values
     else:
         ts[name] = np.full(general['sim_len'], ui[name])
+
+
+def main():
+    mando.main()
+
+
+if __name__ == '__main__':
+    main()

HSP2tools/csvReader.py

@@ -1,6 +1,8 @@
 ''' Copyright 2017 by RESPEC, INC. - see License.txt with this HSP2 distribution
 Author: Robert Heaphy, Ph.D. '''
 
+from __future__ import print_function
+
 import pandas as pd
 
 def read(fname, indexcol=None):
@@ -10,7 +12,7 @@ def read(fname, indexcol=None):
     elif ext.lower() == 'xlsx':
         return pd.read_excel(fname, index_col=indexcol) if indexcol else pd.read_excel(fname)
     else:
-        print 'Unknown file extension', ext
+        print('Unknown file extension: ', ext)
         return None
 
 

README.rst

@@ -0,0 +1,79 @@
+HSP2, Hydrologic Simulation Program Python (HSPsquared)
+=======================================================
+HSPsquared or HSP2 is a Python version of HSPF. Currently it supports the major
+hydrology modules.  It is copyrighted by RESPEC and released under the GNU
+Affero General Public License.
+
+
+MAJOR REPOSITORY DIRECTORIES
+============================
+**HSP2** contains the hydrology codes converted from HSPF and the main programs
+to run HSP2. This software is Python with dependency on Pandas and Numba (open
+source) libraries.
+
+**HSP2notebooks** contains tutorials and useful Juptyer Notebooks.  Some of the
+tutorials demonstrate capabilities that require additional Python modules (like
+Networkx and matplotlib.)
+
+**HSP2tools** contains supporting software modules such as the code to convert
+legacy WDM and UCI files to HDF5 files for HSP2, and to provide additional new
+and legacy capabilities.
+
+The remaining directories are versions of Tim Cera's open source code
+(wdmtoolbox, tstoolbox, and hspfbintoolbox) with versions tested to work with
+HSP2 and other open source code required by Tim Cera's modules.  It is expected
+that these will not be needed in the future when current versions have been
+proven to work.
+
+
+INSTALLATION INSTRUCTIONS
+=========================
+Install Python 2.7 and the additional scientific, open source libraries.
+Ananconda (formerly Continuum Analytics) and Enthought provide free, simple
+installation of all the required Python and scientific libraries.  Check that
+numpy, Pandas, matplotlib, and numba are loaded.  Qgrid (version > 1.0) is also
+used in some of the Jupyter notebook tutorials.  Qgrid is a Jupyter notebook
+widget which uses SlickGrid to render pandas DataFrames within a Jupyter
+notebook. This allows you to explore your DataFrames with intuitive scrolling,
+sorting, and filtering controls, as well as edit your DataFrames by double
+clicking cells.The package managers included with Anaconda or Enthought's
+downloads makes this easy to check and add any missing packages.
+
+From this Github site, click on the green "Clone or Download" dropdown button
+to select "Download ZIP".  Unzip the downloaded zipfile (in your Windows
+"Downloads" directory) and move it  to a convenient location such as your
+Desktop. You should now be able to run the Tutorials and create your own
+Jupyter Notebooks in this directory.
+
+IF AND ONLY IF you need to run HSP2 outside of the distribution directory, you
+will need to use the Windows utility to edit your environmental variables. Find
+or create the PYTHONPATH environmental variable and add the path to where you
+placed the unzipped HSP2 distribution - remember to add the final backslash to
+the path. For example: "C:\Users\myusername\Desktop\HSPsquared\". 
+
+
+TUTORIALS and JUPYTER NOTEBOOKS
+===============================
+You should be able to start the Tutorials and other Jupyter Notebooks once you
+have finished the installation steps above.  In Enthought's Canopy distribution
+you can simply click on the desired file - but this is amazingly slow since it
+starts Canopy which in turn eventually starts the Notebook.  The easiest way
+with either Anaconda or Enthought is to open a command window, move (CD) to the
+location where you put the HSP2 unzipped file, and then type "jupyter notebook"
+at the command prompt.  You will see the Jupyter Notebook open a file browser
+window. Click on the desired Tutorial.  If you are using the Enthought Python
+distribution, Canopy, look for "Enthought Canopy" under the Windows "All
+Programs" to find the "Enthought Canopy Command Window" to use.  You can pin
+this to either your task bar or start window to make starting Notebooks easy.
+
+There is also a YouTube video available at https://youtu.be/aeLScKsP1Wk to get
+you inroduced to HSP2.
+
+NOTE: As a Jupyter project security step, the first time you start any Jupyter
+Notebook, you may need to look at this message in the command window:
+"Copy/past this  URL into your browser when you connect for the first time, to
+login with a token:".  You should copy and paste the following line into your
+browser.  You will NOT need to do this again.  The Jupyter system wants to
+insure that you are authorizing the Jupyter server to run on your system.  This
+is in rapid change to a password based authorization, so follow the
+instructions in the command window.

setup.py

@@ -0,0 +1,67 @@
+
+import sys
+import os
+
+try:
+    from setuptools import setup
+except ImportError:
+    from distutils.core import setup
+
+__version__ = '0.7.7'
+
+if sys.argv[-1] == 'publish':
+    os.system('python setup.py sdist upload')
+    sys.exit()
+
+README = open("./README.rst").read()
+
+install_requires = [
+    'pandas >= 0.17.1',
+    'python-dateutil >= 2.1',
+    'mando >= 0.4',
+    'matplotlib',
+    'rst2ansi >= 0.1.5',
+    'scipy',
+    'dateparser',
+    'tabulate',
+    'docutils',
+    'numba',
+    'h5py',
+    'networkx',
+]
+
+setup(name='HSPsquared',
+      version=__version__,
+      description="Hydrological Simulation Program - Python",
+      long_description=README,
+      classifiers=[
+          # Get strings from
+          # http://pypi.python.org/pypi?%3Aaction=list_classifiers
+          'Development Status :: 4 - Beta',
+          'Intended Audience :: Science/Research',
+          'Intended Audience :: End Users/Desktop',
+          'Intended Audience :: Developers',
+          'Environment :: Console',
+          'Environment :: Web Environment'
+          'License :: OSI Approved :: BSD License',
+          'Natural Language :: English',
+          'Operating System :: OS Independent',
+          'Programming Language :: Python :: 2.7',
+          'Programming Language :: Python :: 3',
+          'Topic :: Scientific/Engineering',
+          'Topic :: Software Development :: Libraries :: Python Modules',
+      ],
+      keywords='hydrology hydrological hydraulic hspf',
+      author='RESPEC, Inc',
+      author_email='',
+      url='http://www.respec.com/product/hydrologic-simulation-program-python-hsp%C2%B2/',
+      packages=['HSP2', 'HSP2tools'],
+      include_package_data=True,
+      zip_safe=False,
+      install_requires=install_requires,
+      entry_points={
+          'console_scripts':
+              ['hsp2=HSP2.main:main']
+      },
+      test_suite='tests',
+      )