Merge pull request #31 from pkgw/astropix

Track AstroPix API additions

docs/api/wwt_api_client.constellations.data.SceneAstroPix.rst

@@ -0,0 +1,35 @@
+SceneAstroPix
+=============
+
+.. currentmodule:: wwt_api_client.constellations.data
+
+.. autoclass:: SceneAstroPix
+   :show-inheritance:
+
+   .. rubric:: Attributes Summary
+
+   .. autosummary::
+
+      ~SceneAstroPix.dataclass_json_config
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+
+      ~SceneAstroPix.from_dict
+      ~SceneAstroPix.from_json
+      ~SceneAstroPix.schema
+      ~SceneAstroPix.to_dict
+      ~SceneAstroPix.to_json
+
+   .. rubric:: Attributes Documentation
+
+   .. autoattribute:: dataclass_json_config
+
+   .. rubric:: Methods Documentation
+
+   .. automethod:: from_dict
+   .. automethod:: from_json
+   .. automethod:: schema
+   .. automethod:: to_dict
+   .. automethod:: to_json

docs/api/wwt_api_client.constellations.data.SceneHydrated.rst

@@ -10,6 +10,7 @@ SceneHydrated
 
    .. autosummary::
 
+      ~SceneHydrated.astropix
       ~SceneHydrated.dataclass_json_config
 
    .. rubric:: Methods Summary
@@ -24,6 +25,7 @@ SceneHydrated
 
    .. rubric:: Attributes Documentation
 
+   .. autoattribute:: astropix
    .. autoattribute:: dataclass_json_config
 
    .. rubric:: Methods Documentation

docs/api/wwt_api_client.constellations.data.SceneUpdate.rst

@@ -10,6 +10,7 @@ SceneUpdate
 
    .. autosummary::
 
+      ~SceneUpdate.astropix
       ~SceneUpdate.content
       ~SceneUpdate.dataclass_json_config
       ~SceneUpdate.outgoing_url
@@ -29,6 +30,7 @@ SceneUpdate
 
    .. rubric:: Attributes Documentation
 
+   .. autoattribute:: astropix
    .. autoattribute:: content
    .. autoattribute:: dataclass_json_config
    .. autoattribute:: outgoing_url

docs/api/wwt_api_client.constellations.handles.AddSceneRequest.rst

@@ -10,6 +10,7 @@ AddSceneRequest
 
    .. autosummary::
 
+      ~AddSceneRequest.astropix
       ~AddSceneRequest.dataclass_json_config
       ~AddSceneRequest.outgoing_url
 
@@ -25,6 +26,7 @@ AddSceneRequest
 
    .. rubric:: Attributes Documentation
 
+   .. autoattribute:: astropix
    .. autoattribute:: dataclass_json_config
    .. autoattribute:: outgoing_url
 

docs/clear-automodapis.sh

@@ -0,0 +1,26 @@
+#! /bin/bash
+
+# For URL structure reasons, our "api/" directory has a mixture of "root" files
+# that must exist (the ones for each module) and other files that live in
+# version control but are generated by the automodapi system. In order to
+# refresh the latter files, they must be deleted before running a doc build.
+# This script does that, while leaving the "root" files.
+
+apidir=$(dirname $0)/api
+
+cd "$apidir"
+
+for f in *.rst; do
+    case "$f" in
+    wwt_api_client.rst|\
+    wwt_api_client.communities.rst|\
+    wwt_api_client.constellations.rst|\
+    wwt_api_client.constellations.data.rst|\
+    wwt_api_client.constellations.handles.rst|\
+    wwt_api_client.constellations.images.rst|\
+    wwt_api_client.constellations.scenes.rst|\
+    wwt_api_client.enums.rst) ;;
+
+    *) rm -f "$f"
+    esac
+done

docs/endpoints/constellations/get-scene-_id.rst

@@ -68,6 +68,11 @@ The structure of the response is:
     },
     "text": $string, // The text associated with this scene
     "outgoing_url": $string(URL)?, // optional outgoing URL associated with this scene
+    "astropix": {
+      // Optional information about this scene's association with an AstroPix image
+      "publisher_id": $string, // the AstroPix image's publisher_id
+      "image_id": $string, // the AstroPix image's image_id
+    }
   }
 
 See :ref:`endpoint-post-handle-_handle-image` for definitions of the contents of the inner

docs/endpoints/constellations/get-scenes-astropix-summary.rst

