Merge pull request #67 from NREL/pip_install

Pip install hescore-hpxml

.gitignore

@@ -6,3 +6,5 @@ docs/build
 *.pyc
 .idea
 .DS_Store
+hescore_hpxml.egg-info
+

MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include hescorehpxml/schemas *.xsd
+

README.rst

@@ -0,0 +1,32 @@
+HPXML to Home Energy Score Translator
+=====================================
+
+This translator script takes an HPXML file or directory of files as an input and generates HEScore inputs from it. The HEScore inputs are exported as json.
+
+Details of the translation assumptions as well instructions for use can be found in `the documentation <http://hescore-hpxml.readthedocs.org/en/latest/>`_.
+
+Installation
+------------
+
+Use a `virtualenv <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_. (Good idea, but not strictly required.)
+
+Install using pip::
+
+    pip install hescore-hpxml
+
+To get the latest and greatest, clone this repository, cd into the directory and install as follows::
+
+    pip install -e .
+
+
+How to use
+----------
+
+Use the command line script::
+
+    hpxml2hescore examples/house1.xml
+
+To get some guidance on how to use the script::
+
+    hpxml2hescore -h
+

docs/source/conf.py

@@ -12,8 +12,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
+import datetime as dt
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -30,7 +30,7 @@
 # ones.
 extensions = [
     'sphinx.ext.todo',
-    'sphinx.ext.pngmath',
+    'sphinx.ext.mathjax',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -47,16 +47,16 @@
 
 # General information about the project.
 project = u'HPXML Import for Home Energy Score'
-copyright = u'2014, Allliance for Sustainable Energy, LLC.'
+copyright = u'{}, Allliance for Sustainable Energy, LLC.'.format(dt.date.today().year)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = 'v2016'
+version = '3.0'
 # The full version, including alpha/beta/rc tags.
-release = 'v2016-beta'
+release = '3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -136,7 +136,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/source/usage.rst

@@ -50,84 +50,57 @@ It it useful to run it this way for debugging a translation of your particular f
 Set Up
 ======
 
-First, get a copy of the `source code from GitHub <https://github.com/NREL/hescore-hpxml>`_, using your preferred method.
-If you're not sure, just click "Download ZIP".
-
-The program runs using `Python 2.7 <https://www.python.org/>`_. Python 2.6 will work, but the outputs will be all out of order.
-It also requires the `lxml <http://lxml.de/>`_ Python library for parsing the xml file, and the argparse module if you're using Python 2.6.
-Below are some instructions depending on platform to get the required programs and libraries if you need help.
+The program runs using `Python 2.7 <https://www.python.org/>`_. The instructions below will help you set up Python
+on your platform and get the translator installed.
 
 Windows
 -------
 
-`Download Python 2.7.10 from python.org <https://www.python.org/downloads/>`_ and Install. 
-
-Add ``C:\Python27`` to your path. `Here's how. <http://superuser.com/questions/143119/how-to-add-python-to-the-windows-path>`_
-
-Figure out whether you have the 32-bit or 64-bit version of python. 
-Open the command line ``cmd.exe``.
-Type in ``python`` and press Enter. The first line returned should be something like:
-
-.. code:: 
-
-    Python 2.7.9 (default, Dec 10 2014, 12:24:55) [MSC v.1500 32 bit (Intel)] on win32
-
-Type in ``quit()``, press Enter.
-
-`Download a precompiled lxml binary <http://www.lfd.uci.edu/~gohlke/pythonlibs/#lxml>`_.
-Make sure it matches your version of Python and windows architecture 
-(``lxml-x.x.x-cp27-none-win32.whl`` or ``lxml-x.x.x-cp27-none-win_amd64.whl``).
-
-Install lxml using pip. Back in your command line window type: 
-
-.. code::
-
-	pip install C:\path\to\lxml-x.x.x-cp27-none-win32.whl
+#. `Download Python 2.7.x (not the 3.x version) from python.org <https://www.python.org/downloads/>`_ and Install.
+#. Add ``C:\Python27`` to your path.
+   `Here's how <http://superuser.com/questions/143119/how-to-add-python-to-the-windows-path>`_.
+#. Follow instructions for :ref:`all_platforms_install_instructions`.
 
 Mac OS X
 --------
 
 #. Install `Homebrew <http://brew.sh/>`_.
 #. Open a terminal.
 #. Install Python 2.7 using homebrew: ``brew install python``
-#. Install lxml using pip: ``pip install lxml``
+#. Follow instructions for :ref:`all_platforms_install_instructions`.
 
 Linux
 -----
 
