Metadata-Version: 1.0
Name: three
Version: 0.2
Summary: An easy-to-use wrapper for the Open311 API
Home-page: UNKNOWN
Author: Zach Williams
Author-email: hey@zachwill.com
License: MIT
Description: Three
        =====
        
        An updated [Open311 API](http://wiki.open311.org/GeoReport_v2) Python wrapper
        that was built to be as absolute **user-friendly** and **easy-to-use as
        possible**. Many of the design decisions made will reflect these
        qualities.
        
        
        Installation
        ------------
        
        This is still a work in progress, but you can `git clone` this repo and
        run `python setup.py install` to check out the current progress.
        
        
        Settings
        --------
        
        ### API Key
        
        If you have an Open311 API key that you always intend to use, rather
        than initializing the `Three` class with it each time, you can set an
        `OPEN311_API_KEY` environment variable on the command line.
        
            export OPEN311_API_KEY="MY_API_KEY"
        
        Otherwise, you can initialize the class with your API key and endpoint.
        
            >>> from three import Three
            >>> t = Three('api.city.gov', api_key='my_api_key')
        
        
        ### HTTPS
        
        By default, `Three` will configure a URL without a specified schema to
        use `HTTPS`.
        
            >>> t = Three('api.city.gov')
            >>> t.endpoint == 'https://api.city.gov/'
            True
        
        
        ### Format
        
        The default format for the `Three` wrapper is `JSON` -- although not all
        [Open311 implementations support it](http://wiki.open311.org/GeoReport_v2#Format_Support).
        This is done mainly for easy-of-use (remember, that's the over-arching
        goal of the `Three` wrapper). You can, however, specifically request to
        use `XML` as your format of choice.
        
            >>> t = Three('api.city.gov', format='xml')
            >>> t.format == 'xml'
            True
        
        
        Usage
        -----
        
        ### Configure
        
        After you've initialized your `Three` class, you can readjust its
        settings with the `configure` method. You can also switch back to the
        orgininal settings with the `reset` method.
        
            >>> from three import Three
            >>> t = Three('api.city.gov', api_key='SECRET_KEY')
            >>> t.services()
            {'service': 'data'}
            >>> t.configure('open311.sfgov.org/dev/V2/', format='xml'
            ...             api_key='SF_OPEN311_API_KEY')
            >>> t.services()
            {'SF': {'service': 'data'}}
            >>> t.configure(api_key='ANOTHER_API_KEY')
            >>> # Switch back to original settings.
            ... t.reset()
        
        
        ### Discovery
        
        In order to use the [Open311 service discovery](http://wiki.open311.org/Service_Discovery),
        simply invoke the `discovery` method.
        
            >>> t = Three('api.city.gov')
            >>> t.discovery()
            {'service': {'discovery': 'data'}}
        
        Sometimes, however, service discovery paths differ from service and
        request URL paths -- in which case you can pass the specified URL to the
        `discovery` method as an argument.
        
            >>> t.discovery('http://another.path.gov/discovery.json')
        
        
        ### Services
        
        To see the available services provided by an Open311 implementation, use
        the `services` method.
        
            >>> t = Three('api.city.gov')
            >>> t.services()
            {'all': {'service_code': 'info'}}
        
        You can also specify a specific service code to get information about.
        
            >>> t.services('033')
            {'033': {'service_code': 'info'}}
        
        
        ### Requests
        
        To see available request data, use the `requests` method.
        
            >>> t = Three('api.city.gov')
            >>> t.requests()
            {'all': {'requests': 'data'}}
        
        You can also specify a specific service code.
        
            >>> t.requests('123')
            {'123': {'requests': 'data'}}
        
        Other parameters can also be passed as keyword arguments.
        
            >>> t.requests('456', status='open')
            {'456': {'open': {'requests': 'data'}}}
        
        
        ### Request
        
        If you're looking for information on a specific Open311 request (and you
        have it's service code ID), you can use the `request` method.
        
            >>> t = Three('api.city.gov')
            >>> t.request('12345')
            {'request': {'service_code_id': {'12345': 'data'}}}
        
        
        ### Post
        
        Sometimes you might need to programmatically create a new request, which
        is what the `post` method can be used for. **NOTE**: the Open311 spec
        states that all POST service requests [require a valid API
        key](http://wiki.open311.org/GeoReport_v2#POST_Service_Request).
        
            >>> t = Three('api.city.gov', api_key='SECRET_KEY')
            >>> t.post('123', name='Zach Williams', address='85 2nd St',
            ...        description='New service code 123 request.')
            {'new': {'request': 'created'}}
        
        
        ### Token
        
        Each service request ID can be tracked with a temporary token. If you
        need to find the service request ID and have the request's token, you
        can use the `token` method.
        
            >>> t = Three('api.city.gov')
            >>> t.token('12345')
            {'service_request_id': {'for': {'token': '12345'}}}
        
Platform: UNKNOWN
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
