Deprecate Garth — final release v0.8.0 (#223)

matin · claude · web-flow · commit f99159a15c4c · 2026-03-27T17:10:17.000-07:00
* Deprecate Garth — final release v0.8.0 Garmin changed their auth flow, breaking the mobile auth approach Garth depends on. This is the final release with: - DeprecationWarning on import pointing to the announcement - Telemetry disabled by default - Development Status classifier set to Inactive - README and docs updated with deprecation notices See #222 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Move deprecation warning after imports to avoid noqa comments Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix ty type checker error for logfire = None assignment Newer ty versions promote invalid-assignment to error for assigning None to a module type. Add knot: ignore comment to suppress. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Fix ty: ignore syntax and upgrade ty to 0.0.26 Use correct `ty: ignore[invalid-assignment]` comment syntax and upgrade ty in lockfile to match CI. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Update telemetry docs and docstring to reflect disabled defaults Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
diff --git a/README.md b/README.md
@@ -1,104 +1,34 @@
 # Garth
 
-[![CI](https://github.com/matin/garth/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/matin/garth/actions/workflows/ci.yml?query=event%3Apush+branch%3Amain+workflow%3ACI)
-[![codecov](https://codecov.io/gh/matin/garth/branch/main/graph/badge.svg?token=0EFFYJNFIL)](https://codecov.io/gh/matin/garth)
+> **Garth is deprecated and no longer maintained.** Garmin changed their auth
+> flow, breaking the mobile auth approach that Garth depends on. I'm not in a
+> position to dedicate the time to adapt to these changes. See the
+> [announcement](https://github.com/matin/garth/discussions/222) for details.
+> Anyone is welcome to fork Garth as a starting point for a new library.
+
 [![PyPI version](https://img.shields.io/pypi/v/garth.svg?logo=python&logoColor=brightgreen&color=brightgreen)](https://pypi.org/project/garth/)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/garth)](https://pypistats.org/packages/garth)
-[![Documentation](https://img.shields.io/badge/docs-readthedocs-blue)](https://garth.readthedocs.io)
 
 Garmin SSO auth + Connect Python client
 
-## Features
-
-- OAuth1/OAuth2 authentication (OAuth1 token lasts ~1 year)
-- MFA support with custom handlers
-- Auto-refresh of OAuth2 token
-- Auto-resume from `GARTH_HOME` or `GARTH_TOKEN` environment variables
-- Works on Google Colab
-- Pydantic dataclasses for validated data
-- Built-in telemetry for diagnosing auth issues
-- Full test coverage
-
-## Installation
-
-```bash
-pip install garth
-```
-
-## Quick Start
-
-### Authenticate and save session
-
-```python
-import garth
-from getpass import getpass
-
-garth.login(input("Email: "), getpass("Password: "))
-garth.save("~/.garth")
-```
-
-### Resume session
-
-```python
-import garth
-from garth.exc import GarthException
+## About
 
-garth.resume("~/.garth")
-try:
-    garth.client.username
-except GarthException:
-    # Session is expired. You'll need to log in again
-    pass
-```
+Garth was a Python library for Garmin Connect API access with OAuth
+authentication. It reached 350k+ downloads per month and was translated into
+multiple programming languages.
 
-Or use environment variables for automatic session restoration:
+Garmin recently changed their auth flow, breaking the mobile auth approach
+that Garth and other libraries depend on
+([#217](https://github.com/matin/garth/issues/217)). This is the final
+release.
 
-```bash
-export GARTH_HOME=~/.garth
-# or
-export GARTH_TOKEN="eyJvYXV0aF90b2tlbi..."  # from `uvx garth login`
-```
+## For existing users
 
-```python
-import garth
-# Session is automatically loaded
-garth.client.username
-```
-
-### Fetch data
-
-```python
-# Get daily stress
-garth.DailyStress.list("2023-07-23", 7)
-
-# Get sleep data
-garth.SleepData.get("2023-07-20")
-
-# Get weight
-garth.WeightData.list("2025-06-01", 30)
-
-# Direct API calls
-garth.connectapi("/usersummary-service/stats/stress/weekly/2023-07-05/52")
-```
+If you already have a saved session with a valid OAuth1 token, Garth may
+continue to work until that token expires (~1 year from when it was issued).
+New logins will not work.
 
 ## Documentation
 
-Full documentation at **[garth.readthedocs.io](https://garth.readthedocs.io)**
-
-## MCP Server
-
-[`garth-mcp-server`](https://github.com/matin/garth-mcp-server) is in early development.
-
-To generate your `GARTH_TOKEN`, use `uvx garth login`.
-
-## Star History
-
-<!-- markdownlint-disable MD013 -->
-<a href="https://www.star-history.com/#matin/garth&Date">
-    <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=matin/garth&type=Date&theme=dark" />
-        <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=matin/garth&type=Date" />
-        <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=matin/garth&type=Date" />
-    </picture>
-</a>
-<!-- markdownlint-enable MD013 -->
+Documentation is still available at
+**[garth.readthedocs.io](https://garth.readthedocs.io)** for reference.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,5 +1,10 @@
 # Getting Started
 
+!!! warning "Deprecated"
+    **Garth is deprecated and no longer maintained.** New logins will not work
+    due to changes in Garmin's auth flow. See the
+    [announcement](https://github.com/matin/garth/discussions/222) for details.
+
 ## Installation
 
 ### From PyPI
diff --git a/docs/index.md b/docs/index.md
@@ -2,65 +2,34 @@
 
 Garmin SSO auth + Connect Python client
 
-[![CI](https://github.com/matin/garth/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/matin/garth/actions/workflows/ci.yml?query=event%3Apush+branch%3Amain+workflow%3ACI)
-[![codecov](https://codecov.io/gh/matin/garth/branch/main/graph/badge.svg?token=0EFFYJNFIL)](https://codecov.io/gh/matin/garth)
-[![PyPI version](https://img.shields.io/pypi/v/garth.svg?logo=python&logoColor=brightgreen&color=brightgreen)](https://pypi.org/project/garth/)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/garth)](https://pypistats.org/packages/garth)
+!!! warning "Deprecated"
+    **Garth is deprecated and no longer maintained.** Garmin changed their auth
+    flow, breaking the mobile auth approach that Garth depends on. See the
+    [announcement](https://github.com/matin/garth/discussions/222) for details.
+    Anyone is welcome to fork Garth as a starting point for a new library.
 
-## Why Garth?
+## About
 
-Garth is meant for personal use and follows the philosophy that your data is
-your data. You should be able to download it and analyze it in the way that
-you'd like. In my case, that means processing with Google Colab, Pandas,
-Matplotlib, etc.
+Garth was a Python library for Garmin Connect API access with OAuth
+authentication. It reached 350k+ downloads per month and was translated into
+multiple programming languages.
 
-There are already a few Garmin Connect libraries. Why write another?
+Garmin recently changed their auth flow, breaking the mobile auth approach
+that Garth and other libraries depend on
+([#217](https://github.com/matin/garth/issues/217)). This is the final
+release.
 
-### Authentication and stability
+## For existing users
 
-The most important reasoning is to build a library with authentication that
-works on [Google Colab](https://colab.research.google.com/) and doesn't require
-tools like Cloudscraper. Garth, in comparison:
+If you already have a saved session with a valid OAuth1 token, Garth may
+continue to work until that token expires (~1 year from when it was issued).
+New logins will not work.
 
-1. Uses OAuth1 and OAuth2 token authentication after initial login
-1. OAuth1 token survives for a year
-1. Supports MFA
-1. Auto-refresh of OAuth2 token when expired
-1. Works on Google Colab
-1. Uses Pydantic dataclasses to validate and simplify use of data
-1. Full test coverage
+## Documentation
 
-### JSON vs HTML
+The rest of this documentation is preserved for reference.
 
-Using `garth.connectapi()` allows you to make requests to the Connect API
-and receive JSON vs needing to parse HTML. You can use the same endpoints the
-mobile app uses.
-
-This also goes back to authentication. Garth manages the necessary Bearer
-Authentication (along with auto-refresh) necessary to make requests routed to
-the Connect API.
-
-## Quick Start
-
-```bash
-pip install garth
-```
-
-```python
-import garth
-from getpass import getpass
-
-# Login and save session
-garth.login(input("Email: "), getpass("Password: "))
-garth.save("~/.garth")
-
-# Later, resume the session
-garth.resume("~/.garth")
-```
-
-## Next Steps
-
-- [Getting Started](getting-started.md) - Detailed authentication and session management
+- [Getting Started](getting-started.md) - Authentication and session management
 - [Configuration](configuration.md) - Domain and proxy settings
-- [API Reference](api/stats.md) - Explore available data types
+- [API Reference](api/stats.md) - Available data types
 - [Examples](examples.md) - Google Colab notebooks
diff --git a/docs/telemetry.md b/docs/telemetry.md
@@ -2,29 +2,8 @@
 
 Garth includes built-in telemetry using
 [Pydantic Logfire](https://pydantic.dev/logfire) for logging and observability.
-Telemetry is **enabled by default** to help diagnose authentication issues. It
-is **isolated to Garth's requests only** — it won't affect other HTTP clients
-in your application.
-
-## Why telemetry is on by default
-
-Garmin occasionally changes their authentication endpoints in ways that only
-affect a subset of users — for example, the
-[SSO migration](https://github.com/cyberjunky/python-garminconnect/issues/332)
-that caused 403 errors for some users while others were unaffected. Without
-telemetry, these issues are nearly impossible to reproduce or diagnose. With
-default-on telemetry, maintainers can look up the exact request/response
-sequence for a failing session using the session ID.
-
-Each session generates a unique `session_id` that is printed to stdout when
-garth is imported:
-
-```text
-Garth session: a01e3fc1d5ac4c9a
-```
-
-When reporting issues, include your session ID so maintainers can look up your
-request logs.
+Telemetry is **disabled by default** as of v0.8.0 since Garth is no longer
+actively maintained.
 
 ## Disable telemetry
 
@@ -66,8 +45,8 @@ Telemetry settings can be configured via environment variables with the
 
 | Environment Variable | Default | Description |
 |---|---|---|
-| `GARTH_TELEMETRY_ENABLED` | `true` | Enable/disable telemetry |
-| `GARTH_TELEMETRY_SEND_TO_LOGFIRE` | `true` | Send to Logfire Cloud |
+| `GARTH_TELEMETRY_ENABLED` | `false` | Enable/disable telemetry |
+| `GARTH_TELEMETRY_SEND_TO_LOGFIRE` | `false` | Send to Logfire Cloud |
 | `GARTH_TELEMETRY_TOKEN` | *(built-in)* | Logfire write token |
 
 ## What gets logged
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,7 +16,7 @@ requires-python = ">=3.10"
 readme = "README.md"
 license = {text = "MIT"}
 classifiers = [
-    "Development Status :: 5 - Production/Stable",
+    "Development Status :: 7 - Inactive",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
diff --git a/src/garth/__init__.py b/src/garth/__init__.py
@@ -1,3 +1,5 @@
+import warnings
+
 from .data import (
     Activity,
     BodyBatteryData,
@@ -32,6 +34,14 @@
 from .version import __version__
 
 
+warnings.warn(
+    "Garth is deprecated and no longer maintained. "
+    "See https://github.com/matin/garth/discussions/222",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+
 __all__ = [
     "Activity",
     "BodyBatteryData",
diff --git a/src/garth/telemetry.py b/src/garth/telemetry.py
@@ -16,7 +16,7 @@
 
     LOGFIRE_AVAILABLE = True
 except ImportError:  # pragma: no cover
-    logfire = None  # type: ignore[assignment]
+    logfire = None  # type: ignore[assignment]  # ty: ignore[invalid-assignment]
     LOGFIRE_AVAILABLE = False
 
 
@@ -109,8 +109,8 @@ class Telemetry(BaseSettings):
         extra="ignore",
     )
 
-    enabled: bool = True
-    send_to_logfire: bool = True
+    enabled: bool = False
+    send_to_logfire: bool = False
     token: str = DEFAULT_TOKEN
     callback: Callable[[dict], None] | None = Field(default=None, exclude=True)
     session_id: str = Field(
@@ -176,11 +176,11 @@ def configure(
         callback: Callable[[dict], None] | None = None,
     ):
         """
-        Configure telemetry. Enabled by default.
+        Configure telemetry. Disabled by default.
 
         Args:
-            enabled: Enable/disable telemetry (default: True)
-            send_to_logfire: Send to Logfire Cloud (default: True)
+            enabled: Enable/disable telemetry (default: False)
+            send_to_logfire: Send to Logfire Cloud (default: False)
             token: Logfire write token
             callback: Custom callback for telemetry data. If provided,
                 logfire will not be configured and data will be passed
diff --git a/src/garth/version.py b/src/garth/version.py
@@ -1 +1 @@
-__version__ = "0.7.11"
+__version__ = "0.8.0"
diff --git a/tests/test_telemetry.py b/tests/test_telemetry.py
@@ -52,8 +52,8 @@ def test_telemetry_defaults(monkeypatch):
     monkeypatch.delenv("GARTH_TELEMETRY_SEND_TO_LOGFIRE", raising=False)
 
     t = Telemetry()
-    assert t.enabled is True
-    assert t.send_to_logfire is True
+    assert t.enabled is False
+    assert t.send_to_logfire is False
     assert t.token == DEFAULT_TOKEN
     assert t.callback is None
     assert t.session_id  # non-empty
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-__version__ = "0.7.11"`
	`1`	`+__version__ = "0.8.0"`