Skip to main content

A sync/async REST and GraphQL client for Shopify API using HTTPX

Project description

basic_shopify_api

Tests Coverage PyPi version

This library extends HTTPX and implements a read-to-use sync/async client for REST and GraphQL API calls to Shopify's API.

Support for:

  • Sync and async API calls
  • REST API
  • GraphQL API
  • REST rate limiting
  • GraphQL cost limiting
  • Automatic retries of failed requests
  • Support for Retry-After headers
  • Pre/post action support

Table of Contents

Installation

$ pip install basic-shopify-api

Requires Python 3.

Options

Options().

There are a variety of options to take advantage of.

You can simply create a new instance to use all default values if you're using public API mode.

Options available:

  • max_retries (int), the number of attempts to retry a failed request; default: 2.
  • retry_on_status (list), the list of HTTP status codes to watch for, and retry if found; default: [429, 502, 503, 504].
  • headers (dict), the list of headers to send with each request.
  • time_store (StateStore), an implementation to store times of requests; default: TimeMemoryStore.
  • cost_store (StateStore), an implementation to store GraphQL response costs; default: CostMemoryStore.
  • deferrer (Deferrer), an implementation to get current time and sleep for time; default: SleepDeferrer.
  • rest_limit (int), the number of allowed REST calls per second; default: 2.
  • graphql_limit (int), the cost allowed per second for GraphQL calls; default: 50.
  • rest_pre_actions (list), a list of pre-callable actions to fire before a REST request.
  • rest_post_actions (list), a list of post-callable actions to fire after a REST request.
  • graphql_pre_actions (list), a list of pre-callable actions to fire before a GraphQL request.
  • graphql_post_actions (list), a list of post-callable actions to fire after a GraphQL request.
  • version (str), the API version to use for all requests; default: 2020-04.
  • mode (str), the type of API to use either public or private; default: public.

Example:

opts = Options()
opts.version = "unstable"
opts.mode = "private"

Session

Create a session to use with a client. Depending on if you're accessing the API public or privately, then you will need to fill different values.

Session(domain, key, password, secret).

For public access, you will need to fill in:

  • domain, the full myshopify domain.
  • password, the shop's access token.
  • secret, the app's secret key.

For private access, you will need to fill in:

  • domain, the full myshopify domain.
  • key, the shop's key.
  • password, the shop's password.

Example:

from basic_shopify_api import Session
session = Session(domain="john-doe.myshopify.com", key="abc", password="123")

REST Usage

rest(method, path[, params, headers]).

  • method (str), being one of get, post, put, or delete.
  • path (str), being an API path, example: /admin/api/shop.json.
  • params (dict) (optional), being a dict of query or json data.
  • headers (dict) (optional), being a dict of additional headers to pass with the request.

REST Sync

Example:

from basic_shopify_api import Client

with Client(sess, opts) as client:
    shop = client.rest("get", "/admin/api/shop.json", {"fields": "name,email"})
    print(shop.response)
    print(shop.body["name"])

    # returns the following:
    # RestResult(
    #   response=The HTTPX response object,
    #   body=A dict of JSON response, or None if errors,
    #   errors=A dict of error response (if possible), or None for no errors, or the exception error,
    #   status=The HTTP status code,
    #   link=A RestLink object of next/previous pagination info,
    #   retries=Number of retires for the request
    # )

REST Async

Example:

from basic_shopify_api import AsyncClient

# ...

async with AsyncClient(sess, opts) as client:
    shop = await client.rest("get", "/admin/api/shop.json", {"fields": "name,email"})
    print(shop.response)
    print(shop.body["name"])

    # returns the following:
    # RestResult(
    #   response=The HTTPX response object,
    #   body=A dict of JSON response, or None if errors,
    #   errors=A dict of error response (if possible), or None for no errors, or the exception error,
    #   status=The HTTP status code,
    #   link=A RestLink object of next/previous pagination info,
    #   retries=Number of retires for the request
    # )

GraphQL Usage

graphql(query[, variables]).

  • query (str), being the GraphQL query string.
  • variables (dict) (optional), being the variables for your query or mutation.

GraphQL Sync

Example:

from basic_shopify_api import Client

# ...