-You don't need help.
+#. Install Python 2.7 using the package manager for your platform.
+#. Follow instructions for :ref:`all_platforms_install_instructions`.
 
-Running the Translator
-======================
+.. _all_platforms_install_instructions:
 
-The best way to figure out how to run the translator is to call it with the ``-h`` flag.
+All Platforms
+-------------
 
-.. code::
+Optionally install and activate a virtual environment.
+`Instructions here <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_.
 
-    python hpxml_to_hescore.py -h
+Install the package using ``pip``::
 
-It is pretty self-explanatory::
+    pip install hescore-hpxml
 
-    usage: hpxml_to_hescore.py [-h] [-o OUTPUT] [--bldgid BLDGID]
-                               [--nrelassumptions]
-                               hpxml_input
+Alternatively, you can install the latest and greatest directly from GitHub, which is useful if you're going to do some development on the translator.
+To do so, get a copy of the `source code from GitHub <https://github.com/NREL/hescore-hpxml>`_, using your preferred method.
+If you're not sure, just click "Download ZIP".
 
-    Convert HPXML v1.1.1 or v2.x files to HEScore inputs
+Open a terminal and use ``pip`` to install it in developer mode::
 
-    positional arguments:
-      hpxml_input           Filename of hpxml file
+    pip install -e path/to/hescore-hpxml
 
-    optional arguments:
-      -h, --help            show this help message and exit
-      -o OUTPUT, --output OUTPUT
-                            Filename of output file in json format. If not
-                            provided, will go to stdout.
-      --bldgid BLDGID       HPXML building id to score if there are more than one
-                            <Building/> elements. Default: first one.
-      --nrelassumptions     Use the NREL assumptions to guess at data elements
-                            that are missing.
+Running the Translator
+======================
 
+The best way to figure out how to run the translator is to call it with the ``-h`` flag.
 
+.. code::
 
+    hpxml2hescore -h
 
-The ``--nrelassumptions`` flag activates some assumptions we make to have our files run that you probably don't want in a production environment.

code/hpxml_to_hescore.py → hescorehpxml/__init__.py

@@ -1,8 +1,3 @@
-'''
-Created on Mar 4, 2014
-
-@author: nmerket
-'''
 # Python standard library imports
 import os
 import sys

code/create_all_example_json.py → hescorehpxml/create_all_example_json.py

@@ -1,10 +1,5 @@
-'''
-Created on Jan 2, 2015
-
-@author: nmerket
-'''
 import os
-from hpxml_to_hescore import HPXMLtoHEScoreTranslator
+from hescorehpxml import HPXMLtoHEScoreTranslator
 
 def main():
     thisdir = os.path.dirname(os.path.abspath(__file__))

setup.py

@@ -0,0 +1,44 @@
+from setuptools import setup
+# To use a consistent encoding
+from codecs import open
+from os import path
+
+here = path.abspath(path.dirname(__file__))
+
+
+# Get the long description from the README file
+with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
+    long_description = f.read()
+
+setup(
+    name='hescore-hpxml',
+    version='3.0',
+    description='HPXML Translator for the HEScore API',
+    long_description=long_description,
+    url='https://github.com/NREL/hescore-hpxml',
+    author='Noel Merket (NREL)',
+    author_email='[email protected]',
+    license='BSD-2',
+    classifiers=[
+        'Development Status :: 5 - Production/Stable',
+        'Environment :: Console',
+        'Intended Audience :: Science/Research',
+        'License :: OSI Approved :: BSD License',
+        'Natural Language :: English',
+        'Operating System :: OS Independent',
+        'Programming Language :: Python :: 2.7',
+        'Topic :: Scientific/Engineering',
+        'Topic :: Text Processing :: Markup :: XML',
+    ],
+    keywords='home energy score hescore doe nrel',
+    packages=['hescorehpxml'],
+    install_requires=['lxml'],
+    include_package_data=True,
+    entry_points={
+        'console_scripts': [
+            'hpxml2hescore=hescorehpxml:main',
+            'hescorejsons=hescorehpxml.create_all_example_json:main'
+        ]
+    }
+)
+

code/tests.py → tests/tests.py

@@ -3,7 +3,7 @@
 import unittest
 import datetime as dt
 from lxml import etree
-from hpxml_to_hescore import HPXMLtoHEScoreTranslator, TranslationError, InputOutOfBounds
+from hescorehpxml import HPXMLtoHEScoreTranslator, TranslationError, InputOutOfBounds
 import StringIO
 import json
 from copy import deepcopy