Merge pull request #37 from mattmanley/add_client_certs

Add functionality for client-side certs

Author: mattmanley

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/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