with Client(sess, opts) as client:
    shop = client.graphql("{ shop { name } }")
    print(shop.response)
    print(shop.body["data"]["shop"]["name"])

    # returns the following:
    # ApiResult(
    #   response=The HTTPX response object,
    #   body=A dict of JSON response, or None if errors,
    #   errors=A dict of error response (if possible), or None for no errors, or the exception error,
    #   status=The HTTP status code,
    #   retries=Number of retires for the request,
    # )

GraphQL Async

Example:

from basic_shopify_api import AsyncClient

# ...

async with AsyncClient(sess, opts) as client:
    shop = await client.graphql("{ shop { name } }")
    print(shop.response)
    print(shop.body["data"]["name"])

    # returns the following:
    # ApiResult(
    #   response=The HTTPX response object,
    #   body=A dict of JSON response, or None if errors,
    #   errors=A dict of error response (if possible), or None for no errors, or the exception error,
    #   status=The HTTP status code,
    #   link=A RestLink object of next/previous pagination info,
    #   retries=Number of retires for the request
    # )

Pre/Post Actions

To register a pre or post action for REST or GraphQL, simply append it to your options setup.

from basic_shopify_api import Options, Client

def say_hello(inst):
    """inst is the current client instance, either Client or AsyncClient"""
    print("hello")

def say_world(inst, result):
    """
    inst is the current client instance, either Client or AsyncClient.
    result is either RestResult or GraphQLResult object.
    """
    print("world")

opts = Options()
opts.rest_pre_actions = [say_hello]
opts.rest_post_ations = [say_world]

sess = Session(domain="john-doe.myshopify.com", key="abc", password="134")

with Client(sess, opts) as client:
    shop = client.rest("get", "/admin/api/shop.json")
    print(shop)
    # Output: "hello" "world" <ApiResult>

Utilities

This will be expanding, but as of now there are utilities to help verify HMAC for 0Auth/URL, proxy requests, and webhook data.

0Auth/URL

from basic_shopify_api.utils import hmac_verify

params = request.args # some method to get a dict of query params
verified = hmac_verify("standard", "secret key", params)
print("Verified? {verified}")

Proxy

from basic_shopify_api.utils import hmac_verify

params = request.args # some method to get a dict of query params
verified = hmac_verify("proxy", "secret key", params)
print("Verified? {verified}")

Webhook

from basic_shopify_api.utils import hmac_verify

hmac_header = request.headers.get("x-shopify-hmac-sha256") # some method to get the HMAC header
params = request.json # some method to get a dict of JSON data
verified = hmac_verify("webhook", "secret key", params, hmac_header)
print("Verified? {verified}")

Development

python -m venv env && source env/bin/activate

python -m pip install -r requirements.txt

Testing

make test.

For coverage reports, use make cover or make cover-html.

Documentation

See this Github page or view docs/.

License

This project is released under the MIT license.

Misc

Using PHP? Check out Basic-Shopify-API.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

basic_shopify_api-1.0.1.tar.gz (15.3 kB view details)

Uploaded Source

Built Distribution

basic_shopify_api-1.0.1-py3-none-any.whl (16.5 kB view details)

Uploaded Python 3

File details

Details for the file basic_shopify_api-1.0.1.tar.gz.

File metadata

  • Download URL: basic_shopify_api-1.0.1.tar.gz
  • Upload date:
  • Size: 15.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/54.0.0 requests-toolbelt/0.9.1 tqdm/4.58.0 CPython/3.8.6

File hashes

Hashes for basic_shopify_api-1.0.1.tar.gz
Algorithm Hash digest
SHA256 b899b8b4bcd9867d03d92aaaeb8a9a16afab434cdc3ce336ec2147436061c639
MD5 286aca66e943e9b8f83b3ae297cc2a1c
BLAKE2b-256 f68ecfe2f63c4258af0c8a34806727e0a80520b17dd73ad44c4344a97ba8858c

See more details on using hashes here.

File details

Details for the file basic_shopify_api-1.0.1-py3-none-any.whl.

File metadata

  • Download URL: basic_shopify_api-1.0.1-py3-none-any.whl
  • Upload date:
  • Size: 16.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/54.0.0 requests-toolbelt/0.9.1 tqdm/4.58.0 CPython/3.8.6

File hashes

Hashes for basic_shopify_api-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 1202862457f2f9c3cfd6b0c1f9fbb703bbcaa0ae5ce12d61de804c5f1f05d557
MD5 252651bb621b4a087031b4c7a205d995
BLAKE2b-256 7e1cc2141eadd1edcee83396aae1fa672182e56eb1fd1ff2991862580002ede8

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page