Targets use ID not UUIDs

Signed-off-by: Cédric Foellmi <cedric@onekiloparsec.dev>

Author: onekiloparsec

arcsecond/api/resources.py

@@ -6,53 +6,76 @@
 class ArcsecondTargetListsResource(ArcsecondAPIEndpoint):
     """Target-list specific helpers built on top of the generic endpoint contract."""
 
-    target_relation_keys = ("targets", "target_uuids", "target_ids")
+    target_relation_key = "targets"
+    target_writable_fields = (
+        "id",
+        "pk",
+        "object",
+        "name",
+        "identifier",
+        "target_class",
+        "mode",
+        "color",
+        "notes",
+        "tags",
+        "profile",
+        "organisation",
+    )
 
     def _ensure_iterable(self, values):
         if values is None:
             return None
+        if isinstance(values, dict):
+            return [values]
         if isinstance(values, (str, int)):
             return [values]
         return list(values)
 
-    def _normalise_target_references(self, targets):
+    def _target_payload_identity(self, target):
+        if target.get("id") is not None:
+            return ("id", target["id"])
+        if target.get("pk") is not None:
+            return ("pk", target["pk"])
+        return (
+            "composite",
+            target.get("target_class"),
+            target.get("identifier"),
+            target.get("name"),
+            target.get("mode"),
+        )
+
+    def _normalise_target_payloads(self, targets):
         values = self._ensure_iterable(targets)
         if values is None:
             return None
 
-        refs = []
+        payloads = []
         for target in values:
