python(refactor): update HDF5 import examples (#597)

Author: wei-qlu

python/examples/data_import/hdf5/compound/.env.example

@@ -0,0 +1,4 @@
+SIFT_GRPC_URI=
+SIFT_REST_URI=
+SIFT_API_KEY=
+ASSET_NAME=

python/examples/data_import/hdf5/compound/main.py

@@ -0,0 +1,68 @@
+"""Import an HDF5 file with the compound schema into Sift.
+
+In this layout, each dataset is a compound (struct-like) type whose first
+field is time and whose remaining fields each become a channel. Channel
+name, units, and description are read from the dataset's attributes when
+present; multi-value datasets emit channels named ``<dataset>.<field>``.
+"""
+
+import os
+
+from dotenv import load_dotenv
+from sift_client import SiftClient
+from sift_client.sift_types.data_import import DataTypeKey
+
+if __name__ == "__main__":
+    load_dotenv()
+
+    grpc_uri = os.getenv("SIFT_GRPC_URI")
+    assert grpc_uri, "expected 'SIFT_GRPC_URI' environment variable to be set"
+
+    rest_uri = os.getenv("SIFT_REST_URI")
+    assert rest_uri, "expected 'SIFT_REST_URI' environment variable to be set"
+
+    apikey = os.getenv("SIFT_API_KEY")
+    assert apikey, "expected 'SIFT_API_KEY' environment variable to be set"
+
+    asset_name = os.getenv("ASSET_NAME")
+    assert asset_name, "expected 'ASSET_NAME' environment variable to be set"
+
+    client = SiftClient(api_key=apikey, grpc_url=grpc_uri, rest_url=rest_uri)
+
+    # Auto-detect the config and import the file. HDF5 requires the layout
+    # (data_type) to be specified since the extension alone is ambiguous.
+    # HDF5 timestamps aren't self-describing, so time_format defaults to
+    # TimeFormat.ABSOLUTE_UNIX_NANOSECONDS; override it if your timestamps
+    # are in a different format.
+    import_job = client.data_import.import_from_path(
+        "sample_data.h5",
+        asset=asset_name,
+        data_type=DataTypeKey.HDF5_COMPOUND,
+    )
+
+    import_job.wait_until_complete()
+
+    # If auto-detect doesn't quite match your file, inspect the config and patch
+    # it before importing. Common fixes: change the time format, override a
+    # channel's data type, or drop a channel that shouldn't be imported.
+    #
+    # from sift_client.sift_types.data_import import TimeFormat
+    #
+    # config = client.data_import.detect_config(
+    #     "sample_data.h5",
+    #     data_type=DataTypeKey.HDF5_COMPOUND,
+    # )
+    # print(config)  # inspect what was auto-detected
+    #
+    # # Example: timestamps are unix microseconds instead of unix nanoseconds
+    # config.time_format = TimeFormat.ABSOLUTE_UNIX_MICROSECONDS
+    #
+    # # Example: drop a channel from the import
+    # config.data = [d for d in config.data if d.name != "sensors.temperature"]
+    #
+    # import_job = client.data_import.import_from_path(
+    #     "sample_data.h5",
+    #     asset=asset_name,
+    #     config=config,
+    # )
+    # import_job.wait_until_complete()

python/examples/data_import/hdf5/compound/requirements.txt

@@ -0,0 +1,2 @@
+python-dotenv
+sift-stack-py[hdf5]

python/examples/data_import/hdf5/compound/sample_data.h5

@@ -0,0 +1,4 @@
+SIFT_GRPC_URI=
+SIFT_REST_URI=
+SIFT_API_KEY=
+ASSET_NAME=

python/examples/data_import/hdf5/main.py

@@ -0,0 +1,68 @@
+"""Import an HDF5 file with the one-dimensional schema into Sift.
+
+In this layout, each value channel is its own 1D dataset that pairs with a
+time dataset in the same group (or an ancestor group's time dataset, walking
+up to the root). Channel name, units, and description are read from the
+dataset's attributes when present.
+"""
+
+import os
+
+from dotenv import load_dotenv
+from sift_client import SiftClient
+from sift_client.sift_types.data_import import DataTypeKey
+
+if __name__ == "__main__":
+    load_dotenv()
+
+    grpc_uri = os.getenv("SIFT_GRPC_URI")
+    assert grpc_uri, "expected 'SIFT_GRPC_URI' environment variable to be set"
+
+    rest_uri = os.getenv("SIFT_REST_URI")
+    assert rest_uri, "expected 'SIFT_REST_URI' environment variable to be set"
+
+    apikey = os.getenv("SIFT_API_KEY")
+    assert apikey, "expected 'SIFT_API_KEY' environment variable to be set"
+
+    asset_name = os.getenv("ASSET_NAME")
+    assert asset_name, "expected 'ASSET_NAME' environment variable to be set"
+
+    client = SiftClient(api_key=apikey, grpc_url=grpc_uri, rest_url=rest_uri)
+
+    # Auto-detect the config and import the file. HDF5 requires the layout
+    # (data_type) to be specified since the extension alone is ambiguous.
+    # HDF5 timestamps aren't self-describing, so time_format defaults to
+    # TimeFormat.ABSOLUTE_UNIX_NANOSECONDS; override it if your timestamps
+    # are in a different format.
+    import_job = client.data_import.import_from_path(
+        "sample_data.h5",
+        asset=asset_name,
+        data_type=DataTypeKey.HDF5_ONE_D,
+    )
+
+    import_job.wait_until_complete()
+
+    # If auto-detect doesn't quite match your file, inspect the config and patch
+    # it before importing. Common fixes: change the time format, override a
+    # channel's data type, or drop a channel that shouldn't be imported.
+    #
+    # from sift_client.sift_types.data_import import TimeFormat
+    #
+    # config = client.data_import.detect_config(
+    #     "sample_data.h5",
+    #     data_type=DataTypeKey.HDF5_ONE_D,
+    # )
+    # print(config)  # inspect what was auto-detected
+    #
+    # # Example: timestamps are ISO-8601 strings instead of unix nanoseconds
+    # config.time_format = TimeFormat.ABSOLUTE_DATETIME
+    #
+    # # Example: drop a channel from the import
+    # config.data = [d for d in config.data if d.name != "channel_0"]
+    #
+    # import_job = client.data_import.import_from_path(
+    #     "sample_data.h5",
+    #     asset=asset_name,
+    #     config=config,
+    # )
+    # import_job.wait_until_complete()

python/examples/data_import/hdf5/one_d/.env.example

@@ -0,0 +1,2 @@
+python-dotenv
+sift-stack-py[hdf5]