first draft of Python Gitcoin API client

Author: raphaelhuefner

.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

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

@@ -27,13 +27,13 @@ api.bounties.filter(pk__gt=100).all()
 
 ## 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)

gitcoin/__init__.py

@@ -0,0 +1,8 @@
+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',
+]

gitcoin/client.py

@@ -0,0 +1,148 @@
+import requests
+
+class Config:
+    """Define Base Class for API Endpoint Config."""
+    params = {}
+
+    def has(self, name):
+        """Tell if a setting for 'name' was defined."""
+        return name in self.params
+
+    def get(self, name):
+        """Get the setting for 'name'."""
+        if self.has(name):
+            return self.params[name]
+        else:
+            msg = 'Unknown config "{name}"'
+            raise KeyError(msg.format(name=name))
+
+
+class BountyConfig(Config):
+    """Define 'bounties' API Endpoint Config."""
+    params = {
+        'raw_data': (True, str),
+        'experience_level': (True, str),
+        'project_length': (True, str),
+        'bounty_type': (True, str),
+        'bounty_owner_address': (True, str),
+        'idx_status': (True, str),
+        'network': (True, str),
+        'bounty_owner_github_username': (True, str),
+        'standard_bounties_id': (True, str),
+        'pk__gt': (False, int),
+        'started': (False, str),
+        'is_open': (False, bool),
+        'github_url': (True, str),
+        'fulfiller_github_username': (False, str),
+        'interested_github_username': (False, str),
+        'order_by': (False, str),
+        'limit': (False, int),
+        'offset': (False, int)
+    }
+
+
+class Endpoint:
+    """Wrap one Gitcoin API end point."""
+
+    def __init__(self, url, config):
+        """Inject URL and Config, default to no query parameters."""
+        self.url = url
+        self.config = config
+        self.params = {}
+
+    def add_param(self, name, value):
+        """Add query parameter with safeguards."""
+        if self.config.has(name):
+            is_multiple, normalize = self.config.get(name)
+            if not is_multiple:
+                self.del_param(name)  # Throw away all previous values, if any.
+            if callable(normalize):
+                value = normalize(value)
+            self.add_param_unchecked(name, value)
+            return self
+        else:
+            msg = 'Tried to filter by unknown param "{name}".'
+            raise KeyError(msg.format(name=name))
+
+    def del_param(self, name):
+        """Delete query parameter."""
+        if name in self.params:
+            del self.params[name]
+        return self
+
+    def add_param_unchecked(self, name, value):
+        """Add query parameter without safeguards.
+
+        This is available in case this API client is out-of-sync with the API.
+        """
+        if name not in self.params:
+            self.params[name] = []
+        self.params[name].append(str(value))
+        return self
+
+    def filter(self, **kwargs):
+        """Filter the result set."""
+        for name, value in kwargs.items():
+            self.add_param(name, value)
+        return self
+
+    def order_by(self, sort):
+        """Sort the result set."""
+        self.add_param('order_by', sort)
+        return self
+
+    def get_page(self, number=1, per_page=25):
+        """Get a page of the result set."""
+        self.add_param('limit', per_page)
+        self.add_param('offset', (number - 1) * per_page)
+        return self._request_get()
+
+    def all(self):
+        """Get the complete result set."""
+        self.del_param('limit')
+        self.del_param('offset')
+        return self._request_get()
+
+    def get(self, pk):
+        """Get 1 object by primary key."""
+        return self._request_get('/'.join((self.url, str(pk))))
+
+    def _request_get(self, url=None):
+        """Fire the actual HTTP GET request as configured."""
+        url = url if url else self.url
+        params = self._prep_get_params()
+        response = requests.get(url, params=params)
+        response.raise_for_status()  # Let API consumer know about HTTP errors.
+        return response.json()
+
+    def _prep_get_params(self):
+        """Send multi-value fields separated by comma."""
+        return {name: ','.join(value) for name, value in self.params.items()}
+
+
+class Gitcoin:
+    """Provide main API entry point."""
+
+    def __init__(self):
+        """Set defaults."""
+        self.classes = {}
+        self.set_class('endpoint', Endpoint)
+        self.set_class('bounties_list_config', BountyConfig)
+        self.urls = {}
+        self.set_url('bounties', 'https://gitcoin.co/api/v0.1/bounties')
+
+    def set_class(self, id, cls):
+        """Inject class dependency, overriding the default class."""
+        self.classes[id] = cls
+
+    def set_url(self, id, url):
+        """Configure API URL, overriding the default URL."""
+        self.urls[id] = url
+
+    @property
+    def bounties(self):
+        """Wrap the 'bounties' API endpoint."""
+        url = self.urls['bounties']
+        endpointClass = self.classes['endpoint']
+        configClass = self.classes['bounties_list_config']
+        return endpointClass(url, configClass())

requirements.txt

