marpledata 3.0.0.dev0__tar.gz → 3.0.1__tar.gz

{marpledata-3.0.0.dev0 → marpledata-3.0.1}/.gitignore

@@ -1,3 +1,9 @@
+lol.py
+.mdb_cache/
+
+python/docs/_build/
+python/docs/api/marple.*.rst
+
 # Default ignored files
 /shelf/
 /workspace.xml

marpledata-3.0.1/.uv-cache/.gitignore

@@ -0,0 +1 @@
+*

marpledata-3.0.1/.uv-cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

{marpledata-3.0.0.dev0 → marpledata-3.0.1}/CONTRIBUTING.md

@@ -11,6 +11,17 @@ export INSIGHT_TOKEN=...
 uv run pytest -vs
 ```
 
+### Documentation
+
+Build the Sphinx docs locally:
+
+```bash
+uv sync --group docs
+uv run sphinx-build -b html docs docs/_build/html
+```
+
+Open `docs/_build/html/index.html` in your browser to view the site.
+
 ### Local build
 
 - `uv build`
@@ -18,7 +29,7 @@ uv run pytest -vs
 - `uv run python`
   - `import marple`
   - `marple.__version__`
-  - `from marple import Marple, Insight, DB`
+  - `from marple import Insight, DB`
 
 ### Publishing (Test Pypi)
 
@@ -32,7 +43,7 @@ Only once on your laptop
 For every build
 
 - `uv version x.y.z.devi`
-- bump version in `__version__` variable in [\_\_init\_\_.py](src/marple/__init__.py)
+- bump version in `__version__` variable
 - `uv build`
 - `uv publish --index testpypi`
 
@@ -59,3 +70,4 @@ To ensure pip correctly updates our package, correct versioning is important. Us
 - `uv config pypi-token.pypi pypi-XXXXXXXXXXXXXXXXXXXXXXXXXXXX`
 - `uv build`
 - `uv publish`
+- Run the GitLab pipeline `pages` to build & release the docs

{marpledata-3.0.0.dev0 → marpledata-3.0.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: marpledata
-Version: 3.0.0.dev0
+Version: 3.0.1
 Summary: Marple SDK for Python
 Project-URL: Homepage, https://www.marpledata.com/
-Project-URL: Documentation, https://docs.marpledata.com/docs
+Project-URL: Documentation, https://marpledata.gitlab.io/marple-sdk/
 Project-URL: Repository, https://gitlab.com/marpledata/marple-sdk/-/tree/main/python
 Project-URL: Issues, https://github.com/marpledata/marple-sdk/issues
 Author-email: Matthias Baert <support@marpledata.com>, Jan Scheers <jan@marpledata.com>
@@ -28,6 +28,7 @@ Requires-Dist: pandas>=2.3.3
 Requires-Dist: pyarrow>=22.0.0
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: requests>=2.32.5
+Requires-Dist: tabulate>=0.9.0
 Description-Content-Type: text/markdown
 
 # Marple SDK
@@ -58,7 +59,8 @@ To get started:
 
 If you are using a VPC or self-hosted version, pass a custom `api_url` to `DB(...)` (it should end in `/api/v1`).
 
-### Example: import a file and poll ingest status
+### Examples
+#### Import a file and wait for it to import
 
 This is the typical flow for importing a new file into Marple DB:
 
@@ -75,23 +77,77 @@ db = DB(API_TOKEN, API_URL)
 
 db.check_connection()
 
-dataset_id = db.push_file(STREAM, "tests/examples_race.csv", metadata={"driver": "Mbaerto"})
+stream = db.get_stream(STREAM)
+dataset = stream.push_file("examples_race.csv", metadata={"driver": "Mbaerto"})
+# Wait at most 10s for the dataset to completely import and get the new state of the dataset
+dataset = dataset.wait_for_import(timeout=10)
+```
+
+#### Filter datasets and get resampled data
+```python
+# See previous example for setup
+import re
+from marple.db import Dataset
+
+datasets = stream.get_datasets()  # Get all datasets in a specific Data Stream
+# OR
+# datasets = db.get_datasets()  # Get all datasets in the datapool
+
+datasets = (
+    datasets
+    .where_metadata({"car_id": [1, 2], "track": "track_1"})
+    .wait_for_import()
+    .where_imported()
+    .where_signal("car.speed", "max", greater_than=75)
+    .where_signal("car.engine.temp", "mean", greater_than=30)
+    .where_dataset("n_datapoints", greater_than=100000)
+)
+
+def custom_filter_function(dataset: Dataset) -> bool:
+    return (
+        dataset.metadata.get("weather") == "sunny"
+        or dataset.get_signal("car.engine.NGear").stats.get("avg", 0) ** 2 > 16
+    )
+
+# Pass any function to filter the datasets on more complex conditions
+datasets = datasets.where(custom_filter_function)
+
+# Create an overview of the datasets as a pandas.DataFrame to save it to a CSV.
+datasets.to_pandas().to_csv("all_datasets.csv")
+
+# Get a dataframe per dataset of the matching signals which is resampled at a period of 0.17s.
+# The regex patterns will match with car.wheel.rear.left.speed, car.wheel.rear.front.speed, ...
+for dataset, data in datasets.get_data(
+    signals=[
+        "car.speed",
+        "car.engine.temp",
+        re.compile("car.wheel.*.speed"),
+        re.compile("car.wheel.*.trq"),
+    ],
+    resample_rule="0.17s",
+):
+    machine_learning_model.train(data)
+```
+
+#### Delete a dataset that failed to import
+```python
+datasets = stream.get_datasets()
+datasets = datasets.where_dataset("import_status", equals="FAILED")
 
-while True:
-    status = db.get_status(STREAM, dataset_id)
-    if status.get("import_status") in {"FINISHED", "FAILED"}:
-        break
-    time.sleep(1)
+# datasets is of type DatasetList which is a subclass of list so you can do all normal list operations on it.
+if len(datasets) > 0:
+    datasets[0].delete()
 ```
 
 ### Common operations
 
 - **List streams**: `db.get_streams()`
