Introduction
============

`collective.cicero` provides access to Azavea_'s `Cicero API`_ for performing
geography-based lookups of political data.  It is designed for integration with
Plone, but can be used in other contexts as well.

.. _Azavea: http://www.azavea.com
.. _`Cicero API`: http://www.azavea.com/products/cicero/api.aspx

Usage
-----

Access to the API is provided via the `call_cicero` method::

  call_cicero(service_name, method_name, *args, **kw)

`service_name` is one of the `Cicero web services`_. Currently the only
supported option is 'ElectedOfficialQueryService'.

`method_name` is one of the SOAP methods supported by the chosen service.

`*args` and `**kw` are the additional parameters required by the chosen
method.  See the `Cicero API documentation`_ for details.

.. _`Cicero web services`: http://www.azavea.com/Products/Cicero/API/CiceroWebServiceEndpoints.aspx
.. _`Cicero API documentation`: http://cicero.azavea.com/Azavea_cicero_v2_docs/

Settings
--------

The Cicero credentials (username and password) are looked up via a
`plone.registry`_-style IRegistry utility. In Plone, activating the
`plone.app.registry`_ package followed by `collective.cicero` will set up a
suitable registry with the relevant settings available.

.. _`plone.registry`: http://pypi.python.org/pypi/plone.registry
.. _`plone.app.registry`: http://pypi.python.org/pypi/plone.app.registry


Test Mode
---------

A `test mode` is supported. In test mode, canned responses will be loaded from
disk instead of actually querying Cicero.

Enable test mode by setting the `CICERO_TEST` environment variable. If this
variable is present in the operating system environment, test mode will be used.

For test mode to work, the tests folder must contain a copy of the WSDL for the
service being tested, as well as a response file for the method being tested.
Responses can be obtained by running in normal mode with suds configured to log
at the debug level. A sample response for the GetOfficialsByAddress method of
the ElectedOfficialQueryService is included.

