feat: add fathomnet-rest-api 2.3.0 endpoints

Author: kevinsbarnard

src/fathomnet/api/boundingboxes.py

@@ -36,6 +36,18 @@ def count_total_by_concept() -> List[dto.ByConceptCount]:
     return list(map(dto.ByConceptCount.from_dict, res_json))
 
 
+def count_total_by_observer() -> List[dto.ByObserverCount]:
+    """Get a count of bounding boxes for each observer."""
+    res_json = BoundingBoxes.get("list/counts/observer")
+    return list(map(dto.ByObserverCount.from_dict, res_json))
+
+
+def count_total_by_reviewer() -> List[dto.ByReviewerCount]:
+    """Get a count of bounding boxes for each reviewer."""
+    res_json = BoundingBoxes.get("list/counts/reviewer")
+    return list(map(dto.ByReviewerCount.from_dict, res_json))
+
+
 def find_observers() -> List[str]:
     """Get a list of all observers."""
     res_json = BoundingBoxes.get("list/observers")
@@ -194,3 +206,45 @@ def audit_by_observer(
         "audit/observer/{}".format(quote(observer)), params=params
     )
     return list(map(dto.BoundingBoxDTO.from_dict, res_json))
+
+
+def bulk_rename(
+    boxes: List[dto.BoundingBoxDTO],
+    auth_header: Optional[dto.AuthHeader] = None,
+) -> List[dto.BoundingBoxDTO]:
+    """Bulk rename bounding boxes."""
+    res_json = BoundingBoxes.put(
+        "bulk/rename",
+        json=[box.to_dict() for box in boxes],
+        auth=auth_header,
+    )
+    return list(map(dto.BoundingBoxDTO.from_dict, res_json))
+
+
+def bulk_review(
+    boxes: List[dto.BoundingBoxDTO],
+    auth_header: Optional[dto.AuthHeader] = None,
+) -> List[dto.BoundingBoxDTO]:
+    """Bulk review bounding boxes."""
+    res_json = BoundingBoxes.put(
+        "bulk/review",
+        json=[box_review.to_dict() for box_review in boxes],
+        auth=auth_header,
+    )
+    return list(map(dto.BoundingBoxDTO.from_dict, res_json))
+
+
+def find(
+    constraints: dto.BoundingBoxConstraintsDTO,
+) -> List[dto.BoundingBoxDTO]:
+    """Query bounding boxes by constraints."""
+    res_json = BoundingBoxes.post("query", json=constraints.to_dict())
+    return list(map(dto.BoundingBoxDTO.from_dict, res_json.get("content", [])))
+
+
+def count(
+    constraints: dto.BoundingBoxConstraintsDTO,
+) -> dto.Count:
+    """Count bounding boxes by constraints."""
+    res_json = BoundingBoxes.post("query/count", json=constraints.to_dict())
+    return dto.Count.from_dict(res_json)

src/fathomnet/api/stats.py

@@ -1,6 +1,7 @@
 # stats.py (fathomnet-py)
 from typing import List
 
+from fathomnet import dto
 from fathomnet.api import EndpointManager
 
 
@@ -12,3 +13,15 @@ def most_popular_searches() -> List[str]:
     """Get a list of the most popular searches."""
     res_json = Stats.get("list/popular/searches")
     return res_json
+
+
+def image_set_upload_positions() -> List[dto.ImageSetUploadPosition]:
+    """Get a list of image set upload positions."""
+    res_json = Stats.get("list/upload/positions")
+    return [dto.ImageSetUploadPosition.from_dict(item) for item in res_json]
+
+
+def contribution_stats() -> List[dto.ContributionStats]:
+    """Get contribution stats by contributing institution."""
+    res_json = Stats.get("list/contributions")
+    return [dto.ContributionStats.from_dict(item) for item in res_json]

src/fathomnet/dto.py

@@ -204,11 +204,62 @@ class BoundingBox(DTO):
     lastReviewedTimestamp: Optional[str] = None
 
 
+class BoundingBoxSort(DTO):
+    class Field(str, Enum):
+        UUID = "UUID"
+        CONCEPT = "CONCEPT"
+        CREATED_AT = "CREATED_AT"
+        UPDATED = "UPDATED"
+        REVIEWED = "REVIEWED"
+        IMAGE_URL = "IMAGE_URL"
+        ROI_SIZE = "ROI_SIZE"
+
+    class Direction(str, Enum):
+        ASC = "ASC"
+        DESC = "DESC"
+
+    field: Optional[Field] = None
+    direction: Optional[Direction] = None
+
+
+class BoundingBoxConstraintsDTO(DTO):
+    concept: Optional[str] = None
+    taxaProviderName: Optional[str] = None
+    contributorsEmails: Optional[List[str]] = None
+    startTimestamp: Optional[str] = None
+    endTimestamp: Optional[str] = None
+    includeUnverified: Optional[bool] = None
+    includeVerified: Optional[bool] = None
+    includeRejected: Optional[bool] = None
+    includeUnknown: Optional[bool] = None
+    minLongitude: Optional[float] = None
+    maxLongitude: Optional[float] = None
+    minLatitude: Optional[float] = None
+    maxLatitude: Optional[float] = None
+    minDepth: Optional[float] = None
+    maxDepth: Optional[float] = None
+    ownerInstitutionCodes: Optional[List[str]] = None
+    tagKeys: Optional[List[str]] = None
+    limit: Optional[int] = None
+    offset: Optional[int] = None
+    sort: Optional[BoundingBoxSort] = None
+
+
 class ByConceptCount(DTO):
     concept: Optional[str] = None
     count: Optional[int] = None
 
 