-- **List datasets in a stream**: `db.get_datasets(stream_key)`
-- **Upload a file to a file-stream**: `db.push_file(stream_key, file_path, metadata={...})`
-- **Poll ingest status**: `db.get_status(stream_key, dataset_id)`
-- **Download original uploaded file**: `db.download_original(stream_key, dataset_id, destination_folder=".")`
-- **Download parquet for a signal**: `db.download_signal(stream_key, dataset_id, signal_id, destination_folder=".")`
+- **List datasets in a stream**: `stream.get_datasets()`
+- **Upload a file to a file-stream**: `stream.push_file(file_path, metadata={...})`
+- **Wait for a dataset to import**: `dataset.wait_for_import(timeout=60)`
+- **Download original uploaded file**: `dataset.download(destination_folder=".")`
+- **Download parquet for a signal**: `dataset.get_signal(signal_name).download(destination_folder=".")`
+- **Get a resampled df of multiple signals**: `dataset.get_data(signals=[...], resample_rule="1s")`
 
 For live/realtime streams (creating and appending data):
 
@@ -105,9 +161,14 @@ For advanced use cases, you can call API endpoints directly:
 
 ```python
 db.get("/health")
-db.post("/query", json={"query": "select 1"})
 ```
 
+### Notes on DB API changes
+
+- Methods like `DB.push_file`, `DB.download_signal`, and `DB.update_metadata` are deprecated.
+- Prefer stream/dataset methods instead: `stream.push_file`, `dataset.get_signal(...).download()`, and `dataset.update_metadata(...)`.
+- These are still available for compatibility, but the examples above use the current API.
+
 ## Marple Insight
 
 ### Common operations
@@ -130,7 +191,7 @@ STREAM = "Car data"
 insight = Insight(INSIGHT_TOKEN, INSIGHT_URL)
 db = DB(DB_TOKEN, DB_URL)
 
