eolas-data 1.2.0__tar.gz → 1.3.0__tar.gz

{eolas_data-1.2.0 → eolas_data-1.3.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: eolas-data
-Version: 1.2.0
+Version: 1.3.0
 Summary: Python client for the eolas.fyi statistical data API (NZ, Australia, OECD)
 Project-URL: Homepage, https://eolas.fyi
-Project-URL: Documentation, https://phildonovan.github.io/vswarehouse-docs/
+Project-URL: Documentation, https://docs.eolas.fyi/
 Project-URL: Repository, https://github.com/phildonovan/eolas-data
 Project-URL: Bug Tracker, https://github.com/phildonovan/eolas-data/issues
 Author-email: Virtus Solutions <phil@virtus-solutions.io>
@@ -36,8 +36,6 @@ Requires-Dist: typer>=0.12; extra == 'dev'
 Provides-Extra: geo
 Requires-Dist: geopandas>=0.14; extra == 'geo'
 Requires-Dist: shapely>=2.0; extra == 'geo'
-Provides-Extra: plot
-Requires-Dist: matplotlib>=3.5; extra == 'plot'
 Provides-Extra: polars
 Requires-Dist: polars>=0.20; extra == 'polars'
 Description-Content-Type: text/markdown
@@ -168,13 +166,17 @@ df = client.get("nz_cpi", engine="polars")
 
 ## Plotting
 
-```bash
-pip install eolas-data[plot]
-```
+`Dataset` is a `pandas.DataFrame` subclass — use matplotlib / seaborn / plotly
+directly. No bundled plot helper, because there's no universal "right" plot for
+a tidy dataset (single-series time series vs. wide multi-measure vs. WKT
+geometry all need different code).
 
 ```python
+import matplotlib.pyplot as plt
+
 df = client.statsnz("nz_cpi")
-df.plot_dataset()
+df.plot(x="date", y="value")
+plt.show()
 ```
 
 ## Type stubs
@@ -198,7 +200,7 @@ The previous package name was `vswarehouse`. Direct equivalents:
 |---|---|
 | `from vswarehouse import Client, VSeries` | `from eolas_data import Client, Dataset` |
 | `df.vs_name`, `df.vs_source` | `df.eolas_name`, `df.eolas_source` |
-| `df.plot_series()` | `df.plot_dataset()` |
+| `df.plot_series()` | *(removed in v1.3.0 — use `df.plot(x="date", y="value")` directly; the helper silently mis-rendered datasets with multi-row dates)* |
 | `VS_API_KEY` env var | `EOLAS_API_KEY` (legacy `VS_API_KEY` still honoured) |
 
 The API surface is otherwise identical. The default base URL is now `https://api.eolas.fyi` (the old `https://api.virtus-solutions.io` still 301-redirects and works fine — but uses the legacy endpoint shape).

{eolas_data-1.2.0 → eolas_data-1.3.0}/README.md

@@ -124,13 +124,17 @@ df = client.get("nz_cpi", engine="polars")
 
 ## Plotting
 
-```bash
-pip install eolas-data[plot]
-```
+`Dataset` is a `pandas.DataFrame` subclass — use matplotlib / seaborn / plotly
+directly. No bundled plot helper, because there's no universal "right" plot for
+a tidy dataset (single-series time series vs. wide multi-measure vs. WKT
+geometry all need different code).
 
 ```python
+import matplotlib.pyplot as plt
+
 df = client.statsnz("nz_cpi")
-df.plot_dataset()
+df.plot(x="date", y="value")
+plt.show()
 ```
 
 ## Type stubs
@@ -154,7 +158,7 @@ The previous package name was `vswarehouse`. Direct equivalents:
 |---|---|
 | `from vswarehouse import Client, VSeries` | `from eolas_data import Client, Dataset` |
 | `df.vs_name`, `df.vs_source` | `df.eolas_name`, `df.eolas_source` |
-| `df.plot_series()` | `df.plot_dataset()` |
+| `df.plot_series()` | *(removed in v1.3.0 — use `df.plot(x="date", y="value")` directly; the helper silently mis-rendered datasets with multi-row dates)* |
 | `VS_API_KEY` env var | `EOLAS_API_KEY` (legacy `VS_API_KEY` still honoured) |
 
 The API surface is otherwise identical. The default base URL is now `https://api.eolas.fyi` (the old `https://api.virtus-solutions.io` still 301-redirects and works fine — but uses the legacy endpoint shape).

{eolas_data-1.2.0 → eolas_data-1.3.0}/eolas_data/cli.py

@@ -580,7 +580,7 @@ def integrate_meltano(
     json_out: bool          = typer.Option(False, "--json"),
     api_key:  Optional[str] = typer.Option(None, "--api-key"),
 ) -> None:
-    """Generate a Meltano project (uses `tap-rest-api-msdk`) for the chosen datasets."""
+    """[verified] Generate a Meltano project (uses `tap-rest-api-msdk`) for the chosen datasets."""
     _run_integration("meltano", datasets, output or _default_output_dir("meltano"),
                      force, api_key, json_out)
 
@@ -593,9 +593,20 @@ def integrate_fivetran(
     json_out: bool          = typer.Option(False, "--json"),
     api_key:  Optional[str] = typer.Option(None, "--api-key"),
 ) -> None:
-    """Generate a Fivetran Connector Builder YAML for the chosen datasets."""
+    """[experimental] Generate a Fivetran Connector Builder YAML for the chosen datasets.
+
+    Output is structure-verified (parses as YAML, has all the fields the spec
+    documents) but has not yet been end-to-end tested against a real Fivetran
+    Connector Builder import. If the import rejects with a schema error,
+    please share the error so the generator can be fixed.
+    """
     _run_integration("fivetran", datasets, output or _default_output_dir("fivetran"),
                      force, api_key, json_out)
+    if not _machine_mode(json_out):
+        err_console.print(
+            "[yellow]experimental:[/yellow] Fivetran output is structure-verified "
+            "but not yet end-to-end tested against a real account."
+        )
 
 
 @integrate_app.command("azure-data-factory")
@@ -606,10 +617,21 @@ def integrate_adf(
     json_out: bool          = typer.Option(False, "--json"),
     api_key:  Optional[str] = typer.Option(None, "--api-key"),
 ) -> None:
-    """Generate Azure Data Factory linked-service / dataset / pipeline JSON."""
+    """[experimental] Generate Azure Data Factory linked-service / dataset / pipeline JSON.
+
+    Output is structure-verified (linked-service references resolve, datasets
+    reference real linked services, pipeline activities reference real
+    datasets) but has not yet been end-to-end tested against a real Azure
+    subscription.
+    """
     _run_integration("azure-data-factory", datasets,
                      output or _default_output_dir("adf"),
                      force, api_key, json_out)
+    if not _machine_mode(json_out):
+        err_console.print(
+            "[yellow]experimental:[/yellow] Azure Data Factory output is "
+            "structure-verified but not yet end-to-end tested against a real subscription."
+        )
 
 
 # Allow `python -m eolas_data.cli`

{eolas_data-1.2.0 → eolas_data-1.3.0}/eolas_data/client.py

@@ -166,8 +166,14 @@ class Client:
         return self._get_source(name, "LINZ", **kwargs)
 
     def statsnz_geo(self, name, **kwargs) -> Dataset:
-        """Fetch a Stats NZ Geospatial dataset."""
-        return self._get_source(name, "Stats NZ Geospatial", **kwargs)
+        """Fetch a Stats NZ geospatial dataset (boundaries, census meshblocks, etc.).
+
+        Kept as a convenience helper for discoverability — the server returns
+        ``source = "Stats NZ"`` for both SDMX time series and Datafinder
+        geospatial datasets, so the metadata on the returned Dataset reads
+        ``"Stats NZ"`` (not ``"Stats NZ Geospatial"``).
+        """
+        return self._get_source(name, "Stats NZ", **kwargs)
 
     def mbie(self, name, **kwargs) -> Dataset:
         """Fetch an MBIE dataset."""

eolas_data-1.3.0/eolas_data/dataset.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import pandas as pd
+
+
+class Dataset(pd.DataFrame):
+    """A pandas DataFrame with eolas dataset metadata.
+
+    Behaves exactly like a DataFrame — all pandas operations work normally.
+    Extra attributes:
+        eolas_name:   Dataset identifier (e.g. ``"nz_cpi"``).
+        eolas_source: Data source label (e.g. ``"Stats NZ"``).
+    """
+
+    _metadata = ["eolas_name", "eolas_source"]
+
+    @property
+    def _constructor(self):
+        return Dataset
+
+    def __repr__(self) -> str:
+        name   = getattr(self, "eolas_name",   "") or ""
+        source = getattr(self, "eolas_source", "") or ""
+        if name:
+            header = f"# Dataset: {name}"
+            if source:
+                header += f" [{source}]"
+            header += f"\n# {len(self)} rows\n"
+            return header + pd.DataFrame.__repr__(self)
+        return pd.DataFrame.__repr__(self)
+
+    # ------------------------------------------------------------------
+    # plot_dataset() was removed in v1.3.0.
+    #
+    # It auto-picked `date` and `value` columns and drew a single matplotlib
+    # line — but datasets with a dimension column (multiple series per date)
+    # produced silent zigzag traces. Rather than ship a helper that has to
+    # know each dataset's shape, plotting is now the caller's responsibility.
+    # `Dataset` subclasses `DataFrame`, so any matplotlib / seaborn / plotly
+    # workflow works straight out of the box:
+    #
+    #     import matplotlib.pyplot as plt
+    #     df.plot(x="date", y="value")
+    #
+    # See README for one-liners.
+    # ------------------------------------------------------------------

{eolas_data-1.2.0 → eolas_data-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "eolas-data"
-version = "1.2.0"
+version = "1.3.0"
 description = "Python client for the eolas.fyi statistical data API (NZ, Australia, OECD)"
 readme = "README.md"
 license = { text = "MIT" }
@@ -30,14 +30,13 @@ classifiers = [
 
 [project.urls]
 Homepage = "https://eolas.fyi"
-Documentation = "https://phildonovan.github.io/vswarehouse-docs/"
+Documentation = "https://docs.eolas.fyi/"
 Repository = "https://github.com/phildonovan/eolas-data"
 "Bug Tracker" = "https://github.com/phildonovan/eolas-data/issues"
 
 [project.optional-dependencies]
 dev = ["pytest", "responses", "pandas", "geopandas>=0.14", "shapely>=2.0", "typer>=0.12", "rich>=13"]
 polars = ["polars>=0.20"]
-plot = ["matplotlib>=3.5"]
 geo = ["geopandas>=0.14", "shapely>=2.0"]
 cli = ["typer>=0.12", "rich>=13"]
 

eolas_data-1.2.0/eolas_data/dataset.py

@@ -1,66 +0,0 @@
-from __future__ import annotations
-
-import pandas as pd
-
-
-class Dataset(pd.DataFrame):
-    """A pandas DataFrame with eolas dataset metadata.
-
-    Behaves exactly like a DataFrame — all pandas operations work normally.
-    Extra attributes:
-        eolas_name:   Dataset identifier (e.g. ``"nz_cpi"``).
-        eolas_source: Data source label (e.g. ``"Stats NZ"``).
-    """
-
-    _metadata = ["eolas_name", "eolas_source"]
-
-    @property
-    def _constructor(self):
-        return Dataset
-
-    def __repr__(self) -> str:
-        name   = getattr(self, "eolas_name",   "") or ""
-        source = getattr(self, "eolas_source", "") or ""
-        if name:
-            header = f"# Dataset: {name}"
-            if source:
-                header += f" [{source}]"
-            header += f"\n# {len(self)} rows\n"
-            return header + pd.DataFrame.__repr__(self)
-        return pd.DataFrame.__repr__(self)
-
-    def plot_dataset(self, ax=None, **kwargs):
-        """Quick line chart using matplotlib.
-
-        Returns the matplotlib Axes object so you can customise further.
-        Requires matplotlib: ``pip install eolas-data[plot]``.
-        """
-        try:
-            import matplotlib.pyplot as plt
-        except ImportError:
-            raise ImportError(
-                "matplotlib is required for plot_dataset(). "
-                "Install with: pip install eolas-data[plot]"
-            )
-
-        date_col  = "date"  if "date"  in self.columns else self.columns[0]
-        value_col = "value" if "value" in self.columns else self.columns[1]
-
-        if ax is None:
-            _, ax = plt.subplots(figsize=(10, 4))
-
-        ax.plot(self[date_col], self[value_col], color="#2563eb", linewidth=1.5, **kwargs)
-
-        name   = getattr(self, "eolas_name",   "") or ""
-        source = getattr(self, "eolas_source", "") or ""
-
-        if name:
-            ax.set_title(name, fontweight="bold", fontsize=13)
-        ax.set_xlabel("")
-        ax.spines[["top", "right"]].set_visible(False)
-
-        caption = f"Source: {source} · eolas.fyi" if source else "eolas.fyi"
-        ax.figure.text(0.99, 0.01, caption, ha="right", fontsize=8, color="#9ca3af")
-
-        plt.tight_layout()
-        return ax