marpledata 3.4.0.dev1__tar.gz → 3.6.0__tar.gz

{marpledata-3.4.0.dev1 → marpledata-3.6.0}/.gitignore

@@ -169,4 +169,7 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
-*.env
+.env*
+
+# Client handoff pack (may contain a real API token)
+/marple-matlab/

{marpledata-3.4.0.dev1 → marpledata-3.6.0}/AGENTS.md

@@ -15,6 +15,7 @@ This directory contains the Python SDK package published as `marpledata`.
 ## Commands
 
 - Run tests with output: `uv run pytest -vs`
+- Unit tests only: `uv run pytest -m "not integration"`
 - Build docs: `uv run --group docs sphinx-build -b html docs docs/_build/html`
 - Build package: `uv build`
 - Fix formatting: `uv run isort src tests && uv run black src tests`
@@ -29,4 +30,6 @@ Run commands from `python/` unless a command explicitly says otherwise.
 - Keep Python SDK tests in `python/tests/`.
 - Integration tests run against live Marple services and may require
   `MDB_TOKEN`, `MDB_URL`, `INSIGHT_TOKEN`, and `INSIGHT_URL`. Tests should skip
-  or fail clearly when required credentials are missing.
+  clearly when required credentials are missing. Mark live tests with
+  `pytest.mark.integration`.
+- Release steps: `RELEASING.md`.

{marpledata-3.4.0.dev1 → marpledata-3.6.0}/CHANGELOG.md

@@ -5,7 +5,41 @@ All notable changes to the Python SDK package `marpledata` will be documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [3.4.0] - 2026-07-16
+## [3.6.0] - 2026-09-04
+
+### Changed
+
+- Exact signal names in `get_data` / `get_signal` / `get_signals` resolve via the dataset cache or `GET /datapool/{pool}/signal/{name}/id` instead of downloading the full datapool `signal_map`. Regex patterns still use the map.
+- Optional `plugin_args` on `DataStream.push_file` (and the deprecated `DB.push_file` wrapper).
+
+### Added
+
+- Processing Pipeline
+  - `DB.create_script` / `get_scripts` / `get_script` / `delete_script`
+  - `Script.update` / `duplicate` / `delete`, to manage stored `process(dataset)` scripts.
+  - `Dataset.run` / `DB.run_script` to execute a stored processing script against a dataset via a server-side sandbox job.
+  - `DataStream.scripts`, `DataStream.update`, and `DataStream.rerun_processing` (`DB.rerun_processing`) to edit a stream and set the script pipeline
+  - `Dataset.rerun_processing` and `Dataset.get_debug_messages`.
+  - `DB.delete_signals`, `Dataset.delete_signal` / `Dataset.delete_signals`, and `Signal.delete` to remove signals from a dataset.
+  - `Dataset.reingest` to reingest a dataset from its original uploaded file, with optional `plugin_args`.
+  - `logger.debug` lines on SDK mutations (`add_signal`, `update_metadata`, …), off by default. Call `db.verbose()` to print them.
+
+### Fixed
+
+- Allow `add_signal` in post-processing
+
+## [3.5.0] - 2026-08-20
+
+### Added
+
+- `Dataset.add_signal` and `Dataset.add_signals` now accept a time-indexed pandas Series or DataFrame (DatetimeIndex / TimedeltaIndex when there is no `time` column).
+- `DataStream.push_file(..., overwrite=False)` to replace an existing dataset with the same name (also on the deprecated `DB.push_file`).
+
+### Fixed
+
+- An empty local parquet cache folder is treated as a cache miss and re-downloaded, instead of being assumed to mean the signal has no data.
+
+## [3.4.0] - 2026-07-28
 
 ### Added
 

