Merge pull request #39 from osmlab/dev

Merging dev -> master

Author: Daniel B

docs/usage/functionality.rst

@@ -27,4 +27,4 @@ Module: configuration
 
 .. automodule:: maproulette.api.configuration
     :members:
-    :show-inheritance:
+    :special-members:

docs/usage/getting_started.rst

@@ -14,8 +14,9 @@ Import the package:
     import maproulette
 
 
-From there, create a configuration object. Depending on your use case, you may need to pass your API key. Specify
-that when you create your configuration. For example:
+From there, create a configuration object. When creating the configuration you can specify a number of of parameters
+depending on your needs including the hostname, protocol, and client-side certificates. Depending on your use case, you
+may need to obtain and pass your API key as well. For example:
 
 .. code-block:: python
 

maproulette/__init__.py

@@ -12,4 +12,4 @@
 from .api.task import Task
 from .api.user import User
 
-__version__ = '0.1.0rc3'
+__version__ = '1.0.0'

maproulette/api/configuration.py

@@ -1,15 +1,41 @@
 """This module contains the basic configuration object that is used to communicate with the MapRoulette API."""
 
-DEFAULT_URL = 'maproulette.org'
+from typing import Union
+
+DEFAULT_HOSTNAME = 'maproulette.org'
 DEFAULT_PROTOCOL = 'https'
 DEFAULT_API_VERSION = '/api/v2'
 
 
 class Configuration:
     """Class for storing the configuration of the MapRoulette server"""
-    def __init__(self, url=DEFAULT_URL, protocol=DEFAULT_PROTOCOL, api_version=DEFAULT_API_VERSION, api_key=None):
-        self.url = f"{protocol}://{url}{api_version}"
-        self.base_url = f"{protocol}://{url}"
+    def __init__(self, hostname=DEFAULT_HOSTNAME, protocol=DEFAULT_PROTOCOL, api_version=DEFAULT_API_VERSION,
+                 api_key=None, certs=None, verify=True):
+        """Create a new configuration object to connect to the MapRoulette server.
+
+        :param hostname: Optional parameter to specify the hostname of the MapRoulette instance being addressed. Do
+            not include the protocol (https, http). Default value is 'maproulette.org'.
+        :type hostname: str, optional
+        :param protocol: Optional parameter to specify the protocol to use for the connection to the MapRoulette
+            instance being addressed such as https or http. Default value is 'https'.
+        :type protocol: str, optional
+        :param api_version: Optional parameter to specify the API version to use. The default is '/api/v2'.
+        :type api_version: str, optional
+        :param api_key: Optional parameter to pass the user-specific API key. This key is necessary for some actions.
+        :type api_key: str, optional
+        :param certs: Optional parameter to pass the client-side certificate and key if necessary to make
+            connection with the MapRoulette instance being addressed. Can be either a tuple containing the cert and key
+            file paths (in that order) or a string representing the filepath to both the cert and key stored in a single
+            file.
+        :type certs: str or tuple, optional
+        :param verify: Optional parameter to specify whether to verify SSL certificates for HTTPS requests. Default
+            is True.
+        :type verify: bool, optional
+        """
+        self.api_url = f"{protocol}://{hostname}{api_version}"
+        self.base_url = f"{protocol}://{hostname}"
+        self.protocol = protocol
         self.headers = dict()
         self.headers['apikey'] = api_key
-        self.protocol = protocol
+        self.certs = certs
+        self.verify = verify

maproulette/api/maproulette_server.py

@@ -10,13 +10,16 @@
 class MapRouletteServer:
     """Class that holds the basic requests that can be made to the MapRoulette API."""
     def __init__(self, configuration):
-        self.url = configuration.url
+        self.url = configuration.api_url
         self.base_url = configuration.base_url
         self.headers = configuration.headers
+        self.certs = configuration.certs
+        self.verify = configuration.verify
         if self.__check_health():
             self.session = requests.Session()
             self.session.headers = self.headers
