Cru Trading API for Python

The Python SDK for the Cru Trading API, Cru World Wine's partner REST API. Read Cru's live bid and offer books for every wine, manage your own bids and offers, see your portfolio, purchases and sales, and trade: buy an offer or sell into a bid. It has a synchronous client, Cru, and an asyncio one, AsyncCru, with typed models for every answer, automatic retries and OAuth token refresh, and nothing to install beyond httpx.

Installation

pip install cruworldwine

Python 3.9 or later.

Connecting

With a partner credential, whose writes run at once:

from cruworldwine import Cru

with Cru(client_key='cru_live_...', client_secret='...', market='uk') as cru:
    client = cru.ping().client
    print(client.organisation, client.market, client.currency, client.scopes)

Or with asyncio, here as a connected app acting for a customer, whose writes wait for the customer to confirm them:

import asyncio

from cruworldwine import AsyncCru


async def main() -> None:
    async with AsyncCru(access_token='...', refresh_token='...', oauth_client_id='...') as cru:
        page = await cru.bids.list(status=['live'])
        async for bid in page:
            print(bid.code, bid.price, bid.quantity)


asyncio.run(main())

Cru() alone reads CRU_CLIENT_KEY and CRU_CLIENT_SECRET (or CRU_ACCESS_TOKEN), CRU_MARKET and CRU_ENVIRONMENT from the environment. Authentication covers both ways in.

Sandbox

To build and test where no real money or wine changes hands, use the sandbox, with credentials issued for it: environment='sandbox' (or CRU_ENVIRONMENT=sandbox) calls https://{market}.crusandbox.com/api/v1 in place of https://{market}.cruworldwine.com/api/v1.

cru = Cru(client_key='...', client_secret='...', environment='sandbox', market='hk')
print(cru.market_info.currency)  # HKD

MARKETS and lookup_market() list each market's name, currency, symbol and URLs; Configuration has the details.

Typed models

Every endpoint is a typed method, and every answer a typed model with an attribute per API field and the API's descriptions as docstrings, so an editor completes and checks them. Fields this version does not know are kept in .raw.

for wine in cru.portfolio.list(is_listed=True).auto_paging_iter():  # PortfolioWine
    for line in wine.portfolio:  # PortfolioLine
        print(wine.wine_name, line.quantity, line.pricing.listing_price, line.pricing.net_proceeds)

Import any model from cruworldwine.models.

Documentation

• Authentication: partner credentials, connected apps and OAuth refresh, the environment.
• Configuration: constructor and per-call options, the sandbox and the markets, with_options(), timeouts, retries, logging, app_info.
• Async: AsyncCru, async paging and concurrency.
• Pagination: pages, and walking every item.
• Writes and confirmations: idempotency references, staged writes and confirming them.
• Errors: the error classes, what they hold, and request ids.
• Compatibility: tolerant models, values that may grow, and the versioning policy.
• Architecture: how the SDK is built, the life of a request, and the code generation.
• The API itself: developers.cruworldwine.com.

Examples

examples/ has scripts to run with credentials in the environment: portfolio.py prints your portfolio, market.py the bids and offers on a wine, place_bid.py places a bid and, as a connected app, confirms it, and async_market.py asks for several wines at once with AsyncCru.

Versioning and support

The SDK follows semantic versioning. While it is 0.x, a minor release may change the public API, and every such change is in the changelog; patch releases never do. It supports Python 3.9 to 3.15 on Linux, macOS and Windows, and only the latest minor release gets fixes. Compatibility has the whole policy.

Every method

Generated from the spec; each method's docstring has the full description. AsyncCru has the same methods: await them, and a Page is an AsyncPage.

Contributing, security and licence

CONTRIBUTING.md explains the layout, the Makefile and how releases are cut. Report a vulnerability privately, as SECURITY.md explains, never in a public issue. Apache License 2.0; see LICENSE.