marpledata-3.6.0/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+## Development (Python)
+
+### Formatting, linting, and typing
+
+Checks run on `src/` and `tests/` in GitLab CI (`python:lint`, `python:typing`).
+
+Fix formatting locally:
+
+```bash
+uv run isort src tests
+uv run black src tests
+```
+
+Verify (mirror CI):
+
+```bash
+uv run isort src tests --check --diff
+uv run flake8 --config .flake8 src tests
+uv run black --check src tests
+uv run mypy --install-types --non-interactive
+```
+
+### Testing
+
+The testing suite includes local unit tests and integration tests against a live Marple DB / Insight deployment. Integration tests share one imported example dataset per session, use a small CSV for extra ingestions, and mark themselves with `pytest.mark.integration`.
+
+```bash
+uv run pytest -m "not integration"   # local unit tests only
+export MDB_TOKEN=...
+export INSIGHT_TOKEN=...
+# Optional, defaults to SaaS URLs:
+export MDB_URL=https://db.marpledata.com/api/v1
+export INSIGHT_URL=https://insight.marpledata.com/api/v1
+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`
+- `uv run pip install dist/*.whl` (Install in your local .venv)
+- `uv run python`
+  - `import marple`
+  - `marple.__version__`
+  - `from marple import Insight, DB`
+
+### Publishing
+
+See [`RELEASING.md`](RELEASING.md).

