{
    "info": {
        "author": "Get a Newsletter",
        "author_email": "tech@getanewsletter.com",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "ganapi\n=======\n\nThe ganapi library presents a simple and easy to use interface to the Get a Newsletter's REST API.\n\nRequirements\n------------\n* Python 2.7.6 tested\n* requests 2.2.1\n* httmock for tests\n\nInstallation\n------------\nVia PIP:\n```bash\npip install ganapi\n```\n\nUsage\n-----\nStart by creating an instance of the ```Api``` object:\n```python\nfrom ganapi import Api\n\ntoken = '...'\ngan_api = Api(token)\n```\nHere ```token``` variable must contain a valid [API token](http://help.getanewsletter.com/en/support/api-token-2/) string.\n\n#### The contact object\nThe instances of the Contact class represent the contact entities in the API.\nThey have the following fields:\n\n*Required fields*\n* ```email``` - contact's email. It's also a ***_lookup field_*** - required when updating or deleting the contact.\n\n*Optional fields*\n* ```attributes``` - list of the contact's [attributes](http://help.getanewsletter.com/en/support/attribute-overview/).\n* ```first_name```\n* ```last_name```\n* ```lists``` - list of the newsletters for which this contact is subscribed to.\n\n*Read-only fields*\n* ```url``` - the contact's resource URL.\n* ```active``` - true if the contact is active and can receive mails, false otherwise.\n* ```updated``` - the date of the last change.\n* ```created``` - the date of creation.\n\n#### Retreiving a contact\nYou have to create an instance of the ```ContactManager``` class and then use it's ```get()``` method to retrieve the contact you need.\n```python\nfrom ganapi import ContactManager\n\ncontact_manager = ContactManager(gan_api)\ncontact = contact_manager.get('john.doe@example.com')\n```\nThe manager methods will throw an ```HTTPError``` in case of HTTP error from the API, so it's a good idea to catch it.\n```python\n\ntry:\n    contact = contact_manager.get('john.doe@example.com')\nexcept HTTPError as e:\n    if e.response.code == 404:\n        print 'Contact not found!'\n    else:\n        print 'API error: ' + e\n\n\n```\n\n### Querying for contacts\nYou have to create an instance of the ```ContactManager``` class and then use it's ```query()``` method to retrieve the contacts you need.\n```query()``` takes a dict of [url parameters](https://api.getanewsletter.com/v3/docs/contacts/#get-contacts)  and will return a ```PaginatedResultSet``` with the first page of contacts in a list in PaginatedResultSet.entities.\n\n```python\n# Get PaginatedResultSet containing contacts with emails starting with name@.\nqueried_contacts = contact_manager.query({'search_email': 'name@'})\n\n# list of contacts in current page(1)\nqueried_contacts.entities\n\n# list of contacts in next page(2) if available and update PaginatedResultSet\nqueried_contacts.next()\n\n# list of contacts in previous page(1) if available and update PaginatedResultSet\nqueried_contacts.prev()\n\n\n```\n\n#### Creating a contact\n```python\n\ncontact = contact_manager.create()\ncontact.email = 'jane.doe@example.com'\ncontact.first_name = 'Jane'\n\ncontact.save()\n```\nThis will create a new contact and save it. Again, it'll be a good idea to catch exceptions when calling the ```save()``` method. The API will respond with an error if the contact already exists.\nOne way to avoid it is to force the creation of the contact, overwriting the existing one:\n```python\n\ncontact.overwrite()\n```\n\nBoth ```save()``` and ```overwrite()``` will return the same contact object with it's read-only fields updated (e.g. ```created```, ```updated```).\n\n```python\n\ncontact = contact.save()\nprint contact.created\n```\n\n#### Updating an existing contact\n```python\n\n# Get the contact.\ncontact = contact_manager.get('john.doe@example.com')\n# Change some fields.\ncontact.first_name = 'John'\n# Save it.\ncontact.save()\n```\nYou can avoid making two calls to the API by forcing a *partial update*.\n```python\n\ncontact = contact_manager.create()\ncontact.set_persisted()\ncontact.email = 'john.doe@example.com'\ncontact.first_name = 'John'\ncontact.save()\n```\nCalling ```set_persisted()``` on the contact object marks it like it's already existing and coming from the API. The calls to the ```save()``` method when a contact is maked as existing will do only a *partial update*, i.e. update only the supplied fields and skipping all the ```None``` fields.\nDo not forget that ```email``` is a ***_lookup field_*** and required when updating or deleting the contact.\n\n#### Deleting a contact\n```python\n\ncontact.delete()\n```\n\n#### The list object\nThe instances of the List class represent the [lists](http://help.getanewsletter.com/en/support/lists-overview/) in the API. They have the following structure:\n\n*Required fields*\n* ```email``` - sender's email.\n* ```name``` - name of the list.\n* ```sender``` - sender's name.\n*\n*Optional fields*\n* ```description```\n\n*Lookup field*\n* ```hash``` - the list's unique hash.\n\n*Read-only fields*\n* ```responders_count```\n* ```subcribers```\n* ```created```\n* ```url```\n* ```subscribers_count```\n* ```active_subscribers_count```\n* ```responders```\n\n#### Retreiving, creating, updating and deleting a list\nThe CRUD operations on lists are no different from the operations on contacts:\n```python\n\nlist_manager = ListManager(gan_api)\n\n# Retrieve a list.\nlist = list_manager.get('hash')\n\n# Update the list.\nlist.name = 'my list'\nlist = list.save()\nprint list.updated\n\n# Create new list.\nnew_list = list_manager.create()\nnew_list.email = 'john.doe@example.com' # required fields\nnew_list.name = 'my new list'\nnew_list.sender = 'John Doe'\nnew_list.save()\n\n# Partial update.\nlist = list_manager.create()\nlist.hash = 'hash' # lookup field\nlist.name = 'updated list'\nlist.save()\n\n# Delete the list.\nlist.delete()\n\n```\n\n#### Subscribing a contact to a list\n```python\n\ncontact.subscribe_to(list)\ncontact.save()\n```\nYou can also create a new contact automatically subscribed.\n```python\n\ncontact = contact_manager.create()\ncontact.email = 'john.doe@example.com'\ncontact.subscribe_to(list)\ncontact.save()\n```\n#### Unsubscribing a contact from a list\n```python\n\ncontact.unsubscribe_from(list)\ncontact.save()\n```\n#### Deleting a contacts subscription from a list\n```python\n\ncontact.delete_subscription_from(list)\ncontact.save()\n```\n\n#### The attribute object\nThe instances of the Attribute class represent the attribute entities in the API.\nThey have the following fields:\n\n*Required fields*\n* ```name``` - attribute name.\n\n*Lookup field*\n* ```code``` - the slugified attribute code. required when updating or deleting the attribute. *The name \"A new attribute\" code will be \"a-new-attribute\"*\n\n*Read-only fields*\n* ```url``` - the attribute resource URL.\n* ```usage_count``` - number of usages.\n\n\n#### Retreiving an attribute\nYou have to create an instance of the ```AttributeManager``` class and then use it's ```get()``` method to retrieve the attribute you need.\n```python\nfrom ganapi import AttributeManager\n\nattribute_manager = AttributeManager(gan_api)\nattribute = attribute_manager.get('code')\n```\nThe manager methods will raise a ```HTTPError``` in case of HTTP error from the API, so it's a good idea to catch it.\n```python\n\ntry:\n    attribute = attribute_manager.get('code')\nexcept HttpError as e:\n    if e.response.code == 404:\n        print 'Attribute not found!'\n    else:\n        print 'API error: ' + e\n\n\n```\n\n#### Creating an attribute\n```python\n\nattribute = attribute_manager.create()\nattribute.name = 'City'\n\nattribute.save()\n```\nThis will create a new attribute and save it. Again, it'll be a good idea to catch exceptions when calling the ```save()``` method. The API will respond with an error if the attribute already exists.\nOne way to avoid it is to force the creation of the attribute, overwriting the existing one:\n```python\n\nattribute.overwrite()\n```\n\nBoth ```save()``` and ```overwrite()``` will return the same attribute object with it's read-only fields updated (e.g. ```url```, ```usage_count```).\n\n```python\n\nattribute = attribute.save()\nprint attribute.usage_count\n```\n\n#### Updating an existing attribute\n```python\n\n# Get the attribute.\nattribute = attribute_manager.get('code')\n# Change name field.\nattribute.name = 'Changed!'\n# Save it.\nattribute.save()\n```\nYou can avoid making two calls to the API by forcing a *partial update*.\n```python\n\nattribute = attribute_manager.create()\nattribute.set_persisted()\nattribute.code = 'code'\nattribute.name = 'Changed!'\nattribute.save()\n```\nCalling ```set_persisted()``` on the attribute object marks it like it's already existing and coming from the API. The calls to the ```save()``` method when a attribute is made as existing will do only a *partial update*, i.e. update only the supplied fields and skipping all the ```None``` fields.\nDo not forget that ```code``` is a ***_lookup field_*** and required when updating or deleting the attribute.\n\n#### Deleting an attribute\n```python\n\nattribute.delete()\n```\n\n### Get all entities of type\nYou can get all contacts, lists or attributes in a generator using the ```all()``` method on their manager.\n\n*Parameters*\n* ```start``` - start index (default: 0)\n* ```stop``` stop index (default: float('inf'))\n\n\n```python\n# Print all contacts emails\nall_contacts = contact_manager.all()\nfor contact in all_contacts:\n    print contact.email\n    \n\n# Get a generator starting on contact 100 stopping on contact 200\nall_contacts = contact_manager.all(start=100, stop=200)\n\n```\n\n\n\n#### The PaginatedResultSet class\nThe instance of the PaginatedResultSet class represent the result of get from the API.\n\n*Parameters*\n* ```data``` - json of result from the ```query()``` method in the managers.\n* ```manager``` - the manager using ```query()```.\n\n*Properties*\n* ```next_link``` - URL to get the next page of the results.\n* ```previous_link``` - URL to get the previous page of the results.\n* ```manager``` - ```EntityManager``` currently used.\n* ```entities``` - List of ```Entity``` for the current result page.\n* ```count``` - Total amount of entity results in all pages.\n\n*Methods*\n* ```prev()``` - replaces the instance with results from the previous page and returns entities.\n* ```next()``` - replaces the instance with results from the next page and returns entities.\n\n```next()``` and ```prev()``` will raise ```StopIteration``` if the end of the direction has been reached.\nThey will raise ```HTTPError``` in case of HTTP error from the API,",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "https://github.com/getanewsletter/api-python/tarball/v0.1.0",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/getanewsletter/api-python",
        "keywords": "Get a newsletter,ganapi",
        "license": "MIT",
        "maintainer": null,
        "maintainer_email": null,
        "name": "ganapi",
        "package_url": "https://pypi.org/project/ganapi/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/ganapi/",
        "project_urls": {
            "Download": "https://github.com/getanewsletter/api-python/tarball/v0.1.0",
            "Homepage": "https://github.com/getanewsletter/api-python"
        },
        "release_url": "https://pypi.org/project/ganapi/0.1.0/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "Get a Newsletter REST API wrapper",
        "version": "0.1.0"
    },
    "last_serial": 1957192,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "d504fa7ee1a61b47305aaba6c2cae77c",
                    "sha256": "7df11cff67e8a0570e6a9c9ff59070be6a165a85aaebf585af128f15e88d75e7"
                },
                "downloads": -1,
                "filename": "ganapi-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "d504fa7ee1a61b47305aaba6c2cae77c",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 15793,
                "upload_time": "2016-02-15T13:25:11",
                "url": "https://files.pythonhosted.org/packages/bf/71/0aadba634a116dd67b118ca28b373d5dc223249b3af7ada64c36283011dd/ganapi-0.1.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "d504fa7ee1a61b47305aaba6c2cae77c",
                "sha256": "7df11cff67e8a0570e6a9c9ff59070be6a165a85aaebf585af128f15e88d75e7"
            },
            "downloads": -1,
            "filename": "ganapi-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "d504fa7ee1a61b47305aaba6c2cae77c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 15793,
            "upload_time": "2016-02-15T13:25:11",
            "url": "https://files.pythonhosted.org/packages/bf/71/0aadba634a116dd67b118ca28b373d5dc223249b3af7ada64c36283011dd/ganapi-0.1.0.tar.gz"
        }
    ]
}