Skip to content

Commit ea43f03

Browse files
DennisMoschinaDennisMoschina
committed
docs: update migration details and deprecation warnings for open-earable-python
1 parent 11fe098 commit ea43f03

9 files changed

Lines changed: 118 additions & 7 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
## 0.0.3
2+
3+
* deprecated `open-earable-python` in favor of `open-wearable`
4+
* added a visible runtime `FutureWarning` on `open_earable_python` imports with migration instructions
5+
* added a dedicated migration guide at `docs/migration-to-open-wearable.md`
6+
* updated README/docs/package metadata to direct users to `open-wearable`
7+
* announced maintenance mode timeline for `open-earable-python` through December 31, 2026
8+
19
## 0.0.2
210

311
* added access to raw microphone dataframes

‎README.md‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,23 @@
11
# Open Earable Python
22

3+
> [!WARNING]
4+
> `open-earable-python` is deprecated and has been renamed to **`open-wearable`**.
5+
> Migrate now:
6+
> - Install: `pip install open-wearable`
7+
> - Update imports: `from open_earable_python import ...` -> `from open_wearable import ...`
8+
> - Deprecation timeline: this package receives only critical fixes until **December 31, 2026**.
9+
> - Migration guide: [docs/migration-to-open-wearable.md](docs/migration-to-open-wearable.md)
10+
311
Python toolkit for parsing and analyzing multi-sensor OpenEarable recordings.
412

513
## Installation
614

15+
```bash
16+
pip install open-wearable
17+
```
18+
19+
Legacy package (deprecated):
20+
721
```bash
822
pip install open-earable-python
923
```
@@ -21,7 +35,7 @@ pip install -e .
2135
## Quick Example
2236

2337
```python
24-
from open_earable_python import SensorDataset
38+
from open_wearable import SensorDataset
2539

2640
dataset = SensorDataset("recording.oe")
2741

@@ -40,6 +54,7 @@ audio_df = dataset.get_audio_dataframe()
4054
- [Getting started](docs/getting-started.md)
4155
- [Data model and sensor channels](docs/data-model.md)
4256
- [API reference](docs/api-reference.md)
57+
- [Migration to open-wearable](docs/migration-to-open-wearable.md)
4358

4459
## License
4560

‎docs/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
11
# Open Earable Python Documentation
22

3+
> [!WARNING]
4+
> `open-earable-python` is deprecated and renamed to **`open-wearable`**.
5+
> Use `pip install open-wearable` and migrate imports to `open_wearable`.
6+
> See [Migration to open-wearable](migration-to-open-wearable.md).
7+
38
`open-earable-python` parses `.oe` recordings into pandas DataFrames and exposes convenient accessors for OpenEarable sensor streams.
49

510
## Contents
611

712
- [Getting started](getting-started.md)
813
- [Data model and sensor channels](data-model.md)
914
- [API reference](api-reference.md)
15+
- [Migration to open-wearable](migration-to-open-wearable.md)
1016

1117
## Package Scope
1218

‎docs/api-reference.md‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,17 @@
11
# API Reference
22

3+
> [!WARNING]
4+
> `open-earable-python` is deprecated and renamed to **`open-wearable`**.
5+
> Prefer importing from `open_wearable`.
6+
37
## Package Exports
48

9+
```python
10+
from open_wearable import SensorDataset, load_recordings
11+
```
12+
13+
Legacy import path (deprecated):
14+
515
```python
616
from open_earable_python import SensorDataset, load_recordings
717
```
@@ -102,7 +112,7 @@ load_recordings(file_paths: Sequence[str]) -> List[SensorDataset]
102112

103113
Creates `SensorDataset` objects for existing files only.
104114

105-
## Parser Module (`open_earable_python.parser`)
115+
## Parser Module (`open_wearable.parser`)
106116

107117
Core classes and helpers for decoding binary packets:
108118

@@ -114,7 +124,7 @@ Core classes and helpers for decoding binary packets:
114124
- `interleaved_mic_to_stereo(samples)`: converts interleaved samples to stereo.
115125
- `mic_packet_to_stereo_frames(packet, sampling_rate)`: timestamp + stereo frame conversion.
116126

117-
## Scheme Module (`open_earable_python.scheme`)
127+
## Scheme Module (`open_wearable.scheme`)
118128

119129
Defines sensor schema primitives:
120130

‎docs/data-model.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Data Model and Sensor Channels
22

3+
> [!WARNING]
4+
> `open-earable-python` is deprecated and renamed to **`open-wearable`**.
5+
> Migration guide: [migration-to-open-wearable.md](migration-to-open-wearable.md).
6+
37
## Time Index
48

59
All sensor DataFrames are indexed by `timestamp` in seconds (`float`), derived from packet timestamps in microseconds.

‎docs/getting-started.md‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,23 @@
11
# Getting Started
22

3+
> [!WARNING]
4+
> `open-earable-python` is deprecated and renamed to **`open-wearable`**.
5+
> Install `open-wearable` for new projects and migrate imports to `open_wearable`.
6+
> Migration steps: [migration-to-open-wearable.md](migration-to-open-wearable.md).
7+
38
## Requirements
49

510
- Python 3.9+
611
- `numpy`, `pandas`, `scipy`, `ipython` (installed automatically with this package)
712

813
## Installation
914

15+
```bash
16+
pip install open-wearable
17+
```
18+
19+
Deprecated legacy package:
20+
1021
```bash
1122
pip install open-earable-python
1223
```
@@ -24,7 +35,7 @@ pip install -e .
2435
## Load a Recording
2536

2637
```python
27-
from open_earable_python import SensorDataset
38+
from open_wearable import SensorDataset
2839

