Metadata-Version: 1.1
Name: restorm
Version: 0.2
Summary: RestORM allows you to interact with resources as if they were objects.
Home-page: http://github.com/joeribekker/restorm
Author: Joeri Bekker
Author-email: joeri@maykinmedia.nl
License: MIT
Description: .. image:: https://secure.travis-ci.org/joeribekker/restorm.png?branch=master
            :alt: Build Status
            :target: http://travis-ci.org/joeribekker/restorm
        
        RestORM
        =======
        
        RestORM allows you to interact with resources as if they were objects (object
        relational mapping), mock an entire API and incorporate custom client logic.
        
        Description
        -----------
        
        RestORM structures the way you access a RESTful API and allows you to easily
        access related resources. It tries to be as generic as possible so it's not
        tailored to any specific API or server-side API library. With RestORM you can
        mock an entire API and replace the real client with a mock version in unit
        tests. RestORM is very extensible but offers many functionalities out of the box
        to get you up and running quickly.
        
        Currently, RestORM works on Python 2.5+ with Python 3 support on its way.
        
        Features
        --------
        
        * Object relational mapping of API resources (Django-like but does not depend on
          Django at all).
        * Flexible client architecture that can be used with your own or third party
          clients (like oauth).
        * Extensive mocking module allows you to mock API responses, or even 
          complete API's.
        * Examples for Twitter and Flickr API.
        
        Quick start
        ===========
        
        This is a compressed version of the tutorial. The full documentation can be 
        found `here <https://restorm.readthedocs.org>`_.
        
        Create a client
        ---------------
        
        A typical client that can talk to a RESTful API using JSON, is no more then:
        
        .. sourcecode:: python
        
            from restorm.clients.jsonclient import JSONClient
            
            client = JSONClient(root_uri='http://www.example.com/api/')
            
        Instead of this client, we mock its intended behaviour.
            
        Create a mock API
        -----------------
        
        In order to test your client, you can emulate a whole API using the
        ``MockApiClient`` and add pre-defined responses.
        
        The mock API below contains a list of books and a list of authors. To keep it 
        simple, both list resources contain only 1 item:
        
        .. sourcecode:: python
        
            from restorm.clients.mockclient import MockApiClient
            
            mock_client = MockApiClient(
                responses={
                    'book/': {'GET': ({'Status': 200}, [{'isbn': 1, 'title': 'Dive into Python', 'resource_url': 'http://www.example.com/api/book/1'}])},
                    'book/1': {'GET': ({'Status': 200}, {'isbn': 1, 'title': 'Dive into Python', 'author': 'http://www.example.com/api/author/1'})},
                    'author/': {'GET': ({'Status': 200}, [{'id': 1, 'name': 'Mark Pilgrim', 'resource_url': 'http://www.example.com/author/1'}])},
                    'author/1': {'GET': ({'Status': 200}, {'id': 1, 'name': 'Mark Pilgrim'})}
                },
                root_uri='http://www.example.com/api/'
            )
        
        Define resources
        ----------------
        
        We start with our main resource, the ``Book`` resource as a subclass of 
        ``Resource``. Two attributes in the inner ``Meta`` class indicate a URL-pattern
        how we can access all books (``list``) and a single book (``item``):
        
        .. sourcecode:: python
        
            from restorm.resource import Resource
        
            class Book(Resource):
                class Meta:
                    list = r'^book/$'
                    item = r'^book/(?P<isbn>\d)$'
        
        Bringing it all together
        ------------------------
        
        You can access the ``Book`` resource and the (runtime created) related 
        ``Author`` resource using the ``mock_client``:
        
        .. sourcecode:: python
        
            >>> book = Book.objects.get(isbn=1, client=mock_client) # Get book with ISBN number 1.
            >>> book.data['title'] # Get the value of the key "name".
            u'Dive into Python'
            >>> book.data['author'] # Get the value of the key "author".
            u'http://www.example.com/api/author/1'
            >>> author = book.data.author # Perform a GET on the "author" resource.
            >>> author.data['name']
            u'Mark Pilgrim'
        
        Installation
        ============
        
        RestORM is on PyPI, so you can simply use::
        
            $ pip install restorm
        
        If you want the latest development version, get the code from Github::
        
            $ pip install -e git+git://github.com/joeribekker/restorm.git#egg=restorm
        
        
        Changes
        =======
        
        0.2
        ---
        **December 4, 2012**
        
        - Fixed bug in ``MockClient`` to pop the correct response.
        - Added ``restorm.conf.settings`` to store the DEFAULT_CLIENT to use.
        - Added ability to create a development server from your ``MockApiClient``.
        - Added ``root_uri`` parameter to ``Client`` constructor.
        - Added initial XML client implemention (alpha).
        - Added initial documentation.
        - Added simplejson 2.2.1 or above as required library.
        
        0.1
        ---
        **November 9, 2012**
        
        - Initial version released on PyPI.
        
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development
