# OpenEarth python guidelines #

This is the directory for python applications and libraries. 

There are important directories:
OpenEarthTools -> General and small utilties (plot, io)
applications   -> Separate applications and packages that are distributed on their own. 
notebooks      -> Html-based tutorials

If you want to use a package (and develop it) go to the main package directory
http://stackoverflow.com/questions/19048732/python-setup-py-develop-vs-install
http://stackoverflow.com/questions/458550/standard-way-to-embed-version-into-python-package

> cd X:\checkouts\OpenEarthTools\python\OpenEarthTools\

and use:

> python setup.py develop

It will be added to your path so you can use it anywhere on your machine.
Register any new package in ....\OpenEarthTools\OpenEarthTools.egg-info\SOURCES.txt
For example, this will add the main OpenEarthTools package to your path:
> cd OpenEarthTools
> python setup.py develop
you will get a log like this:

# running develop
# running egg_info
# writing OpenEarthTools.egg-info\PKG-INFO
# writing top-level names to OpenEarthTools.egg-info\top_level.txt
# writing dependency_links to OpenEarthTools.egg-info\dependency_links.txt
# writing entry points to OpenEarthTools.egg-info\entry_points.txt
# reading manifest file 'OpenEarthTools.egg-info\SOURCES.txt'
# writing manifest file 'OpenEarthTools.egg-info\SOURCES.txt'
# running build_ext
# Creating c:\python27\lib\site-packages\OpenEarthTools.egg-link (link to .)
# Adding OpenEarthTools 0.1dev to easy-install.pth file
# 
# Installed d:\checkouts\openearthtools\python\openearthtools
# Processing dependencies for OpenEarthTools==0.1dev
# Finished processing dependencies for OpenEarthTools==0.1dev

You can now use it for instance as 
> python

>>> import openearthtools.io.delft3d as d3d
More on adding python modules under development:
https://docs.python.org/2/install/
https://docs.python.org/2/distutils/setupscript.html

If you want to add python applications or libraries, please use pep-8 as a style
guide (http://www.python.org/dev/peps/pep-0008/).
Add your tools by adding a folder, and putting an empty __init__.py in that folder.

Please make sure that the library you make is installable using distutils. The distutils guide
should get you started (http://docs.python.org/distutils/index.html#distutils-index).
To install libraries please use pip. Refer to the install guide
(http://docs.python.org/install/index.html#install-index) and pip 
guide (http://www.pip-installer.org/en/latest/index.html)  for details. 
Make sure you setup the dependencies in your library or application, so they will automatically download. 

For mature packages please register and upload them to pypi. 

* As a python distribution for windows, we recommend PythonXY 
  (http://code.google.com/p/pythonxy/)
  It has loads of packages, all of which are optional. You can use   
  the windows installer too to remove packages.
  Manually install the following additional packages:
* pyproj installer from pythonXY to convert coordinates using PROJ4 library.
  (http://code.google.com/p/pyproj/)
  The underlying PROJ4 library is also shipped with the baseplot package.
  (http://matplotlib.org/basemap/)
* netCDF4 with OPeNDAP support: installer from pythonXY 
  netCDF4 is already included in PythonXY, but this version 
  has not been compiled with OPeNDAP support. Remove the present 
  netCDF4 package before installing an OPeNDAP-enabled one.
  (http://code.google.com/p/netcdf4-python/)
* pydap: see http://pydap.org/
  not strictly needed with OPeNDAP-enabled netCDF4 package
  (http://code.google.com/p/pydap/)

For OSX you are advised to use macports. 
Also try to be ready to support python 3, see http://wiki.python.org/moin/PortingPythonToPy3k for details.
My suggestion would be to use: Approach 2: Make code run unmodified in both Python 2 and Python 3. 

Don't put effort into supporting python <2.7 and <3.2. 
Make sure you check your code using:
- pep8
- PyFlakes
- pychecker
- pylint

Please make unit tests (nosetests). Aim for a 60-70% coverage.

# Documentation # 
If you want to learn python please refer to the following interesting sources:

http://en.wikibooks.org/wiki/How_to_Think_Like_a_Computer_Scientist:_Learning_with_Python_2nd_Edition
http://openbookproject.net/thinkcs/python/english2e/index.html

Please feel free to update this document with useful comments.