2940
dataset = SensorDataset("my_recording.oe")
3041
```
@@ -88,7 +99,7 @@ dataset.save_csv("recording.csv")
8899
## Load Multiple Files
89100

90101
```python
91-
from open_earable_python import load_recordings
102+
from open_wearable import load_recordings
92103

93104
recordings = load_recordings(["session1.oe", "session2.oe"])
94105
for rec in recordings:

‎docs/migration-to-open-wearable.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Migration to open-wearable
2+
3+
`open-earable-python` has been renamed to `open-wearable`.
4+
5+
This follows the common Python package-rename migration pattern:
6+
7+
- Keep the old package available temporarily as a compatibility package.
8+
- Emit a runtime deprecation warning from the old import path.
9+
- Point users to a single new package name and migration guide.
10+
- Set and communicate a concrete deprecation timeline.
11+
12+
## Timeline
13+
14+
- Rename announced: February 24, 2026.
15+
- `open-earable-python` maintenance mode until December 31, 2026 (critical fixes only).
16+
- New features should target `open-wearable`.
17+
18+
## What to Change
19+
20+
1. Update install commands:
21+
22+
```bash
23+
pip uninstall open-earable-python
24+
pip install open-wearable
25+
```
26+
27+
2. Update imports:
28+
29+
```python
30+
# Old (deprecated)
31+
from open_earable_python import SensorDataset, load_recordings
32+
33+
# New
34+
from open_wearable import SensorDataset, load_recordings
35+
```
36+
37+
3. Pin the new package in your environment files (`requirements.txt`, lockfiles, CI configs).
38+
39+
## Notes for Maintainers
40+
41+
- Keep the deprecation warning in the legacy package import path.
42+
- Keep this migration guide linked from README, docs index, and package metadata.
43+
- Keep deprecation and end-of-support dates explicit in release notes.

‎pyproject.toml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@ build-backend = "setuptools.build_meta"
55
[project]
66
name = "open-earable-python"
77
dynamic = ["version"]
8-
description = "Reader and utilities for multi-sensor OpenEarable recordings."
8+
description = "DEPRECATED: renamed to open-wearable. Reader and utilities for multi-sensor OpenEarable recordings."
99
readme = "README.md"
1010
requires-python = ">=3.9"
1111
license = "MIT"
1212
license-files = ["LICEN[CS]E*"]
1313
authors = [
1414
{ name = "Karlsruhe Institut of Technology (KIT)", email = "open-earable@lists.kit.edu" }
1515
]
16-
keywords = ["openearable", "earable", "sensors", "imu", "ppg", "audio", "wearables", ".oe"]
16+
keywords = ["openearable", "open-wearable", "earable", "sensors", "imu", "ppg", "audio", "wearables", ".oe", "deprecated"]
1717
classifiers = [
1818
"Programming Language :: Python :: 3",
1919
"Development Status :: 4 - Beta",
@@ -33,6 +33,8 @@ dependencies = [
3333
[project.urls]
3434
Source = "https://github.com/OpenEarable/open-earable-python"
3535
Issues = "https://github.com/OpenEarable/open-earable-python/issues"
36+
"Migration Guide" = "https://github.com/OpenEarable/open-earable-python/blob/main/docs/migration-to-open-wearable.md"
37+
"New Package (PyPI)" = "https://pypi.org/project/open-wearable/"
3638

3739
[tool.setuptools_scm]
3840
version_scheme = "no-guess-dev"

‎src/open_earable_python/__init__.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,20 @@
1+
import warnings
2+
13
from .dataset import (
24
SensorDataset,
35
load_recordings,
46
)
57

8+
_DEPRECATION_MESSAGE = (
9+
"open-earable-python is deprecated and has been renamed to open-wearable. "
10+
"Install open-wearable and migrate imports from `open_earable_python` to "
11+
"`open_wearable`. This package will no longer be developed or maintained,"
12+
" and will eventually be removed from PyPI. "
13+
)
14+
15+
# Use FutureWarning so migration guidance is visible by default.
16+
warnings.warn(_DEPRECATION_MESSAGE, FutureWarning, stacklevel=2)
17+
618
__all__ = [
719
"SensorDataset",
820
"load_recordings",

0 commit comments

Comments
 (0)