Metadata-Version: 2.4
Name: newwave
Version: 0.2.0
Summary: Drop-in replacement for Pythons wave.py
Project-URL: Homepage, https://codeberg.org/michielb/newwave
Project-URL: Changelog, https://codeberg.org/michielb/newwave/src/branch/main/CHANGES.md
Project-URL: Code, https://codeberg.org/michielb/newwave
Project-URL: Issue tracker, https://codeberg.org/michielb/newwave/issues
Author-email: "Michiel W. Beijen" <mb@x14.nl>
License-Expression: PSF-2.0
License-File: LICENSE.txt
Keywords: audio,pcm,wave
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# newwave - drop-in replacement for wave.py

_"Enjoy the silence"_

`newwave` is a drop-in replacement for Python's standard library `wave` module,
which is used for reading and writing WAVE audio files.

It backports features from newer Python versions to older ones, so you can use
the latest `wave` improvements on Python 3.10 and later.

## Features

Features backported from newer Python versions:

- Support for `bytes` and path-like objects in `wave.open()` (from Python 3.15)
- Fix for `Wave_write` emitting unraisable exception when `open()` raises (from Python 3.15)
- Removal of deprecated `setmark`, `getmark`, `getmarkers` interfaces (from Python 3.15)
- Support for reading WAVE_FORMAT_EXTENSIBLE files (from Python 3.12)

## Installation

```bash
pip install newwave
```
or with uv:

```bash
uv add newwave
```

Requires Python 3.10 or later.

## Usage

Simply replace your `wave` import with `newwave`:

```python
# Before
import wave

# After
import newwave as wave
```

All existing code using `wave` will continue to work:

```python
import newwave as wave

with wave.open('audio.wav', 'rb') as f:
    print(f.getnchannels(), f.getsampwidth(), f.getframerate())
```

## Relationship to CPython

`newwave` is not a fork in spirit, but a compatibility and incubation layer for
Python’s standard-library `wave` module.

The goals of this project are to:

- Backport features from newer Python releases to older supported versions.
- Provide fixes for correctness issues in `wave.py`, such as malformed headers
  or incorrect frame padding.
- Experiment with and stabilize enhancements (e.g. higher bit depths, extended
  formats) before proposing them upstream to CPython.

Where practical, fixes and features developed in `newwave` are intended to be
upstreamed to CPython. Some enhancements may remain in `newwave` if they are
not suitable for inclusion in the standard library due to
backward-compatibility, policy, or maintenance constraints.

`newwave` aims to remain a drop-in replacement for `wave`, preserving the
public API and behavior of the standard library wherever possible.

## Development

This project uses [uv](https://docs.astral.sh/uv/) for dependency management and running tests.

### Prerequisites

- [uv](https://docs.astral.sh/uv/getting-started/installation/) must be installed

### Running tests

A `Makefile` is provided for common development tasks:

```bash
make test       # Run tests with the default Python version
make typecheck  # Run type checker (ty)
make fulltest   # Run type checker + tests on Python 3.10–3.15
make clean      # Remove cache directories
```

Or run tests directly:

```bash
uv run pytest
```

_Make WAVEs!_
