python-parsely 1.4

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/>.