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 <http://developer.bigcommerce.com>`__
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
Raw data
{
"_id": null,
"home_page": "https://github.com/bigcommerce/bigcommerce-api-python",
"name": "bigcommerce",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "bigcommerce,api,v2,client",
"author": "Bigcommerce Engineering",
"author_email": "api@bigcommerce.com",
"download_url": "https://files.pythonhosted.org/packages/7b/7a/3e33b6dfc83b279d93e522b2f4ff27d884c20840a86a40c0b6e7c3ec5144/bigcommerce-0.23.4.tar.gz",
"platform": null,
"description": "Bigcommerce API Python Client\n==================================\n\n|Build Status| |Package Version|\n\nWrapper over the ``requests`` library for communicating with the Bigcommerce v2 API.\n\nInstall with ``pip install bigcommerce`` or ``easy_install bigcommerce``. Tested with\npython 3.7-3.9, and only requires ``requests`` and ``pyjwt``.\n\nUsage\n-----\n\nConnecting\n~~~~~~~~~~\n\n.. code:: python\n\n import bigcommerce\n\n # Public apps (OAuth)\n # Access_token is optional, if you don't have one you can use oauth_fetch_token (see below)\n api = bigcommerce.api.BigcommerceApi(client_id='', store_hash='', access_token='')\n\n # Private apps (Basic Auth)\n api = bigcommerce.api.BigcommerceApi(host='store.mybigcommerce.com', basic_auth=('username', 'api token'))\n\n``BigcommerceApi`` also provides two helper methods for connection with OAuth2:\n\n- ``api.oauth_fetch_token(client_secret, code, context, scope, redirect_uri)``\n -- fetches and returns an access token for your application. As a\n side effect, configures ``api`` to be ready for use.\n\n- ``BigcommerceApi.oauth_verify_payload(signed_payload, client_secret)``\n -- Returns user data from a signed payload.\n\nAccessing and objects\n~~~~~~~~~~~~~~~~~~~~~\n\nThe ``api`` object provides access to each API resource, each of which\nprovides CRUD operations, depending on capabilities of the resource:\n\n.. code:: python\n\n api.Products.all() # GET /products (returns only a single page of products as a list)\n api.Products.iterall() # GET /products (autopaging generator that yields all\n # products from all pages product by product.)\n api.Products.get(1) # GET /products/1\n api.Products.create(name='', type='', ...) # POST /products\n api.Products.get(1).update(price='199.90') # PUT /products/1\n api.Products.delete_all() # DELETE /products\n api.Products.get(1).delete() # DELETE /products/1\n api.Products.count() # GET /products/count\n\nThe client provides full access to subresources, both as independent\nresources:\n\n::\n\n api.ProductOptions.get(1) # GET /products/1/options\n api.ProductOptions.get(1, 2) # GET /products/1/options/2\n\nAnd as helper methods on the parent resource:\n\n::\n\n api.Products.get(1).options() # GET /products/1/options\n api.Products.get(1).options(1) # GET /products/1/options/1\n\nThese subresources implement CRUD methods in exactly the same way as\nregular resources:\n\n::\n\n api.Products.get(1).options(1).delete()\n\nFilters\n~~~~~~~\n\nFilters can be applied to ``all`` methods as keyword arguments:\n\n.. code:: python\n\n customer = api.Customers.all(first_name='John', last_name='Smith')[0]\n orders = api.Orders.all(customer_id=customer.id)\n\nError handling\n~~~~~~~~~~~~~~\n\nMinimal validation of data is performed by the client, instead deferring\nthis to the server. A ``HttpException`` will be raised for any unusual\nstatus code:\n\n- 3xx status code: ``RedirectionException``\n- 4xx status code: ``ClientRequestException``\n- 5xx status code: ``ServerException``\n\nThe low level API\n~~~~~~~~~~~~~~~~~\n\nThe high level API provided by ``bigcommerce.api.BigcommerceApi`` is a\nwrapper around a lower level api in ``bigcommerce.connection``. This can\nbe accessed through ``api.connection``, and provides helper methods for\nget/post/put/delete operations.\n\nAccessing V3 API endpoints\n~~~~~~~~~~~~~~~~~~~~~~~~~~\nAlthough this library currently only supports high-level modeling for V2 API endpoints,\nit can be used to access V3 APIs using the OAuthConnection object:\n\n::\n\n v3client = bigcommerce.connection.OAuthConnection(client_id=client_id,\n store_hash=store_hash,\n access_token=access_token,\n api_path='/stores/{}/v3/{}')\n v3client.get('/catalog/products', include_fields='name,sku', limit=5, page=1)\n\nAccessing GraphQL Admin API\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\nThere is a basic GraphQL client which allows you to submit GraphQL queries to the GraphQL Admin API.\n\n::\n\n gql = bigcommerce.connection.GraphQLConnection(\n client_id=client_id,\n store_hash=store_hash,\n access_token=access_token\n )\n # Make a basic query\n time_query_result = gql.query(\"\"\"\n query {\n system {\n time\n }\n }\n \"\"\")\n # Fetch the schema\n schema = gql.introspection_query()\n\n\nManaging Rate Limits\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nYou can optionally pass a ``rate_limiting_management`` object into ``bigcommerce.api.BigcommerceApi`` or ``bigcommerce.connection.OAuthConnection`` for automatic rate limiting management, ex:\n\n.. code:: python\n\n import bigcommerce\n\n api = bigcommerce.api.BigcommerceApi(client_id='', store_hash='', access_token=''\n rate_limiting_management= {'min_requests_remaining':2,\n 'wait':True,\n 'callback_function':None})\n\n``min_requests_remaining`` will determine the number of requests remaining in the rate limiting window which will invoke the management function\n\n``wait`` determines whether or not we should automatically sleep until the end of the window\n\n``callback_function`` is a function to run when the rate limiting management function fires. It will be invoked *after* the wait, if enabled.\n\n``callback_args`` is an optional parameter which is a dictionary passed as an argument to the callback function.\n\nFor 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.\n\nFurther documentation\n---------------------\n\nFull documentation of the API is available on the Bigcommerce\n`Developer Portal <http://developer.bigcommerce.com>`__\n\nTo do\n-----\n\n- Automatic enumeration of multiple page responses for subresources.\n\n.. |Build Status| image:: https://api.travis-ci.org/bigcommerce/bigcommerce-api-python.svg?branch=master\n :target: https://travis-ci.org/bigcommerce/bigcommerce-api-python\n.. |Package Version| image:: https://badge.fury.io/py/bigcommerce.svg\n :target: https://pypi.python.org/pypi/bigcommerce\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Connect Python applications with the Bigcommerce API",
"version": "0.23.4",
"project_urls": {
"Download": "https://pypi.python.org/packages/source/b/bigcommerce/bigcommerce-0.23.4.tar.gz",
"Homepage": "https://github.com/bigcommerce/bigcommerce-api-python"
},
"split_keywords": [
"bigcommerce",
"api",
"v2",
"client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ddbb94a2203c1beb08331817d407f0fcc4d4c79582d7e64fff71fe56f30bbf1a",
"md5": "20a4c4b5bf371dafe25a068ba8528b50",
"sha256": "a5668ff171a2cf856e6dca3bd2e1a05b5e1cf10d964faebf83ce6eda316846a7"
},
"downloads": -1,
"filename": "bigcommerce-0.23.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "20a4c4b5bf371dafe25a068ba8528b50",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 26411,
"upload_time": "2024-01-08T20:44:32",
"upload_time_iso_8601": "2024-01-08T20:44:32.275610Z",
"url": "https://files.pythonhosted.org/packages/dd/bb/94a2203c1beb08331817d407f0fcc4d4c79582d7e64fff71fe56f30bbf1a/bigcommerce-0.23.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7b7a3e33b6dfc83b279d93e522b2f4ff27d884c20840a86a40c0b6e7c3ec5144",
"md5": "c04fea2ff52f3c49844ed065d3f093a9",
"sha256": "bc0bcc981a80bb78ac5406d230666c8f7d5a5ebbbb896c41341f80945efe7a85"
},
"downloads": -1,
"filename": "bigcommerce-0.23.4.tar.gz",
"has_sig": false,
"md5_digest": "c04fea2ff52f3c49844ed065d3f093a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22144,
"upload_time": "2024-01-08T20:44:34",
"upload_time_iso_8601": "2024-01-08T20:44:34.189660Z",
"url": "https://files.pythonhosted.org/packages/7b/7a/3e33b6dfc83b279d93e522b2f4ff27d884c20840a86a40c0b6e7c3ec5144/bigcommerce-0.23.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-08 20:44:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bigcommerce",
"github_project": "bigcommerce-api-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "PyYAML",
"specs": [
[
"==",
"5.4.1"
]
]
},
{
"name": "cov-core",
"specs": [
[
"==",
"1.15.0"
]
]
},
{
"name": "coverage",
"specs": [
[
"==",
"5.5"
]
]
},
{
"name": "mock",
"specs": [
[
"==",
"4.0.3"
]
]
},
{
"name": "nose",
"specs": [
[
"==",
"1.3.7"
]
]
},
{
"name": "nose-cov",
"specs": [
[
"==",
"1.6"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.31.0"
]
]
},
{
"name": "pyjwt",
"specs": [
[
"==",
"2.4.0"
]
]
}
],
"lcname": "bigcommerce"
}
JSON
