pysits 2.0.0.dev7__tar.gz → 2.0.0.dev9__tar.gz

{pysits-2.0.0.dev7 → pysits-2.0.0.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pysits
-Version: 2.0.0.dev7
+Version: 2.0.0.dev9
 Summary: Python wrapper for the sits R package
 Project-URL: Homepage, https://github.com/e-sensing/pysits
 Project-URL: Issue Tracker, https://github.com/e-sensing/pysits/issues
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: GIS
 Requires-Python: <4,>=3.10
 Requires-Dist: geopandas>=1.1.0
+Requires-Dist: httpx2>=2.13.0
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: matplotlib>=3.10.1
 Requires-Dist: pandas>=2.2.3

{pysits-2.0.0.dev7 → pysits-2.0.0.dev9}/pyproject.toml

@@ -17,7 +17,7 @@
 
 [project]
 name = "pysits"
-version = "2.0.0.dev7"
+version = "2.0.0.dev9"
 description = "Python wrapper for the sits R package"
 readme = "README.md"
 requires-python = ">=3.10,<4"
@@ -71,6 +71,7 @@ dependencies = [
     "shapely>=2.1.1",
     "pyarrow>=20.0.0",
     "jinja2>=3.1.6",
+    "httpx2>=2.13.0",
 ]
 
 [project.urls]

{pysits-2.0.0.dev7 → pysits-2.0.0.dev9}/pysits/__init__.py

@@ -87,8 +87,10 @@ from .sits.data import sits_summary as summary
 from .sits.exporters import (
     sits_as_geopandas,
     sits_as_xarray,
+    sits_from_parquet,
     sits_timeseries_to_csv,
     sits_to_csv,
+    sits_to_parquet,
     sits_to_xlsx,
 )
 from .sits.impute import (
@@ -276,6 +278,8 @@ __all__ = (
     "sits_as_geopandas",
     "sits_to_xlsx",
     "sits_timeseries_to_csv",
+    "sits_to_parquet",
+    "sits_from_parquet",
     # Tuning
     "sits_tuning_hparams",
     "sits_tuning",

pysits-2.0.0.dev9/pysits/docs/content/sits_from_parquet.md

@@ -0,0 +1,26 @@
+Read sits time series from the Parquet format
+
+Reads a file written by `sits_to_parquet` and rebuilds the time series,
+with its class, column order and nested series.
+
+Files written by other programs are also read. Their class is then
+inferred from the columns, which must include "longitude", "latitude",
+"start_date", "end_date" and "label".
+
+Args:
+    file (str | pathlib.Path): Full path or HTTP(S) URL of the file to
+        read (valid file name with extension ".parquet").
+
+Returns:
+    SITSTimeSeriesModel: Time series.
+
+Raises:
+    httpx2.HTTPError: If a remote file cannot be downloaded.
+
+Examples:
+    import tempfile
+    from pysits import *
+
+    parquet_file = tempfile.gettempdir() + "/samples.parquet"
+    sits_to_parquet(samples_modis_ndvi, file=parquet_file)
+    samples = sits_from_parquet(parquet_file)

pysits-2.0.0.dev9/pysits/docs/content/sits_to_parquet.md

@@ -0,0 +1,23 @@
+Export sits time series to the Parquet format
+
+Writes a set of time series to a Parquet file. The layout is long: one
+row per sample and date, with the time series as plain columns. The
+file metadata keeps what is needed to rebuild the data with
+`sits_from_parquet` (class, column order and bands). It also follows
+GeoParquet 1.1, so tools like GDAL and QGIS read the file as points.
+
+Args:
+    data (SITSTimeSeriesModel): Time series.
+
+    file (str | pathlib.Path): Full path of the exported file (valid
+        file name with extension ".parquet").
+
+Returns:
+    None
+
+Examples:
+    import tempfile
+    from pysits import *
+
+    parquet_file = tempfile.gettempdir() + "/samples.parquet"
+    sits_to_parquet(samples_modis_ndvi, file=parquet_file)

pysits-2.0.0.dev9/pysits/network.py

@@ -0,0 +1,100 @@
+#
+# Copyright (C) 2025 sits developers.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+
+"""Network operations."""
+
+import os
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from urllib.parse import urlparse
+
+import httpx2
+
+#
+# Supported URL schemes
+#
+REMOTE_SCHEMES = ("http", "https")
+
+
+#
+# Auxiliary functions
+#
+def is_remote(location: str | Path) -> bool:
+    """Check if a location points to a remote resource.
+
+    Args:
+        location (str | Path): File location (local path or URL).
+
+    Returns:
+        bool: ``True`` when ``location`` is an URL with a supported scheme.
+
+    Notes:
+        - Supported schemes are ``http`` and ``https``.
+    """
+    return urlparse(str(location)).scheme in REMOTE_SCHEMES
+
+
+#
+# File management
+#
+@contextmanager
+def fetch_to_tempfile(url: str, *, suffix: str = "") -> Iterator[Path]:
+    """Download a remote file to a temporary file.
+
+    Args:
+        url (str): File URL.
+
+        suffix (str): Suffix for the temporary file name.
+
+    Yields:
+        Path: Path of the downloaded file.
+
+    Raises:
+        httpx2.HTTPError: If the file cannot be downloaded.
+
+    Notes:
+        - The temporary file is removed when the context exits, including
+        when the download fails or the caller raises.
+    """
+    # Create a temporary file
+    descriptor, name = tempfile.mkstemp(suffix=suffix)
+
+    # Name as path
+    local_file = Path(name)
+
+    # Try to download the file
+    try:
+        # Open the stream in binary mode
+        with os.fdopen(descriptor, "wb") as stream:
+            # Enable redirects to facilitate operations on remote files
+            # stored in systems like huggingface and similar platforms.
+            with httpx2.stream("GET", url, follow_redirects=True) as response:
+                # Raise an exception if the response is not successful
+                response.raise_for_status()
+
+                # Write the content to the temporary file
+                for chunk in response.iter_bytes():
+                    stream.write(chunk)
+
+        # Yield the path to the temporary file
+        yield local_file
+
+    finally:
+        # Remove the temporary file
+        local_file.unlink(missing_ok=True)

{pysits-2.0.0.dev7 → pysits-2.0.0.dev9}/pysits/sits/exporters/__init__.py

@@ -17,7 +17,13 @@
 
 """Exporters module."""
 
-from .files import sits_timeseries_to_csv, sits_to_csv, sits_to_xlsx
+from .files import (
+    sits_from_parquet,
+    sits_timeseries_to_csv,
+    sits_to_csv,
+    sits_to_parquet,
+    sits_to_xlsx,
+)
 from .sf import sits_as_geopandas
 from .xarray import sits_as_xarray
 
@@ -27,4 +33,6 @@ __all__ = (
     "sits_to_csv",
     "sits_to_xlsx",
     "sits_timeseries_to_csv",
+    "sits_to_parquet",
+    "sits_from_parquet",
 )

{pysits-2.0.0.dev7 → pysits-2.0.0.dev9}/pysits/sits/exporters/files.py

@@ -17,10 +17,15 @@
 
 """Files exporter."""
 
+from pathlib import Path
+
 from pysits.backend.pkgs import r_pkg_sits
 from pysits.conversions.decorators import function_call
 from pysits.docs import attach_doc
 from pysits.models.data.frame import SITSFrame
+from pysits.models.data.ts import SITSTimeSeriesModel
+from pysits.models.resolver import resolve_and_invoke_content_class
+from pysits.network import fetch_to_tempfile, is_remote
 
 
 @function_call(r_pkg_sits.sits_to_csv, SITSFrame)
@@ -41,3 +46,28 @@ def sits_to_xlsx(*args, **kwargs) -> None:
 @attach_doc("sits_timeseries_to_csv")
 def sits_timeseries_to_csv(*args, **kwargs) -> None:
     """Export a full sits timeseries to CSV format."""
+
+
+@function_call(r_pkg_sits.sits_to_parquet, lambda x: None)
+@attach_doc("sits_to_parquet")
+def sits_to_parquet(*args, **kwargs) -> None:
+    """Export sits time series to the Parquet format."""
+
+
+@function_call(r_pkg_sits.sits_from_parquet, resolve_and_invoke_content_class)
+def _sits_from_parquet(*args, **kwargs) -> SITSTimeSeriesModel:
+    """Read sits time series from a local Parquet file."""
+
+
+@attach_doc("sits_from_parquet")
+def sits_from_parquet(file: str | Path) -> SITSTimeSeriesModel:
+    """Read sits time series from the Parquet format."""
+    # If file is remote
+    if is_remote(file):
+        # Download it to a temporary file
+        with fetch_to_tempfile(str(file), suffix=".parquet") as local_file:
+            # Read it
+            return _sits_from_parquet(local_file)
+
+    # Otherwise, read it directly
+    return _sits_from_parquet(file)

{pysits-2.0.0.dev7 → pysits-2.0.0.dev9}/pysits/sits/ml.py

@@ -84,7 +84,9 @@ sits_lightgbm = closure_factory("sits_lightgbm")
 sits_ssl_mae = closure_factory("sits_ssl_mae", converters=dl_converters)
 sits_ssl_lejepa = closure_factory("sits_ssl_lejepa", converters=dl_converters)
 sits_ssl_vicreg = closure_factory("sits_ssl_vicreg", converters=dl_converters)
-sits_ssl_barlow_twins = closure_factory("sits_ssl_barlow_twins", converters=dl_converters)
+sits_ssl_barlow_twins = closure_factory(
+    "sits_ssl_barlow_twins", converters=dl_converters
+)
 
 sits_barlow_twins = closure_factory("sits_barlow_twins", converters=dl_converters)
 sits_contrastive_learning = closure_factory(

{pysits-2.0.0.dev7 → pysits-2.0.0.dev9}/pysits/sits/utils.py

@@ -27,6 +27,7 @@ from pysits.models.resolver import (
     resolve_and_invoke_accuracy_class,
     resolve_and_invoke_content_class,
 )
+from pysits.network import fetch_to_tempfile, is_remote
 
 #
 # Data class resolver
@@ -56,19 +57,41 @@ def read_rds(file: str | Path) -> SITSFrame:
     """Read RDS file compatible with SITS.
 
     Args:
-        file (str | Path): RDS file.
+        file (str | Path): RDS file. It can be a local path or an HTTP(S) URL.
 
     Returns:
         SITSFrame: SITS Data instance (can be a ``cube`` or a ``time-series`` object).
-    """
-    file = Path(file)
 
-    # Check if file exists
-    if not file.exists():
-        raise FileNotFoundError("Failed to read RDS: File does not exist.")
+    Raises:
+        FileNotFoundError: If a local RDS file does not exist. A missing
+                           remote file is reported by ``httpx2`` instead,
+                           as an ``HTTPStatusError``.
+
+        httpx2.HTTPError: If a remote RDS file cannot be downloaded.
 
-    # Read RDS
-    rds_content = r_fnc_read_rds(file.as_posix())
+        ValueError: If the RDS file has an object not supported by sits.
+    """
+    # If is remote file, we download it
+    if is_remote(file):
+        # Remote files are downloaded before being read. In R, it is possible
+        # to read RDS straight from an ``url`` connection, but that only works
+        # when the content is gzipped: the other compressions ``saveRDS`` produces
+        # (``xz`` and ``bzip2``) are rejected when read this way.
+        # So we download the file to a temporary file and read it from there to avoid
+        # this issue.
+        with fetch_to_tempfile(str(file), suffix=".rds") as local_file:
+            # Download and read content!
+            rds_content = r_fnc_read_rds(local_file.as_posix())
+
+    else:
+        file = Path(file)
+
+        # Check if file exists
+        if not file.exists():
+            raise FileNotFoundError("Failed to read RDS: File does not exist.")
+
+        # Read RDS
+        rds_content = r_fnc_read_rds(file.as_posix())
 
     # Resolve and invoke data class
     for resolver in RDS_RESOLVERS:

{pysits-2.0.0.dev7 → pysits-2.0.0.dev9}/tests/conftest.py

@@ -25,6 +25,10 @@ import os
 os.environ.setdefault("MPLBACKEND", "Agg")
 
 import webbrowser
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from threading import Thread
 from typing import Any
 
 import matplotlib
@@ -36,6 +40,11 @@ from pysits.sits.cube import sits_cube
 from pysits.sits.utils import r_package_dir
 from pysits.visualization.options import reset_plot_options
 
+#
+# Path prefix the test server answers with a redirect
+#
+REDIRECT_PREFIX = "/redirect/"
+
 
 #
 # Helpers
@@ -107,3 +116,45 @@ def no_browser(monkeypatch):
     monkeypatch.setattr(webbrowser, "open_new_tab", lambda x: None)
 
     yield
+
+
+class _RedirectingRequestHandler(SimpleHTTPRequestHandler):
+    """Serve a directory with a redirect."""
+
+    def do_GET(self) -> None:  # noqa: N802 (name defined by the base class)
+        # If path starts with a given prefix, simulate a redirect
+        if self.path.startswith(REDIRECT_PREFIX):
+            # Simulate a redirect
+            self.send_response(302)
+            self.send_header("Location", self.path[len(REDIRECT_PREFIX) - 1 :])
+            self.end_headers()
+
+            return
+
+        super().do_GET()
+
+    def log_message(self, *args, **kwargs) -> None:
+        """Keep the per-request log out of the test output."""
+
+
+@pytest.fixture
+def http_server(tmp_path: Path):
+    """HTTP server serving a directory with a redirect."""
+    handler = partial(
+        _RedirectingRequestHandler,
+        directory=str(tmp_path),
+    )
+    server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
+
+    # Start the server in a daemon thread
+    thread = Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+
+    # Yield the directory and its base URL
+    try:
+        yield tmp_path, f"http://127.0.0.1:{server.server_port}"
+
+    # Shutdown the server
+    finally:
+        server.shutdown()
+        server.server_close()

{pysits-2.0.0.dev7 → pysits-2.0.0.dev9}/tests/test_exporters.py

@@ -25,8 +25,15 @@ import pytest
 from pysits.backend.pkgs import r_pkg_sits
 from pysits.models.data.frame import SITSFrame
 from pysits.models.data.matrix import SITSConfusionMatrix
+from pysits.models.data.ts import SITSTimeSeriesModel
 from pysits.sits.context import cerrado_2classes
-from pysits.sits.exporters import sits_timeseries_to_csv, sits_to_csv, sits_to_xlsx
+from pysits.sits.exporters import (
+    sits_from_parquet,
+    sits_timeseries_to_csv,
+    sits_to_csv,
+    sits_to_parquet,
+    sits_to_xlsx,
+)
 from pysits.sits.ml import sits_rfor
 from pysits.sits.ts import sits_sample, sits_validate
 
@@ -94,3 +101,46 @@ def test_sits_to_xlsx(tmp_path: Path, accuracy):
     r_pkg_sits.sits_to_xlsx(accuracy._instance, file=str(r_file))
 
     assert read_xlsx(py_file) == read_xlsx(r_file)
+
+
+def test_sits_parquet(tmp_path: Path):
+    """Test time series export / import using parquet."""
+    # local file
+    file = tmp_path / "samples.parquet"
+
+    # export samples as parquet
+    sits_to_parquet(cerrado_2classes, file=file)
+
+    # import samples from parquet
+    samples = sits_from_parquet(file)
+
+    # samples must be a time series model
+    assert isinstance(samples, SITSTimeSeriesModel)
+
+    # metadata and nested series must be equal to the original samples
+    metadata = samples.drop(columns="time_series")
+    expected = cerrado_2classes.drop(columns="time_series")
+
+    assert metadata.equals(expected)
+    assert all(
+        ts.equals(expected_ts)
+        for ts, expected_ts in zip(
+            samples["time_series"], cerrado_2classes["time_series"], strict=True
+        )
+    )
+
+
+def test_sits_from_parquet_remote(http_server):
+    """Test time series import using remote parquet file."""
+    # remote file
+    directory, base_url = http_server
+
+    # export samples as parquet
+    sits_to_parquet(cerrado_2classes, file=directory / "samples.parquet")
+
+    # import samples from parquet
+    samples = sits_from_parquet(f"{base_url}/samples.parquet")
+
+    # samples must be a time series model
+    assert isinstance(samples, SITSTimeSeriesModel)
+    assert len(samples) == len(cerrado_2classes)

pysits-2.0.0.dev9/tests/test_network.py

@@ -0,0 +1,160 @@
+#
+# Copyright (C) 2025 sits developers.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
+#
+
+"""Unit tests for network operations."""
+
+import socket
+import tempfile
+from pathlib import Path
+from threading import Thread
+
+import httpx2
+import pytest
+
+from pysits.network import fetch_to_tempfile, is_remote
+
+
+#
+# Auxiliary functions
+#
+def temporary_files() -> set[Path]:
+    """List the files currently in the temporary directory."""
+    return set(Path(tempfile.gettempdir()).iterdir())
+
+
+#
+# Fixtures
+#
+@pytest.fixture
+def raw_server():
+    """HTTP Server."""
+    server_sockets = []
+
+    def start(response: bytes) -> str:
+        """Start the HTTP server."""
+        # Create a socket and bind it to a random port
+        server_socket = socket.socket()
+        server_socket.bind(("127.0.0.1", 0))
+        server_socket.listen(1)
+        server_sockets.append(server_socket)
+
+        # Start a thread to serve the response
+        def serve() -> None:
+            try:
+                connection, _ = server_socket.accept()
+                connection.recv(4096)
+                connection.sendall(response)
+                connection.close()
+
+            except OSError:
+                pass
+
+        # Start the thread
+        Thread(target=serve, daemon=True).start()
+
+        # Return the URL of the server
+        return f"http://127.0.0.1:{server_socket.getsockname()[1]}/samples.rds"
+
+    yield start
+
+    for server_socket in server_sockets:
+        server_socket.close()
+
+
+#
+# Tests
+#
+@pytest.mark.parametrize(
+    ("location", "expected"),
+    [
+        ("https://example.org/samples.rds", True),
+        ("http://example.org/samples.rds", True),
+        ("/data/samples.rds", False),
+        ("/home/user/samples.rds", False),
+        # Note: ``urlparse`` reads the drive letter as the scheme,
+        # so a Windows path must not be mistaken for a remote location
+        (r"C:\data\samples.rds", False),
+    ],
+)
+def test_is_remote(location: str, expected: bool):
+    """Test remote location identification."""
+    assert is_remote(location) is expected
+
+
+def test_fetch_to_tempfile_downloads_and_cleans_up(http_server):
+    """Test remote content download."""
+    directory, base_url = http_server
+
+    # Save payload
+    samples_file_local = directory / "samples.rds"
+    samples_file_local.write_bytes(b"sits-payload")
+
+    # Fetch the file
+    samples_file_remote = f"{base_url}/samples.rds"
+
+    with fetch_to_tempfile(samples_file_remote, suffix=".rds") as local_file:
+        assert local_file.read_bytes() == b"sits-payload"
+
+    # Check the file is deleted
+    assert not local_file.exists()
+
+
+def test_fetch_to_tempfile_follows_redirects(http_server):
+    """Test redirect following."""
+    directory, base_url = http_server
+
+    # Save payload
+    samples_file_local = directory / "samples.rds"
+    samples_file_local.write_bytes(b"sits-payload")
+
+    # Fetch the file
+    samples_file_remote = f"{base_url}/redirect/samples.rds"
+
+    with fetch_to_tempfile(samples_file_remote, suffix=".rds") as local_file:
+        assert local_file.read_bytes() == b"sits-payload"
+
+
+def test_fetch_to_tempfile_rejects_error_status(http_server):
+    """Test error response handling."""
+    _, base_url = http_server
+
+    # Save payload
+    before = temporary_files()
+
+    # Fetch file
+    with pytest.raises(httpx2.HTTPStatusError):
+        with fetch_to_tempfile(f"{base_url}/non-existing-file.rds"):
+            pass
+
+    assert temporary_files() == before
+
+
+def test_fetch_to_tempfile_rejects_truncated_response(raw_server):
+    """Test truncated response handling."""
+    # Create a server that returns a truncated response
+    url = raw_server(b"HTTP/1.1 200 OK\r\nContent-Length: 5000\r\n\r\n" + b"x" * 100)
+
+    # Save payload
+    before = temporary_files()
+
+    # Fetch file
+    with pytest.raises(httpx2.RemoteProtocolError):
+        with fetch_to_tempfile(url):
+            pass
+
+    # Check the file is deleted
+    assert temporary_files() == before

{pysits-2.0.0.dev7 → pysits-2.0.0.dev9}/tests/test_utils.py

@@ -53,6 +53,26 @@ def test_read_rds(tmp_path: Path):
     assert isinstance(rds_content, SITSTimeSeriesModel)
 
 
+@pytest.mark.parametrize("compress", ["gzip", "xz", "bzip2"])
+def test_read_rds_remote(http_server, compress: str):
+    """Test read RDS from a remote file."""
+    directory, base_url = http_server
+
+    # Save RDS
+    r_fnc_save_rds = load_function_from_package("base::saveRDS")
+    r_fnc_save_rds(
+        samples_modis_ndvi._instance,
+        (directory / "samples.rds").as_posix(),
+        compress=compress,
+    )
+
+    # Read remote RDS
+    rds_content = read_rds(f"{base_url}/samples.rds")
+
+    # Check the content
+    assert isinstance(rds_content, SITSTimeSeriesModel)
+
+
 def test_read_rds_file_not_found():
     """Test read RDS file not found."""
     with pytest.raises(FileNotFoundError):