-            self.session.verify = False
+            self.session.verify = self.verify
+            self.session.cert = self.certs
 
     def __check_health(self, retries=3, delay=5):
         """Checks health of connection to host by pinging the URL set in the configuration
@@ -30,7 +33,8 @@ def __check_health(self, retries=3, delay=5):
                 response = requests.get(
                     self.base_url + '/ping',
                     headers=self.headers,
-                    verify=False
+                    verify=self.verify,
+                    cert=self.certs
                 )
                 if not response.ok:
                     print(f"Unsuccessful connection. Retrying in {str(delay)} seconds")

maproulette/api/project.py

@@ -1,6 +1,5 @@
 """This module contains the methods that the user will use directly to interact with MapRoulette projects"""
 
-import json
 from maproulette.api.maproulette_server import MapRouletteServer
 from maproulette.models.project import ProjectModel
 
@@ -85,6 +84,96 @@ def create_project(self, data):
             body=data)
         return response
 
+    def add_challenge_to_project(self, project_id, challenge_id):
+        """
+        Method to add a challenge to a virtual project.
+
+        :param project_id: the id of the virtual project
+        :param challenge_id: the id of the challenge being added
+        :return: the API response from the POST request
+        """
+        response = self.post(
+            endpoint=f"/project/{project_id}/challenge/{challenge_id}/add"
+        )
+        return response
+
+    def remove_challenge_from_project(self, project_id, challenge_id):
+        """
+        Method to remove a challenge from a virtual project.
+
+        :param project_id: the id of the virtual project
+        :param challenge_id: the id of the challenge being removed
+        :return: the API response from the POST request
+        """
+        response = self.post(
+            endpoint=f"/project/{project_id}/challenge/{challenge_id}/remove"
+        )
+        return response
+
+    def delete_project(self, project_id):
+        """
+        Method to delete a project.
+
+        :param project_id: the id of the project being deleted
+        :return: the API response form the DELETE request
+        """
+        response = self.delete(
+            endpoint=f"/project/{project_id}"
+        )
+        return response
+
+    def update_project(self, project_id, data):
+        """
+        Method to update an existing project
+
+        :param project_id: the id of the project being updated
+        :param data: the data to use to update the project
+        :return: the API response from the PUT request
+        """
+        if self.is_project_model(data):
+            data = ProjectModel.to_dict(data)
+        response = self.put(
+            endpoint=f"/project/{project_id}",
+            body=data)
+        return response
+
+    def get_projects_by_ids(self, project_ids):
+        """
+        Method to retrieve projects from comma separated list of ids
+
+        :param project_ids: comma separated list of project ids to be retrieved
+        :return: the API response from the GET request
+        """
+        query_params = {
+            "projectIds": project_ids
+        }
+        response = self.get(
+            endpoint=f"/projectsById",
+            params=query_params
+        )
+        return response
+
+    def get_random_tasks(self, project_id, limit=1, proximity=-1, search=''):
+        """
+        Method to retrieve random tasks from a project.
+
+        :param project_id: the id of the parent project of tasks
+        :param limit: limit amount of results returned
+        :param proximity: task to find based on proximity of that task
+        :param search: a search parameter object stored in a cookie
+        :return: the API response form the GET request
+        """
+        query_params = {
+            "limit": str(limit),
+            "proximity": str(proximity),
+            "search": str(search)
+        }
+        response = self.get(
+            endpoint=f"/project/{project_id}/tasks",
+            params=query_params
+        )
+        return response
+
     @staticmethod
     def is_project_model(input_object):
         """Method to determine whether user input is a valid project model

tests/test_project_api.py

@@ -44,3 +44,61 @@ def test_create_project(self, mock_request, api_instance=api):
         mock_request.return_value.status_code = '200'
         response = api_instance.create_project(test_project_model)
         self.assertEqual(response['status'], '200')
+
+    @patch('maproulette.api.maproulette_server.requests.Session.post')
+    def test_add_challenge_to_project(self, mock_request, api_instance=api):
+        test_virtual_project_model = maproulette.ProjectModel(name='Test Virtual Project Name',
+                                                              id=1234,
+                                                              is_virtual=True)
+        test_challenge_model = maproulette.ChallengeModel(name='Test Challenge Name',
+                                                          id=246)
+        test_virtual_project_id = test_virtual_project_model.id
+        test_challenge_id = test_challenge_model.id
+        mock_request.return_value.status_code = '200'
+        response = api_instance.add_challenge_to_project(test_virtual_project_id, test_challenge_id)
+        self.assertEqual(response['status'], '200')
+
+    @patch('maproulette.api.maproulette_server.requests.Session.post')
+    def test_remove_challenge_from_project(self, mock_request, api_instance=api):
+        test_virtual_project_model = maproulette.ProjectModel(name='Test Virtual Project Name',
+                                                              id=1234,
+                                                              is_virtual=True)
+        test_challenge_model = maproulette.ChallengeModel(name='Test Challenge Name', id=246)
+        test_virtual_project_id = test_virtual_project_model.id
+        test_challenge_id = test_challenge_model.id
+        mock_request.return_value.status_code = '200'
+        response = api_instance.remove_challenge_from_project(test_virtual_project_id, test_challenge_id)
+        self.assertEqual(response['status'], '200')
+
+    @patch('maproulette.api.maproulette_server.requests.Session.delete')
+    def test_delete_project(self, mock_request, api_instance=api):
+        test_project_model = maproulette.ProjectModel(name='Test Project Name', id=1234)
+        test_project_id = test_project_model.id
+        mock_request.return_value.status_code = '200'
+        response = api_instance.delete_project(test_project_id)
+        self.assertEqual(response['status'], '200')
+
+    @patch('maproulette.api.maproulette_server.requests.Session.put')
+    def test_update_project(self, mock_request, api_instance=api):
+        test_project_model = maproulette.ProjectModel(name='Test Project Name', id=1234)
+        test_updated_project_model = maproulette.ProjectModel(name='Test Updated Project Name')
+        test_project_model_id = test_project_model.id
+        mock_request.return_value.status_code = '200'
+        response = api_instance.update_project(test_project_model_id, test_updated_project_model)
+        self.assertEqual(response['status'], '200')
+
+    @patch('maproulette.api.maproulette_server.requests.Session.get')
+    def test_get_project_by_ids(self, mock_request, api_instance=api):
+        test_project_ids = '1234,2468,1356'
+        mock_request.return_value.status_code = '200'
+        response = api_instance.get_projects_by_ids(test_project_ids)
+        self.assertEqual(response['status'], '200')
+
+    @patch('maproulette.api.maproulette_server.requests.Session.get')
+    def test_get_random_tasks(self, mock_request, api_instance=api):
+        test_project_model = maproulette.ProjectModel(name='Test Project Name',
+                                                      id=1234)
+        test_project_id = test_project_model.id
+        mock_request.return_value.status_code = '200'
+        response = api_instance.get_random_tasks(test_project_id)
+        self.assertEqual(response['status'], '200')