Metadata-Version: 2.3
Name: reverb-python
Version: 0.1.0
Summary: Python CLI and client library for the Reverb.com API
Keywords: reverb,music,marketplace,api,cli
Author: Gil Aviv
Author-email: Gil Aviv <reverb-python@gil.fyi>
License: MIT License
         
         Copyright (c) 2026 Gil Aviv
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: babel>=2.18.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: requests>=2.32.5
Requires-Dist: structlog>=25.5.0
Requires-Dist: toml>=0.10.2
Requires-Dist: typer>=0.24.1
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/ggiill/reverb-python
Project-URL: Repository, https://github.com/ggiill/reverb-python
Project-URL: Issues, https://github.com/ggiill/reverb-python/issues
Description-Content-Type: text/markdown

# reverb-python

[![PyPI](https://img.shields.io/pypi/v/reverb-python)](https://pypi.org/project/reverb-python/)
[![Python versions](https://img.shields.io/pypi/pyversions/reverb-python)](https://pypi.org/project/reverb-python/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A Python CLI and client library for [Reverb](https://reverb.com)'s [API](https://www.reverb-api.com).

## Install

```sh
pip install reverb-python   # or: uv add reverb-python
```

The CLI and client authenticate with a Reverb personal access token, read from the `REVERB_PERSONAL_ACCESS_TOKEN` environment variable:

```sh
export REVERB_PERSONAL_ACCESS_TOKEN="your-token"
reverb --help
```

(Product search and price guide are public and need no token.)

## Usage

### CLI

**Listings**

| Command | Description |
|---|---|
| `reverb listings list` | Your live listings |
| `reverb listings list --ownership all --query "fender jazz"` | Search all listings |
| `reverb listings list --state all` | Include sold listings |
| `reverb listings list --ownership drafts` | Your drafts |
| `reverb listings list --condition excellent --price-min 500` | Filter by condition/price |
| `reverb listings list --fields title --fields price` | Choose columns |
| `reverb listings list --output json` | JSON output |

**Orders**

| Command | Description |
|---|---|
| `reverb orders list` | Your selling orders |
| `reverb orders list --side buying` | Your purchases |
| `reverb orders list --status awaiting_shipment` | Needs shipping |
| `reverb orders list --status awaiting_feedback` | Needs feedback |
| `reverb orders list --limit 10` | Limit results |

**Feedback**

| Command | Description |
|---|---|
| `reverb feedback list` | Received feedback |
| `reverb feedback list --direction sent` | Feedback you've left |

**Conversations**

| Command | Description |
|---|---|
| `reverb conversations list` | All conversations |
| `reverb conversations list --unread-only` | Unread only |
| `reverb conversations list --search "jazz bass"` | Search |

**Payouts**

| Command | Description |
|---|---|
| `reverb payouts list` | All payouts |

**Products & Price Guide**

| Command | Description |
|---|---|
| `reverb products search --query "Telecaster"` | Search product catalog |
| `reverb products search --make Fender --query "American Vintage 62 Precision Bass"` | Narrow by brand |
| `reverb products price-guide <id>` | Price history for a product |
| `reverb products price-guide <id> --condition used --number-of-months 12` | Longer price history |

**Account**

| Command | Description |
|---|---|
| `reverb account show` | Profile details |
| `reverb account counts` | Actionable item counts |
| `reverb account addresses` | Saved addresses |

### Client library

```python
>>> from reverb_python.client import ReverbHttpClient
>>> from reverb_python.enums import ListingOwnership, PriceGuideCondition, ReverbEndpoint
>>> from reverb_python.schemas.listings import ListingSearchFilters

>>> client = ReverbHttpClient(personal_access_token="your-token")

>>> listings = client.get_listings(filters=ListingSearchFilters(query="fender jazz bass"), ownership=ListingOwnership.MINE)
>>> orders = client.get_orders(endpoint=ReverbEndpoint.MY_ORDERS_SELLING_ALL)
>>> feedback = client.get_feedback(endpoint=ReverbEndpoint.MY_FEEDBACK_RECEIVED)
>>> conversations = client.get_conversations(unread_only=True)
>>> payouts = client.get_payouts()
>>> account = client.get_account()
>>> counts = client.get_counts()
>>> products = client.search_comparison_shopping_pages(make="Fender", query="American Vintage 62 Precision Bass")
>>> price_guide = client.get_price_guide(product_id=products[0].id, condition=PriceGuideCondition.USED, number_of_months=12)

```

## Development

See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
