agent-discogs 0.2.0__tar.gz → 0.3.0__tar.gz

agent_discogs-0.3.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: agent-discogs
+Version: 0.3.0
+Summary: Token-efficient Discogs CLI for AI agents
+Keywords: ai-agent,cli,discogs,discogs-api,music-database
+Author: Jean-Marc Fontaine
+Author-email: Jean-Marc Fontaine <jm@jmfontaine.net>
+License-Expression: Apache-2.0
+License-File: LICENSE.txt
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.15
+Requires-Dist: click>=8.3.1
+Requires-Dist: discogs-sdk>=0.8.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/jmfontaine/agent-discogs
+Project-URL: Issues, https://github.com/jmfontaine/agent-discogs/issues
+Project-URL: Repository, https://github.com/jmfontaine/agent-discogs
+Description-Content-Type: text/markdown
+
+# agent-discogs
+
+A token-efficient Discogs CLI for AI agents that minimizes API calls.
+
+```bash
+agent-discogs search "Nine Inch Nails"
+agent-discogs get release @r352665      # ref from search output
+agent-discogs tracks @r352665          # tracklist shortcut
+agent-discogs price @r352665           # price guide shortcut
+```
+
+## Installation
+
+```bash
+pipx install agent-discogs
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install agent-discogs
+```
+
+Or with pip:
+
+```bash
+pip install agent-discogs
+```
+
+pipx, uv and pip need Python 3.10 or later.
+
+### Homebrew
+
+```bash
+brew install jmfontaine/tap/agent-discogs
+```
+
+The formula comes from the maintainer's [Homebrew](https://brew.sh/) tap. It installs the PyPI release into a virtualenv on Homebrew's own Python, whatever Python you have.
+
+To tap once and then use the short name:
+
+```bash
+brew tap jmfontaine/tap
+brew install agent-discogs
+```
+
+Or in a Brewfile:
+
+```ruby
+tap "jmfontaine/tap"
+brew "agent-discogs"
+```
+
+A prebuilt bottle exists only for Apple Silicon Macs on macOS 26 or later. Everywhere else (Intel Macs, earlier macOS, Linux) Homebrew builds from source, which needs Rust (for pydantic-core; Homebrew installs it as a build dependency) and takes a few minutes.
+
+`brew upgrade` installs a new release once the tap has picked it up from PyPI.
+
+### AI Coding Agent Skill
+
+Install the skill so your AI coding agent can use agent-discogs automatically:
+
+```bash
+npx skills add jmfontaine/agent-discogs
+```
+
+The installed skill is a thin pointer; the usage guide itself ships inside the package and is served by `agent-discogs skills get core`, so agents always read instructions that match the version they run (see [skills](https://github.com/jmfontaine/agent-discogs/blob/main/docs/commands.md#skills)).
+
+## Authentication
+
+Set your personal access token from [your Discogs developer settings](https://www.discogs.com/settings/developers):
+
+```bash
+export DISCOGS_TOKEN="your-token-here"
+```
+
+Credentials are required for price lookups, and Discogs' API documentation requires them for search too: unauthenticated searches currently get answers, but Discogs may refuse one with `auth_required`. Without any credentials the limit is 25 requests/minute; with a token, every command works at 60 requests/minute.
+
+`price` needs one thing more than a token or OAuth credentials: Discogs only returns price suggestions to accounts that have filled out their [seller settings](https://www.discogs.com/settings/seller). Until you do, the endpoint answers 404 and `price` tells you so; every other command is unaffected.
+
+The CLI sends whichever credentials discogs-sdk finds in the environment, in this order:
+
+1. `DISCOGS_TOKEN`;
+2. OAuth 1.0a (`DISCOGS_CONSUMER_KEY`, `DISCOGS_CONSUMER_SECRET`, `DISCOGS_ACCESS_TOKEN` and `DISCOGS_ACCESS_TOKEN_SECRET`, all four);
+3. a consumer key and secret alone (`DISCOGS_CONSUMER_KEY` and `DISCOGS_CONSUMER_SECRET`);
+4. otherwise none.
+
+A consumer key and secret get 60 requests/minute but identify an app, not a user, so `price` needs a token or OAuth, and so do `--owned`, `--in-wantlist`, `get owned`, `get collection`, `get lists` and `get wantlist`, which read your own collection, lists and wantlist. `get inventory` alone works without credentials: Discogs shows anyone a seller's For Sale listings. `agent-discogs status` reports the mode in use.
+
+> [!TIP]
+> Use a `.env` file with [direnv](https://direnv.net/) to avoid exporting tokens manually in every shell.
+
+## Commands
+
+```bash
+agent-discogs search release "The Downward Spiral" --year 1994
+agent-discogs search artist "Nine Inch Nails" --limit 10
+agent-discogs get artist @a3857
+agent-discogs get versions @m3719 --country US --format Vinyl
+agent-discogs get owned @r352665 @r847868
+agent-discogs search release --artist "Nine Inch Nails" --year 1994 --limit 20 --owned
+agent-discogs get collection --style Techno --format 12\" --max-requests 20
+agent-discogs get wantlist --for-sale --max-price 20 --currency EUR --max-requests 60
+agent-discogs get inventory <seller> --in-wantlist --condition VG+ --max-requests 60
+agent-discogs get lists
+agent-discogs get list 123
+agent-discogs get release @r352665 --json
+agent-discogs status
+agent-discogs cache clear
+agent-discogs skills get core
+```
+
+Each command, its own flags and its text output are described in [Commands](https://github.com/jmfontaine/agent-discogs/blob/main/docs/commands.md). The global flags (`--cached`, `--fresh`, `--debug`, `--color`), the output modes (`--json`, `--full`) and the `--max-requests` cap have their own pages:
+
+- `--json` and `--full`: [JSON output](https://github.com/jmfontaine/agent-discogs/blob/main/docs/json-output.md);
+- `--cached`, `--fresh` and `--max-requests`: [Caching and request budget](https://github.com/jmfontaine/agent-discogs/blob/main/docs/caching-and-budget.md);
+- `--debug`: [Debugging](https://github.com/jmfontaine/agent-discogs/blob/main/docs/debugging.md);
+- `--color`: [Color](https://github.com/jmfontaine/agent-discogs/blob/main/docs/debugging.md#color); the default, `auto`, colors a terminal only, never a pipe.
+
+For Tab completion in an interactive bash, zsh or fish shell, add `eval "$(agent-discogs completion zsh)"` (or `bash`) to the shell's startup file; see [Shell completion](https://github.com/jmfontaine/agent-discogs/blob/main/docs/commands.md#shell-completion) for fish.
+
+## Ref system
+
+Output includes typed refs that encode the entity type and Discogs ID. Copy them into subsequent commands.
+
+| Prefix | Type | Example |
+|---|---|---|
+| `@r` | Release | `@r352665` |
+| `@a` | Artist | `@a3857` |
+| `@m` | Master | `@m3719` |
+| `@l` | Label | `@l647` |
+
+Raw numeric IDs also work: `agent-discogs get release 352665`.
+
+Smart resolution: `get versions @r352665` auto-resolves the release to its master.
+
+## Documentation
+
+- [Commands](https://github.com/jmfontaine/agent-discogs/blob/main/docs/commands.md): `search` (filters, sorting, client-side scans, `--added-since`, `--owned`), `get` and its nouns (`get owned`, `get collection` and its filters, `get wantlist` and its `--for-sale` scan, `get inventory` and its grade, origin, price and `--in-wantlist` filters, `get lists` and `get list`), `tracks` / `price`, `status`, `cache`, `skills`, shell completion.
+- [JSON output](https://github.com/jmfontaine/agent-discogs/blob/main/docs/json-output.md): projections, `--full`, the pagination envelope, `owned` rows, collection rows, wantlist rows and their `market`, inventory listings and their `wantlist` object, lists and their items, non-ASCII and control-character escaping.
+- [Caching and request budget](https://github.com/jmfontaine/agent-discogs/blob/main/docs/caching-and-budget.md): `--cached` / `--fresh`, cache errors, rate limits, what each command costs, `--max-requests`.
+- [Errors](https://github.com/jmfontaine/agent-discogs/blob/main/docs/errors.md): the error layout, error codes, and the 401, 429 and connection-error hints.
+- [Debugging](https://github.com/jmfontaine/agent-discogs/blob/main/docs/debugging.md): the `--debug` panel, output encoding, how Discogs text is neutralized, and `--color`.
+
+## License
+
+agent-discogs is licensed under the [Apache License 2.0](LICENSE.txt).

agent_discogs-0.3.0/README.md

@@ -0,0 +1,146 @@
+# agent-discogs
+
+A token-efficient Discogs CLI for AI agents that minimizes API calls.
+
+```bash
+agent-discogs search "Nine Inch Nails"
+agent-discogs get release @r352665      # ref from search output
+agent-discogs tracks @r352665          # tracklist shortcut
+agent-discogs price @r352665           # price guide shortcut
+```
+
+## Installation
+
+```bash
+pipx install agent-discogs
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install agent-discogs
+```
+
+Or with pip:
+
+```bash
+pip install agent-discogs
+```
+
+pipx, uv and pip need Python 3.10 or later.
+
+### Homebrew
+
+```bash
+brew install jmfontaine/tap/agent-discogs
+```
+
+The formula comes from the maintainer's [Homebrew](https://brew.sh/) tap. It installs the PyPI release into a virtualenv on Homebrew's own Python, whatever Python you have.
+
+To tap once and then use the short name:
+
+```bash
+brew tap jmfontaine/tap
+brew install agent-discogs
+```
+
+Or in a Brewfile:
+
+```ruby
+tap "jmfontaine/tap"
+brew "agent-discogs"
+```
+
+A prebuilt bottle exists only for Apple Silicon Macs on macOS 26 or later. Everywhere else (Intel Macs, earlier macOS, Linux) Homebrew builds from source, which needs Rust (for pydantic-core; Homebrew installs it as a build dependency) and takes a few minutes.
+
+`brew upgrade` installs a new release once the tap has picked it up from PyPI.
+
+### AI Coding Agent Skill
+
+Install the skill so your AI coding agent can use agent-discogs automatically:
+
+```bash
+npx skills add jmfontaine/agent-discogs
+```
+
+The installed skill is a thin pointer; the usage guide itself ships inside the package and is served by `agent-discogs skills get core`, so agents always read instructions that match the version they run (see [skills](https://github.com/jmfontaine/agent-discogs/blob/main/docs/commands.md#skills)).
+
+## Authentication
+
+Set your personal access token from [your Discogs developer settings](https://www.discogs.com/settings/developers):
+
+```bash
+export DISCOGS_TOKEN="your-token-here"
+```
+
+Credentials are required for price lookups, and Discogs' API documentation requires them for search too: unauthenticated searches currently get answers, but Discogs may refuse one with `auth_required`. Without any credentials the limit is 25 requests/minute; with a token, every command works at 60 requests/minute.
+
+`price` needs one thing more than a token or OAuth credentials: Discogs only returns price suggestions to accounts that have filled out their [seller settings](https://www.discogs.com/settings/seller). Until you do, the endpoint answers 404 and `price` tells you so; every other command is unaffected.
+
+The CLI sends whichever credentials discogs-sdk finds in the environment, in this order:
+
+1. `DISCOGS_TOKEN`;
+2. OAuth 1.0a (`DISCOGS_CONSUMER_KEY`, `DISCOGS_CONSUMER_SECRET`, `DISCOGS_ACCESS_TOKEN` and `DISCOGS_ACCESS_TOKEN_SECRET`, all four);
+3. a consumer key and secret alone (`DISCOGS_CONSUMER_KEY` and `DISCOGS_CONSUMER_SECRET`);
+4. otherwise none.
+
+A consumer key and secret get 60 requests/minute but identify an app, not a user, so `price` needs a token or OAuth, and so do `--owned`, `--in-wantlist`, `get owned`, `get collection`, `get lists` and `get wantlist`, which read your own collection, lists and wantlist. `get inventory` alone works without credentials: Discogs shows anyone a seller's For Sale listings. `agent-discogs status` reports the mode in use.
+
+> [!TIP]
+> Use a `.env` file with [direnv](https://direnv.net/) to avoid exporting tokens manually in every shell.
+
+## Commands
+
+```bash
+agent-discogs search release "The Downward Spiral" --year 1994
+agent-discogs search artist "Nine Inch Nails" --limit 10
+agent-discogs get artist @a3857
+agent-discogs get versions @m3719 --country US --format Vinyl
+agent-discogs get owned @r352665 @r847868
+agent-discogs search release --artist "Nine Inch Nails" --year 1994 --limit 20 --owned
+agent-discogs get collection --style Techno --format 12\" --max-requests 20
+agent-discogs get wantlist --for-sale --max-price 20 --currency EUR --max-requests 60
+agent-discogs get inventory <seller> --in-wantlist --condition VG+ --max-requests 60
+agent-discogs get lists
+agent-discogs get list 123
+agent-discogs get release @r352665 --json
+agent-discogs status
+agent-discogs cache clear
+agent-discogs skills get core
+```
+
+Each command, its own flags and its text output are described in [Commands](https://github.com/jmfontaine/agent-discogs/blob/main/docs/commands.md). The global flags (`--cached`, `--fresh`, `--debug`, `--color`), the output modes (`--json`, `--full`) and the `--max-requests` cap have their own pages:
+
+- `--json` and `--full`: [JSON output](https://github.com/jmfontaine/agent-discogs/blob/main/docs/json-output.md);
+- `--cached`, `--fresh` and `--max-requests`: [Caching and request budget](https://github.com/jmfontaine/agent-discogs/blob/main/docs/caching-and-budget.md);
+- `--debug`: [Debugging](https://github.com/jmfontaine/agent-discogs/blob/main/docs/debugging.md);
+- `--color`: [Color](https://github.com/jmfontaine/agent-discogs/blob/main/docs/debugging.md#color); the default, `auto`, colors a terminal only, never a pipe.
+
+For Tab completion in an interactive bash, zsh or fish shell, add `eval "$(agent-discogs completion zsh)"` (or `bash`) to the shell's startup file; see [Shell completion](https://github.com/jmfontaine/agent-discogs/blob/main/docs/commands.md#shell-completion) for fish.
+
+## Ref system
+
+Output includes typed refs that encode the entity type and Discogs ID. Copy them into subsequent commands.
+
+| Prefix | Type | Example |
+|---|---|---|
+| `@r` | Release | `@r352665` |
+| `@a` | Artist | `@a3857` |
+| `@m` | Master | `@m3719` |
+| `@l` | Label | `@l647` |
+
+Raw numeric IDs also work: `agent-discogs get release 352665`.
+
+Smart resolution: `get versions @r352665` auto-resolves the release to its master.
+
+## Documentation
+
+- [Commands](https://github.com/jmfontaine/agent-discogs/blob/main/docs/commands.md): `search` (filters, sorting, client-side scans, `--added-since`, `--owned`), `get` and its nouns (`get owned`, `get collection` and its filters, `get wantlist` and its `--for-sale` scan, `get inventory` and its grade, origin, price and `--in-wantlist` filters, `get lists` and `get list`), `tracks` / `price`, `status`, `cache`, `skills`, shell completion.
+- [JSON output](https://github.com/jmfontaine/agent-discogs/blob/main/docs/json-output.md): projections, `--full`, the pagination envelope, `owned` rows, collection rows, wantlist rows and their `market`, inventory listings and their `wantlist` object, lists and their items, non-ASCII and control-character escaping.
+- [Caching and request budget](https://github.com/jmfontaine/agent-discogs/blob/main/docs/caching-and-budget.md): `--cached` / `--fresh`, cache errors, rate limits, what each command costs, `--max-requests`.
+- [Errors](https://github.com/jmfontaine/agent-discogs/blob/main/docs/errors.md): the error layout, error codes, and the 401, 429 and connection-error hints.
+- [Debugging](https://github.com/jmfontaine/agent-discogs/blob/main/docs/debugging.md): the `--debug` panel, output encoding, how Discogs text is neutralized, and `--color`.
+
+## License
+
+agent-discogs is licensed under the [Apache License 2.0](LICENSE.txt).

{agent_discogs-0.2.0 → agent_discogs-0.3.0}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
 build-backend = "uv_build"
-requires = ["uv-build>=0.12.13,<0.13"]
+requires = ["uv-build>=0.12.13,<0.14"]
 
 [project]
 name = "agent-discogs"
-version = "0.2.0"
+version = "0.3.0"
 description = "Token-efficient Discogs CLI for AI agents"
 readme = "README.md"
 keywords = [
@@ -28,7 +28,7 @@ classifiers = [
 ]
 dependencies = [
     "click>=8.3.1",
-    "discogs-sdk>=0.5.0",
+    "discogs-sdk>=0.8.1",
     "pydantic>=2.12.5",
 ]
 
@@ -47,6 +47,7 @@ agent-discogs = "agent_discogs:main"
 [dependency-groups]
 dev = [
     "deptry>=0.24",
+    "pre-commit>=4.6.2",
     "pyproject-fmt>=2.16.1",
     "pyright>=1.1.408",
     "ruff>=0.15.2",
@@ -107,7 +108,6 @@ select = [
 ignore = [
     "EM101",
     "EM102",
-    "PLC0415",
     "PLR0911",
     "PLR0912",
     "PLR0913",
@@ -121,7 +121,6 @@ ignore = [
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = [
-    "ARG001",
     "ARG005",
     "PLR2004",
     "S101",
@@ -137,13 +136,25 @@ max_supported_python = "3.15"
 addopts = "-m 'not live'"
 markers = ["live: hits the real Discogs API; run with `just test-live` (needs DISCOGS_TOKEN)"]
 
+[tool.coverage.run]
+source = ["agent_discogs"]
+
+[tool.coverage.report]
+fail_under = 100
+
 [tool.deadcode]
 ignore-names = [
+    "_color_terminal",
+    "_fake_api",
+    "_isolate_env",
+    "_patch_clients",
     "_patch_get",
     "_patch_search",
     "_reset_singleton",
+    "_real_client",
     "_scoped_client",
     "format_help",
     "get_skill",
+    "pytest_plugins",
     "skill_path",
 ]

{agent_discogs-0.2.0 → agent_discogs-0.3.0}/pyproject.toml.orig

@@ -1,10 +1,10 @@
 [build-system]
 build-backend = "uv_build"
-requires = [ "uv-build>=0.12.13,<0.13" ]
+requires = [ "uv-build>=0.12.13,<0.14" ]
 
 [project]
 name = "agent-discogs"
-version = "0.2.0"
+version = "0.3.0"
 description = "Token-efficient Discogs CLI for AI agents"
 readme = "README.md"
 keywords = [ "ai-agent", "cli", "discogs", "discogs-api", "music-database" ]
@@ -21,7 +21,11 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Programming Language :: Python :: 3.15",
 ]
-dependencies = [ "click>=8.3.1", "discogs-sdk>=0.5.0", "pydantic>=2.12.5" ]
+dependencies = [
+  "click>=8.3.1",
+  "discogs-sdk>=0.8.1",
+  "pydantic>=2.12.5",
+]
 urls.Homepage = "https://github.com/jmfontaine/agent-discogs"
 urls.Issues = "https://github.com/jmfontaine/agent-discogs/issues"
 urls.Repository = "https://github.com/jmfontaine/agent-discogs"
@@ -30,6 +34,7 @@ scripts.agent-discogs = "agent_discogs:main"
 [dependency-groups]
 dev = [
   "deptry>=0.24",
+  "pre-commit>=4.6.2",
   "pyproject-fmt>=2.16.1",
   "pyright>=1.1.408",
   "ruff>=0.15.2",
@@ -90,7 +95,6 @@ lint.select = [
 lint.ignore = [
   "EM101",   # raw-string-in-exception - the test doubles that raise use one-off literals; naming them first adds a line and no clarity
   "EM102",   # f-string-in-exception - refs.py and get.py interpolate the offending ref or noun, which is what makes the message actionable
-  "PLC0415", # import-outside-top-level - errors.py and __init__.py import discogs_sdk lazily so --help and --version never pay to load it
   "PLR0911", # too-many-return-statements - format_error() returns one tailored message per SDK exception type
   "PLR0912", # too-many-branches - verbose release output walks a long list of independently optional Discogs fields
   "PLR0913", # too-many-arguments - click hands every command option to the callback as its own keyword argument
@@ -102,12 +106,11 @@ lint.ignore = [
   "TRY003",  # raise-vanilla-args - these messages are read by agents, so they belong at the raise site rather than in an exception subclass
 ]
 lint.per-file-ignores."tests/**" = [
-  "ARG001",  # unused-function-argument - the fake _send() in test_pagination.py must accept params= because fetch_page passes it by keyword, then ignores it
   "ARG005",  # unused-lambda-argument - the SimpleNamespace lambdas standing in for SDK methods take the real signature and use only part of it
   "PLR2004", # magic-value-comparison - assertions compare against literal Discogs IDs and counts, which read better inline than as named constants
   "S101",    # assert - pytest expresses every assertion this way
   "S108",    # hardcoded-temp-file - test_formatting.py only formats /tmp/test-cache into the status output; nothing is created or written there
-  "SLF001",  # private-member-access - test_client.py resets the module-level _client singleton around each test
+  "SLF001",  # private-member-access - conftest.py's real_sdk resets the module-level client._client singleton, and tests read private state such as trace._trace
 ]
 
 [tool.pyproject-fmt]
@@ -120,13 +123,27 @@ ini_options.markers = [
   "live: hits the real Discogs API; run with `just test-live` (needs DISCOGS_TOKEN)",
 ]
 
+# Line coverage only. Branch coverage would fail fail_under today on partial
+# branches in cache.py (#18), formatting.py and projections.py.
+[tool.coverage]
+# Only the package: this also keeps out the test modules pytester writes under
+# the basetemp, which its in-process runs would otherwise add to the report.
+run.source = [ "agent_discogs" ]
+report.fail_under = 100
+
 [tool.deadcode]
 ignore-names = [
+  "_color_terminal",
+  "_fake_api",
+  "_isolate_env",
+  "_patch_clients",
   "_patch_get",
   "_patch_search",
   "_reset_singleton",
+  "_real_client",
   "_scoped_client",
   "format_help",
   "get_skill",        # click subcommands are registered by decorator, invisible to deadcode
+  "pytest_plugins",   # pytest reads it from conftest.py, invisible to deadcode
   "skill_path",
 ]