xradio 0.0.40__py3-none-any.whl → 0.0.42__py3-none-any.whl

xradio/schema/check.py

@@ -374,30 +374,50 @@ def check_data_vars(
 
     issues = SchemaIssues()
     for data_var_schema in data_vars_schema:
-        # Data_Varinate missing?
-        data_var = data_vars.get(data_var_schema.name)
-        if data_var is None:
-            if not data_var_schema.optional:
-                if data_var_kind == "coords":
-                    message = (
-                        f"Required coordinate '{data_var_schema.name}' is missing!"
-                    )
-                else:
-                    message = (
-                        f"Required data variable '{data_var_schema.name}' is missing "
-                        f"(have {','.join(data_vars)})!"
-                    )
-                issues.add(
-                    SchemaIssue(
-                        path=[(data_var_kind, data_var_schema.name)], message=message
+
+        allow_mutiple_versions = False
+        for attr in data_var_schema.attributes:
+            if hasattr(attr, "name"):
+                if attr.name == "allow_mutiple_versions":
+                    allow_mutiple_versions = attr.default
+
+        data_vars_names = []
+        if allow_mutiple_versions:
+            for data_var_name in data_vars:
+                if data_var_schema.name in data_var_name:
+                    data_vars_names.append(data_var_name)
+        else:
+            data_vars_names = [data_var_schema.name]
+
+        if (len(data_vars_names) == 0) and ~data_var_schema.optional:
+            data_vars_names = [data_var_schema.name]
+
+        for data_var_name in data_vars_names:
+            data_var = data_vars.get(data_var_name)
+
+            if data_var is None:
+                if not data_var_schema.optional:
+                    if data_var_kind == "coords":
+                        message = (
+                            f"Required coordinate '{data_var_schema.name}' is missing!"
+                        )
+                    else:
+                        message = (
+                            f"Required data variable '{data_var_schema.name}' is missing "
+                            f"(have {','.join(data_vars)})!"
+                        )
+                    issues.add(
+                        SchemaIssue(
+                            path=[(data_var_kind, data_var_schema.name)],
+                            message=message,
+                        )
                     )
-                )
-            continue
+                continue
 
-        # Check array schema
-        issues += check_array(data_var, data_var_schema).at_path(
-            data_var_kind, data_var_schema.name
-        )
+            # Check array schema
+            issues += check_array(data_var, data_var_schema).at_path(
+                data_var_kind, data_var_schema.name
+            )
 
     # Extra data_varinates / data variables are always okay
 

xradio/schema/dataclass.py

@@ -67,18 +67,60 @@ def extract_field_docstrings(klass):
     return docstrings
 
 
-def extract_xarray_dataclass(klass):
+def _check_invalid_dims(
+    dims: list[list[str]], all_coord_names: list[str], klass_name: str, field_name: str
+):
+    """
+    Check dimension possibilities for undefined coordinates
+    """
+
+    # Filter out dimension possibilities with undefined coordinates
+    valid_dims = [ds for ds in dims if set(ds).issubset(all_coord_names)]
+    # print(f"{klass_name}.{field_name}", valid_dims, dims, all_coord_names)
+
+    # Raise an exception if this makes the dimension set impossible
+    if dims and not valid_dims:
+        required_dims = sorted(map(lambda ds: set(ds) - all_coord_names, dims), key=len)
+        raise ValueError(
+            f"In '{klass_name}', field '{field_name}' has"
+            f" undefined coordinates, consider defining {required_dims}!"
+        )
+    return valid_dims
+
+
+def extract_xarray_dataclass(klass, allow_undefined_coords: bool = False):
     """
     Go through dataclass fields and interpret them according to xarray-dataclass
 
     Returns a tuple of coordinates, data variables and attributes
+
+    :param allow_undefined_coords: Allow data variables with dimensions
+      that do not have associated coordinates (e.g. for data arrays).
     """
 
     field_docstrings = extract_field_docstrings(klass)
 
+    # Collect type hints, identify coordinates
+    type_hints = get_type_hints(klass, include_extras=True)
+    if allow_undefined_coords:
+
+        def check_invalid_dims(dims, field_name):
+            return dims
+
+    else:
+        all_coord_names = {
+            field.name
+            for field in dataclasses.fields(klass)
+            if get_role(type_hints[field.name]) == Role.COORD
+        }
+
+        def check_invalid_dims(dims, field_name):
+            return _check_invalid_dims(
+                dims, all_coord_names, klass.__name__, field_name
+            )
+
     # Go through attributes, collecting coordinates, data variables and
     # attributes
-    type_hints = get_type_hints(klass, include_extras=True)
     coordinates = []
     data_vars = []
     attributes = []
@@ -122,6 +164,11 @@ def extract_xarray_dataclass(klass):
                 for f in dataclasses.fields(ArraySchema)
             }
 
+            # Check for undefined coordinates
+            arr_schema_fields["dimensions"] = check_invalid_dims(
+                arr_schema_fields["dimensions"], field.name
+            )
+
             # Repackage as reference
             schema_ref = ArraySchemaRef(
                 name=field.name,
@@ -152,7 +199,10 @@ def extract_xarray_dataclass(klass):
                     f.name: getattr(arr_schema, f.name)
                     for f in dataclasses.fields(ArraySchema)
                 }
-                arr_schema_fields["dimensions"] = combined_dimensions
+
+                arr_schema_fields["dimensions"] = check_invalid_dims(
+                    combined_dimensions, field.name
+                )
                 schema_ref = ArraySchemaRef(
                     name=field.name,
                     optional=is_optional(typ),
@@ -167,8 +217,8 @@ def extract_xarray_dataclass(klass):
                     optional=is_optional(typ),
                     default=field.default,
                     docstring=field_docstrings.get(field.name),
-                    schema_name=f"{klass.__module__}.{klass.__qualname__}.{field.name}",
-                    dimensions=dims,
+                    schema_name=None,
+                    dimensions=check_invalid_dims(dims, field.name),
                     dtypes=[numpy.dtype(typ) for typ in types],
                     coordinates=[],
                     attributes=[],
@@ -206,7 +256,7 @@ def xarray_dataclass_to_array_schema(klass):
         return klass.__xradio_array_schema
 
     # Extract from data class
-    coordinates, data_vars, attributes = extract_xarray_dataclass(klass)
+    coordinates, data_vars, attributes = extract_xarray_dataclass(klass, True)
 
     # For a dataclass there must be exactly one data variable
     if not data_vars:

xradio/sphinx/__init__.py

@@ -0,0 +1,12 @@
+from . import schema_table
+
+
+def setup(app):
+    app.add_directive(
+        "xradio_array_schema_table", schema_table.ArraySchemaTableDirective
+    )
+    app.add_directive(
+        "xradio_dataset_schema_table", schema_table.DatasetSchemaTableDirective
+    )
+    app.add_directive("xradio_dict_schema_table", schema_table.DictSchemaTableDirective)
+    return {"version": "0.1.0"}

xradio/sphinx/schema_table.py

@@ -0,0 +1,351 @@
+import importlib
+import dataclasses
+import typing
+
+from docutils import nodes, utils
+from docutils.parsers.rst import Directive, DirectiveError
+from docutils.parsers.rst import directives
+from docutils.utils import SystemMessagePropagation
+from docutils.statemachine import StringList
+
+from sphinx.directives import ObjectDescription
+from sphinx.util.docutils import switch_source_input
+
+from xradio.schema import (
+    xarray_dataclass_to_array_schema,
+    xarray_dataclass_to_dataset_schema,
+    xarray_dataclass_to_dict_schema,
+)
+
+
+class SchemaTableDirective(ObjectDescription):
+    required_arguments = 1  # Xarray dataclass of schema
+    has_content = False
+
+    option_spec = {
+        # "headers": directives.unchanged,
+        # "widths": directives.unchanged,
+        "title": directives.unchanged,
+        # "columns": directives.unchanged,
+        "class": directives.unchanged,
+    }
+
+    def run(self):
+        # Import the referenced class
+        klass_path = self.arguments[0].rsplit(".", 1)
+        if len(klass_path) != 2:
+            raise ValueError(
+                f"Should be absolute Python name of xarray dataclass definition: {self.arguments[0]}"
+            )
+        klass_module = importlib.import_module(klass_path[0])
+        klass = getattr(klass_module, klass_path[1])
+
+        # Make table node
+        classes = ["tbl", "colwidths-given"]
+        if "class" in self.options:
+            classes.append(self.options["class"])
+        self._table = nodes.table(
+            classes=classes, ids=[f"schema-table-{self.arguments[0]}"]
+        )
+
+        # Add title, if requested
+        if "title" in self.options:
+            self._table += nodes.title(text=caption)
+
+        # Declare columns
+        column_widths = [10, 10, 5, 5, 40]
+        self._tgroup = nodes.tgroup(cols=len(column_widths))
+        self._table += self._tgroup
+        for colwidth in column_widths:
+            self._tgroup += nodes.colspec(colwidth=colwidth)
+
+        # Create head row
+        header_row = nodes.row()
+        header_row += nodes.entry("", nodes.paragraph(text=""))
+        header_row += nodes.entry("", nodes.strong(text="Dimensions"))
+        header_row += nodes.entry("", nodes.strong(text="Dtype"))
+        header_row += nodes.entry("", nodes.strong(text="Model"))
+        header_row += nodes.entry("", nodes.strong(text="Description"))
+        self._thead = nodes.thead("", header_row)
+        self._tgroup += self._thead
+
+        # Add body
+        self._tbody = nodes.tbody()
+        self._tgroup += self._tbody
+
+        # Add table contents (overridden in subclasses)
+        self._add_table_contents(klass)
+
+        # Register table
+        # tbl = self.env.get_domain("tbl")
+        # tbl.add_table(caption, table_id)
+
+        return [self._table]
+
+    def _add_section(self, name):
+        # Create row
+        row = nodes.row("", nodes.entry("", nodes.strong("", name), morecols=4))
+        self._tbody += row
+
+    def _add_row(
+        self,
+        name="",
+        dimss=[],
+        types=[],
+        meta=None,
+        descr="",
+        optional=False,
+        default=dataclasses.MISSING,
+    ):
+        # Create row
+        row = nodes.row()
+        self._tbody += row
+
+        # Add name
+        name_nds = [nodes.literal(text=name)]
+        if optional:
+            name_nds = [nodes.Text("(")] + name_nds + [nodes.Text(")")]
+        row += nodes.entry("", *name_nds)
+
+        # Add dimensions
+        def mk_multi_entry(lines):
+            if not lines:
+                return nodes.entry()
+            if len(lines) == 0:
+                return nodes.entry(lines[0])
+            else:
+                entry = nodes.entry()
+                for i, line in enumerate(lines):
+                    entry += nodes.line("", "" if i == 0 else "or\xa0", line)
+                return entry
+
+        row += mk_multi_entry(
+            [nodes.literal(text=f"[{','.join(dims)}]") for dims in dimss]
+        )
+
+        # Add types
+        row += mk_multi_entry([nodes.literal(text=typ) for typ in types])
+
+        # Add model link
+        entry = nodes.entry()
+        row += entry
+        if meta is not None:
+            # Preformatted? Just pass through
+            if isinstance(meta, nodes.line):
+                entry += meta
+            else:
+                vl = StringList()
+                vl.append(f":py:class:`~{meta}`", "")
+                with switch_source_input(self.state, vl):
+                    self.state.nested_parse(vl, 0, entry)
+
+        # Add description
+        entry = nodes.entry()
+        row += entry
+        if descr:
+            vl = StringList()
+            vl.append(descr, "")
+            with switch_source_input(self.state, vl):
+                self.state.nested_parse(vl, 0, entry)
+        if default is not dataclasses.MISSING:
+            vl = StringList()
+            vl.append(f"**Default:** ``{repr(default)}``", "")
+            with switch_source_input(self.state, vl):
+                self.state.nested_parse(vl, 0, entry)
+
+
+def format_literals(typ):
+
+    # a | b | c: Recurse and merge
+    if typing.get_origin(typ) == typing.Union:
+        type_args = typing.get_args(typ)
+        options = []
+        for arg in type_args:
+            options += format_literals(arg)
+        return options
+
+    # Literal['a', 'b', ...]: Wrap into individual "literal" nodes
+    if typing.get_origin(typ) == typing.Literal:
+        return list(map(lambda t: nodes.literal(text=repr(t)), typing.get_args(typ)))
+
+    # list[Literal['a'], Literal['b'], ...]: Format as one literal (compound) value
+    if typing.get_origin(typ) == list:
+        type_args = typing.get_args(typ)
+        if any([typing.get_origin(arg) != typing.Literal for arg in type_args]):
+            raise ValueError(f"List must contain only literals: {typ}")
+        values = [repr(typing.get_args(val)[0]) for val in typing.get_args(typ)]
+        return [nodes.literal(text=f"[{', '.join(values)}]")]
+
+    raise ValueError(f"Must be either a type or a literal: {typ}")
+
+
+def format_attr_model_text(state, attr) -> StringList:
+    """
+    Formats the text for the 'model' column in schema tables (arrays and datasets).
+    Doesn't aim at supporting any literal types or combinations of types in general,
+    but the following three ones specifically:
+
+    - Literals (with multiple options (implicit Union of literals))
+    - List of literals (e.g. ["rad","rad"]
+    - Union of list of literals (e.g. ["m","m","m"]/["rad","rad","m"]
+
+    This is meant to produce readable text listing literals as quoted text and
+    their combinations, in schema attributes (particularly quantities and measures).
+
+    Everything else than these expected literal based types would be printed as the
+    type name.
+    """
+
+    type_args = typing.get_args(attr.typ)
+    is_list_of_literals = typing.get_origin(attr.typ) is list and all(
+        [typing.get_origin(arg) is typing.Literal for arg in type_args]
+    )
+
+    line = nodes.line()
+
+    if not is_list_of_literals:
+        # A type?
+        if isinstance(attr.typ, type):
+            vl = StringList()
+            vl.append(f":py:class:`~{attr.typ.__module__}.{attr.typ.__name__}`", "")
+            with switch_source_input(state, vl):
+                state.nested_parse(vl, 0, line)
+            return line
+
+        # Derived type, e.g. list of types?
+        if typing.get_origin(attr.typ) == list and all(
+            [isinstance(arg, type) for arg in type_args]
+        ):
+            vl = StringList()
+            vl.append("[", "")
+            for i, arg in enumerate(typing.get_args(attr.typ)):
+                if i > 0:
+                    vl.append(", ", "")
+                vl.append(f":py:class:`~{arg.__module__}.{arg.__name__}`", "")
+            vl.append("]", "")
+            with switch_source_input(state, vl):
+                state.nested_parse(vl, 0, line)
+            return line
+
+    # Assume it's a literal of some kind - collect options
+    literals = format_literals(attr.typ)
+    for i, lit in enumerate(literals):
+        if i > 0:
+            if i + 1 >= len(literals):
+                line += nodes.Text(" or\xa0")
+            else:
+                line += nodes.Text(", ")
+        line += lit
+
+    return line
+
+
+class ArraySchemaTableDirective(SchemaTableDirective):
+    def _add_table_contents(self, klass):
+        # Extract schema
+        schema = xarray_dataclass_to_array_schema(klass)
+
+        # Add dataarray reference as first element
+        self._add_row(
+            "data",
+            schema.dimensions,
+            schema.dtypes,
+            schema.schema_name,
+            schema.data_docstring,
+        )
+
+        # Add coordinates
+        if schema.coordinates:
+            self._add_section("Coordinates:")
+            for coord in schema.coordinates:
+                self._add_row(
+                    coord.name,
+                    coord.dimensions,
+                    coord.dtypes,
+                    coord.schema_name,
+                    coord.docstring or coord.data_docstring,
+                    optional=coord.optional,
+                    default=coord.default,
+                )
+
+        # Add attributes
+        if schema.attributes:
+            self._add_section("Attributes:")
+            for attr in schema.attributes:
+                model_text = format_attr_model_text(self.state, attr)
+                self._add_row(
+                    attr.name,
+                    [],
+                    [],
+                    model_text,
+                    attr.docstring,
+                    optional=attr.optional,
+                    default=attr.default,
+                )
+
+
+class DatasetSchemaTableDirective(SchemaTableDirective):
+    def _add_table_contents(self, klass):
+        # Extract schema
+        schema = xarray_dataclass_to_dataset_schema(klass)
+
+        # Add coordinates
+        if schema.coordinates:
+            self._add_section("Coordinates:")
+            for coord in schema.coordinates:
+                self._add_row(
+                    coord.name,
+                    coord.dimensions,
+                    coord.dtypes,
+                    coord.schema_name,
+                    coord.docstring or coord.data_docstring,
+                    optional=coord.optional,
+                    default=coord.default,
+                )
+
+        # Add data variables
+        if schema.data_vars:
+            self._add_section("Data Variables:")
+            for data_var in schema.data_vars:
+                self._add_row(
+                    data_var.name,
+                    data_var.dimensions,
+                    data_var.dtypes,
+                    data_var.schema_name,
+                    data_var.docstring or data_var.data_docstring,
+                    optional=data_var.optional,
+                    default=data_var.default,
+                )
+
+        # Add attributes
+        if schema.attributes:
+            self._add_section("Attributes:")
+            for attr in schema.attributes:
+                model_text = format_attr_model_text(self.state, attr)
+                self._add_row(
+                    attr.name,
+                    [],
+                    [],
+                    model_text,
+                    attr.docstring,
+                    optional=attr.optional,
+                    default=attr.default,
+                )
+
+
+class DictSchemaTableDirective(SchemaTableDirective):
+    def _add_table_contents(self, klass):
+        # Extract schema
+        schema = xarray_dataclass_to_dict_schema(klass)
+
+        # Add attributes
+        if schema.attributes:
+            self._add_section("Fields:")
+            for attr in schema.attributes:
+                self._add_row(
+                    attr.name,
+                    types=[f"{attr.typ.__name__}"],
+                    optional=attr.optional,
+                    descr=attr.docstring,
+                    default=attr.default,
+                )

{xradio-0.0.40.dist-info → xradio-0.0.42.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: xradio
-Version: 0.0.40
+Version: 0.0.42
 Summary: Xarray Radio Astronomy Data IO
 Author-email: Jan-Willem Steeb <jsteeb@nrao.edu>
 License: BSD 3-Clause License
@@ -43,18 +43,14 @@ License-File: LICENSE.txt
 Requires-Dist: astropy
 Requires-Dist: dask
 Requires-Dist: distributed
-Requires-Dist: graphviper
 Requires-Dist: toolviper
-Requires-Dist: matplotlib
 Requires-Dist: numba >=0.57.0
 Requires-Dist: numpy
-Requires-Dist: prettytable
 Requires-Dist: pytest
 Requires-Dist: pytest-cov
 Requires-Dist: pytest-html
 Requires-Dist: s3fs
 Requires-Dist: scipy
-Requires-Dist: tqdm
 Requires-Dist: xarray
 Requires-Dist: zarr
 Requires-Dist: pyarrow
@@ -62,11 +58,6 @@ Requires-Dist: typeguard
 Requires-Dist: typing-extensions ; python_version < "3.10"
 Requires-Dist: python-casacore >=3.6.1 ; sys_platform != "darwin"
 Provides-Extra: docs
-Requires-Dist: jupyterlab ; extra == 'docs'
-Requires-Dist: ipykernel ; extra == 'docs'
-Requires-Dist: ipympl ; extra == 'docs'
-Requires-Dist: ipython ; extra == 'docs'
-Requires-Dist: jupyter-client ; extra == 'docs'
 Requires-Dist: nbsphinx ; extra == 'docs'
 Requires-Dist: recommonmark ; extra == 'docs'
 Requires-Dist: scanpydoc ; extra == 'docs'
@@ -75,22 +66,33 @@ Requires-Dist: sphinx-autosummary-accessors ; extra == 'docs'
 Requires-Dist: sphinx-rtd-theme ; extra == 'docs'
 Requires-Dist: twine ; extra == 'docs'
 Requires-Dist: pandoc ; extra == 'docs'
+Provides-Extra: interactive
+Requires-Dist: matplotlib ; extra == 'interactive'
+Requires-Dist: prettytable ; extra == 'interactive'
+Requires-Dist: jupyterlab ; extra == 'interactive'
+Requires-Dist: ipykernel ; extra == 'interactive'
+Requires-Dist: ipympl ; extra == 'interactive'
+Requires-Dist: ipython ; extra == 'interactive'
+Requires-Dist: jupyter-client ; extra == 'interactive'
 
 # xradio
 Xarray Radio Astronomy Data IO is still in development.
 
-[![Python 3.9 3.10 3.11](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11-blue)](https://www.python.org/downloads/release/python-380/)
+[![Python 3.9 3.10 3.11 3.12](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%203.12-blue)](https://www.python.org/downloads/release/python-380/)
 
 # Installing
-It is recommended to use the [conda](https://docs.conda.io/projects/conda/en/latest/) environment manager to create a clean, self-contained runtime where xradio and all its dependencies can be installed:
+It is recommended to use the conda environment manager from [miniforge](https://github.com/conda-forge/miniforge) to create a clean, self-contained runtime where XRADIO and all its dependencies can be installed:
 ```sh
-conda create --name xradio python=3.11 --no-default-packages
+conda create --name xradio python=3.12 --no-default-packages
 conda activate xradio
-
 ```
 > 📝 On macOS it is required to pre-install `python-casacore` using `conda install -c conda-forge python-casacore`.
 
-Making xradio available for download from conda-forge directly is pending, so until then the current recommendation is to sully that pristine environment by calling pip [from within conda](https://www.anaconda.com/blog/using-pip-in-a-conda-environment), like this:
+XRADIO can now be installed using:
 ```sh
 pip install xradio
 ```
+This will also install the minimal dependencies for XRADIO. To install the minimal dependencies and the interactive components (JupyterLab) use:
+```sh
+pip install "xradio[interactive]"
+```