ravelpy

Python client for the Ravelry REST API, supporting read-only Basic Auth (public catalog data), personal account keys (full authenticated access), and OAuth 2.0 (scoped delegated access).

Built with Claude AI

The requirements, architecture, and implementation of ravelpy were developed collaboratively with Claude by Anthropic. Claude wrote the majority of the code in this repository through an iterative conversation-driven process. This is disclosed prominently because we believe AI development transparency matters.

Install

pip install ravelpy

To also run the optional Swagger UI server:

pip install "ravelpy[server]"

Auth

Ravelry supports three credential tiers:

Get your developer credentials from ravelry.com/pro/developer.

Basic Auth (read-only or personal key)

Set credentials as environment variables (or in a .env file):

RAVELRY_USERNAME=read-xxxxxxxxxxxx   # or your personal username
RAVELRY_API_KEY=your_api_key

from ravelpy import RavelryClient

# Read-only key — public catalog data only
client = RavelryClient(username="read-xxxxxxxxxxxx", api_key="your_api_key")

# Personal key — full authenticated access, all scopes auto-granted
client = RavelryClient(username="your_username", api_key="your_personal_key")

OAuth 2.0

from ravelpy import RavelryClient
from ravelpy.oauth import OAuthClient, OAuthScope

oauth = OAuthClient(
    client_id="your_client_id",
    client_secret="your_client_secret",
)

# Build an auth URL and redirect the user there
url, state = oauth.auth_url(scopes=[OAuthScope.OFFLINE])

# After the user grants access, exchange the code for a token
token = oauth.exchange_code(code="the_code_from_callback")

# Build a RavelryClient from the access token
client = RavelryClient.from_oauth_token(token.access_token)

See docs/authentication.md for the full OAuth scope list, a tested scope matrix, and notes on which endpoints require specific scopes.

Quickstart

RavelryClient is async-only. Use it as an async context manager:

import asyncio
from ravelpy import RavelryClient

async def main():
    async with RavelryClient(username="read-xxxxxxxxxxxx", api_key="your_api_key") as client:
        # Search for free sock patterns
        data, etag, raw = await client.patterns.search(
            query="socks", weight="fingering", availability="free"
        )
        for p in raw["patterns"]:
            print(p["name"])

        # Get a specific yarn
        data, etag, raw = await client.yarns.show(yarn_id=90897)
        print(raw["yarn"]["name"])

asyncio.run(main())

For a personal key or OAuth token (required for write endpoints and user data):

async with RavelryClient(username="your_username", api_key="your_personal_key") as client:
    data, etag, raw = await client.people.me()
    print(raw["user"]["username"])

    # Add a yarn to your stash
    _, _, raw = await client.stash.create("your_username", {
        "yarn_id": 95245,
        "colorway_name": "Natural",
        "skeins": 3,
    })
    print("New stash ID:", raw["stash"]["id"])

ETag caching

Every method returns (model, etag, raw_dict). Pass the etag back on subsequent calls — the server returns 304 Not Modified and both model and raw_dict will be None.

data, etag, raw = client.patterns.search(query="socks")

# later...
data, etag, raw = client.patterns.search(query="socks", etag=etag)
if data is None:
    print("not modified — use cached data")

API coverage

Swagger UI server

The examples/server.py FastAPI proxy exposes all endpoints with interactive docs:

uvicorn examples.server:app --reload

Open http://localhost:8000/docs.

Links

• Ravelry API documentation
• Ravelry Developer Agreement
• Report an issue

License

MIT — see LICENSE.