Metadata-Version: 1.1
Name: bigcommerce
Version: 0.22.0
Summary: Connect Python applications with the Bigcommerce API
Home-page: https://github.com/bigcommerce/bigcommerce-api-python
Author: Bigcommerce Engineering
Author-email: api@bigcommerce.com
License: MIT
Download-URL: https://pypi.python.org/packages/source/b/bigcommerce/bigcommerce-0.22.0.tar.gz
Description: 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.8, 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)
        
        Managing OAuth 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
        
Keywords: bigcommerce,api,v2,client
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.9
