SweatStack Python client library

This is the official Python client library for SweatStack.

Documentation can be found here.

Sports follow OpenSportTaxonomy: sweatstack.Sport is the OST Sport type. See the OpenSportTaxonomy Python guide for the full Sport API.

Install

uv add "sweatstack[polars]"          # analysis with Polars
uv add "sweatstack[pandas]"          # analysis with pandas
uv add "sweatstack[arrow]" duckdb    # SQL over your data with DuckDB
uv add sweatstack                    # models only: FastAPI services, webhook consumers

sweatstack[streamlit] and sweatstack[jupyter] include pandas. Extras combine: sweatstack[polars,arrow] for Polars frames that DuckDB can query.

Choosing your frame library

Every method that returns a collection takes output=. Time-series endpoints return "pandas", "polars", "arrow" or "bytes"; list endpoints return "models" (default), "pandas", "polars" or "arrow". When you don't say, time series come back in the frame library you installed: Polars, then pandas, then Arrow. Set it once to be explicit.

from datetime import date
from pathlib import Path

import polars as pl
import sweatstack

sweatstack.authenticate()

df = sweatstack.get_activity_data(activity_id)                    # Polars if installed, else pandas
pf = sweatstack.get_activity_data(activity_id, output="polars")   # polars.DataFrame
tb = sweatstack.get_activity_data(activity_id, output="arrow")    # pyarrow.Table

sweatstack.set_output("polars")                                   # or Client(output="polars")
season = sweatstack.get_longitudinal_data(sports=["cycling"], start=date(2025, 1, 1))
season.group_by("activity_id").agg(pl.col("power").mean())

acts = sweatstack.get_activities(output="polars")                 # nested fields as structs
acts.unnest("summary").unnest("power").select("id", "mean", "max")

raw = sweatstack.get_longitudinal_data(sports=["cycling"], start=date(2025, 1, 1), output="bytes")
Path("season.parquet").write_bytes(raw)                           # then query it with DuckDB

No frame carries an index: timestamp, the mean-max metric value and the dailies date are ordinary first columns on every backend. pandas frames keep float64 dtypes; Polars and Arrow keep the compact wire dtypes.

Using DuckDB

DuckDB queries every output directly. Its Python API bridges in-memory frames through pyarrow, so install sweatstack[arrow] for the first two routes.

Route	Code	Needs
Arrow table	`tb = sweatstack.get_longitudinal_data(..., output="arrow")` then `duckdb.sql("select ... from tb")`	`sweatstack[arrow]`
Polars frame	`pf = sweatstack.get_longitudinal_data(..., output="polars")` then `duckdb.sql("select ... from pf")`	`sweatstack[polars,arrow]`
Parquet file	`Path("season.parquet").write_bytes(sweatstack.get_longitudinal_data(..., output="bytes"))` then `duckdb.sql("select ... from 'season.parquet'")`	nothing extra

import duckdb
import sweatstack
from datetime import date

tb = sweatstack.get_longitudinal_data(sports=["cycling"], start=date(2025, 1, 1), output="arrow")
duckdb.sql("""
    select sport, count(distinct activity_id) as rides, round(avg(power)) as avg_power
    from tb group by sport order by rides desc
""")

Durations arrive as INTERVAL and timestamps as TIMESTAMP WITH TIME ZONE. With an [arrow]-only install, output defaults to "arrow", so the output= above is optional.

Upgrading from 0.88 and earlier

Four mechanical changes:

Install line. pandas is an extra now: uv add "sweatstack[pandas]" (or [polars], or [arrow] for DuckDB). Streamlit and Jupyter extras already include pandas.
Keep pandas frames explicitly. If Polars is also installed, time series now come back as Polars frames. Add sweatstack.set_output("pandas") once (or Client(output="pandas")) to keep every frame exactly as before.
as_dataframe=True → output="pandas".
Indexes are columns. If you relied on df.index (.loc[timestamp], .resample(), .plot()), add .set_index("timestamp") (or "power", "speed", "date") once after the call. The set of columns is unchanged; the former index comes first.

Metadata

Release files for sweatstack 0.89.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sweatstack 0.89.0
File	Size	Uploaded
sweatstack-0.89.0.tar.gz	314.5 kB	Sep 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sweatstack 0.89.0
File	Interpreter	ABI	Platform	Reset
sweatstack-0.89.0-py3-none-any.whl 85.3 kB Sep 28, 2026	Python 3	none	any	Details

Total release size: 399.7 kB

Release files / sweatstack-0.89.0.tar.gz

Download URL	sweatstack-0.89.0.tar.gz
Size	314.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`181941ccccc9ae389520dc782c78ed7b4bf82f48e882ba1fe601ebc8ab10d2c7`
BLAKE2b-256 checksum How to use checksums	`d31a414f1f132f7405933e69410a93392511e9369d36eb197498f0239b5404d7`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.10.10`

Release files / sweatstack-0.89.0-py3-none-any.whl

Download URL	sweatstack-0.89.0-py3-none-any.whl
Size	85.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f910136902cbae5c8189af4fe9427f98ea8e1f393f22d8de1a6cc6f7264c7fd2`
BLAKE2b-256 checksum How to use checksums	`72d2d7d68cc623ad80b3daaae8af758f697331768df7ad95370175ff58402497`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.10.10`