capabilities docs, cleanup

spacetelescope · Sep 26, 2024 · 252dd54 · 252dd54
1 parent 0b95bd4
commit 252dd54
Show file tree

Hide file tree

Showing 5 changed files with 204 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -18,6 +18,7 @@ The following IVOA protocols are currently supported:
 - **VOSI (IVOA Support Interfaces) version 1.1**
   - VOSI Availability
   - VOSI Tables
+  - VOSI Capabilities
 - **VODataService version 1.2 (limited)**
   - DataType
   - FKColumn
@@ -26,6 +27,7 @@ The following IVOA protocols are currently supported:
   - TableParam
   - TableSchema
   - TableSet
+  - others
 - **VOResource version 1.1**
 - **TAPRegExt version 1.0**
 

diff --git a/docs/source/pages/api/vosi_api.rst b/docs/source/pages/api/vosi_api.rst
@@ -15,6 +15,14 @@ Tables
 ^^^^^^
 
 .. automodule:: vo_models.vosi.tables.models
+   :members:
+   :no-inherited-members:
+   :exclude-members: model_config, model_fields,
+
+Capabilities
+^^^^^^^^^^^^
+
+.. automodule:: vo_models.vosi.capabilities.models
    :members:
    :no-inherited-members:
    :exclude-members: model_config, model_fields,
diff --git a/docs/source/pages/protocols/vosi.rst b/docs/source/pages/protocols/vosi.rst
@@ -8,7 +8,7 @@ VOSI (VO Support Interface)
 Availability
 ^^^^^^^^^^^^
 
-The Availability model is used to represent the response given by a UWS service to a
+The Availability model is used to represent the response given by a service to a
 ``GET /availability`` request.
 
 .. grid:: 2
@@ -81,4 +81,28 @@ For requests to the ``GET /tables`` endpoint, you can use the ``TableSet`` model
             :language: xml
             :lines: 2-
             :start-after: tableset-xml-start