-            if isinstance(target, dict):
-                ref = (
-                    target.get("uuid")
-                    or target.get("id")
-                    or target.get("pk")
-                    or target.get("name")
+            if not isinstance(target, dict):
+                raise ArcsecondError(
+                    "Target list helpers expect target payload dictionaries, not scalar IDs or UUIDs. "
+                    "Pass dictionaries such as `plan_target_payload(...).payload` or target objects returned "
+                    "by `api.targets.read()/list()/upsert()`."
                 )
-                if ref is None:
-                    raise ArcsecondError(
-                        "Target dictionaries must include one of: uuid, id, pk or name."
-                    )
-                refs.append(ref)
-            else:
-                refs.append(target)
-        return refs
-
-    def _target_key_from_payload(self, payload, target_key=None):
-        if target_key:
-            return target_key
-        for key in self.target_relation_keys:
-            if payload and key in payload:
-                return key
-        return self.target_relation_keys[0]
+
+            payload = {
+                key: value
+                for key, value in target.items()
+                if key in self.target_writable_fields and value is not None
+            }
+            if not payload:
+                raise ArcsecondError(
+                    "Target dictionaries must include at least one writable target field."
+                )
+
+            payloads.append(payload)
+        return payloads
 
     def _build_payload(self, json=None, targets=None, target_key=None, **fields):
         payload = super()._build_payload(json=json, **fields) or {}
-        normalised_targets = self._normalise_target_references(targets)
+        normalised_targets = self._normalise_target_payloads(targets)
         if normalised_targets is not None:
-            payload[self._target_key_from_payload(payload, target_key=target_key)] = (
-                normalised_targets
-            )
+            payload[target_key or self.target_relation_key] = normalised_targets
         return payload or None
 
     def create(self, json=None, targets=None, target_key=None, **fields):
@@ -74,14 +97,14 @@ def upsert(self, match_field="name", json=None, targets=None, target_key=None, *
         return super().upsert(match_field=match_field, json=payload)
 
     def _read_target_refs(self, target_list, target_key=None):
-        key = self._target_key_from_payload(target_list or {}, target_key=target_key)
+        key = target_key or self.target_relation_key
         raw_targets = (target_list or {}).get(key, [])
-        refs = self._normalise_target_references(raw_targets) or []
+        refs = self._normalise_target_payloads(raw_targets) or []
         return key, refs
 
     def set_targets(self, id_name_uuid, targets, target_key=None):
-        target_key = self._target_key_from_payload({}, target_key=target_key)
-        return self.update(id_name_uuid, **{target_key: self._normalise_target_references(targets)})
+        target_key = target_key or self.target_relation_key
+        return self.update(id_name_uuid, **{target_key: self._normalise_target_payloads(targets)})
 
     def clear_targets(self, id_name_uuid, target_key=None):
         return self.set_targets(id_name_uuid, [], target_key=target_key)
@@ -92,9 +115,14 @@ def add_targets(self, id_name_uuid, targets, target_key=None):
             return None, error
 
         key, current_refs = self._read_target_refs(target_list, target_key=target_key)
-        for ref in self._normalise_target_references(targets) or []:
-            if ref not in current_refs:
-                current_refs.append(ref)
+        current_identities = {
+            self._target_payload_identity(target): target for target in current_refs
+        }
+        for target in self._normalise_target_payloads(targets) or []:
+            identity = self._target_payload_identity(target)
+            if identity not in current_identities:
+                current_refs.append(target)
+                current_identities[identity] = target
         return self.update(id_name_uuid, **{key: current_refs})
 
     def remove_targets(self, id_name_uuid, targets, target_key=None):
@@ -103,8 +131,15 @@ def remove_targets(self, id_name_uuid, targets, target_key=None):
             return None, error
 
         key, current_refs = self._read_target_refs(target_list, target_key=target_key)
-        refs_to_remove = set(self._normalise_target_references(targets) or [])
-        remaining_refs = [ref for ref in current_refs if ref not in refs_to_remove]
+        refs_to_remove = {
+            self._target_payload_identity(target)
+            for target in (self._normalise_target_payloads(targets) or [])
+        }
+        remaining_refs = [
+            ref
+            for ref in current_refs
+            if self._target_payload_identity(ref) not in refs_to_remove
+        ]
         return self.update(id_name_uuid, **{key: remaining_refs})
 
     def add_target(self, id_name_uuid, target, target_key=None):

docs/resources.md

@@ -64,10 +64,9 @@ For many resources, `upsert()` is convenient when your script wants create-or-up
 semantics:
 
 ```python
-target, error = api.targets.upsert(
-    name="M 42",
-    ra_deg=83.82208,
-    dec_deg=-5.39111,
+dataset, error = api.datasets.upsert(
+    name="My dataset",
+    description="Synced from Python",
 )
 ```
 
@@ -170,27 +169,26 @@ JSON payloads yourself.
 
 ```python
 target, error = api.targets.create(
-    name="47 Tuc",
-    ra_deg=6.023625,
-    dec_deg=-72.08128,
+    name="51 Peg b",
+    target_class="Exoplanet",
 )
 ```
 
 ```python
 target, error = api.targets.update(
-    "6d7f9f0b-2d67-4d3d-9e74-2d6d0e749b91",
-    description="Globular cluster in Tucana",
+    42,
+    notes="Globular cluster in Tucana",
 )
 ```
 
 ```python
-target, error = api.targets.upsert(
+plan = plan_target_payload(
     name="M 42",
-    ra_deg=83.82208,
-    dec_deg=-5.39111,
-    source_name="Orion Nebula",
+    inferred_target_class="AstronomicalObject",
 )
 
+target, error = api.targets.upsert(json=plan.payload)
+
 if error:
     raise error
 ```
@@ -222,16 +220,34 @@ if error:
 `api.targetlists` supports the generic CRUD methods above, and also a few helpers for
 managing the list membership.
 
+Targets are managed through integer target IDs on `api.targets`, but target lists
+themselves are managed through UUIDs on `api.targetlists`.
+
+When you create or update a target list, the `targets` field must contain target
+payload dictionaries, not target IDs or UUIDs. The easiest inputs are:
+
+- payloads returned by `plan_target_payload(...).payload`
+- target objects returned by `api.targets.read()`, `api.targets.list()`, or `api.targets.upsert()`
+
 You can create a target list and attach targets in the same call:
 
 ```python
+from arcsecond import plan_target_payload
+
+m42 = plan_target_payload(
+    name="M 42",
+    inferred_target_class="AstronomicalObject",
+).payload
+
+pegb = plan_target_payload(
+    name="51 Peg b",
+    inferred_target_class="Exoplanet",
+).payload
+
 target_list, error = api.targetlists.create(
     name="Tonight candidates",
     description="Targets imported for Night Explorer",
-    targets=[
-        "6d7f9f0b-2d67-4d3d-9e74-2d6d0e749b91",
-        "c17cb272-5ed6-4a6f-a219-0ff4727863c2",
-    ],
+    targets=[m42, pegb],
 )
 
 if error:
@@ -241,12 +257,12 @@ if error:
 To replace the full content of a list:
 
 ```python
+target_a, error = api.targets.read(42)
+target_b, error = api.targets.read(314)
+
 target_list, error = api.targetlists.set_targets(
     "a0e974a6-6f2d-4b7a-b9d2-3a3f7d7ef61a",
-    [
-        "6d7f9f0b-2d67-4d3d-9e74-2d6d0e749b91",
-        "c17cb272-5ed6-4a6f-a219-0ff4727863c2",
-    ],
+    [target_a, target_b],
 )
 ```
 
@@ -255,24 +271,31 @@ To incrementally manage membership:
 ```python
 target_list, error = api.targetlists.add_targets(
     "a0e974a6-6f2d-4b7a-b9d2-3a3f7d7ef61a",
-    ["c17cb272-5ed6-4a6f-a219-0ff4727863c2"],
+    [
+        plan_target_payload(
+            name="M 31",
+            inferred_target_class="AstronomicalObject",
+        ).payload
+    ],
 )
 ```
 
 ```python
 target_list, error = api.targetlists.remove_target(
     "a0e974a6-6f2d-4b7a-b9d2-3a3f7d7ef61a",
-    "c17cb272-5ed6-4a6f-a219-0ff4727863c2",
+    target_b,
 )
 ```
 
 If you want create-or-update semantics for a list name:
 
 ```python
+target_a, error = api.targets.read(42)
+
 target_list, error = api.targetlists.upsert(
     name="Tonight candidates",
     description="Synced from Python",
-    targets=["6d7f9f0b-2d67-4d3d-9e74-2d6d0e749b91"],
+    targets=[target_a],
 )
 ```
 
@@ -287,7 +310,7 @@ deleted, error = api.targetlists.delete("a0e974a6-6f2d-4b7a-b9d2-3a3f7d7ef61a")
 ## Target Lists With Planned Targets
 
 When you import a target list from an external source, apply the same planning rule to
-each individual target first, then create the list from the created target UUIDs.
+each individual target first, then create the list from the resulting target payloads.
 
 ```python
 from arcsecond import ArcsecondAPI, ArcsecondConfig, plan_target_payload
@@ -307,7 +330,7 @@ candidates = [
     },
 ]
 
-target_ids = []
+targets = []
 for candidate in candidates:
     plan = plan_target_payload(**candidate)
     if not plan.is_valid:
@@ -317,11 +340,11 @@ for candidate in candidates:
     if error:
         raise error
 
-    target_ids.append(target["uuid"])
+    targets.append(target)
 
 target_list, error = api.targetlists.create(
     name="Imported targets",
-    targets=target_ids,
+    targets=targets,
 )
 ```