Skip to content
This repository has been archived by the owner on Jan 26, 2023. It is now read-only.

gitcoinco/python-api-client

Repository files navigation

Gitcoin Python API Client

Build Status

This Python package provides the bounties endpoint of the Gitcoin API, which allows you to:

  • list all bounties
  • list all bounties which meet certain conditions (i.e. filter them)
  • retrieve a single bounty by it's primary key

Install via pypi

pip install gitcoin

Usage Examples

List all bounties

from gitcoin import Gitcoin
api = Gitcoin()
all_bounties = api.bounties.all()

List all open bounties

from gitcoin import Gitcoin
api = Gitcoin()
open_bounties = api.bounties.filter(is_open=True).all()

List all open "Beginner" bounties

from gitcoin import Gitcoin
api = Gitcoin()
bounties_api = api.bounties
bounties_api.filter(is_open=True)
bounties_api.filter(experience_level='Beginner')
open_beginner_bounties = bounties_api.all()

The example above has been reformatted for easier reading. A fluent interface is also available. Please scroll the following code block all the way to the end to see the whole line:

from gitcoin import Gitcoin
api = Gitcoin()
open_beginner_bounties = api.bounties.filter(is_open=True, experience_level='Beginner').all()

List all open bounties marked for either "Beginner" OR "Intermediate" experience level

For some filter conditions, multiple different values can be given, which results in a logical OR for that condition:

from gitcoin import Gitcoin
api = Gitcoin()
bounties_api = api.bounties
bounties_api.filter(is_open=True)
bounties_api.filter(experience_level='Beginner')
bounties_api.filter(experience_level='Intermediate')
open_beginner_and_intermediate_bounties = bounties_api.all()

The example above has been reformatted for easier reading. A fluent interface is also available. Please scroll the following code block all the way to the end to see the whole line:

from gitcoin import Gitcoin
api = Gitcoin()
open_beginner_and_intermediate_bounties = api.bounties.filter(is_open=True).filter(experience_level='Beginner').filter(experience_level='Intermediate').all()

API

Instantiation

  1. Create a Gitcoin() API root object:
from gitcoin import Gitcoin
api = Gitcoin()
  1. The bounties API endpoint is accessible as a property of the API root object:
bounties_endpoint = api.bounties

Each access to the bounties property results in a new Endpoint object with no filter conditions or any other parameters (like sorting) set. If you want to keep a specific set of filter conditions, simply store the Endpoint object in a variable instead of referring to the bounties property of the root object.

bounties.filter(**kwargs)

Limit the list of bounties returned by either get_page() or all() to those bounties meeting the filter condition(s). For some filter conditions, multiple different values can be given, which results in a logical OR for that condition.

The condition name is the name of the keyword argument, and the condition value is the value of the keyword argument:

open_bounties = api.bounties.filter(is_open=True).all()

Conditions with different names can be given in one filter() call:

open_beginner bounties = api.bounties.filter(is_open=True, experience_level='Beginner').all()

Or if preferred, they can also be given in separate filter() calls:

open_beginner bounties = api.bounties.filter(is_open=True).filter(experience_level='Beginner').all()

Giving multiple values for the same filter condition has to be done in separate calls to filter():

beginner_and_intermediate_bounties = api.bounties.filter(experience_level='Beginner').filter(experience_level='Intermediate').all()

For the following filter conditions, multiple values can be given to achieve a logical OR:

  • experience_level (str)
  • project_length (str)
  • bounty_type (str)
  • bounty_owner_address (str)
  • bounty_owner_github_username (str)
  • idx_status (str)
  • network (str)
  • standard_bounties_id (int)
  • github_url (str)
  • raw_data (str)

The following filter conditions are single value, in other words, multiple values result in the last value overwriting all earlier values:

  • pk__gt (int)
  • started (str)
  • is_open (bool)
  • fulfiller_github_username (str)
  • interested_github_username (str)

filter() returns the Endpoint object itself to enable a fluent interface.

bounties.order_by(sort)

Determine the order of the bounties returned by either get_page() or all(). The sort argument is a string containing a DB field name to sort by. It can also have an optional "-" prefix for reversing the direction. Choose from these field names:

  • accepted
  • balance
  • bounty_owner_address
  • bounty_owner_email
  • bounty_owner_github_username
  • bounty_owner_name
  • bounty_type
  • canceled_on
  • contract_address
  • current_bounty
  • experience_level
  • expires_date
  • fulfillment_accepted_on
  • fulfillment_started_on
  • fulfillment_submitted_on
  • github_comments
  • github_url
  • idx_experience_level
  • idx_project_length
  • idx_status
  • interested
  • interested_comment
  • is_open
  • issue_description
  • last_comment_date
  • metadata
  • network
  • num_fulfillments
  • override_status
  • privacy_preferences
  • project_length
  • raw_data
  • snooze_warnings_for_days
  • standard_bounties_id
  • submissions_comment
  • title
  • token_address
  • token_name
  • token_value_in_usdt
  • token_value_time_peg
  • _val_usd_db
  • value_in_eth
  • value_in_token
  • value_in_usdt
  • value_in_usdt_now
  • value_true
  • web3_created
  • web3_type

order_by() returns the Endpoint object itself to enable a fluent interface.

bounties.get_page(number=1, per_page=25)

Returns one page of the (potentially filter()ed) list of bounties with the given 1-based index number (int). The page size can be set with per_page (int). Each bounty is a dict, basically the direct output of requests' .json() call.

bounties.all()

Returns the complete (potentially filter()ed) list of bounties. Each bounty is a dict, basically the direct output of requests' .json() call.

bounties.get(primary_key)

Returns one (1) bounty as specified by primary_key (int). It is returned as a dict, basically the direct output of requests' .json() call.


Todo

  • Add base gitcoin.Gitcoin client
  • Add bounties api filter
    • Implement all filter fields present in gitcoinco/web/app/dashboard/router.py
  • Add universe api filter
    • Implement all filter fields present in gitcoinco/web/app/external_bounties/router.py
  • Add sorting/order_by
  • Add pagination (page/limit)
  • Add travis-ci.com project and twine/pypi credentials.
  • Add codecov.io project.
  • Cut first release (Tag github release, push changes, and let CI deploy to pypi)
  • Maintain +90% coverage