Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

rename sunlight.common to sunlight.config and move API_KEY into it

  • Loading branch information...
commit 6f2e2caf50a7332c39ebda1830142c29afac8a22 1 parent f72b443
James Turk jamesturk authored
1  .gitignore
View
@@ -1,2 +1,3 @@
*.swp
*.pyc
+docs/build
33 docs/source/index.rst
View
@@ -5,7 +5,7 @@ python-sunlight
Overview
========
-python-sunlight serves as a unified API wrapper for the various `open government data
+python-sunlight provides a unified set of API clients for the various `open government data
APIs <http://services.sunlightlabs.com>`_ made available by `Sunlight Foundation <http://sunlightfoundation.com>`_
projects.
@@ -24,33 +24,33 @@ Installation
The simplest way to install python-sunlight is via `pip <http://www.pip-installer.org/>`_::
- pip install python-sunlight
+ $ pip install python-sunlight
You may also wish to check the project out from `GitHub <http://github.com/sunlightlabs/python-sunlight>`_::
- git clone git://github.com/sunlightlabs/python-sunlight.git
+ $ git clone git://github.com/sunlightlabs/python-sunlight.git
-Now all you need is a `Sunlight API Key <http://services.sunlightlabs.com/accounts/register/>`_ and you can get started!
-.. note::
- After obtaining a key you can use it without exposing it in your code by placing it in a file at :file:`~/.sunlight.key` or in an
- environment variable named :envvar:`SUNLIGHT_API_KEY`. Alternatively you can set :data:`sunlight.service.API_KEY`.
+Usage
+=====
-import sunlight
-===============
+`Register for a Sunlight API Key <http://services.sunlightlabs.com/accounts/register/>`_ if you haven't already, then you'll be ready to start using the library.
+
+The recommended method of providing the library with your API key is by placing your key in a file at :file:`~/.sunlight.key`. Alternatively you can use an environment variable named :envvar:`SUNLIGHT_API_KEY` or set :data:`sunlight.service.API_KEY` within your program.
After setting your API key simply ``import sunlight`` and start using the APIs::
- import sunlight
- nc_legs = sunlight.openstates.legislators(state='nc')
+ >>> import sunlight
+ >>> nc_legs = sunlight.openstates.legislators(state='nc')
You can also import a specific API client::
- from sunlight import congress
- pelosi = congress.legislators(lastname='Pelosi')[0]
+ >>> from sunlight import congress
+ >>> pelosi = congress.legislators(lastname='Pelosi')[0]
+
-APIs
-----
+For details on how to use the various APIs check out the documentation for the
+individual clients:
.. toctree::
:maxdepth: 2
@@ -67,9 +67,8 @@ Implementation details, for extending python-sunlight or more untraditional uses
.. toctree::
:maxdepth: 2
- sunlight.rst
sunlight/service.rst
- sunlight/common.rst
+ sunlight/config.rst
sunlight/errors.rst
Indices and tables
48 docs/source/sunlight.rst
View
@@ -1,48 +0,0 @@
-__init__ -- Facade for the OpenStates API Bindings
-==================================================
-
-The module __init__ contains a number of things to help make using the API a
-bit easier then it usually is. At it's core, the APIs are implemented as
-subclasses of the :class:`sunlight.service.Service` class, so importing each
-would require ugly imports (such as ``import sunlight.services.openstates``)
-
-.. warning::
- Currently, the bindings are incomplete. Please keep this in mind, and
- do consider contributing some code to interface with the API in question.
-
-Bugs with the API (as you're no doubt aware) can be filed, searched, adored
-and jeered `on github <https://github.com/paultag/python-sunlight/issues>`_.
-Please do note, however, that issues with the *data* that's returned by the API
-should be filed with the project in question. For information on where to file
-that brand of bug, please check the class that you're using.
-
-Methods and Aliases
-*******************
-
-.. automodule:: sunlight
- :members:
-
-Example Usage
-*************
-
-Here are some examples on how to use some of the more notable members of the
-Sunlight API family. For more examples, check the doc page of the exact class
-that you're using - there'll be more on them there.
-
-.. note::
- Please do note these examples may be incomplete or break at any time.
- They're maintained as part of the documentation effort, so please report
- any breakage you find!
-
-OpenStates in 5 seconds::
-
- from sunlight import openstates
-
- bills = openstates.bills(
- q="agriculture",
- state="vt",
- chamber="upper"
- )
-
- for bill in bills:
- print "%s: %s" % ( bill['bill_id'], bill['title'] )
6 docs/source/sunlight/common.rst → docs/source/sunlight/config.rst
View
@@ -1,5 +1,5 @@
-sunlight.common -- Yar! Here be dragons!
-========================================
+sunlight.config
+===============
This particular module is full of all sorts of fun tidbits
that the API uses all over the place, such as file locations, strings that might
@@ -8,6 +8,6 @@ change at some point and all that.
Methods and Constants
*********************
-.. automodule:: sunlight.common
+.. automodule:: sunlight.config
:members:
9 docs/source/sunlight/services/influenceexplorer.rst
View
@@ -1,9 +0,0 @@
-Influence Explorer - Explore people or companies
-================================================
-
-Class Documentation
-*******************
-
-.. automodule:: sunlight.services.influenceexplorer
- :members:
-
23 sunlight/__init__.py
View
@@ -24,10 +24,11 @@
influenceexplorer = sunlight.services.influenceexplorer.InfluenceExplorer()
import os.path
-import sunlight.common
+import warnings
+import sunlight.config
import sunlight.service
-def attempt_to_load_apikey():
+def _attempt_to_load_apikey():
"""
This function (which will be auto-called on import of :mod:`sunlight`),
will attempt to pull the Sunlight API Key from a few places (to offload
@@ -39,21 +40,17 @@ def attempt_to_load_apikey():
"""
try:
- fp = os.path.expanduser(sunlight.common.KEY_LOCATION)
+ fp = os.path.expanduser(sunlight.config.KEY_LOCATION)
fd = open(fp, 'r')
- sunlight.service.API_KEY = fd.read().strip()
- # print "D: Read API key from: %s" % fp
+ sunlight.config.API_KEY = fd.read().strip()
except IOError as e:
- # print "D: No API key found at: %s" % fp
if e.errno != 2:
- print "W: Warning! " + e
+ warnings.warn('key file %s exists but could not be opened: %s' % (
+ sunlight.config.KEY_LOCATION, str(e)))
try:
- sunlight.service.API_KEY = \
- os.environ[sunlight.common.KEY_ENVVAR].strip()
- #print "D: Found API key in the env: %s" % sunlight.common.KEY_ENVVAR
+ sunlight.config.API_KEY = \
+ os.environ[sunlight.config.KEY_ENVVAR].strip()
except KeyError as e:
pass
- #print "D: No API key in the environ: %s" % sunlight.common.KEY_ENVVAR
- #print "D: API key: %s" % sunlight.service.API_KEY
-attempt_to_load_apikey()
+_attempt_to_load_apikey()
12 sunlight/common.py → sunlight/config.py
View
@@ -10,6 +10,18 @@
wrong.
"""
+
+API_KEY = None
+"""
+This might be populated from :func:`sunlight.attempt_to_load_apikey`, or
+``None`` (as it is out of the box). All :class:`sunlight.service.Service`
+objects will make use of this API key (once, in it's __init__, not after that)
+to do their job.
+
+.. note::
+ All Sunlight services share API keys. Nice, right?
+"""
+
API_SIGNUP_PAGE = "http://services.sunlightlabs.com/accounts/register/"
"""
This is a link to the API Key signup page - so that we can sanely direct people
4 sunlight/errors.py
View
@@ -48,7 +48,7 @@ class InvalidRequestException(BadRequestException):
class NoAPIKeyException(SunlightException):
"""
- This gets thrown if the bindings are asked to issue a requst, but the
- ``sunlight.service.API_KEY`` variable is ``None``.
+ This gets thrown if the bindings are asked to issue a request, but the
+ ``sunlight.config.API_KEY`` variable is ``None``.
"""
pass
24 sunlight/service.py
View
@@ -9,21 +9,11 @@
:class:`sunlight.services.openstates.OpenStates`) inherit from this.
"""
-import sunlight.common
+import sunlight.config
import sunlight.errors
import urllib2
-API_KEY = None
-"""
-This might be populated from :func:`sunlight.attempt_to_load_apikey`, or ``Null``
-(as it is out of the box). All :class:`sunlight.service.Service` objects will
-make use of this API key (once, in it's __init__, not after that) to do their
-job.
-
-.. note::
- All Sunlight services share API keys. Nice, right?
-"""
class Service:
"""
@@ -43,29 +33,29 @@ def get( self, top_level_object, **kwargs ):
args:
``top_level_object`` (str): Thing to query for (such as say,
"bills" for OpenStates )
-
+
kwargs:
These arguments will be passed to the underlying API implementation
to help create a query. Validation will happen down below, and
on a per-API level.
"""
- if API_KEY == None:
+ if sunlight.config.API_KEY == None:
raise sunlight.errors.NoAPIKeyException(
-"Warning: Missing API Key. please visit " + sunlight.common.API_SIGNUP_PAGE +
+"Warning: Missing API Key. please visit " + sunlight.config.API_SIGNUP_PAGE +
" to register for a key.")
- url = self._get_url( top_level_object, API_KEY, **kwargs)
+ url = self._get_url(top_level_object, sunlight.config.API_KEY,
+ **kwargs)
req = urllib2.Request(url)
try:
r = urllib2.urlopen(req)
return_data = r.read()
return self._decode_response( return_data )
except urllib2.HTTPError as e:
-
message = e.read()
code = e.getcode()
- ex = sunlight.errors.BadRequestException( "Error (%s) -- %s" % (
+ ex = sunlight.errors.BadRequestException("Error (%s) -- %s" % (
code, message
))
Please sign in to comment.
Something went wrong with that request. Please try again.