==========================
Active Resource for Python
==========================

**Note**: This not Active *Record*, but Active *Resource*.

What is Active Resource?
------------------------

From the `Active Resource README <http://api.rubyonrails.com/files/vendor/rails/activeresource/README.html>`_: 

    Active Resource attempts to provide a coherent wrapper object-relational mapping for REST web services. It follows the same philosophy as Active Record, in that one of its prime aims is to reduce the amount of code needed to map to these resources.

PyActiveResource aims to be a comprehensive translation of Active Resource in Python.

Install
-------

Requirements:

- Python 2.3+
- `ElementTree (cElementTree recommended) <http://effbot.org/zone/element-index.htm>`_

If you have setuptools installed, simply run::

    $ easy_install pyactiveresource
    
Otherwise download the package from here and run the setup::

    $ python setup.py install
    
Example Usage
-------------
::

    from pyactiveresource import ActiveResource

    class Person(ActiveResource):
        class Meta:
            site = 'https://example.com/'
            
At this point we can create, update, retrieve, and delete Person objects::

    # Creation
    p = Person(name='Jared Kuolt')
    p.save()    # True

    # Updating
    p.awesome = True
    p.save()

    # Deleting
    p.destroy()

    # Retrieval
    
    # One resource
    Person.find(id=1)[0]
    # All resources
    Person.find()
    
Since Ruby on Rails uses advanced pluralization of objects, PyActiveResource automatically sets the plural name, however this isn't smart pluralization; it simply appends an 's' to the object. In our example we need to set the plural name to "people" which we can do like so::

    class Person(ActiveResource):
        class Meta:
            site = 'https://example.com/'
            name_plural = 'people'
