Package: tictail
tictail-python==============[![Build Status](https://travis-ci.org/tictail/tictail-python.svg?branch=master)](https://travis-ci.org/tictail/tictail-python)Python bindings for the Tictail API ([API reference](https://tictail.com/developers/documentation/api-reference/)).### InstallationThe easiest way to install `tictail-python` is via `pip`:```shell$ pip install tictail```Alternatively, you can download the [source](https://github.com/tictail/tictail-python/releases) and then run:```shell$ python setup.py install```#### Mac OS XYou might get the following error on Mac OS X:```clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]```This is caused by the latest (5.1) version of Xcode which ships with a compilerthat treats unknown passed parameters as errors. The workaround is to set theARCHFLAGS environment variable to treat such errors as warnings:```shell$ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install tictail```### Version Support`tictail-python` supports Python 2.6 and 2.7. Python 3.2+ support is coming soon.### DependenciesThe following packages will be installed together with `tictail-python`:- `requests==2.2.1`- `pyasn1==0.1.6`- `pyOpenSSL==0.13`- `ndg-httpsclient==0.3.2`### ContributingFor bugs and feature requests, please open an [issue](https://github.com/tictail/tictail-python/issues). If you'd like to contributeto the development of `tictail-python` – a fact of grandiose awesomeness – then clone the repo, install the development dependencies and hack away. Make sure you include tests, update the changelog and add your name to the contributors list.### TestingThe library uses `pytest` and `coverage` for unit and integration tests. Run `make test` torun all the tests. Alternatively, you can use the `py.test` binary to run specific tests.### QuickstartThe Tictail platform uses OAuth 2.0 for authentication so you need to create your application and obtain an access token for a store. The details of how to do that are not in the scope of this document, but the [authentication](https://tictail.com/developers/documentation/authentication/) section of the documentation has a nice set of instructions and best practices.Once you have an access token you can instantiate the `Tictail` client and get the store associated with the token:```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()```### ConfigurationThe `Tictail` client comes preconfigured with sane defaults. If you wish tooverride the default configuration, you can supply the constructor with a configurationdictionary:```pythonfrom tictail import Tictailconfig = {'timeout': 40}client = Tictail('<access_token>', config=config)```See `client.py` for details on what can be overriden.### Usage & Examples#### StoreReference: [Store](https://tictail.com/developers/documentation/api-reference/#Store)The `Store` resource is the only top-level API object and exposes properties forall its subresources which are documented further below.**Retrieving a store**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()```An example (partial) response:```python>>> print storeStore({'contact_email': u'thestartupstore@example.com','country': u'SE','currency': u'SEK','dashboard_url': u'https://tictail.com/dashboard/store/thestartupstore','description': u'Support your local Startup! ...','id': u't','language': u'en','logotype': [...],'name': u'The Startup Store','sandbox': False,'storekeeper_email': u'johndoe@example.com','url': u'http://thestartupstore.tictail.com'})```#### CardReference: [Card](https://tictail.com/developers/documentation/api-reference/#Card)Cards are how you get your content into the feed of the store. The `Card` resourceonly allows for creating cards at this point.**Creating a new card**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()card = store.cards.create({'title': 'Check out this amazing site','action': 'http://example.com','card_type': 'media','content': {'header': 'You will not regret this'}})```An example response:```python>>> print cardCard({'action': u'http://example.com','card_type': u'media','content': {u'header': u'You will not regret this'},'created_at': u'2014-04-23T20:25:47.745085','id': u'fREx','modified_at': u'2014-04-23T20:25:47.752799','title': u'Check out this amazing site'})```#### ProductReference: [Product](https://tictail.com/developers/documentation/api-reference/#Product)Using the `Product` resource you can list all the visible products of a store or get a specific product by id.Listing products accepts four optional query parameters:- `limit` for page size- `before` and `after` for paginating on products created before or after a product with a given id- `categories` for filtering products on certain categories**List 50 products created after the product with id '7bxv'**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()products = store.products.all(after='7bxv', limit=50)```**List all shirts (id:'aVr') and jeans (id: 'bEt2')**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()products = store.products.all(categories=['aVr', 'bEt2'])```**Retrieve a specific product**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()product = store.products.get('7bxv')```An example response:```python>>> print productProduct({'created_at': u'2014-01-29T13:41:43','currency': u'PLN','description': u'','id': u'7bxv','images': [],'modified_at': u'2014-01-29T13:41:43','price': 1200,'price_includes_tax': True,'quantity': None,'slug': u'super-duper-tshirt','status': u'published','store_id': u'scV','title': u'super duper tshirt','unlimited': True,'variations': []})```#### CustomerReference: [Customer](https://tictail.com/developers/documentation/api-reference/#Customer)The `Customer` resource returns all the customers of a store, i.e people that boughtsomething at least once from that store. Listing customers accepts three optionalquery parameters:- `limit` for page size- `before` and `after` for paginating on customers created before or after a customers with a given id**Retrieve a specific customer**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()customer = store.customers.get('7')```**List all customers**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()customers = store.customers.all()```An example response:```python>>> print customerCustomer({'country': u'SE','created_at': u'2012-12-10T19:31:07','email': u'johndoe@example.com','id': u'bz21','language': u'en','modified_at': None,'name': u'John Doe'})```#### FollowerReference: [Follower](https://tictail.com/developers/documentation/api-reference/#Follower)The `Follower` resource returns all the followers of a store. Listing followers accepts three optionalquery parameters:- `limit` for page size- `before` and `after` for paginating on followers created before or after a follower with a given id**Create a follower**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()follower = store.followers.create({'email': 'newfollower@example.com'})```**Delete a follower**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()# You can either delete a follower from the `Collection`...deleted = store.followers.delete(7)assert deleted# ...or from the `Resource` itself.follower = store.followers.all()[0]deleted = follower.delete()assert deleted```**List all followers**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()followers = store.followers.all()```**List all followers created before the follower with id '7aN'**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()followers = store.followers.all(before='7aN')```An example response:```python>>> print followerFollower({'created_at': u'2013-12-10T19:31:07','modified_at': None,'email': u'johndoe@example.com','id': u'NZUr'})```#### OrderReference: [Order](https://tictail.com/developers/documentation/api-reference/#Order)The `Order` resource returns all the orders of a store. If you wish to get the customersof the store then use the `Customer` resource instead. Listing orders acceptsfive optional query parameters:- `limit` for page size- `before` and `after` for for paginating on orders created before or after a orders with a given id- `modified_before` and `modified_after` for paginating on orders modified before or after a given date (the datecan be either a string in `ISO 8601` format or a `datetime` object)**List all orders after a specific id**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()orders = store.orders.all(after='aFQX')```**List all orders modified after a date**```pythonfrom datetime import datetimefrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()# Using a datetime object...now = datetime.now()orders = store.orders.all(modified_after=now)# ...or a string.orders = store.orders.all(modified_after=now.isoformat())```**Retrieve a specific order**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()order = store.orders.get('aFQX')```An example (partial) response:```python>>> print orderOrder({'customer': {'name': u'John Doe',...},'transaction': {'status': u'paid',...},'prices_include_vat': True,'discounts': [],'items': [{'currency': u'SEK','price': 0,...},...],'fullfilment': {'status': u'unhandled',...},'price': 0,'id': u'aFQX','vat': {'price': 0,'rate': u'0.250000'}})```#### ThemeReference: [Theme](https://tictail.com/developers/documentation/api-reference/#Theme)The `Theme` resource is a singleton resource that returns the currently activetheme of the store.**Get the theme**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()theme = store.theme.get()```An example (partial) response:```python>>> print themeTheme({'id': u'Ag','markup': u'<!DOCTYPE html>\n<html lang="en">\n<head>\n...'})```#### CategoryReference: [Category](https://tictail.com/developers/documentation/api-reference/#Category)The `Category` resource returns the categories which make up the store's navigation.They are implemented as a classical parent-child hierarchy, limited to one level of depth.**List all categories**```pythonfrom tictail import Tictailclient = Tictail('<access_token>')store = client.me()categories = store.categories.all()```An example (partial) response:```python>>> print categories[Category({'created_at': u'2012-05-01T00:47:16','id': u'dn','modified_at': u'2012-02-13T16:58:40','parent_id': None,'position': 0,'title': u'Stickers'}),Category({'created_at': u'2012-10-29T12:02:09','id': u'dA','modified_at': None,'parent_id': u'dn','position': 1,'title': u'DevAwsmbx'})...]```