Parsely API Python Binding
==========================

This library provides a pure Python interface for the Parsely API.
The documentation, on which this binding is based, can be found at
http://parsely.com/api/api_ref.html

Installation
------------

python-parsely is available on PyPI. To download it, use pip:

    pip install python-parsely requests

You need to install requests alongside python-parsely due to a pip bug.

Getting the Code
----------------

Git clone this repository - it's the primary source of the python-parsely code.

    git clone http://github.com/emmett9001/python-parsely.git

Using python-parsely
--------------------

To use Parsely from Python, first import it

    >>> import parsely

Create a new Parsely object with your public and private API keys

    >>> p = parsely.Parsely("arstechnica.com", secret="asf98gf7aw98ev7nwe98vfayewfa9hew8f7ha")

To get a list of recent top posts, use

    >>> posts = p.analytics()

The objects in this list are Posts:

    >>> posts[1]
    <models.Post instance at 0x21bc828>

You can pass these Posts to other library functions. `meta_detail` returns a list of
Posts sharing the same `aspect` as the Post you give it.

    >>> p.meta_detail(posts[1], aspect="section")[1:2]
    [<models.Post instance at 0x21bc828>]

`post_detail` gives more detailed information on the Post

    >>> p.post_detail(posts[1])

You can also use the library to get shares and referrers information surrounding
given posts.

    >>> p.referrers_meta_detail(posts[1], meta="author")
    >>> p.referrers_post_detail(posts[1])
    >>> p.shares()
    >>> p.shares(post=posts[1])

The `realtime` call can be used to make a live-updating feed of pageview data:

    import time
    for i in range(1,5):
        real = p.realtime(limit=1)
        for r in real:
            print "%s: %d" % (r.title, r.hits)
            print "\n"
        time.sleep(3)

Recommendations API
-------------------

The library handles personalized recommendations via the User class

    >>> from recommendations import User
    >>> user = User(p, "myuuid")

You can train a user profile with a post

    >>> user.train(posts[1])

Get a user's history with `history`

    >>> user.history()

Receive personalized User recommendations with `related`

    >>> user.related()

Testing
-------

To run the unit tests for this library, use

    python tests.py

License
-------

    Copyright (C) 2013 Emmett Butler, Parsely Inc.

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
