caps
====


.. module:: pyogp.lib.base.tests.caps

This is a doctest, the content here is verbatim from the source file at pyogp.lib.base.tests.caps.txt.


The Capabilities component
~~~~~~~~~~~~~~~~~~~~~~~~~~

The Capabilities component basically gives us two objects: a Capability 
and a SeedCapability.

We can instantiate a SeedCapability like this:

    >>> from pyogp.lib.base.tests.mockup_client import MockupClient
    >>> from pyogp.lib.base.caps import SeedCapability, Capability
    >>> from pyogp.lib.base.tests.base import MockAgentDomain
    >>> client = MockupClient(MockAgentDomain())
    >>> seed = SeedCapability('seed', 'http://127.0.0.1:12345/seed_cap', client)

We assume that we got the seed capability URL itself from login or some other service.

We can now ask this SeedCapability object for new capabilities:

    >>> caps = seed.get(['some_capability', 'some_other'])

The result is a dictionary object:

    >>> len(caps.keys())
    2

whose contents are:

    >>> caps['some_capability']
    <Capability 'some_capability' for http://localhost:12345/cap/some_capability>
    >>> caps['some_other']
    <Capability 'some_other' for http://localhost:12345/cap/some_other>

Let's store the some_capability cap in a variable:

    >>> some_cap = caps['some_capability']

The capability now can be simply called with a payload and returns some data itself.

First we call it:

    >>> data = some_cap.POST({'a':'b'})

And now we can check the data:

    >>> data['something']
    'else'
    >>> data['some']
    12345

This data here is provided by the mockup server for testing.

Internals
~~~~~~~~~

Each capability stores it's name and public URL which it is instantiated with. 
We can access these like this:

    >>> some_cap.name
    'some_capability'

    >>> some_cap.public_url
    'http://localhost:12345/cap/some_capability'

As we can see, it's not a secret URL in this mockup case but in production it will be.

We can of course also just instantiate some capability directly:

    >>> cap = Capability("cap", "http://localhost:12345/cap/some_capability", client)

and retrieve it via GET:

    >>> cap.GET()
    {'some': 12345, 'something': 'else'}

or post something to it (the demo will simply update the base dict):

    >>> cap.POST({'Tao':'Takashi'})
    {'Tao': 'Takashi', 'some': 12345, 'something': 'else'}

Testing errors
~~~~~~~~~~~~~~

Now we can test what happens to our code when the server returns a wrong content type.
In this case it should not find a deserializer and say so::

    >>> seed = SeedCapability('seed', 'http://127.0.0.1:12345/seed_cap_wrong_content_type', client)
    >>> cap = seed.get(['some_capability'])
    Traceback (most recent call last):
    ...
    DeserializerNotFound: deserialization for 'text/foobar' not supported

Try the same for GET:

    >>> cap = Capability('test','http://127.0.0.1:12345/cap_wrong_content_type', client)
    >>> cap.GET()
    Traceback (most recent call last):
    ...
    DeserializerNotFound: deserialization for 'text/foobar' not supported

Now we test if network errors are handled correctly::

    >>> cap = Capability('test','http://127.0.0.1:12345/cap/error', client)
    >>> cap.POST({'test':'testing'})
    Traceback (most recent call last):
    ...
    ResourceError: Error using 'POST' on resource 'http://127.0.0.1:12345/cap/error': Internal Server Error (500)

And some 404:

    >>> cap = Capability('test','http://127.0.0.1:12345/cap/unkown', client)
    >>> cap.POST({'test':'testing'})
    Traceback (most recent call last):
    ...
    ResourceNotFound: http://127.0.0.1:12345/cap/unkown