Merge pull request #46 from osmlab/dev

dev > master

docs/usage/functionality.rst

@@ -1,5 +1,6 @@
 Functionality
 =====================================================
+For usage examples check out `this link. <https://github.com/osmlab/maproulette-python-client/tree/dev/examples>`_
 
 Module: project
 -----------------------------------------------------

examples/create_challenge_from_model.py → examples/challenge_examples.py

@@ -7,7 +7,25 @@
 # Create an API objects with the above config object:
 api = maproulette.Challenge(config)
 
-# Creating a test challenge model with name and child task
+# Fetching a challenge based on challenge ID is easy. Specify the ID of the challenge you want:
+challenge_id = '12974'
+
+# Printing response
+print(json.dumps(api.get_challenge_by_id(challenge_id), indent=4, sort_keys=True))
+
+# We can also access a challenge by specifying the parent project ID and the challenge name:
+challenge_name = 'Test_Challenge'
+project_id = '2491'
+print(json.dumps(api.get_challenge_by_name(project_id=project_id,
+                                           challenge_name=challenge_name), indent=4, sort_keys=True))
+
+# We can access challenge statistics as well:
+print(json.dumps(api.get_challenge_statistics_by_id(challenge_id)))
+
+# Accessing a challenge's tasks is easy too. Specify the ID of the challenge you want:
+print(json.dumps(api.get_challenge_tasks(challenge_id), indent=4, sort_keys=True))
+
+# In order to create a new challenge, we can make our lives easier by using the Challenge Model
 challenge_data = maproulette.ChallengeModel(name='Test_Challenge_Name')
 
 # Adding example description
@@ -29,7 +47,15 @@
 # Adding example overpass QL input for challenge
 challenge_data.overpassQL = open('data/Example_OverpassQL_Query', 'r').read()
 
-print(challenge_data.overpassQL)
-
 # Create challenge
 print(json.dumps(api.create_challenge(challenge_data)))
+
+# If we want to add tasks to an existing challenge we can specify the challenge ID:
+challenge_id = 'TEST_ID'
+
+# Provide a GeoJSON of the task data:
+with open('data/Example_Geometry.geojson', 'r') as data_file:
+    data = json.loads(data_file.read())
+
+# Printing response:
+print(api.add_tasks_to_challenge(data, challenge_id))

examples/project_examples.py

@@ -0,0 +1,32 @@
+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.Project(config)
+
+# We can fetch a project using the name 'Health Facilities in India':
+my_project_name = 'Health Facilities in India'
+
+# Print the API response
+print(json.dumps(api.find_project(my_project_name), indent=4, sort_keys=True))
+
+# We can also fetch a project using the project ID:
+my_project_id = '4719'
+
+# Print the API response
+print(json.dumps(api.get_project_by_id(my_project_id), indent=4, sort_keys=True))
+
+# We can access the project's challenges as well:
+print(json.dumps(api.get_project_challenges(my_project_id), indent=4, sort_keys=True))
+
+# If we want to create a new project, we can use the Project Model:
+my_project = maproulette.ProjectModel(name='my_new_project_name_20200120_abc')
+
+# You can set other parameters like your project description like this:
+my_project.description = 'my project description'
+
+# Print the API response
+print(json.dumps(api.create_project(my_project), indent=4, sort_keys=True))

examples/task_examples.py

@@ -0,0 +1,24 @@
+import maproulette
+import json
+
+# Create a configuration object for MapRoulette using your API key:
+config = maproulette.Configuration(api_key="API_KEY")
+
+# Create an API object with the above config object:
+api = maproulette.Task(config)
+
+# To fetch a task, specify the task ID
+task_id = '42914448'
+
+# Printing response
+print(json.dumps(api.get_task_by_id(task_id), indent=4, sort_keys=True))
+
+# You can access a task's history:
+print(json.dumps(api.get_task_history(task_id), indent=4, sort_keys=True))
+
+# Or get a task's tags:
+print(json.dumps(api.get_task_tags(task_id), indent=4, sort_keys=True))
+
+# You can also fetch tasks by specifying a list of tags:
+tags = 'tag1,tag2'
+print(json.dumps(api.get_tasks_by_tags(tags), indent=4, sort_keys=True))

examples/user_examples.py

@@ -0,0 +1,42 @@
+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))
+
+# To add a user to a project, specify the user ID
+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))
+
+# We can also pass a list of user IDs to save time
+user_ids = [123, 456, 789]
+
+# 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_list_to_project(user_ids=user_ids,
+                                              project_id=project_id,
+                                              group_type=group), indent=4, sort_keys=True))

maproulette/__init__.py

@@ -14,4 +14,4 @@
 from .api.task import Task
 from .api.user import User
 
-__version__ = '1.1.0'
+__version__ = '1.2.0'