xconv2 0.1.0a1__tar.gz

xconv2-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NCAS University of Reading
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xconv2-0.1.0a1/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: xconv2
+Version: 0.1.0a1
+Summary: High-performance data viewer and simple data converter
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: PySide6
+Requires-Dist: superqt
+Requires-Dist: cf-python
+Requires-Dist: cf-plot
+Requires-Dist: zarr
+Requires-Dist: pandas
+Requires-Dist: setuptools>80
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file

xconv2-0.1.0a1/README.md

@@ -0,0 +1,46 @@
+# xconv2
+
+xconv2 provides (or will provide) a graphical interface to local and remote weather and climate data.  It is a replacement for the venerable [xconv](https://ncas-cms.github.io/xconv-doc/html/index.html) package that has been supported by NCAS CMS for decades.
+
+<table>
+  <tr>
+    <td style="vertical-align: middle; padding: 2px;">
+      <img src="xconv2/assets/under-construction.svg" alt="Under construction icon" height="128px" />
+    </td>
+    <td style="vertical-align: middle;">
+      This version is under development. If you encounter something that looks like it should work, but doesn't, please
+      raise a bug issue at the address found in the About menu. If there is function that you would like to see, feel
+      free to raise an enhancement request at the same location.
+    </td>
+  </tr>
+</table>
+
+## Installation
+
+We intend to release this as a standalone executable for linux and macos, but for the moment you should use a Python 3.12 (or later) environment with
+udunits2 installed, then you can pip install from the source using one of these:
+
+`pip install "git+https://github.com/ncas-cms/xconv2.git"`
+`pip install "git+ssh://github.com/ncas-cms/xconv2.git"`
+
+and then you should have `xconv2` available on your command line.
+
+## Documentation
+
+No user documentation is yet available, but it is designed to be intuitive
+and basic usage should be possible without documentation once it is installed.
+
+### Developer Documentation
+
+Limited developer documentation is available. For the moment it is
+limited to the following:
+
+#### UML Diagrams
+
+- `docs/uml/alpha_core_window.puml`
+- `docs/uml/core_window_gui_worker_signals.puml`
+- `docs/uml/core_window_options_sequence.puml`
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE`.

xconv2-0.1.0a1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xconv2"
+version = "0.1.0a1"
+description = "High-performance data viewer and simple data converter"
+requires-python = ">=3.12"
+dependencies = [
+    "PySide6",
+    "superqt",
+    "cf-python",
+    "cf-plot",
+    "zarr",
+    "pandas",
+    "setuptools>80",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+]
+
+[project.gui-scripts]
+# This creates an 'xconv2' command that launches your GUI
+xconv2 = "xconv2.gui:main"
+
+[project.scripts]
+# This creates a 'cf-worker' command for the backend process
+cf-worker = "xconv2.worker:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["xconv2*"]
+
+[tool.setuptools.package-data]
+xconv2 = ["assets/*.svg", "assets/*.png"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

xconv2-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xconv2-0.1.0a1/tests/test_cf_interface.py

@@ -0,0 +1,352 @@
+from __future__ import annotations
+
+import pytest
+import xconv2.xconv_cf_interface as cf_interface
+
+from xconv2.xconv_cf_interface import (
+    auto_contour_title,
+    coordinate_info,
+    field_info,
+    get_data_for_plotting,
+    run_contour_plot,
+    run_line_plot,
+)
+
+import numpy as np
+
+
+cf = pytest.importorskip("cf")
+
+
+class _MockCellMeasures:
+    def __call__(self) -> str:
+        return "cell_measures: area: areacella"
+
+
+class _MockField:
+    shape = (2, 3)
+
+    def __str__(self) -> str:
+        return "mock-field-summary"
+
+    def identity(self) -> str:
+        return "air_temperature"
+
+    def properties(self) -> dict[str, str]:
+        return {"units": "K", "standard_name": "air_temperature"}
+
+    def coordinates(self) -> dict[str, str]:
+        return {
+            "dimensioncoordinate0": "Dimension coordinate: latitude(2) degrees_north",
+            "dimensioncoordinate1": "Dimension coordinate: longitude(3) degrees_east",
+        }
+
+    def cell_methods(self) -> str:
+        return ""
+
+    def cell_measures(self) -> str:
+        return _MockCellMeasures()()
+
+
+def test_field_info_returns_serialized_rows() -> None:
+    payload = field_info([_MockField()])
+
+    assert isinstance(payload, list)
+    assert len(payload) == 1
+    assert isinstance(payload[0], str)
+
+    parts = payload[0].split("\x1f", 2)
+    assert len(parts) == 3
+    assert parts[0].startswith("air_temperature")
+    assert parts[1] == "mock-field-summary"
+    assert "units" in parts[2]
+
+
+class _MockCoord:
+    def __init__(self, name: str, values: list[object]) -> None:
+        self._name = name
+        self.array = values
+
+    def identity(self, default: str = "unknown") -> str:
+        return self._name or default
+
+
+class _MockCoordField:
+    def __init__(self) -> None:
+        self._coords = {
+            "time": _MockCoord("time", [1, 2, 3]),
+            "height": _MockCoord("height", [10]),
+            "lat": _MockCoord("latitude", [-90, 0, 90]),
+        }
+
+    def dimension_coordinates(self, **kwargs) -> list[str]:
+        return self._coords
+
+    def coordinate(self, key: str) -> _MockCoord:
+        return self._coords[key]
+
+
+def test_coordinate_info_filters_singletons_and_serializes_values() -> None:
+    payload = coordinate_info(_MockCoordField())
+
+    assert payload == [
+        ("time", ["1", "2", "3"], ""),
+        ("latitude", ["-90", "0", "90"], ""),
+    ]
+
+
+class _FakePlotField:
+    def __init__(self) -> None:
+        self.kwargs: dict[str, object] | None = None
+        self.collapse_calls: list[tuple[str, str, bool]] = []
+
+    def subspace(self, **kwargs: object) -> "_FakePlotField":
+        self.kwargs = kwargs
+        return self
+
+    def dimension_coordinate(self, coord_name) -> None:
+        return np.array([0.0, 1.0])
+
+    def collapse(self, instruction: str, weights: bool = False) -> "_FakePlotField":
+        self.collapse_calls.append((instruction, weights))
+        return self
+
+
+def test_get_data_for_plotting_builds_subspace_kwargs() -> None:
+    fld = _FakePlotField()
+
+    pfld = get_data_for_plotting(
+        fld,
+        {
+            "time": ("3", "1"),
+            "level": ("850", "850"),
+            "name": ("foo", "foo"),
+        },
+        {"time": "mean", "name": "max"},
+    )
+
+    assert pfld is fld
+    assert fld.kwargs is not None
+    assert fld.kwargs["level"] == 850
+    assert fld.kwargs["name"] == "foo"
+    assert str(fld.kwargs["time"]) == str(cf.wi(1, 3))
+    assert fld.collapse_calls == [
+        ("time: mean name: max", True),
+    ]
+
+
+class _FakeCFPlot:
+    def __init__(self) -> None:
+        self.levs_calls: list[dict[str, object]] = []
+        self.con_calls: list[dict[str, object]] = []
+        self.lineplot_calls: list[dict[str, object]] = []
+        self.cscale_calls: list[dict[str, object]] = []
+        self.gopen_calls: list[dict[str, object]] = []
+        self.setvars_calls: list[dict[str, object]] = []
+        self.gclose_calls = 0
+
+    def levs(self, **kwargs: object) -> None:
+        self.levs_calls.append(kwargs)
+
+    def con(self, _field: object, **kwargs: object) -> None:
+        self.con_calls.append(kwargs)
+
+    def lineplot(self, _field: object, **kwargs: object) -> None:
+        self.lineplot_calls.append(kwargs)
+
+    def cscale(self, **kwargs: object) -> None:
+        self.cscale_calls.append(kwargs)
+
+    def gopen(self, file: str = "cfplot.png", **kwargs: object) -> None:
+        payload: dict[str, object] = {"file": file}
+        payload.update(kwargs)
+        self.gopen_calls.append(payload)
+
+    def setvars(self, **kwargs: object) -> None:
+        self.setvars_calls.append(kwargs)
+
+    def gclose(self) -> None:
+        self.gclose_calls += 1
+
+
+class _FakeFigure:
+    def __init__(self) -> None:
+        self.text_calls: list[tuple[tuple[object, ...], dict[str, object]]] = []
+        self.suptitle_calls: list[tuple[tuple[object, ...], dict[str, object]]] = []
+
+    def text(self, *args: object, **kwargs: object) -> None:
+        self.text_calls.append((args, kwargs))
+
+    def suptitle(self, *args: object, **kwargs: object) -> None:
+        self.suptitle_calls.append((args, kwargs))
+
+
+class _FakePlt:
+    def __init__(self) -> None:
+        self.figure = _FakeFigure()
+
+    def gcf(self) -> _FakeFigure:
+        return self.figure
+
+
+def test_run_contour_plot_applies_levels_annotations_and_save(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    cfp = _FakeCFPlot()
+    plt_obj = _FakePlt()
+
+    monkeypatch.setattr(cf_interface, "cfp", cfp)
+    monkeypatch.setattr(cf_interface, "plt", plt_obj)
+
+    run_contour_plot(
+        pfld=object(),
+        options={
+            "mode": "explicit",
+            "levels": [-1.0, 0.0, 1.0],
+            "cscale": "magma",
+            "filename": "/tmp/mock.png",
+            "annotation_display": True,
+            "annotation_properties": [("units", "K")],
+        },
+    )
+
+    assert cfp.cscale_calls == [{"scale": "magma"}]
+    assert cfp.gopen_calls == [{"file": "/tmp/mock.png"}]
+    assert cfp.levs_calls == [{"manual": [-1.0, 0.0, 1.0]}]
+    assert cfp.setvars_calls == [{"title_fontsize": 10.5}]
+    assert cfp.con_calls
+    assert cfp.gclose_calls == 1
+    assert plt_obj.figure.text_calls
+    assert plt_obj.figure.text_calls[-1][1]["fontsize"] == 8.0
+
+
+def test_run_contour_plot_uses_configured_title_font_sizes(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    cfp = _FakeCFPlot()
+    plt_obj = _FakePlt()
+
+    monkeypatch.setattr(cf_interface, "cfp", cfp)
+    monkeypatch.setattr(cf_interface, "plt", plt_obj)
+
+    run_contour_plot(
+        pfld=object(),
+        options={
+            "mode": "default",
+            "page_title": "Overview",
+            "page_title_display": True,
+            "annotation_display": True,
+            "annotation_properties": [("units", "K")],
+            "contour_title_fontsize": 12.5,
+            "page_title_fontsize": 14.0,
+            "annotation_fontsize": 9.5,
+        },
+    )
+
+    assert cfp.setvars_calls == [{"title_fontsize": 12.5}]
+    assert plt_obj.figure.suptitle_calls == [
+        (("Overview",), {"y": 0.995, "fontsize": 14.0})
+    ]
+    assert plt_obj.figure.text_calls == [
+        ((0.5, 0.02, "units: K"), {"ha": "center", "va": "bottom", "fontsize": 9.5})
+    ]
+
+
+def test_run_contour_plot_sets_title_from_singleton_selection(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    cfp = _FakeCFPlot()
+    plt_obj = _FakePlt()
+
+    monkeypatch.setattr(cf_interface, "cfp", cfp)
+    monkeypatch.setattr(cf_interface, "plt", plt_obj)
+
+    run_contour_plot(
+        pfld=object(),
+        options={"mode": "default"},
+        selection_spec={"time": ("2000-01-01", "2000-01-01"), "lat": ("-90", "90")},
+        collapse_by_coord={},
+    )
+
+    assert cfp.gopen_calls == [{"file": "cfplot.png", "user_plot": 1}]
+    assert cfp.con_calls
+    assert cfp.con_calls[-1]["title"] == "time=2000-01-01"
+
+
+def test_run_contour_plot_prefers_cell_method_title_for_collapses(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    cfp = _FakeCFPlot()
+    plt_obj = _FakePlt()
+
+    monkeypatch.setattr(cf_interface, "cfp", cfp)
+    monkeypatch.setattr(cf_interface, "plt", plt_obj)
+    monkeypatch.setattr(cf_interface, "cell_methods_string_from_field", lambda _field, *args: "time: mean")
+
+    run_contour_plot(
+        pfld=object(),
+        options={"mode": "default"},
+        selection_spec={"time": ("2000-01-01", "2000-12-31")},
+        collapse_by_coord={"time": "mean"},
+    )
+
+    assert cfp.con_calls
+    assert cfp.con_calls[-1]["title"] == "time: mean"
+
+
+def test_auto_contour_title_from_singleton_selection() -> None:
+    title = auto_contour_title(
+        pfld=object(),
+        selection_spec={"time": ("2001-01-01", "2001-01-01"), "lat": ("-90", "90")},
+        collapse_by_coord={},
+    )
+    assert title == "time=2001-01-01"
+
+
+def test_auto_contour_title_prefers_cell_method_for_collapse(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(cf_interface, "cell_methods_string_from_field", lambda _field, *args: "time: mean")
+    title = auto_contour_title(
+        pfld=object(),
+        selection_spec={"time": ("2001-01-01", "2001-12-31")},
+        collapse_by_coord={"time": "mean"},
+    )
+    assert title == "time: mean"
+
+
+def test_run_line_plot_uses_canonical_axes_and_wraps_file_output() -> None:
+    field_eg = object()
+    monkeypatch = pytest.MonkeyPatch()
+
+    captured: dict[str, object] = {}
+
+    class _FakeLinePlot:
+        def __init__(
+                self,
+                pfld: object,
+                options: dict[str, object] | None,
+                collapse_by_coord: dict[str, str] | None
+        ) -> None:
+            captured["pfld"] = pfld
+            captured["options"] = options
+
+        def render(self) -> None:
+            captured["rendered"] = True
+
+    monkeypatch.setattr(cf_interface, "LinePlot", _FakeLinePlot)
+
+    try:
+        run_line_plot(
+            pfld=field_eg,
+            options={"filename": "/tmp/line.png", "title": "line"},
+            selection_spec={"time": ("1", "2")},
+            collapse_by_coord={},
+        )
+    finally:
+        monkeypatch.undo()
+
+    assert captured["pfld"] is field_eg
+    assert captured["options"] == {"filename": "/tmp/line.png", "title": "line"}
+    assert captured["rendered"] is True
+