@@ -0,0 +1,24 @@
+apipkg==1.4
+attrs==18.1.0
+certifi==2018.4.16
+chardet==3.0.4
+coverage==4.5.1
+execnet==1.5.0
+flake8==3.5.0
+idna==2.6
+isort==4.3.4
+mccabe==0.6.1
+more-itertools==4.1.0
+pluggy==0.6.0
+py==1.5.3
+pycodestyle==2.3.1
+pyflakes==1.6.0
+pytest==3.5.1
+pytest-cache==1.0
+pytest-cov==2.5.1
+pytest-isort==0.2.0
+pytest-runner==4.2
+requests==2.18.4
+six==1.11.0
+urllib3==1.22
+yapf==0.22.0

tests/__init__.py

@@ -0,0 +1,19 @@
+
+
+class MockResponse:
+    def __init__(self, url, params, kwargs):
+        self.url = url
+        self.params = params
+        self.kwargs = kwargs
+
+    def json(self):
+        return {
+            'url': self.url,
+            'params': self.params,
+            'kwargs': self.kwargs,
+        }
+
+    def raise_for_status(self):
+        if 'raise_for_status' in self.params:
+            if self.params['raise_for_status']:
+                raise ValueError('Mock HTTP Error')

tests/mocks/__init__.py

@@ -0,0 +1,123 @@
+import pytest
+import requests
+from gitcoin import BountyConfig, Gitcoin
+from tests.mocks.requests import MockResponse
+
+
+def mock_requests_get(url, params=None, **kwargs):
+    return MockResponse(url, params, kwargs)
+
+
+class TestGitcoinDryRun():
+
+    @pytest.fixture(autouse=True)
+    def no_requests(self, monkeypatch):
+        monkeypatch.setattr(requests, 'get', mock_requests_get)
+
+    def test_cfg_raises_on_unknown_param(self):
+        cfg = BountyConfig()
+        with pytest.raises(KeyError):
+            cfg.get('does_not_exist')
+
+    def test_api_raises_on_unknown_param(self):
+        api = Gitcoin()
+        with pytest.raises(KeyError):
+            api.bounties.filter(does_not_exist=True)
+
+    def test_all(self):
+        api = Gitcoin()
+        expected = {
+            'url': 'https://gitcoin.co/api/v0.1/bounties',
+            'params': {},
+            'kwargs': {},
+        }
+        result = api.bounties.all()
+        assert expected == result
+
+    def test_filter_pk__gt(self):
+        api = Gitcoin()
+        expected = {
+            'url': 'https://gitcoin.co/api/v0.1/bounties',
+            'params': {
+                'pk__gt': '100'
+            },
+            'kwargs': {},
+        }
+        result = api.bounties.filter(pk__gt=100).all()
+        assert expected == result
+
+    def test_filter_2x_bounty_type_paged(self):
+        api = Gitcoin()
+        expected = {
+            'url': 'https://gitcoin.co/api/v0.1/bounties',
+            'params': {
+                'bounty_type': 'Feature,Bug',
+                'offset': '0',
+                'limit': '25',
+            },
+            'kwargs': {},
+        }
+        result = api.bounties.filter(bounty_type='Feature').filter(bounty_type='Bug').get_page()
+        assert expected == result
+
+    def test_del_param(self):
+        api = Gitcoin()
+        expected = {
+            'url': 'https://gitcoin.co/api/v0.1/bounties',
+            'params': {
+                'bounty_type': 'Bug',
+                'offset': '0',
+                'limit': '25',
+            },
+            'kwargs': {},
+        }
+        result = api.bounties.filter(bounty_type='Feature').del_param('bounty_type').filter(bounty_type='Bug').get_page()
+        assert expected == result
+
+    def test_order_by(self):
+        api = Gitcoin()
+        expected = {
+            'url': 'https://gitcoin.co/api/v0.1/bounties',
+            'params': {
+                'order_by': '-project_length',
+                'offset': '0',
+                'limit': '25',
+            },
+            'kwargs': {},
+        }
+        result = api.bounties.order_by('-project_length').get_page()
+        assert expected == result
+
+    def test_get(self):
+        api = Gitcoin()
+        expected = {
+            'url': 'https://gitcoin.co/api/v0.1/bounties/123',
+            'params': {},
+            'kwargs': {},
+        }
+        result = api.bounties.get(123)
+        assert expected == result
+
+    def test_no_normalize(self):
+        class ExtendedBountyConfig(BountyConfig):
+            def __init__(self):
+                self.params['no_normalize'] = (True, None)
+
+        api = Gitcoin()
+        api.set_class('bounties_list_config', ExtendedBountyConfig)
+        expected = {
+            'url': 'https://gitcoin.co/api/v0.1/bounties',
+            'params': {
+                'no_normalize': 'not_normal',
+                'offset': '0',
+                'limit': '25',
+            },
+            'kwargs': {},
+        }
+        result = api.bounties.filter(no_normalize='not_normal').get_page()
+        assert expected == result
+
+    def test_raise_for_status(self):
+        api = Gitcoin()
+        with pytest.raises(ValueError):  # ValueError only in mock setup
+            result = api.bounties.add_param_unchecked('raise_for_status', True).all()