{marpledata-3.4.0.dev1 → marpledata-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: marpledata
-Version: 3.4.0.dev1
+Version: 3.6.0
 Summary: Marple SDK for Python
 Project-URL: Homepage, https://www.marpledata.com/
 Project-URL: Documentation, https://marpledata.gitlab.io/marple-sdk/
@@ -52,7 +52,7 @@ from marple import DB      # Marple DB
 from marple import Insight # Marple Insight
 ```
 
-For release notes, see [`CHANGELOG.md`](CHANGELOG.md).
+For release notes, see [`CHANGELOG.md`](CHANGELOG.md). To publish a release, see [`RELEASING.md`](RELEASING.md).
 
 ## Marple DB
 
@@ -78,6 +78,7 @@ 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.verbose()  # print SDK mutation activity (push_file, add_signal, …) to stdout
 
 db.check_connection()
 
@@ -90,34 +91,75 @@ dataset = dataset.wait_for_import(timeout=10)
 #### Add signals to an imported dataset
 
 Upload additional signals (for example derived channels) on an existing dataset.
-Each signal is a DataFrame, Arrow table, or on-disk parquet matching `LAKE_ARROW_SCHEMA`:
-columns `time` (int64 nanoseconds) plus `value` and/or `value_text`.
+DataFrames, Arrow tables, and on-disk parquet use `LAKE_ARROW_SCHEMA`: columns
+`time` (int64 nanoseconds) plus `value` and/or `value_text`.
 Times must overlap the dataset time range. Use `overwrite=True` to replace an existing signal name;
 a conflict without overwrite raises `SignalsAlreadyExistError`.
 
-```python
-import pandas as pd
-from marple.db import LAKE_ARROW_SCHEMA  # time + value and/or value_text
+A Series, or a DataFrame without a `time` column, takes its times from a `DatetimeIndex` or
+`TimedeltaIndex`. Indexed DataFrames must still have a `value` and/or `value_text` column.
 
-speed = dataset.get_signal("car.speed").get_data()
-derived = pd.DataFrame({
-    "time": speed.index.asi8,
-    "value": speed["value"] * 3.6,
-})
+```python
 # Single signal: wait until available before reading
+speed = dataset.get_signal("car.speed").get_data()
 signal = dataset.add_signal(
     "car.speed_kmh",
-    derived,
+    speed * 3.6,
     metadata={"unit": "km/h"},
 ).wait_until_available()
 
 # Batch: returns IDs as soon as upload completes (no wait)
 ids = dataset.add_signals([
-    {"name": "car.speed_kmh", "data": derived, "metadata": {"unit": "km/h"}},
+    {"name": "car.speed_kmh", "data": speed * 3.6, "metadata": {"unit": "km/h"}},
 ], overwrite=True, concurrency=4)
 signals = dataset.get_signals(signal_ids=ids)
 ```
 
+Data assembled from scratch uses the explicit schema columns instead:
+
+```python
+import pandas as pd
+from marple.db import LAKE_ARROW_SCHEMA  # time + value and/or value_text
+
+samples = pd.DataFrame({"time": [t0, t0 + 1_000_000_000], "value": [1.0, 2.0]})
+dataset.add_signal("car.custom", samples)
+```
+
+#### Processing scripts
+
+Write a `process(dataset)` function, store it, and try it on any imported dataset. This runs on the server and writes to that dataset.
+
+```python
+source = """
+from marple.db import Dataset
+
+def process(dataset: Dataset) -> None:
+    speed = dataset.get_signal("car.speed").get_data()
+    dataset.add_signal("car.speed_kmh", speed * 3.6, metadata={"unit": "km/h"})
+"""
+
+script = db.create_script("speed_kmh", source)
+dataset = stream.get_dataset(path="lap.csv")
+# or: dataset = stream.push_file("lap.csv").wait_for_import()
+dataset.run(script)
+```
+
+Pass a `.py` path or `pathlib.Path` to `create_script` / `script.update` instead of source text. Iterate with `script.update(script=...)` then `dataset.run(script)` again (or `dataset.run(script, source=...)` to save and run in one step). New signals written by the script may need `signal.wait_until_available(...)` before you read them.
+
+When the script looks right, attach it to the stream with `stream.update(scripts=...)`. That **replaces** the pipeline (pass `[]` to detach all). New uploads then run those scripts after ingest.
+
+```python
+stream = stream.update(scripts=[script.id])
+```
+
+For files already imported, rerun aliasing and the stream's script pipeline:
+
+```python
+dataset = dataset.rerun_processing().wait_for_import()
+```
+
+Use `script.update(...)` to change source or metadata, and `dataset.get_debug_messages()` for the latest ingestion's debug log (not the sandbox job log from `dataset.run`).
+
 #### Upload large files
 
 `stream.push_file(...)` starts an ingestion and lets the Marple DB API choose the best upload mode. Depending on the deployment and file size, the SDK can upload through the API server, upload directly to Azure Blob Storage, use a single presigned URL, or split the file into multipart uploads.
@@ -203,7 +245,8 @@ if len(datasets) > 0:
 
 - **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={...}, concurrency=4)`
+- **Upload a file (file stream, default)**: `stream.push_file(file_path, metadata={...}, concurrency=4)`
+- **Custom lake ingest (file stream)**: `stream.add_dataset(...)` then `dataset.add_signal(...)` / `add_signals([...])`
 - **Add signals to a dataset**: `dataset.add_signal(name, data, ...)` / `dataset.add_signals([...])` — data matches `LAKE_ARROW_SCHEMA` (`time` + `value` and/or `value_text`)
 - **Wait until a signal is available**: `signal.wait_until_available(timeout=60)`
 - **Fetch signals by ID**: `dataset.get_signals(signal_ids=[...], refresh=False)`
@@ -213,13 +256,19 @@ if len(datasets) > 0:
 - **Get a resampled df of multiple signals**: `dataset.get_data(signals=[...], resample_rule="1s")`
 - **Delete a stream**: `stream.delete()` or `db.delete_stream(stream_key)`
 - **Delete a dataset**: `dataset.delete()` or `db.delete_dataset(dataset_id, dataset_path)`
+- **Delete signals**: `signal.delete()`, `dataset.delete_signal(signal_id)` / `dataset.delete_signals(signal_ids)`, or `db.delete_signals(dataset_id, dataset_path, signal_ids)`
+- **Run a processing script**: `dataset.run(script)` or `db.run_script(dataset_id, script)`
+- **Create a processing script**: `db.create_script(name, script)`
+- **Set script pipeline** (replaces the full list): `stream.update(scripts=[script.id])`
+- **Rerun aliasing + scripts**: `dataset.rerun_processing().wait_for_import()` or `stream.rerun_processing([dataset.id])`
+- **Read ingest debug logs**: `dataset.get_debug_messages()`
 
-For live/realtime streams (creating and appending data):
+For live streams:
 
 - **Create an empty dataset**: `stream.add_dataset(dataset_name, metadata=None)`
 - **Upsert signal definitions**: `dataset.upsert_signals(signals=[...])`
 - **Append timeseries data**: `dataset.append(data=df, shape="long"|"wide"|None)`
-- **Cool a realtime dataset**: `dataset.cool()` then `dataset.wait_for_import()` to wait until `FINISHED`
+- **Cool to cold storage**: `dataset.cool()` then `dataset.wait_for_import()` until `FINISHED`
 
 ### Calling endpoints directly
 

{marpledata-3.4.0.dev1 → marpledata-3.6.0}/README.md

@@ -17,7 +17,7 @@ from marple import DB      # Marple DB
 from marple import Insight # Marple Insight
 ```
 
