Add VOSI Tables Support (#16)

VOSITables support added
spacetelescope · Jun 14, 2024 · 6432dbf · 6432dbf
1 parent b8b8b10
commit 6432dbf
Show file tree

Hide file tree

Showing 26 changed files with 1,890 additions and 72 deletions.
diff --git a/README.md b/README.md
@@ -1,14 +1,14 @@
 # vo-models
 
-`vo-models` an open-source project to provide Python models for [IVOA](https://www.ivoa.net/) service protocols.
+`vo-models` is an open-source project to provide Python models for [IVOA](https://www.ivoa.net/) service protocols.
 
 The project is designed to be used by IVOA members, service implementors, and developers to help facilitate the development of IVOA-compliant services and clients.
 
 ## Features
 
 - **Pydantic-xml Models:** The project includes Python models for IVOA protocols, using [pydantic-xml](https://github.com/dapper91/pydantic-xml). Based on [Pydantic](https://docs.pydantic.dev/latest/), these models describe transactions for an IVOA protocol, such as UWS, and feature automatic validation, parsing and serialization of XML data for use with Python clients and web frameworks.
 
-- **Expandability:** The project is designed with future expansion in mind. Plans include extending the schema and models to cover other IVOA standards.
+- **Expandability:** The project is designed with future expansion in mind. Plans include extending the schema and models to cover other IVOA standards and future versions of existing standards where possible.
 
 ## Protocols
 
@@ -17,6 +17,15 @@ The following IVOA protocols are currently supported:
 - **UWS (Universal Worker Service) version 1.1**
 - **VOSI (IVOA Support Interfaces) version 1.1**
   - VOSI Availability
+  - VOSI Tables
+- **VODataService version 1.2 (limited)**
+  - DataType
+  - FKColumn
+  - ForeignKey
+  - Table
+  - TableParam
+  - TableSchema
+  - TableSet
 
 You can read more about using these models in our documentation: https://vo-models.readthedocs.io/
 
@@ -48,12 +57,6 @@ For active development, install the project in development mode:
 pip install -e .[dev,test]
 ```
 
-### Pydantic-XML Models
-
-Python models using [pydantic-xml](https://github.com/dapper91/pydantic-xml), a library based on [Pydantic](https://docs.pydantic.dev/latest/), are provided in the `vo/models/xml` directory.
-
-These models can be used to parse and validate XML data into Python objects, as well as serialize Python objects into XML data. These models can be used with any Python web framework, but are particularly useful when used libraries that leverage the power of Pydantic, such as [FastAPI](https://fastapi.tiangolo.com/).
-
 ### Contributing
 
 Contributions to the project are more than welcome. Collaboration and discussion with other IVOA members, service implementors, and developers is what started this project, and is what makes the IVOA great.

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -33,6 +33,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
 ]
 
 autodoc_default_options = {

diff --git a/docs/source/pages/api/index.rst b/docs/source/pages/api/index.rst
@@ -10,4 +10,5 @@ This section contains documentation on the package's modules and classes.
 
     uws_api
     vosi_api
-    voresource_api
+    voresource_api
+    vodataservice_api
diff --git a/docs/source/pages/api/vodataservice_api.rst b/docs/source/pages/api/vodataservice_api.rst
@@ -0,0 +1,12 @@
+.. _vodataservice_api:
+
+VODataservice API
+-----------------
+
+Models
+^^^^^^
+
+.. automodule:: vo_models.vodataservice.models
+    :members:
+    :no-inherited-members:
+    :exclude-members: model_config, model_fields, Job
diff --git a/docs/source/pages/api/vosi_api.rst b/docs/source/pages/api/vosi_api.rst
@@ -7,6 +7,14 @@ Availability
 ^^^^^^^^^^^^
 
 .. automodule:: vo_models.vosi.availability.models
+   :members:
+   :no-inherited-members:
+   :exclude-members: model_config, model_fields,
+
+Tables
+^^^^^^
+
+.. automodule:: vo_models.vosi.tables.models
    :members:
    :no-inherited-members:
    :exclude-members: model_config, model_fields,
diff --git a/docs/source/pages/protocols/index.rst b/docs/source/pages/protocols/index.rst
@@ -9,4 +9,5 @@ The following IVOA protocols are currently supported:
     :maxdepth: 3
 
     uws
-    vosi
+    vosi
+    vodataservice
diff --git a/docs/source/pages/protocols/vodataservice.rst b/docs/source/pages/protocols/vodataservice.rst
@@ -0,0 +1,173 @@
+.. _vodataservice:
+
+VODataService
+-------------
+
+VODataService is an IVOA XML encoding standard for data collections and services that access them. It is an extension of the VOResource standard.
+
+`vo-models` currently supports the following VODataService v1.2 elements:
+
+Models
+^^^^^^
+
+FKColumn
+********
+
+Represents a single foreign key column.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: python
+            :start-after: FKColumn-model-start
+            :end-before: FKColumn-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: xml
+            :lines: 2-
+            :start-after: FKColumn-xml-start
+            :end-before: FKColumn-xml-end
+
+ForeignKey
+**********
+
+Represents one or more foreign key columns.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: python
+            :start-after: ForeignKey-model-start
+            :end-before: ForeignKey-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: xml
+            :lines: 2-
+            :start-after: ForeignKey-xml-start
+            :end-before: ForeignKey-xml-end
+
+DataType
+********
+
+A simple element containing a column's datatype.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: python
+            :start-after: DataType-model-start
+            :end-before: DataType-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: xml
+            :lines: 2-
+            :start-after: DataType-xml-start
+            :end-before: DataType-xml-end
+
+TableParam
+**********
+
+A description of a table parameter (a column within the table) with a fixed datatype.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: python
+            :start-after: TableParam-model-start
+            :end-before: TableParam-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: xml
+            :lines: 2-
+            :start-after: TableParam-xml-start
+            :end-before: TableParam-xml-end
+
+Table
+*****
+
+A single table element.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: python
+            :start-after: Table-model-start
+            :end-before: Table-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: xml
+            :lines: 2-
+            :start-after: Table-xml-start
+            :end-before: Table-xml-end
+
+TableSchema
+***********
+
+Represents a description of a logically related group of tables.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: python
+            :start-after: TableSchema-model-start
+            :end-before: TableSchema-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: xml
+            :lines: 2-
+            :start-after: TableSchema-xml-start
+            :end-before: TableSchema-xml-end
+
+
+TableSet
+********
+
+Represents a collection of tables that are part of a single resource.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: python
+            :start-after: TableSet-model-start
+            :end-before: TableSet-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/vodataservice/vodataservice.py
+            :language: xml
+            :lines: 2-
+            :start-after: TableSet-xml-start
+            :end-before: TableSet-xml-end
diff --git a/docs/source/pages/protocols/vosi.rst b/docs/source/pages/protocols/vosi.rst
@@ -6,7 +6,7 @@ VOSI (VO Support Interface)
 ``vo-models`` supports the following VOSI v1.0 protocols:
 
 Availability
-*****************
+^^^^^^^^^^^^
 
 The Availability model is used to represent the response given by a UWS service to a
 ``GET /availability`` request.
@@ -27,4 +27,58 @@ The Availability model is used to represent the response given by a UWS service
             :language: xml
             :lines: 2-
             :start-after: xml-start
-            :end-before: xml-end
+            :end-before: xml-end
+
+Tables
+^^^^^^
+
+VOSITable
+*********
+
+For requests for a single table from the ``GET /tables/{table_name}`` endpoint, you can use the ``Table`` model.
+
+.. note:: This model is functionally identical to the :ref:`pages/protocols/vodataservice:table` element, specifically namespaced under VOSI.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/vosi/tables.py
+            :language: python
+            :start-after: table-model-start
+            :end-before: table-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/vosi/tables.py
+            :language: xml
+            :lines: 2-
+            :start-after: table-xml-start
+            :end-before: table-xml-end
+
+
+VOSITableSet
+************
+
+For requests to the ``GET /tables`` endpoint, you can use the ``TableSet`` model to represent table schemas, their child tables, and columns.
+
+.. note:: This model is functionally identical to the :ref:`pages/protocols/vodataservice:tableset` element, specifically namespaced under VOSI.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/vosi/tables.py
+            :language: python
+            :start-after: tableset-model-start
+            :end-before: tableset-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/vosi/tables.py
+            :language: xml
+            :lines: 2-
+            :start-after: tableset-xml-start
+            :end-before: tableset-xml-end
diff --git a/docs/source/pages/quickstart.rst b/docs/source/pages/quickstart.rst
@@ -6,7 +6,7 @@ Quickstart
 Basic Usage
 -----------
 
-Working with ``vo-models`` classes is easy. They can be created and modified like any Pydantic model.
+``vo-models`` objects can be created and modified like any Python class or Pydantic model.
 
 The following example creates a UWS :ref:`pages/protocols/uws:shortjobdescription` model using keyword arguments and updates the phase:
-Original file line number
+Diff line change
@@ Expand Up / @@ -9,4 +9,5 @@ The following IVOA protocols are currently supported: @@
         :maxdepth: 3
         uws
-        vosi
+        vosi
+        vodataservice