Merge pull request #3 from raphaelhuefner/release_candidate

Release candidate

Author: Mark Beacom

.gitignore

@@ -9,6 +9,7 @@ __pycache__/
 
 # Distribution / packaging
 .Python
+bin/
 build/
 develop-eggs/
 dist/
@@ -25,6 +26,8 @@ wheels/
 .installed.cfg
 *.egg
 MANIFEST
+pip-selfcheck.json
+pyvenv.cfg
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

.travis.yml

@@ -18,6 +18,7 @@ matrix:
     - python: 3.4
     - python: 3.5
     - python: 3.6
+    # - python: 3.7 # As of 2018-07-18T13-10-00Z, Python 3.7 is not available on Travis just yet.
 
 install: pip install .
 

Makefile

@@ -19,10 +19,10 @@ test: ## Run pytest.
 	@python setup.py test
 
 fix-isort: ## Run isort against python files in the project directory.
-	@isort -rc --atomic .
+	@isort -rc --atomic ./gitcoin ./tests
 
 fix-yapf: ## Run yapf against any included or newly introduced Python code.
-	@yapf -i -r -p .
+	@yapf -i -r -p ./gitcoin ./tests
 
 fix: fix-isort fix-yapf ## Attempt to run all fixes against the project directory.
 

README.md

@@ -1,39 +1,220 @@
-# python-api-client
-Python API Client
+# 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
 
 ```bash
 pip install gitcoin
 ```
 
-## Usage
+## Usage Examples
+
+### List all bounties
+
+```python
+from gitcoin import Gitcoin
+api = Gitcoin()
+all_bounties = api.bounties.all()
+```
+
+### List all open bounties
+
+```python
+from gitcoin import Gitcoin
+api = Gitcoin()
+open_bounties = api.bounties.filter(is_open=True).all()
+```
+
+### List all open "Beginner" bounties
+
+```python
+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](https://en.wikipedia.org/wiki/Fluent_interface#Python) is also available. Please scroll the following code block all the way to the end to see the whole line:
+
+```python
+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:
 
 ```python
 from gitcoin import Gitcoin
 api = Gitcoin()
-api.bounties.all()
-api.bounties.filter(pk__gt=100).all()
+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](https://en.wikipedia.org/wiki/Fluent_interface#Python) is also available. Please scroll the following code block all the way to the end to see the whole line:
+
+```python
+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
 
-### public (unrestricted)
+### Instantiation
+
+1. Create a `Gitcoin()` API root object:
+```python
+from gitcoin import Gitcoin
+api = Gitcoin()
+```
+2. The `bounties` API endpoint is accessible as a property of the API root object:
+```python
+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:
+
+```python
+open_bounties = api.bounties.filter(is_open=True).all()
+```
+
+Conditions with different names can be given in one `filter()` call:
+
+```python
+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:
+
+```python
+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()`:
+
+```python
+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](https://en.wikipedia.org/wiki/Fluent_interface#Python).
+
+### `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](https://en.wikipedia.org/wiki/Fluent_interface#Python).
+
+### `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()`](http://docs.python-requests.org/en/master/user/quickstart/#json-response-content) call.
+
+### `bounties.all()`
+
+Returns the complete (potentially `filter()`ed) `list` of bounties. Each bounty is a `dict`, basically the direct output of [`requests`' `.json()`](http://docs.python-requests.org/en/master/user/quickstart/#json-response-content) call.
 
-`GET /api/v2/bounties`
+### `bounties.get(primary_key)`
 
-### private (restricted)
+Returns one (1) bounty as specified by `primary_key (int)`. It is returned as a `dict`, basically the direct output of [`requests`' `.json()`](http://docs.python-requests.org/en/master/user/quickstart/#json-response-content) call.
 
+-------------------------
 
 ## Todo
 
-- [ ] Add base gitcoin.Gitcoin client
-- [ ] Add `bounties` api filter
-  - [ ] Implement all filter fields present in `gitcoinco/web/app/dashboard/router.py`
+- [x] Add base gitcoin.Gitcoin client
+- [x] Add `bounties` api filter
+  - [x] 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)
+- [x] Add sorting/order_by
+- [x] 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)

conftest.py

@@ -0,0 +1,7 @@
+import pytest
+
+
+# see https://docs.pytest.org/en/latest/example/simple.html#control-skipping-of-tests-according-to-command-line-option
+def pytest_addoption(parser):
+    parser.addoption('--liveapi', action='store_true',
+                     default=False, help='run some tests againts live API')

gitcoin/__init__.py

@@ -0,0 +1,10 @@
+"""Define the Gitcoin API client."""
+
+from gitcoin.client import Config
+from gitcoin.client import BountyConfig
+from gitcoin.client import Endpoint
+from gitcoin.client import Gitcoin
+
+__all__ = [
+    'Config', 'BountyConfig', 'Endpoint', 'Gitcoin',
+]