GitLocker: The Coding Marketplace

Description:

gitcoin 0.1.0

Gitcoin Python API Client

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

Create a Gitcoin() API root object:

from gitcoin import Gitcoin
api = Gitcoin()

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