/jabbbar

Python 3 wrapper for the dribbble API

Primary LanguagePythonDo What The F*ck You Want To Public LicenseWTFPL

Jabbbar

Jabbbar is a Python 3 wrapper for the Dribbble API. It is designed to help you effortlessly interface with the resources and content served by Dribbble.

Please note that you are limited to 60 requests per minute and 1440 requests per day (for calls using OAuth)

Requirements

Before you start using Jabbbar, please ensure you have that you have registered an application with Dribbble on their developers site.

You will be asked to give your app a name, a description, a url and a callback url. (Which will be used to redirect users to your site after they agree to grant you access to their account).

When your app is registered, You will be receive two keys: a client id and a client secret. Make note of those as you will need both to request an access token.

Be careful NOT to share your client secret publicly

Installation

Note: jabbbar is only compatible with python 3.3 and up

To start using Jabbbar in your project, simply run

pip install jabbbar

Depending on your setup and virtualenv settings you may need sudo privileges.

Usage

Authentication

from jabbbar import Jabbbar

# Instantiate the client object
client  = Jabbbar(client_id='CLIENT_ID', client_secret='CLIENT_SECRET', redirect_uri='https://yoursite.com/authorize')

# You can also pass optional scope and state params
client = Jabbbar(client_id='CLIENT_ID', client_secret='CLIENT_SECRET', scope=['write','upload'], state="somerandomsecretstring")

# Generate an authorisation url for your application
auth_url = client.auth_url

Send your users to the auth_url. After they authorise your app, they will be redirected to the redirect_uri you've set in the previous step. The url will contain a query parameter of code that looks something like this: http://yoursite.com/your_redirect_url?code="CODE_RETURNED_IN_REDIRECT".

In your web application back-end, retrieve the code and use it to request an access_token.

# Request an access token based on the code returned in the redirect
access_token = client.set_access_token("CODE_RETURNED_IN_REDIRECT")

You can also instantiate a client directly by passing it an access_token if you have one

client = Jabbbar(access_token="YOUR_ACCESS_TOKEN")

With your access token set, you can start making calls to the API.

Userless Access

Since version 0.2.0, you can make read-only requests against the API's public endpoints.

To do so, just copy your client access token (found in your application page on dribbble.com) and pass it to the client instance.

client = Jabbbar(client_token="YOUR_CLIENT_TOKEN")

Note that you will not be able to access protected resources with a userless instance

Usage

Jabbbar exposes the following classes to help you create more readable code: Bucket, Project, Shot, Shots, Team, User

Each class is a direct representation of a resource collection accessible through the API.

To use them, simply import them into your app like this:

from jabbar import Bucket, Project # etc ...

Examples

Users

Create a user object

# ...
# Instantiate your client above
my_user = User(client)
# Get your user's account details
my_user.get_details()

# Get another user's account details
my_user.get_details(username="therealmichaeljordan")

Shots

# Instantiate a Shots object
shots = Shots(client)

# List all shots
shots.list_all()

# Get a specific shot's details
shots.get_one(1234567890)

Teams

# Instantiate a Team object
my_team = Team(client, team_name="name_of_the_team")

# Get a list of all of the team players
my_team.list_players()

# You can also list the players for other teams
my_team.list_players(team_name="some_other_team")

Projects

# Instantiate a Project object
project = Project(client, project_id=1234567890)

# Get details for the instantiated project
project.get_details()

# You can also details for other projects
project.get_details(project_id=12345678980)

Buckets

# Instantiate a Bucket object
bucket = Bucket(client, bucket_id=1234567890)

# Get details for the instantiated bucket
bucket.get_details()

# Create a bucket
bucket.create(name="my_new_bucket", description="a cool bucket")

Shots (individual shots)

# Instantiate a Bucket object
shot = Shot(client, shot_id=1234567890)

# Get a list of all attachments for the instantiated shot
shot.list_attachments()

# Get a list of all attachments for another shot
shot.list_attachments(shot_id=9283328392)

Full List Of Methods

User.get_details()
User.list_buckets()
User.list_shot_likes()
User.list_projects()
User.list_shots()
User.list_teams()
User.list_followers()
User.list_following()
User.list_shots_from_following()
User.check_following()
User.follow_user()
User.unfollow_user()

Team.list_players()
Team.list_shots()

Shots.list_all()
Shots.get_one()

Shot.list_attachments()
Shot.get_attachment()
Shot.list_buckets()
Shot.list_comments()
Shot.list_comment_likes()
Shot.get_comment()
Shot.check_user_likes_comment()
Shot.like_comment()
Shot.unlike_comment()
Shot.list_likes()
Shot.like()
Shot.unlike()
Shot.list_projects()
Shot.list_rebounds()
Shot.check_user_likes_shots()

Project.get_details()
Project.get_shots()

Bucket.get_details()
Bucket.create()
Bucket.update()
Bucket.delete()
Bucket.list_shots()
Bucket.add_shot()
Bucket.remove_shot()

Testing

In order to run the tests, follow these 3 steps:

  • Rename jabbbar/tests/credentials.example.py to credentials.py
  • Fill in your credentials
  • run nosetests

Contribution and Improvements

If you spot code smells and wish to make improvements, please feel free to do so by way of pull requests, explaining how the solution you're proposing is better (I don't have a massive ego, I'm just trying to improve 😄)

License

Jabbbar is licensed under the Do What The Fuck You Want license.

Todo

  • Create a Jabbar.rate_limit() method
  • Create a Jabbar.remaining_requests() method

Need a player account

  • Shots.upload
  • Shots.update
  • Shots.delete
  • Shot.create_attachement
  • Shot.delete_comment
  • Shot.create_comment
  • Shot.update_comment
  • Shot.delete_comment

Build Status

Build Status