-dataset_id = db.get_datasets(STREAM)[0]["id"]
+dataset_id = db.get_datasets(STREAM)[0].id
 insight_dataset = insight.get_dataset_mdb(dataset_id)
 
 file_path = insight.export_data_mdb(
@@ -141,3 +202,10 @@ file_path = insight.export_data_mdb(
 )
 print("Wrote", file_path)
 ```
+
+### Calling endpoints directly
+For advanced use cases, you can call API endpoints directly:
+```python
+insight.get("/user/info")
+insight.post("sources/search")
+```

marpledata-3.0.1/README.md

@@ -0,0 +1,178 @@
+# Marple SDK
+
+An SDK to interact with [Marple](https://www.marpledata.com) DB & Insight
+
+## Installation and importing
+
+Install the Marple SDK using your package manager:
+
+- `poetry add marpledata`
+- `uv add marpledata`
+- `pip install marpledata`
+
+The SDK currently exposes:
+
+```python
+from marple import DB      # Marple DB
+from marple import Insight # Marple Insight
+```
+
+## Marple DB
+
+To get started:
+
+- Create a **stream** in the Marple DB UI
+- Create an **API token** (in user settings)
+
+If you are using a VPC or self-hosted version, pass a custom `api_url` to `DB(...)` (it should end in `/api/v1`).
+
+### Examples
+#### Import a file and wait for it to import
+
+This is the typical flow for importing a new file into Marple DB:
+
+```python
+import time
+from marple import DB
+
+# Create a stream + API token in the Marple DB web application
+STREAM = "Car data"
+API_TOKEN = "<your api token>"
+API_URL = "https://db.marpledata.com/api/v1"  # optional if using the default SaaS
+
+db = DB(API_TOKEN, API_URL)
+
+db.check_connection()
+
+stream = db.get_stream(STREAM)
+dataset = stream.push_file("examples_race.csv", metadata={"driver": "Mbaerto"})
+# Wait at most 10s for the dataset to completely import and get the new state of the dataset
+dataset = dataset.wait_for_import(timeout=10)
+```
+
+#### Filter datasets and get resampled data
+```python
+# See previous example for setup
+import re
+from marple.db import Dataset
+
+datasets = stream.get_datasets()  # Get all datasets in a specific Data Stream
+# OR
+# datasets = db.get_datasets()  # Get all datasets in the datapool
+
+datasets = (
+    datasets
+    .where_metadata({"car_id": [1, 2], "track": "track_1"})
+    .wait_for_import()
+    .where_imported()
+    .where_signal("car.speed", "max", greater_than=75)
+    .where_signal("car.engine.temp", "mean", greater_than=30)
+    .where_dataset("n_datapoints", greater_than=100000)
+)
+
+def custom_filter_function(dataset: Dataset) -> bool:
+    return (
+        dataset.metadata.get("weather") == "sunny"
+        or dataset.get_signal("car.engine.NGear").stats.get("avg", 0) ** 2 > 16
+    )
+
+# Pass any function to filter the datasets on more complex conditions
+datasets = datasets.where(custom_filter_function)
+
+# Create an overview of the datasets as a pandas.DataFrame to save it to a CSV.
+datasets.to_pandas().to_csv("all_datasets.csv")
+
+# Get a dataframe per dataset of the matching signals which is resampled at a period of 0.17s.
+# The regex patterns will match with car.wheel.rear.left.speed, car.wheel.rear.front.speed, ...
+for dataset, data in datasets.get_data(
+    signals=[
+        "car.speed",
+        "car.engine.temp",
+        re.compile("car.wheel.*.speed"),
+        re.compile("car.wheel.*.trq"),
+    ],
+    resample_rule="0.17s",
+):
+    machine_learning_model.train(data)
+```
+
+#### Delete a dataset that failed to import
+```python
+datasets = stream.get_datasets()
+datasets = datasets.where_dataset("import_status", equals="FAILED")
+
+# datasets is of type DatasetList which is a subclass of list so you can do all normal list operations on it.
+if len(datasets) > 0:
+    datasets[0].delete()
+```
+
+### Common operations
+
+- **List streams**: `db.get_streams()`
+- **List datasets in a stream**: `stream.get_datasets()`
+- **Upload a file to a file-stream**: `stream.push_file(file_path, metadata={...})`
+- **Wait for a dataset to import**: `dataset.wait_for_import(timeout=60)`
+- **Download original uploaded file**: `dataset.download(destination_folder=".")`
+- **Download parquet for a signal**: `dataset.get_signal(signal_name).download(destination_folder=".")`
+- **Get a resampled df of multiple signals**: `dataset.get_data(signals=[...], resample_rule="1s")`
+
+For live/realtime streams (creating and appending data):
+
+- **Create an empty dataset**: `db.add_dataset(stream_key, dataset_name, metadata=None)`
+- **Upsert signal definitions**: `db.upsert_signals(stream_key, dataset_id, signals=[...])`
+- **Append timeseries data**: `db.dataset_append(stream_key, dataset_id, data=df, shape="long"|"wide"|None)`
+
+### Calling endpoints directly
+
+For advanced use cases, you can call API endpoints directly:
+
+```python
+db.get("/health")
+```
+
+### Notes on DB API changes
+
+- Methods like `DB.push_file`, `DB.download_signal`, and `DB.update_metadata` are deprecated.
+- Prefer stream/dataset methods instead: `stream.push_file`, `dataset.get_signal(...).download()`, and `dataset.update_metadata(...)`.
+- These are still available for compatibility, but the examples above use the current API.
+
+## Marple Insight
+
+### Common operations
+
+- **List datasets in the workspace**: `insight.get_datasets()`
+- **Get a Marple DB dataset (by dataset id)**: `insight.get_dataset_mdb(dataset_id)`
+- **List signals in a dataset**: `insight.get_signals(dataset_filter)` / `insight.get_signals_mdb(dataset_id)`
+
+### Example: export a dataset (H5/MAT)
+
+```python
+from marple import DB, Insight
+
+INSIGHT_TOKEN = "<your api token>"
+INSIGHT_URL = "https://insight.marpledata.com/api/v1"  # optional if using the default SaaS
+DB_TOKEN = "<your api token>"
+DB_URL = "https://db.marpledata.com/api/v1"  # optional if using the default SaaS
+STREAM = "Car data"
+
+insight = Insight(INSIGHT_TOKEN, INSIGHT_URL)
+db = DB(DB_TOKEN, DB_URL)
+
+dataset_id = db.get_datasets(STREAM)[0].id
+insight_dataset = insight.get_dataset_mdb(dataset_id)
+
+file_path = insight.export_data_mdb(
+    dataset_id,
+    format="h5",
+    signals=["car.speed"],
+    destination=".",
+)
+print("Wrote", file_path)
+```
+
+### Calling endpoints directly
+For advanced use cases, you can call API endpoints directly:
+```python
+insight.get("/user/info")
+insight.post("sources/search")
+```

marpledata-3.0.1/docs/DEPLOYMENT.md

@@ -0,0 +1,24 @@
+# Documentation Deployment
+
+The Sphinx documentation can be manually built and deployed to GitLab Pages with a single click.
+
+## How to Deploy
+Click **Run pipeline** to trigger it
+The`pages` job will start and automatically build the docs and serve them as a static gitlab page under `https://marpledata.gitlab.io/marple-sdk/`
+
+## Local Development
+
+To build docs locally:
+```bash
+cd python
+uv run sphinx-build -b html docs docs/_build/html
+```
+
+Then open `docs/_build/html/index.html` in your browser.
+
+
+**Sphinx configuration:** `python/docs/conf.py`
+- Uses PyData theme
+- Includes Pydantic filtering to hide internal methods
+- 2-product structure (Insight, DB, Files)
+

marpledata-3.0.1/docs/_static/custom.css

@@ -0,0 +1,4 @@
+:root {
+    /* The primary color used for links and active states */
+    --pst-color-primary: #0253A3;
+}

marpledata-3.0.1/docs/api/db.rst

@@ -0,0 +1,12 @@
+Marple DB
+=========
+
+.. autosummary::
+   :toctree: .
+   :nosignatures:
+
+   marple.db.DB
+   marple.db.DataStream
+   marple.db.Dataset
+   marple.db.DatasetList
+   marple.db.Signal

marpledata-3.0.1/docs/api/insight.rst

@@ -0,0 +1,8 @@
+Marple Insight
+==============
+
+.. autosummary::
+   :toctree: .
+   :nosignatures:
+
+   marple.Insight

marpledata-3.0.1/docs/api.rst

@@ -0,0 +1,8 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   api/insight
+   api/db

marpledata-3.0.1/docs/conf.py

@@ -0,0 +1,128 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../src"))
+
+project = "Marple SDK"
+author = "Marple"
+copyright = "2026, Marple"
+
+try:
+    import marple
+
+    release = marple.__version__
+except Exception:
+    release = "unknown"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+    "sphinxcontrib.autodoc_pydantic",
+]
+
+autosummary_generate = True
+autodoc_default_options = {
+    "members": True,
+    "show-inheritance": True,
+    "member-order": "groupwise",
+    "inherited-members": False,
+    "private-members": False,
+}
+
+# Pydantic Settings: Clean up the docs
+autodoc_pydantic_model_show_json = False
+autodoc_pydantic_model_show_config = False
+autodoc_pydantic_settings_show_json = False
+
+# This hides the 'model_dump', 'model_validate', etc. methods
+autodoc_pydantic_model_members = False
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_logo = "_static/logo.png"
+html_favicon = "_static/favicon.png"
+
+html_theme_options = {
+    "header_links_before_dropdown": 6,
+    "navigation_with_keys": True,
+    "use_edit_page_button": True,
+    "show_nav_level": 2,
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/marpledata/marple-sdk",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "GitLab",
+            "url": "https://gitlab.com/marpledata/marple-sdk",
+            "icon": "fa-brands fa-gitlab",
+        },
+    ],
+}
+
+html_context = {
+    "github_url": "https://github.com",
+    "github_user": "marpledata",
+    "github_repo": "marple-sdk",
+    "github_version": "main",
+    "doc_path": "python/docs",
+    "gitlab_url": "https://gitlab.com",
+    "gitlab_user": "marpledata",
+    "gitlab_repo": "marple-sdk",
+    "gitlab_version": "main",
+}
+
+
+def skip_pydantic_internals(app, what, name, obj, skip, options):
+    """
+    Triggers on every member. If it looks like a Pydantic internal, skip it.
+    """
+    # List of exact names to skip (Pydantic V1/V2 compat methods)
+    pydantic_internals = {
+        "model_copy",
+        "model_dump",
+        "model_dump_json",
+        "model_json_schema",
+        "model_parametrized_name",
+        "model_post_init",
+        "model_rebuild",
+        "model_validate",
+        "model_validate_json",
+        "schema",
+        "schema_json",
+        "update_forward_refs",
+        "model_validate_strings",
+        "parse_file",
+        "parse_obj",
+        "parse_raw",
+        "from_orm",
+        "validate",
+        "construct",
+        "copy",
+        "json",
+        "dict",
+    }
+
+    # If the name is in our blacklist, SKIP it (return True)
+    if name in pydantic_internals:
+        return True
+
+    # Optional: Skip anything starting with "model_" if you are bold
+    if name.startswith("model_"):
+        return True
+
+    if name.startswith("_"):
+        return True
+
+    return skip
+
+
+def setup(app):
+    # Register the function above to run during the build
+    app.connect("autodoc-skip-member", skip_pydantic_internals)