@@ -0,0 +1,58 @@
+.. _endpoint-GET-scenes-astropix-summary:
+
+============================
+GET /scenes/astropix-summary
+============================
+
+This API gets a summary of associations between Constellations scenes and images
+in the `AstroPix`_ service. This API is generally available, but only expected
+to be useful for the AstroPix web server, which can use it to know which
+AstroPix images have associated WWT images.
+
+.. _AstroPix: https://www.astropix.org/
+
+
+Request Structure
+=================
+
+The request takes no content.
+
+
+Response Structure
+==================
+
+The structure of the response is:
+
+.. code-block:: javascript
+
+  {
+    "error": $bool, // whether an error occurred
+    "result": {
+      // Outer dictionary of associations, keyed by AstroPix publisher ID
+      $publisher_id(str): {
+        // Inner dictionary of associations, keyed by AstroPix image ID
+        $image_id(str): [
+          $wwt_handle(str),  // The WWT Constellations handle of the associated scene, with at-sign
+          $wwt_scene_id(str) // The WWT Constellations ID of the associated scene
+        ],
+      }
+    }
+  }
+
+For instance, in a world where there were only three WWT scenes associated with
+AstroPix content, the result might be:
+
+.. code-block:: javascript
+
+  {
+    "error": false,
+    "result": {
+      "eso": {
+        "eso0209g": ["@eso", "6426ed2448ae71323babb17a"],
+        "eso0622a": ["@eso", "6426ed2448ae71323babb18b"]
+      },
+      "ensci": {
+        "euclid20231107a": ["@euclid", "647a0909cd45eb52a07076b4"]
+      }
+    }
+  }

docs/endpoints/constellations/patch-scene-_id.rst

@@ -28,6 +28,14 @@ The structure of the request is:
     "text": $string?,  // New textual content for the scene
     "outgoing_url": $string?,  // New outgoing URL for the scene
     "place": $Place?, // New place information for the scene
+    "content": $Content?, // New content information for the scene
+    "published": $bool?, // New setting for publication flag
+    "astropix": {
+      // Optional dict associating this scene with an AstroPix image. Only user accounts
+      // with the "manage-astropix" role may set or modify this information.
+      "publisher_id": $string,
+      "image_id": $string,
+    }
   }
 
 For the definition of substructures such as ``Place``, see

docs/endpoints/constellations/post-handle-_handle-scene.rst

@@ -44,6 +44,13 @@ The structure of the request is:
     },
     "outgoing_url": $string?, // A "see more" URL associated with this scene
     "text": $string, // Freeform text describing the scene
+    "published": $bool?, // Whether this scene should be published upon creation
+    "astropix": {
+      // Optional dict associating this scene with an AstroPix image. Only user accounts
+      // with the "manage-astropix" role may set or modify this information.
+      "publisher_id": $string,
+      "image_id": $string,
+    }
   }
 
 

docs/index.rst

@@ -67,6 +67,7 @@ Constellations API endpoints:
    endpoints/constellations/delete-scene-_id-likes
    endpoints/constellations/get-scene-_id-permissions
    endpoints/constellations/get-scene-_id-place_wtml
+   endpoints/constellations/get-scenes-astropix-summary
    endpoints/constellations/get-scenes-home-timeline
    endpoints/constellations/post-session-init
 

setup.py

@@ -64,7 +64,7 @@ setup_args = dict(
     include_package_data=True,
     install_requires=[
         "dataclasses-json >=0.5",
-        "html-sanitizer",
+        "html-sanitizer >=2.4",
         "license-expression >=21.6",
         "openidc_client >=0.6",
         "requests >=2.10",

wwt_api_client/constellations/data.py

@@ -33,6 +33,7 @@ ImageStorage
 ImageSummary
 ImageUpdate
 ImageWwt
+SceneAstroPix
 SceneContent
 SceneContentHydrated
 SceneContentUpdate
@@ -271,6 +272,16 @@ class ScenePreviews:
     thumbnail: Optional[str] = None
 
 
+@dataclass_json(undefined="EXCLUDE")
+@dataclass
+class SceneAstroPix:
+    """Information about an association between a Constellations scene and an
+    AstroPix image."""
+
+    publisher_id: str
+    image_id: str
+
+
 @dataclass_json(undefined="EXCLUDE")
 @dataclass
 class SceneHydrated:
@@ -288,6 +299,7 @@ class SceneHydrated:
     text: str
     previews: ScenePreviews
     published: bool
+    astropix: Optional[SceneAstroPix] = None
 
 
 @dataclass_json(undefined="EXCLUDE")
@@ -324,3 +336,4 @@ class SceneUpdate:
     text: Optional[str] = None
     content: Optional[SceneContentUpdate] = None
     published: Optional[bool] = None
+    astropix: Optional[SceneAstroPix] = None

wwt_api_client/constellations/handles.py

@@ -28,6 +28,7 @@ from .data import (
     ImageContentPermissions,
     ImageStorage,
     ImageSummary,
+    SceneAstroPix,
     SceneContent,
     SceneHydrated,
     SceneImageLayer,
@@ -72,6 +73,7 @@ class AddSceneRequest:
     text: str
     published: bool
     outgoing_url: Optional[str] = None
+    astropix: Optional[SceneAstroPix] = None
 
 
 @dataclass_json(undefined="EXCLUDE")