Merge pull request #44 from osmlab/dev

mattmanley · web-flow · commit 21e2d1d46460 · 2020-06-12T11:32:08.000-07:00
Merging dev &gt; master
diff --git a/README.md b/README.md
@@ -1,6 +1,10 @@
 # MapRoulette - A Python Client for the MapRoulette API
 
-https://maproulette-python-client.readthedocs.io/
+
+https://maproulette-python-client.readthedocs.io
+
+[![PyPI version](https://badge.fury.io/py/maproulette.svg)](https://badge.fury.io/py/maproulette)
+[![Build Status](https://travis-ci.com/osmlab/maproulette-python-client.svg?branch=master)](https://travis-ci.com/osmlab/maproulette-python-client)
 
 This client makes it easy for users to communicate with the MapRoulette API from within
 their Python environment. In the example below, we are able to access a MapRoulette project in just four lines of code:
diff --git a/docs/index.rst b/docs/index.rst
@@ -17,6 +17,7 @@ Welcome to MapRoulette's documentation!
    usage/models/project
    usage/models/challenge
    usage/models/task
+   usage/models/priority_rule
    usage/exceptions
 
 ---------------
diff --git a/docs/usage/functionality.rst b/docs/usage/functionality.rst
@@ -22,6 +22,13 @@ Module: task
     :members:
     :show-inheritance:
 
+Module: user
+-----------------------------------------------------
+
+.. automodule:: maproulette.api.user
+    :members:
+    :show-inheritance:
+
 Module: configuration
 -----------------------------------------------------
 
diff --git a/docs/usage/models/priority_rule.rst b/docs/usage/models/priority_rule.rst
@@ -0,0 +1,27 @@
+Priority Rule Model
+=====================================================
+
+.. autoclass:: maproulette.models.priority_rule.PriorityRule
+    :members:
+
+.. autoclass:: maproulette.models.priority_rule.PriorityRuleModel
+    :members:
+
+.. autoclass:: maproulette.models.priority_rule.Conditions
+    :members:
+
+.. autoclass:: maproulette.models.priority_rule.Types
+    :members:
+    :undoc-members:
+
+.. autoclass:: maproulette.models.priority_rule.Conditions
+    :members:
+    :undoc-members:
+
+.. autoclass:: maproulette.models.priority_rule.StringOperators
+    :members:
+    :undoc-members:
+
+.. autoclass:: maproulette.models.priority_rule.NumericOperators
+    :members:
+    :undoc-members:
diff --git a/examples/add_user_list_to_project.py b/examples/add_user_list_to_project.py
@@ -0,0 +1,22 @@
+import maproulette
+import json
+
+# Create a configuration object using a url and API key
+config = maproulette.Configuration(api_key='{YOUR_API_KEY}')
+
+# Create an API object using your config object
+api = maproulette.User(config)
+
+# Specify the user IDs to grant privileges to
+user_ids = [123, 456, 789]
+
+# Specify the project ID to update the privileges for
+project_id = '147'
+
+# Specify what level of access you want to grant this user (1 - Admin, 2 - Write, 3 - Read)
+group = '2'
+
+# Print the API response
+print(json.dumps(api.add_user_list_to_project(user_ids=user_ids,
+                                              project_id=project_id,
+                                              group_type=group), indent=4, sort_keys=True))
diff --git a/examples/add_user_to_project.py b/examples/add_user_to_project.py
@@ -0,0 +1,22 @@
+import maproulette
+import json
+
+# Create a configuration object using a url and API key
+config = maproulette.Configuration(api_key='{YOUR_API_KEY}')
+
+# Create an API object using your config object
+api = maproulette.User(config)
+
+# Specify the user ID to grant privileges to
+user_id = '{SOME_USER_ID}'
+
+# Specify the project ID to update the privileges for
+project_id = '{YOUR_PROJECT_ID}'
+
+# Specify what level of access you want to grant this user (1 - Admin, 2 - Write, 3 - Read)
+group = '2'
+
+# Print the API response
+print(json.dumps(api.add_user_to_project(user_id=user_id,
+                                         project_id=project_id,
+                                         group_type=group), indent=4, sort_keys=True))
diff --git a/examples/create_challenge_from_model.py b/examples/create_challenge_from_model.py
@@ -16,6 +16,16 @@
 # Adding required instruction
 challenge_data.instruction = "Do something"
 
+# Let's create a basic rule to classify features with tags 'highway' = 'footway' to be high priority
+rule_1 = maproulette.PriorityRule(priority_value='highway.footway',
+                                  priority_type=maproulette.priority_rule.Types.STRING,
+                                  priority_operator=maproulette.priority_rule.StringOperators.EQUAL)
+
+# Create a formal priority rule for the challenge
+challenge_data.high_priority_rule = maproulette.PriorityRuleModel(condition=maproulette.priority_rule.Conditions.OR,
+                                                                  rules=rule_1
+                                                                  ).to_json()
+
 # Adding example overpass QL input for challenge
 challenge_data.overpassQL = open('data/Example_OverpassQL_Query', 'r').read()
 
diff --git a/examples/find_user_by_username.py b/examples/find_user_by_username.py
@@ -0,0 +1,14 @@
+import maproulette
+import json
+
+# Create a configuration object using a url and API key
+config = maproulette.Configuration(api_key='{YOUR_API_KEY}')
+
+# Create an API object using your config object
+api = maproulette.User(config)
+
+# We want to fetch a user with a particular name
+username = '{YOUR_USERNAME}'
+
+# Print the API response
+print(json.dumps(api.find_user_by_username(username), indent=4, sort_keys=True))
diff --git a/maproulette/__init__.py b/maproulette/__init__.py
@@ -7,9 +7,11 @@
 from .models.project import ProjectModel
 from .models.challenge import ChallengeModel
 from .models.task import TaskModel
+from .models.priority_rule import PriorityRule, PriorityRuleModel
+from .models import priority_rule
 from .api.project import Project
 from .api.challenge import Challenge
 from .api.task import Task
 from .api.user import User
 
-__version__ = '1.0.0'
+__version__ = '1.1.0'
diff --git a/maproulette/api/maproulette_server.py b/maproulette/api/maproulette_server.py
@@ -57,7 +57,8 @@ def get(self, endpoint, params=None):
         """
         response = self.session.get(
             self.url + endpoint,
-            params=params)
+            params=params
+        )
         try:
             response.raise_for_status()
         except requests.exceptions.HTTPError as e:
@@ -89,16 +90,19 @@ def get(self, endpoint, params=None):
                 "status": response.status_code
             }
 
-    def post(self, endpoint, body=None):
+    def post(self, endpoint, body=None, params=None):
         """Method that completes a POST request to the MapRoulette API
 
         :param endpoint: the server endpoint to use for the POST request
         :param body: the body of the request (optional)
+        :param params: the parameters that pertain to the request (optional)
         :returns: a JSON object containing the API response
         """
         response = self.session.post(
             self.url + endpoint,
-            json=body)
+            params=params,
+            json=body
+        )
         try:
             response.raise_for_status()
         except requests.exceptions.HTTPError as e:
@@ -132,16 +136,19 @@ def post(self, endpoint, body=None):
                 "status": response.status_code
             }
 
-    def put(self, endpoint, body=None):
+    def put(self, endpoint, body=None, params=None):
         """Method that completes a PUT request to the MapRoulette API
 
         :param endpoint: the server endpoint to use for the PUT request
         :param body: the body of the request (optional)
+        :param params: the parameters that pertain to the request (optional)
         :returns: a JSON object containing the response code and the API response if
         """
         response = self.session.put(
             self.url + endpoint,
-            json=body)
+            params=params,
+            json=body
+        )
         try:
             response.raise_for_status()
         except requests.exceptions.HTTPError as e:
diff --git a/maproulette/api/user.py b/maproulette/api/user.py
@@ -1,6 +1,5 @@
 """This module contains the methods that the user will use directly to interact with MapRoulette users"""
 
-import json
 from maproulette.api.maproulette_server import MapRouletteServer
 
 
@@ -9,3 +8,58 @@ class User(MapRouletteServer):
 
     def __init__(self, config):
         super().__init__(configuration=config)
+
+    def find_user_by_username(self, username, limit=10, page=0):
+        """Method to search for a user based on a specific username
+
+        :param username: the username to search for.
+        :param limit: the limit to the number of results returned in the response. Default is 10
+        :param page: used in conjunction with the limit parameter to page through X number of responses. Default is 0.
+        :returns: the API response from the GET request
+        """
+        query_params = {
+            "limit": str(limit),
+            "page": str(page)
+        }
+        response = self.get(
+            endpoint=f"/users/find/{username}",
+            params=query_params
+        )
+        return response
+
+    def add_user_to_project(self, user_id, project_id, group_type, is_osm_user_id='true'):
+        """Method to add a user to a project group
+
+        :param user_id: the user ID to add to the specified project group
+        :param project_id: the ID of the project
+        :param group_type: the group type to add the user to (1 - Admin, 2 - Write, 3 - Read)
+        :param is_osm_user_id: whether or not the specified user ID is an OSM user ID. Default is 'false'.
+        :returns: the API response from the POST request
+        """
+        query_params = {
+            "isOSMUserId": str(is_osm_user_id)
+        }
+        response = self.post(
+            endpoint=f"/user/{user_id}/project/{project_id}/{group_type}",
+            params=query_params
+        )
+        return response
+
+    def add_user_list_to_project(self, user_ids, project_id, group_type, is_osm_user_id='true'):
+        """Method to add a user to a project group
+
+        :param user_ids: a list of user IDs to add to the specified project group. IDs should be integers.
+        :param project_id: the ID of the project
+        :param group_type: the group type to add the user to (1 - Admin, 2 - Write, 3 - Read)
+        :param is_osm_user_id: whether or not the specified user ID is an OSM user ID. Default is 'false'.
+        :returns: the API response from the PUT request
+        """
+        query_params = {
+            "isOSMUserId": str(is_osm_user_id)
+        }
+        response = self.put(
+            endpoint=f"/user/project/{project_id}/{group_type}",
+            params=query_params,
+            body=user_ids
+        )
+        return response
diff --git a/maproulette/models/__init__.py b/maproulette/models/__init__.py
@@ -1,3 +1,4 @@
 from .project import ProjectModel
 from .challenge import ChallengeModel
 from .task import TaskModel
+from .priority_rule import PriorityRule, PriorityRuleModel
diff --git a/maproulette/models/challenge.py b/maproulette/models/challenge.py
diff --git a/maproulette/models/priority_rule.py b/maproulette/models/priority_rule.py
diff --git a/maproulette/models/project.py b/maproulette/models/project.py
diff --git a/maproulette/models/task.py b/maproulette/models/task.py
diff --git a/tests/test_project_api.py b/tests/test_project_api.py
diff --git a/tests/test_user_api.py b/tests/test_user_api.py
