https://github.com/bigcommerce/bigcommerce-api-python
Python client library for Bigcommerce API
https://github.com/bigcommerce/bigcommerce-api-python
api-client bigcommerce heroku-ready oauth python
Last synced: 9 months ago
JSON representation
Python client library for Bigcommerce API
- Host: GitHub
- URL: https://github.com/bigcommerce/bigcommerce-api-python
- Owner: bigcommerce
- License: mit
- Created: 2011-09-07T04:48:59.000Z (over 14 years ago)
- Default Branch: master
- Last Pushed: 2024-01-25T19:41:53.000Z (almost 2 years ago)
- Last Synced: 2025-03-29T00:08:52.321Z (9 months ago)
- Topics: api-client, bigcommerce, heroku-ready, oauth, python
- Language: Python
- Homepage: https://pypi.python.org/pypi/bigcommerce
- Size: 331 KB
- Stars: 91
- Watchers: 27
- Forks: 81
- Open Issues: 24
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
Bigcommerce API Python Client
==================================
|Build Status| |Package Version|
Wrapper over the ``requests`` library for communicating with the Bigcommerce v2 API.
Install with ``pip install bigcommerce`` or ``easy_install bigcommerce``. Tested with
python 3.7-3.9, and only requires ``requests`` and ``pyjwt``.
Usage
-----
Connecting
~~~~~~~~~~
.. code:: python
import bigcommerce
# Public apps (OAuth)
# Access_token is optional, if you don't have one you can use oauth_fetch_token (see below)
api = bigcommerce.api.BigcommerceApi(client_id='', store_hash='', access_token='')
# Private apps (Basic Auth)
api = bigcommerce.api.BigcommerceApi(host='store.mybigcommerce.com', basic_auth=('username', 'api token'))
``BigcommerceApi`` also provides two helper methods for connection with OAuth2:
- ``api.oauth_fetch_token(client_secret, code, context, scope, redirect_uri)``
-- fetches and returns an access token for your application. As a
side effect, configures ``api`` to be ready for use.
- ``BigcommerceApi.oauth_verify_payload(signed_payload, client_secret)``
-- Returns user data from a signed payload.
Accessing and objects
~~~~~~~~~~~~~~~~~~~~~
The ``api`` object provides access to each API resource, each of which
provides CRUD operations, depending on capabilities of the resource:
.. code:: python
api.Products.all() # GET /products (returns only a single page of products as a list)
api.Products.iterall() # GET /products (autopaging generator that yields all
# products from all pages product by product.)
api.Products.get(1) # GET /products/1
api.Products.create(name='', type='', ...) # POST /products
api.Products.get(1).update(price='199.90') # PUT /products/1
api.Products.delete_all() # DELETE /products
api.Products.get(1).delete() # DELETE /products/1
api.Products.count() # GET /products/count
The client provides full access to subresources, both as independent
resources:
::
api.ProductOptions.get(1) # GET /products/1/options
api.ProductOptions.get(1, 2) # GET /products/1/options/2
And as helper methods on the parent resource:
::
api.Products.get(1).options() # GET /products/1/options
api.Products.get(1).options(1) # GET /products/1/options/1
These subresources implement CRUD methods in exactly the same way as
regular resources:
::
api.Products.get(1).options(1).delete()
Filters
~~~~~~~
Filters can be applied to ``all`` methods as keyword arguments:
.. code:: python
customer = api.Customers.all(first_name='John', last_name='Smith')[0]
orders = api.Orders.all(customer_id=customer.id)
Error handling
~~~~~~~~~~~~~~
Minimal validation of data is performed by the client, instead deferring
this to the server. A ``HttpException`` will be raised for any unusual
status code:
- 3xx status code: ``RedirectionException``
- 4xx status code: ``ClientRequestException``
- 5xx status code: ``ServerException``
The low level API
~~~~~~~~~~~~~~~~~
The high level API provided by ``bigcommerce.api.BigcommerceApi`` is a
wrapper around a lower level api in ``bigcommerce.connection``. This can
be accessed through ``api.connection``, and provides helper methods for
get/post/put/delete operations.
Accessing V3 API endpoints
~~~~~~~~~~~~~~~~~~~~~~~~~~
Although this library currently only supports high-level modeling for V2 API endpoints,
it can be used to access V3 APIs using the OAuthConnection object:
::
v3client = bigcommerce.connection.OAuthConnection(client_id=client_id,
store_hash=store_hash,
access_token=access_token,
api_path='/stores/{}/v3/{}')
v3client.get('/catalog/products', include_fields='name,sku', limit=5, page=1)
Accessing GraphQL Admin API
~~~~~~~~~~~~~~~~~~~~~~~~~~~
There is a basic GraphQL client which allows you to submit GraphQL queries to the GraphQL Admin API.
::
gql = bigcommerce.connection.GraphQLConnection(
client_id=client_id,
store_hash=store_hash,
access_token=access_token
)
# Make a basic query
time_query_result = gql.query("""
query {
system {
time
}
}
""")
# Fetch the schema
schema = gql.introspection_query()
Managing Rate Limits
~~~~~~~~~~~~~~~~~~~~~~~~~~
You can optionally pass a ``rate_limiting_management`` object into ``bigcommerce.api.BigcommerceApi`` or ``bigcommerce.connection.OAuthConnection`` for automatic rate limiting management, ex:
.. code:: python
import bigcommerce
api = bigcommerce.api.BigcommerceApi(client_id='', store_hash='', access_token=''
rate_limiting_management= {'min_requests_remaining':2,
'wait':True,
'callback_function':None})
``min_requests_remaining`` will determine the number of requests remaining in the rate limiting window which will invoke the management function
``wait`` determines whether or not we should automatically sleep until the end of the window
``callback_function`` is a function to run when the rate limiting management function fires. It will be invoked *after* the wait, if enabled.
``callback_args`` is an optional parameter which is a dictionary passed as an argument to the callback function.
For simple applications which run API requests in serial (and aren't interacting with many different stores, or use a separate worker for each store) the simple sleep function may work well enough for most purposes. For more complex applications that may be parallelizing API requests on a given store, it's adviseable to write your own callback function for handling the rate limiting, use a ``min_requests_remaining`` higher than your concurrency, and not use the default wait function.
Further documentation
---------------------
Full documentation of the API is available on the Bigcommerce
`Developer Portal `__
To do
-----
- Automatic enumeration of multiple page responses for subresources.
.. |Build Status| image:: https://api.travis-ci.org/bigcommerce/bigcommerce-api-python.svg?branch=master
:target: https://travis-ci.org/bigcommerce/bigcommerce-api-python
.. |Package Version| image:: https://badge.fury.io/py/bigcommerce.svg
:target: https://pypi.python.org/pypi/bigcommerce