+class ByObserverCount(DTO):
+    observer: Optional[str] = None
+    count: Optional[int] = None
+
+
+class ByReviewerCount(DTO):
+    reviewer: Optional[str] = None
+    count: Optional[int] = None
+
+
 class ByContributorCount(DTO):
     contributorsEmail: Optional[str] = None
     count: Optional[int] = None
@@ -570,3 +621,15 @@ class WormsNames(DTO):
     name: Optional[str] = None
     acceptedName: Optional[str] = None
     alternateNames: Optional[List[str]] = None
+
+
+class ImageSetUploadPosition(DTO):
+    latitude: Optional[float] = None
+    longitude: Optional[float] = None
+    imageSetUploadUuid: Optional[str] = None
+
+
+class ContributionStats(DTO):
+    ownerInstitutionCode: Optional[str] = None
+    totalUploads: Optional[int] = None
+    totalImages: Optional[int] = None

test/test_boundingboxes.py

@@ -1,5 +1,6 @@
 from unittest import SkipTest, TestCase
 
+from fathomnet import dto
 from fathomnet.api import boundingboxes
 
 from . import skipIfNoAuth
@@ -31,6 +32,26 @@ def test_count_total_by_concept(self):
         else:
             self.fail()
 
+    def test_count_total_by_observer(self):
+        observer_counts = boundingboxes.count_total_by_observer()
+        self.assertIsNotNone(observer_counts)
+        self.assertGreater(len(observer_counts), 0)
+        # Verify the structure of the returned data
+        for observer_count in observer_counts:
+            self.assertIsNotNone(observer_count.observer)
+            self.assertIsNotNone(observer_count.count)
+            self.assertGreater(observer_count.count, 0)
+
+    def test_count_total_by_reviewer(self):
+        reviewer_counts = boundingboxes.count_total_by_reviewer()
+        self.assertIsNotNone(reviewer_counts)
+        self.assertGreater(len(reviewer_counts), 0)
+        # Verify the structure of the returned data
+        for reviewer_count in reviewer_counts:
+            self.assertIsNotNone(reviewer_count.reviewer)
+            self.assertIsNotNone(reviewer_count.count)
+            self.assertGreater(reviewer_count.count, 0)
+
     def test_find_observers(self):
         observers = boundingboxes.find_observers()
         self.assertIsNotNone(observers)
@@ -111,3 +132,35 @@ def test_audit_by_observer(self):
         observer = "brian@mbari.org"
         boxes = boundingboxes.audit_by_observer(observer)
         self.assertIsNotNone(boxes)
+
+    @skipIfNoAuth
+    def test_bulk_rename(self):
+        raise SkipTest("Write tests not yet implemented")  # TODO bulk_rename test
+
+    @skipIfNoAuth
+    def test_bulk_review(self):
+        raise SkipTest("Write tests not yet implemented")  # TODO bulk_review test
+
+    def test_find(self):
+        # Test with a simple concept constraint
+        constraints = dto.BoundingBoxConstraintsDTO(
+            concept="Bathochordaeus",
+            limit=10,
+        )
+        boxes = boundingboxes.find(constraints)
+        self.assertIsNotNone(boxes)
+        # Should return a list (might be empty if no results)
+        self.assertIsInstance(boxes, list)
+        # If there are results, verify the concept matches
+        for box in boxes:
+            self.assertEqual(box.concept, "Bathochordaeus")
+
+    def test_count(self):
+        # Test with a simple concept constraint
+        constraints = dto.BoundingBoxConstraintsDTO(
+            concept="Bathochordaeus",
+            limit=10,
+        )
+        count = boundingboxes.count(constraints)
+        self.assertIsNotNone(count)
+        self.assertGreater(count.count, 0)

test/test_stats.py

@@ -8,3 +8,27 @@ def test_most_popular_searches(self):
         results = stats.most_popular_searches()
         self.assertIsNotNone(results)
         self.assertGreater(len(results), 0)
+
+    def test_image_set_upload_positions(self):
+        positions = stats.image_set_upload_positions()
+        self.assertIsNotNone(positions)
+        # Should return a list
+        self.assertIsInstance(positions, list)
+        # If there are results, verify the structure
+        if len(positions) > 0:
+            position = positions[0]
+            self.assertIsNotNone(position.latitude)
+            self.assertIsNotNone(position.longitude)
+            self.assertIsNotNone(position.imageSetUploadUuid)
+
+    def test_contribution_stats(self):
+        stats_list = stats.contribution_stats()
+        self.assertIsNotNone(stats_list)
+        # Should return a list
+        self.assertIsInstance(stats_list, list)
+        # If there are results, verify the structure
+        if len(stats_list) > 0:
+            contribution_stat = stats_list[0]
+            self.assertIsNotNone(contribution_stat.ownerInstitutionCode)
+            self.assertIsNotNone(contribution_stat.totalUploads)
+            self.assertIsNotNone(contribution_stat.totalImages)