-            :end-before: tableset-xml-end
+            :end-before: tableset-xml-end
+
+Capabilities
+^^^^^^^^^^^^
+
+The VOSICapabilities model is used to represent the response given by a service to a
+``GET /capabilities`` request. Below is a relatively full example of a VOSI capabilities document for a TAP service.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/vosi/capabilities.py
+            :language: python
+            :start-after: capabilities-model-start
+            :end-before: capabilities-model-end
+
+    .. grid-item-card:: XML Output
+
+            .. literalinclude:: ../../../../examples/snippets/vosi/capabilities.py
+                :language: xml
+                :lines: 2-
+                :start-after: capabilities-xml-start
+                :end-before: capabilities-xml-end
diff --git a/examples/snippets/vosi/capabilities.py b/examples/snippets/vosi/capabilities.py
@@ -0,0 +1,166 @@
+"""Example snippets for VOSI capabilities."""
+
+from vo_models.tapregext.models import (
+    DataLimit,
+    DataLimits,
+    Language,
+    LanguageFeature,
+    LanguageFeatureList,
+    OutputFormat,
+    TableAccess,
+    Version,
+)
+from vo_models.vodataservice.models import ParamHTTP
+from vo_models.voresource.models import AccessURL, Capability, WebBrowser
+from vo_models.vosi.capabilities.models import VOSICapabilities
+
+# pylint: disable=invalid-name
+
+# [capabilities-model-start]
+vosi_capabilities_model = VOSICapabilities(
+    capability=[
+        TableAccess(
+            type="tr:TableAccess",
+            interface=[
+                ParamHTTP(
+                    role="std",
+                    version="1.1",
+                    access_url=[AccessURL(use="full", value="https://someservice.edu/tap")],
+                )
+            ],
+            language=[
+                Language(
+                    name="ADQL",
+                    version=[Version(value="2.0", ivo_id="ivo://ivoa.net/std/ADQL#v2.0")],
+                    description="ADQL-2.0. Positional queries using CONTAINS with POINT and CIRCLE are supported.",
+                    language_features=[
+                        LanguageFeatureList(
+                            type="ivo://ivoa.net/std/TAPRegExt#features-adql-geo",
+                            feature=[
+                                LanguageFeature(form="POINT"),
+                                LanguageFeature(form="CIRCLE"),
+                            ],
+                        ),
+                    ],
+                )
+            ],
+            output_format=[
+                OutputFormat(
+                    mime="application/x-votable+xml",
+                    alias=["votable"],
+                    ivo_id="ivo://ivoa.net/std/TAPRegExt#output-votable-td",
+                ),
+                OutputFormat(
+                    mime="text/csv;header=present",
+                    alias=["csv"],
+                ),
+            ],
+            output_limit=DataLimits(
+                default=DataLimit(unit="row", value=100000),
+                hard=DataLimit(unit="row", value=100000),
+            ),
+        ),
+        Capability(
+            standard_id="ivo://ivoa.net/std/VOSI#capabilities",
+            interface=[
+                ParamHTTP(
+                    role="std",
+                    access_url=[AccessURL(use="full", value="https://someservice.edu/tap/capabilities")],
+                )
+            ],
+        ),
+        Capability(
+            standard_id="ivo://ivoa.net/std/VOSI#availability",
+            interface=[
+                ParamHTTP(
+                    role="std",
+                    access_url=[AccessURL(use="full", value="https://someservice.edu/tap/availability")],
+                )
+            ],
+        ),
+        Capability(
+            standard_id="ivo://ivoa.net/std/VOSI#tables",
+            interface=[
+                ParamHTTP(
+                    role="std",
+                    version="1.1",
+                    access_url=[AccessURL(use="full", value="https://someservice.edu/tap/tables")],
+                )
+            ],
+        ),
+        Capability(
+            standard_id="ivo://ivoa.net/std/DALI#examples",
+            interface=[
+                WebBrowser(
+                    access_url=[AccessURL(use="full", value="https://someservice.edu/tap/examples")],
+                )
+            ],
+        ),
+    ]
+)
+# [capabilities-model-end]
+
+# [capabilities-xml-start]
+capabilities_xml = """<vosi:capabilities>
+        <capability standardID="ivo://ivoa.net/std/TAP" xsi:type="tr:TableAccess">
+            <interface role="std" xsi:type="vs:ParamHTTP" version="1.1">
+                <accessURL use="full">https://someservice.edu/tap</accessURL>
+            </interface>
+            <language>
+                <name>ADQL</name>
+                <version ivo-id="ivo://ivoa.net/std/ADQL#v2.0">2.0</version>
+                <description>
+                    ADQL-2.0. Positional queries using CONTAINS with POINT and CIRCLE are supported.
+                </description>
+                <languageFeatures type="ivo://ivoa.net/std/TAPRegExt#features-adql-geo">
+                    <feature>
+                        <form>POINT</form>
+                    </feature>
+                    <feature>
+                        <form>CIRCLE</form>
+                    </feature>
+                </languageFeatures>
+            </language>
+            <outputFormat ivo-id="ivo://ivoa.net/std/TAPRegExt#output-votable-td">
+                <mime>application/x-votable+xml</mime>
+                <alias>votable</alias>
+            </outputFormat>
+            <outputFormat>
+                <mime>text/csv;header=present</mime>
+                <alias>csv</alias>
+            </outputFormat>
+            <outputLimit>
+                <default unit="row">100000</default>
+                <hard unit="row">100000</hard>
+            </outputLimit>
+        </capability>
+        <capability standardID="ivo://ivoa.net/std/VOSI#capabilities">
+            <interface xsi:type="vs:ParamHTTP" role="std">
+                <accessURL use="full">
+                    https://someservice.edu/tap/capabilities
+    </accessURL>
+            </interface>
+        </capability>
+        <capability standardID="ivo://ivoa.net/std/VOSI#availability">
+            <interface xsi:type="vs:ParamHTTP" role="std">
+                <accessURL use="full">
+                    https://someservice.edu/tap/availability
+    </accessURL>
+            </interface>
+        </capability>
+        <capability standardID="ivo://ivoa.net/std/VOSI#tables">
+            <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
+                <accessURL use="full">
+                    https://someservice.edu/tap/tables
+    </accessURL>
+            </interface>
+        </capability>
+        <capability standardID="ivo://ivoa.net/std/DALI#examples">
+            <interface xsi:type="vr:WebBrowser">
+                <accessURL use="full">
+                    https://someservice.edu/tap/examples
+    </accessURL>
+            </interface>
+        </capability>
+    </vosi:capabilities>
+"""  # [capabilities-xml-end]
diff --git a/vo_models/voresource/models.py b/vo_models/voresource/models.py
@@ -49,6 +49,8 @@ class ResourceName(BaseXmlModel, nsmap=NSMAP):
     Parameters:
         ivo_id:
             (attr) - The IVOA identifier for the resource referred to.
+        value:
+            (content) - The name of the resource.
     """
 
     value: str