marpledata-3.0.1/docs/getting-started.rst

@@ -0,0 +1,54 @@
+Getting Started
+===============
+
+Install
+-------
+
+Install the Marple SDK using your package manager:
+
+.. code-block:: bash
+
+   poetry add marpledata
+   uv add marpledata
+   pip install marpledata
+
+The SDK exposes the main entry points:
+
+.. code-block:: python
+
+   from marple import DB
+   from marple import Insight
+
+Marple DB quickstart
+--------------------
+
+.. code-block:: python
+
+   from marple import DB
+
+   stream_name = "Car data"
+   api_token = "<your api token>"
+   api_url = "https://db.marpledata.com/api/v1"
+
+   db = DB(api_token, api_url)
+
+   stream = db.get_stream(stream_name)
+   dataset = stream.push_file("examples_race.csv", metadata={"driver": "Mbaerto"})
+   dataset = dataset.wait_for_import(timeout=10)
+
+Marple Insight quickstart
+-------------------------
+
+.. code-block:: python
+
+   from marple import Insight
+
+   insight_token = "<your api token>"
+   insight_url = "https://insight.marpledata.com/api/v1"
+
+   insight = Insight(insight_token, insight_url)
+
+   # For more advanced dataset/signal searches/exports, use DB instead of Insight.
+   datasets = insight.get_datasets()
+   dataset = datasets[0]
+   signals = insight.get_signals(dataset["dataset_filter"])

marpledata-3.0.1/docs/index.rst

@@ -0,0 +1,12 @@
+Marple SDK
+==========
+
+The Marple SDK provides Python clients to interact with Marple DB and Marple Insight.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   getting-started
+   tutorials
+   api