-For release notes, see [`CHANGELOG.md`](CHANGELOG.md).
+For release notes, see [`CHANGELOG.md`](CHANGELOG.md). To publish a release, see [`RELEASING.md`](RELEASING.md).
 
 ## Marple DB
 
@@ -43,6 +43,7 @@ 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.verbose()  # print SDK mutation activity (push_file, add_signal, …) to stdout
 
 db.check_connection()
 
@@ -55,34 +56,75 @@ dataset = dataset.wait_for_import(timeout=10)
 #### Add signals to an imported dataset
 
 Upload additional signals (for example derived channels) on an existing dataset.
-Each signal is a DataFrame, Arrow table, or on-disk parquet matching `LAKE_ARROW_SCHEMA`:
-columns `time` (int64 nanoseconds) plus `value` and/or `value_text`.
+DataFrames, Arrow tables, and on-disk parquet use `LAKE_ARROW_SCHEMA`: columns
+`time` (int64 nanoseconds) plus `value` and/or `value_text`.
 Times must overlap the dataset time range. Use `overwrite=True` to replace an existing signal name;
 a conflict without overwrite raises `SignalsAlreadyExistError`.
 
-```python
-import pandas as pd
-from marple.db import LAKE_ARROW_SCHEMA  # time + value and/or value_text
+A Series, or a DataFrame without a `time` column, takes its times from a `DatetimeIndex` or
+`TimedeltaIndex`. Indexed DataFrames must still have a `value` and/or `value_text` column.
 
-speed = dataset.get_signal("car.speed").get_data()
-derived = pd.DataFrame({
-    "time": speed.index.asi8,
-    "value": speed["value"] * 3.6,
-})
+```python
 # Single signal: wait until available before reading
+speed = dataset.get_signal("car.speed").get_data()
 signal = dataset.add_signal(
     "car.speed_kmh",
-    derived,
+    speed * 3.6,
     metadata={"unit": "km/h"},
 ).wait_until_available()
 
 # Batch: returns IDs as soon as upload completes (no wait)
 ids = dataset.add_signals([
-    {"name": "car.speed_kmh", "data": derived, "metadata": {"unit": "km/h"}},
+    {"name": "car.speed_kmh", "data": speed * 3.6, "metadata": {"unit": "km/h"}},
 ], overwrite=True, concurrency=4)
 signals = dataset.get_signals(signal_ids=ids)
 ```
 
+Data assembled from scratch uses the explicit schema columns instead:
+
+```python
+import pandas as pd
+from marple.db import LAKE_ARROW_SCHEMA  # time + value and/or value_text
+
+samples = pd.DataFrame({"time": [t0, t0 + 1_000_000_000], "value": [1.0, 2.0]})
+dataset.add_signal("car.custom", samples)
+```
+
+#### Processing scripts
+
+Write a `process(dataset)` function, store it, and try it on any imported dataset. This runs on the server and writes to that dataset.
+
+```python
+source = """
+from marple.db import Dataset
+
+def process(dataset: Dataset) -> None:
+    speed = dataset.get_signal("car.speed").get_data()
+    dataset.add_signal("car.speed_kmh", speed * 3.6, metadata={"unit": "km/h"})
+"""
+
+script = db.create_script("speed_kmh", source)
+dataset = stream.get_dataset(path="lap.csv")
+# or: dataset = stream.push_file("lap.csv").wait_for_import()
+dataset.run(script)
+```
+
+Pass a `.py` path or `pathlib.Path` to `create_script` / `script.update` instead of source text. Iterate with `script.update(script=...)` then `dataset.run(script)` again (or `dataset.run(script, source=...)` to save and run in one step). New signals written by the script may need `signal.wait_until_available(...)` before you read them.
+
+When the script looks right, attach it to the stream with `stream.update(scripts=...)`. That **replaces** the pipeline (pass `[]` to detach all). New uploads then run those scripts after ingest.
+
+```python
+stream = stream.update(scripts=[script.id])
+```
+
+For files already imported, rerun aliasing and the stream's script pipeline:
+
+```python
+dataset = dataset.rerun_processing().wait_for_import()
+```
+
+Use `script.update(...)` to change source or metadata, and `dataset.get_debug_messages()` for the latest ingestion's debug log (not the sandbox job log from `dataset.run`).
+
 #### Upload large files
 
 `stream.push_file(...)` starts an ingestion and lets the Marple DB API choose the best upload mode. Depending on the deployment and file size, the SDK can upload through the API server, upload directly to Azure Blob Storage, use a single presigned URL, or split the file into multipart uploads.
@@ -168,7 +210,8 @@ if len(datasets) > 0:
 
 - **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={...}, concurrency=4)`
