Metadata-Version: 2.1
Name: gitcoin
Version: 0.1.0
Summary: The Gitcoin.co python API client
Home-page: https://github.com/gitcoinco/python-api-client
Author: Gitcoin
Author-email: team@gitcoin.co
License: UNKNOWN
Project-URL: Bug Reports, https://github.com/gitcoinco/python-api-client/issues
Project-URL: Homepage, https://gitcoin.co
Project-URL: Source, https://github.com/gitcoinco/python-api-client/
Project-URL: API Project, https://github.com/gitcoinco/web
Description: # Gitcoin Python API Client
        
        [![Build Status](https://travis-ci.com/gitcoinco/python-api-client.svg?branch=master)](https://travis-ci.com/gitcoinco/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 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()
        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
        
        ### 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.
        
        ### `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()`](http://docs.python-requests.org/en/master/user/quickstart/#json-response-content) call.
        
        -------------------------
        
        ## Todo
        
        - [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`
        - [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)
        - [ ] Maintain +90% coverage
        
Keywords: gitcoin api client bounties bounty rest
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Natural Language :: English
Requires-Python: ~=3.5
Description-Content-Type: text/markdown
Provides-Extra: deploy
