Tamu docs, Tamu CLI, test_cli.py, parallelize tests

AUTHORS.rst

@@ -0,0 +1 @@
+docs/authors.rst

Makefile

@@ -7,7 +7,7 @@ init:
 	pip install -r requirements.txt
 
 test:
-	py.test test_geocoder.py --verbose
+	py.test -n auto tests --doctest-modules --pep8 geocoder -v --cov geocoder --cov-report term-missing
 
 clean:
 	python setup.py clean --all

docs/authors.rst

@@ -11,7 +11,7 @@ Contributors
 
 A big thanks to all the people that help contribute:
 
-- `Yed Podtrzitko`_ - Cleaned out code & implemented six.
+- `Michael R. Okun`_ - Implemented Tamu provider
 - `Palo Dravecky`_ - Added Google for Work.
 - `Dunice Vadimh`_ - Added IPInfo provider.
 - `Yed Podtrzitko`_ - Cleaned up code & Added Six
@@ -27,6 +27,7 @@ A big thanks to all the people that help contribute:
 - patrickyan_ - Submitted Github Issues
 - esy_ - Submitted Github Issues
 
+.. _`Michael R. Okun`: https://github.com/ac6y
 .. _`Yed Podtrzitko`: https://github.com/yedpodtrzitko
 .. _`Palo Dravecky`: https://github.com/Chartres
 .. _`Dunice Vadimh`: https://github.com/dunice-vadimh
@@ -45,4 +46,4 @@ A big thanks to all the people that help contribute:
 .. _`Alexander Lukanin`: https://github.com/alexanderlukanin13
 .. _flebel: https://github.com/flebel
 .. _patrickyan: https://github.com/patrickyan
-.. _esy: https://github.com/lambda-conspiracy
+.. _esy: https://github.com/lambda-conspiracy

docs/index.rst

@@ -81,6 +81,7 @@ Detailed information about each individual provider that are within Geocoder.
     providers/GeoOttawa.rst
     providers/HERE.rst
     providers/IPInfo.rst
+    providers/Tamu.rst
     providers/TomTom.rst
     providers/What3Words.rst
     providers/Yahoo.rst

docs/providers/Tamu.rst

@@ -0,0 +1,75 @@
+Tamu
+======
+The Texas A&M Geoservices Geocoding API provides output including Lat and Lon
+and numerous census data values.
+
+An API key linked to an account with Texas A&M is required.
+
+Tamu's API differs from the other geocoders in this package in that it
+requires the street address, city, state, and US zipcode to be passed in
+separately, rather than as a single string.  Because of this requirement,
+the "location", "city", "state", and "zipcode" parameters are all required
+when using the Tamu provider.  The "location" parameter should contain only
+the street address of the location.
+
+Geocoding
+~~~~~~~~~
+
+.. code-block:: python
+
+    >>> import geocoder
+    >>> g = geocoder.tamu(
+                '595 Market St',
+                city='San Francisco',
+                state='California',
+                zipcode='94105',
+                key='demo')
+    >>> g.json
+    ...
+
+Command Line Interface
+----------------------
+
+.. code-block:: bash
+
+    $ geocode '595 Market St' --provider tamu --city San Francisco --state CA --zipcode 94105 --key <Secret API Key>
+
+Environment Variables
+----------------------
+
+To make sure your API key is store safely on your computer, you can define that API key using your system's environment variables.
+
+.. code-block:: bash
+
+    $ export TAMU_API_KEY=<Secret API Key>
+
+Parameters
+----------
+
+- `location`: The street address of the location you want geocoded.
+- `city`: The city of the location to geocode.
+- `state`: The state of the location to geocode.
+- `zipcode`: The zipcode of the location to geocode.
+- `key`: use your own API Key from Tamu.
+- `method`: (default=geocode) Use the following:
+
+  - geocode
+
+Census Output Fields
+-------------
+Note: "FIPS" stands for "Federal Information Processing System"
+
+- `census_block`: Census Block value for location
+- `census_tract`: Census Tract value for location
+- `census_county_fips`: Census County FIPS value
+- `census_cbsa_fips`: Census Core Base Statistical Area FIPS value
+- `census_mcd_fips`: Census Minor Civil Division FIPS value
+- `census_msa_fips`: Census Metropolitan Statistical Area FIPS value
+- `census_place_fips`: Census Place FIPS value
+- `census_state_fips`: Census State FIPS value
+- `census_year`: Census Year from which these values originated
+
+
+References
+----------
+- `Tamu Geocoding API <http://geoservices.tamu.edu/Services/Geocode/WebService/>`_

geocoder/cli.py

@@ -10,7 +10,7 @@
 from geocoder.api import options
 
 
-providers = options.keys()
+providers = sorted(options.keys())
 methods = ['geocode', 'reverse', 'elevation', 'timezone']
 outputs = ['json', 'osm', 'geojson', 'wkt']
 units = ['kilometers', 'miles', 'feet', 'meters']
@@ -27,6 +27,10 @@
 @click.option('--url', default='')
 @click.option('--proxies')
 @click.option('--key')
+# following are for Tamu provider
+@click.option('--city', '-c', default='')
+@click.option('--state', '-s', default='')
+@click.option('--zipcode', '-z', default='')
 def cli(location, **kwargs):
     "Geocode an arbitrary number of strings from Command Line."
 

requirements-dev.txt

@@ -3,4 +3,5 @@ setuptools >= 0.9.8
 pytest
 pytest-cov
 pytest-pep8
-wheel
+pytest-xdist
+wheel

tests/test_cli.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python
+# coding: utf8
+"""
+Unit tests for cli functionality
+"""
+
+# --- Imports
+
+import subprocess
+
+import geocoder
+
+# --- Constants
+
+_CLI_EX = './geocoder/cli.py'  # CLI executable path
+
+
+us_address = '595 Market St'
+us_city = 'San Francisco'
+us_state = 'CA'
+us_zipcode = '94105'
+
+location = ' '.join([us_address, us_city, us_state, us_zipcode])
+
+
+# --- CLI tests.  Each shell call should have return code 0 if successfull.
+
+def test_cli_default():
+    # default provider cli test
+    assert not subprocess.call(['python', _CLI_EX, location])
+
+
+def test_cli_tamu():
+    # tamu provider cli test
+    provider = 'tamu'
+    key_env_var = '$TAMU_API_KEY'
+    assert not subprocess.call([
+        'python', _CLI_EX, us_address,
+        '--city', us_city, '--state', us_state, '--zipcode', us_zipcode,
+        '--provider', provider,
+        '--key', key_env_var,
+    ])