+- **Upload a file (file stream, default)**: `stream.push_file(file_path, metadata={...}, concurrency=4)`
+- **Custom lake ingest (file stream)**: `stream.add_dataset(...)` then `dataset.add_signal(...)` / `add_signals([...])`
 - **Add signals to a dataset**: `dataset.add_signal(name, data, ...)` / `dataset.add_signals([...])` — data matches `LAKE_ARROW_SCHEMA` (`time` + `value` and/or `value_text`)
 - **Wait until a signal is available**: `signal.wait_until_available(timeout=60)`
 - **Fetch signals by ID**: `dataset.get_signals(signal_ids=[...], refresh=False)`
@@ -178,13 +221,19 @@ if len(datasets) > 0:
 - **Get a resampled df of multiple signals**: `dataset.get_data(signals=[...], resample_rule="1s")`
 - **Delete a stream**: `stream.delete()` or `db.delete_stream(stream_key)`
 - **Delete a dataset**: `dataset.delete()` or `db.delete_dataset(dataset_id, dataset_path)`
+- **Delete signals**: `signal.delete()`, `dataset.delete_signal(signal_id)` / `dataset.delete_signals(signal_ids)`, or `db.delete_signals(dataset_id, dataset_path, signal_ids)`
+- **Run a processing script**: `dataset.run(script)` or `db.run_script(dataset_id, script)`
+- **Create a processing script**: `db.create_script(name, script)`
+- **Set script pipeline** (replaces the full list): `stream.update(scripts=[script.id])`
+- **Rerun aliasing + scripts**: `dataset.rerun_processing().wait_for_import()` or `stream.rerun_processing([dataset.id])`
+- **Read ingest debug logs**: `dataset.get_debug_messages()`
 
-For live/realtime streams (creating and appending data):
+For live streams:
 
 - **Create an empty dataset**: `stream.add_dataset(dataset_name, metadata=None)`
 - **Upsert signal definitions**: `dataset.upsert_signals(signals=[...])`
 - **Append timeseries data**: `dataset.append(data=df, shape="long"|"wide"|None)`
-- **Cool a realtime dataset**: `dataset.cool()` then `dataset.wait_for_import()` to wait until `FINISHED`
+- **Cool to cold storage**: `dataset.cool()` then `dataset.wait_for_import()` until `FINISHED`
 
 ### Calling endpoints directly
 

marpledata-3.6.0/RELEASING.md

