Merge pull request #289 from zooniverse/inaturalist

Add iNaturalist class & import method

docs/user_guide.rst

@@ -307,7 +307,30 @@ already known::
         settings=new_settings,
     )
 
-Other examples (Caesar features by Workflow)
+Importing iNaturalist observations to Panoptes as subjects is possible via an
+API endpoint. Project owners and collaborators can use this client to send
+a request to begin that import process::
+
+    # The ID of the iNat taxon to be imported
+    taxon_id = 1234
+
+    # The subject set to which new subjects will be added
+    subject_set_id = 5678
+
+    Inaturalist.inat_import(taxon_id, subject_set_id)
+
+As an optional parameter, the updated_since timestamp string can be included
+and will filter obeservations by that parameter::
+
+    Inaturalist.inat_import(taxon_id, subject_set_id, '2022-10-31')
+
+Be aware that this command only initiates a background job on the Zooniverse
+to import Observations. The request will return a 200 upon success, but there
+is no progress to observe. You can refresh the subject set in the project builder
+to see how far along it is, and the authenticated user will receive an email
+when this job is completed.
+
+Other examples Caesar features by Workflow
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Most Caesar use cases are usually through a workflow: the following are examples of Caesar functions that can be done via Workflow.
 

panoptes_client/__init__.py

@@ -12,3 +12,4 @@
 from panoptes_client.workflow import Workflow
 from panoptes_client.subject_workflow_status import SubjectWorkflowStatus
 from panoptes_client.caesar import Caesar
+from panoptes_client.inaturalist import Inaturalist

panoptes_client/inaturalist.py

@@ -0,0 +1,42 @@
+from panoptes_client.panoptes import Panoptes
+
+
+class Inaturalist(object):
+    """
+    The class that interacts with the Panoptes' iNaturalist functionality.
+    Currently, this includes a single route that allows the importing of
+    iNaturalist Observations as Zooniverse Subjects.
+    """
+
+    def inat_import(
+        taxon_id,
+        subject_set_id,
+        updated_since=None
+    ):
+        """
+        Begins an import of iNaturalist Observations as Zooniverse Subjects.
+        Response is a 200 if Panoptes begins the import successfully.
+        Requires owner or collaborator access to the subject set's linked project.
+        Takes three arguments:
+            taxon_id:       the iNat taxon ID of a particular species
+            subject_set_id: the Zoo subject set id subjects should be imported into.
+                            Updated observations will upsert their respective subjects.
+            updated_since:  a date range limiter on the iNat Observations query.
+                            Warning: defaults to None and will import ALL Observations
+                            by default. This will likely be a lot and take a while.
+        Examples::
+            # Import gray squirrel observations updated during or after Halloween 2022 to subject set id 3:
+            Inaturalist.inat_import(46017, 3, '2022-10-31')
+
+            # Import all royal flycatcher observations to subject set id 4:
+            Inaturalist.inat_import(16462, 4)
+        """
+
+        return Panoptes.client().post(
+            f'/inaturalist/import',
+            json={
+                'taxon_id': taxon_id,
+                'subject_set_id': subject_set_id,
+                'updated_since': updated_since
+            }
+        )

panoptes_client/tests/test_inaturalist.py

@@ -0,0 +1,42 @@
+from __future__ import absolute_import, division, print_function
+
+import unittest
+import sys
+
+if sys.version_info <= (3, 0):
+    from mock import patch, Mock
+else:
+    from unittest.mock import patch, Mock
+
+from panoptes_client.inaturalist import Inaturalist
+
+
+class TestInaturalist(unittest.TestCase):
+
+    def test_inat_import(self):
+        with patch('panoptes_client.panoptes.Panoptes.client') as pc:
+            pc().post = Mock(return_value=200)
+            Inaturalist.inat_import(16462, 4)
+
+            pc().post.assert_called_with(
+                '/inaturalist/import',
+                json={
+                    'taxon_id': 16462,
+                    'subject_set_id': 4,
+                    'updated_since': None
+                }
+            )
+
+    def test_inat_import_updated_since(self):
+        with patch('panoptes_client.panoptes.Panoptes.client') as pc:
+            pc().post = Mock(return_value=200)
+            Inaturalist.inat_import(16462, 4, '2022-10-31')
+
+            pc().post.assert_called_with(
+                '/inaturalist/import',
+                json={
+                    'taxon_id': 16462,
+                    'subject_set_id': 4,
+                    'updated_since': '2022-10-31'
+                }
+            )