@@ -0,0 +1,13 @@
+# Releasing `marpledata`
+
+Tokens: 1Password (`username: __token__`). Run from `python/`.
+
+- **Bump version**
+  - `uv version --bump minor` / `uv version x.y.z`
+  - Manual update `__init__.py`, `CHANGELOG.md`
+- **TestPyPI** — `rm -rf dist && uv build && uv publish --index testpypi`
+  Smoke: `pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple marpledata==<version>`
+- **PyPI** — `rm -rf dist && uv build && uv publish`
+- **Docs** — run the GitLab `pages` job (Sphinx → https://marpledata.gitlab.io/marple-sdk/)
+
+No GitHub tag/release; `CHANGELOG.md` is the release history.

{marpledata-3.4.0.dev1 → marpledata-3.6.0}/docs/api/db.rst

@@ -14,6 +14,10 @@ See :doc:`../tutorials` for upload examples.
    marple.db.DataStream
    marple.db.Dataset
    marple.db.DatasetList
+   marple.db.SandboxJob
+   marple.db.SandboxJobStatus
+   marple.db.Script
+   marple.db.ScriptVersion
    marple.db.Signal
    marple.db.SignalUpload
    marple.db.SignalsAlreadyExistError

{marpledata-3.4.0.dev1 → marpledata-3.6.0}/docs/api/marple.db.DB.rst

@@ -15,10 +15,8 @@
    
       ~DB.add_dataset
       ~DB.check_connection
-      ~DB.connect_trino
       ~DB.create_stream
       ~DB.dataset_append
-      ~DB.dataset_cool
       ~DB.delete
       ~DB.delete_dataset
       ~DB.delete_stream
@@ -35,7 +33,6 @@
       ~DB.patch
       ~DB.post
       ~DB.push_file
-      ~DB.query
       ~DB.update_metadata
       ~DB.upsert_signals
    
@@ -47,7 +44,6 @@
 
    .. autosummary::
    
-      ~DB.trino_info
       ~DB.client
    
    

{marpledata-3.4.0.dev1 → marpledata-3.6.0}/docs/api/marple.db.DataStream.rst

@@ -13,7 +13,6 @@
 
    .. autosummary::
    
-      ~DataStream.add_dataset
       ~DataStream.delete
       ~DataStream.get_dataset
       ~DataStream.get_datasets

{marpledata-3.4.0.dev1 → marpledata-3.6.0}/docs/api/marple.db.Dataset.rst

@@ -13,10 +13,6 @@
 
    .. autosummary::
    
-      ~Dataset.add_signal
-      ~Dataset.add_signals
-      ~Dataset.append
-      ~Dataset.cool
       ~Dataset.delete
       ~Dataset.download
       ~Dataset.fetch
@@ -24,7 +20,6 @@
       ~Dataset.get_signal
       ~Dataset.get_signals
       ~Dataset.update_metadata
-      ~Dataset.upsert_signals
       ~Dataset.wait_for_import
    
    

{marpledata-3.4.0.dev1 → marpledata-3.6.0}/docs/api/marple.db.Signal.rst

@@ -13,10 +13,10 @@
 
    .. autosummary::
    
-      ~Signal.cache_parquet
+      ~Signal.download
+      ~Signal.from_dict
       ~Signal.get_data
-      ~Signal.list_parquet_files
-      ~Signal.wait_until_cold
+      ~Signal.get_parquet_files
    
    
 

{marpledata-3.4.0.dev1 → marpledata-3.6.0}/docs/getting-started.rst

@@ -37,8 +37,9 @@ Marple DB quickstart
    dataset = dataset.wait_for_import(timeout=10)
 
 After import, you can add derived signals with
-``dataset.add_signal(...)`` / ``dataset.add_signals([...])``. See
-:doc:`tutorials` for a full example.
+``dataset.add_signal(...)`` / ``dataset.add_signals([...])``. For custom
+ingest without file parsing, use ``stream.add_dataset(...)`` then
+``add_signal``. See :doc:`tutorials` for a full example.
 
 ``stream.push_file(...)`` starts an ingestion and lets the Marple DB API choose
 the best upload mode for the deployment and file size. For large files, use a
@@ -49,6 +50,13 @@ longer ``wait_for_import`` timeout and optionally increase upload concurrency:
    dataset = stream.push_file("large_export.csv", concurrency=8)
    dataset = dataset.wait_for_import(timeout=180)
 
+To replace an existing dataset with the same name, pass ``overwrite=True``:
+
+.. code-block:: python
+
+   dataset = stream.push_file("examples_race.csv", overwrite=True)
+   dataset = dataset.wait_for_import(timeout=10)
+
 If direct storage uploads are blocked by your network or proxy, force upload
 through the Marple DB API server: