prospyr


Nameprospyr JSON
Version 0.7.0 PyPI version JSON
download
home_pagehttps://github.com/salespreso/prospyr/
SummaryProsperWorks client library
upload_time2017-01-12 09:52:02
maintainer
docs_urlNone
authorBen Graham
requires_python
licenseMIT
keywords prosperworks
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI
Coveralis test coverage No Coveralis.
            Prospyr
#######

A Python client library for ProsperWorks.

.. image:: https://api.travis-ci.org/salespreso/prospyr.svg?branch=master
   :target: https://travis-ci.org/salespreso/prospyr
   :alt: Prospyr builds.

.. image:: https://img.shields.io/codecov/c/github/salespreso/prospyr.svg
   :target: https://codecov.io/github/salespreso/prospyr
   :alt: Prospyr on Codecov.

.. image:: https://landscape.io/github/salespreso/prospyr/master/landscape.svg?style=flat
   :target: https://landscape.io/github/salespreso/prospyr/master
   :alt: Code Health

.. image:: https://badge.fury.io/py/prospyr.svg
   :target: https://pypi.python.org/pypi/prospyr/
   :alt: Prospyr on Pypi.

Prospyr runs on Python 2.7 or Python 3.4+. 

Installation
============

.. code-block:: sh

    pip install prospyr

Quickstart
==========

If you've used Django, Prospyr might feel strangely familiar.

.. code-block:: python

    from prospyr import connect, Person, Company

    # see https://www.prosperworks.com/developer_api/token_generation to obtain
    # a token.
    cn = connect(email='user@domain.tld', token='1aefcc3...')

    # collections can be ordered and sliced.
    newest_person = Person.objects.order_by('-date_modified')[0]

    # new records can be created.
    art = Person(
        name='Art Vandelay',
        emails=[{'email': 'art@vandelayindustries.net', 'category': 'work'}]
    )
    art.create()  # Art is local-only until .create() is called

    # related objects can be read and assigned
    art.company = Company.objects.all()[0]
    art.update()

    # and deleting works too.
    art.delete()


Resources
=========

The following ProsperWorks resources are supported by Prospyr:

- Account (read-only)
- Activity (read–only)
- ActivityType
- Company
- CustomerSource (read–only)
- Identifier
- Lead
- LossReason (read–only)
- Opportunity
- Person
- Pipeline (read–only)
- PipelineStage (read–only)
- Task (read–only)
- User (read–only)

The following resources are not supported, but will still appear when
referenced by the supported resources above. In this case, they come only with
an ``id`` attribute.

- Project

Note you will receive errors trying to deal with the Lead resource if the Leads
feature is not enabled in your ProsperWorks account. You can change this at
Settings / Customize ProsperWorks / Lead Management.


Usage
=====

Connecting
----------

To connect, you'll need an email and token per
`token generation <https://www.prosperworks.com/developer_api/token_generation>`_.

.. code-block:: python

    from prospyr import connect

    cn = connect(email='...', token='...')

All reads are cached per–connection for five minutes. You can pass a custom
cache instance when connecting to ProsperWorks to change this behaviour.

.. code-block:: python

    from prospyr import connect
    from prospyr.cache import NoOpCache, InMemoryCache

    # only cache the last request
    cn = connect(email='...', token='...', cache=InMemoryCache(size=1))

    # no caching
    cn = connect(email='...', token='...', cache=NoOpCache())

You can also substitute your own custom cache here to use e.g. Redis or
memcached.

Prospyr also supports multiple named connections. Provide a ``name='...'``
argument when calling ``connect()`` and refer to the connection when
interacting with the API later, e.g. ``Person.objects.get(id=1, using='...')``.

Create
------

You can create new records in ProsperWorks.

.. code-block:: python

    from prospyr import Person

    steve = Person(
        name='Steve Cognito',
        emails=[{'category': 'work', 'email': 'steve@example.org'}]
    )

    # steve only exists locally at this stage
    steve.id
    >>> None

    # now he exists remotely too
    steve.create()
    >>> True
    steve.id
    >>> 1

Read
----

There are two ways to read a single record from ProsperWorks. A new instance
can be fetched using the resource's ``objects.get()`` method, or you can call
``read()`` on an existing instance to have its attributes refreshed.

.. code-block:: python

    from prospyr import Person

    # a new instance
    steve = Person.objects.get(id=1)
    steve.name
    >>> 'Steve Cognito'

    # update an existing instance
    steve = Person(id=1)
    steve.read()
    >>> True
    steve.name
    >>> 'Steve Cognito'

    # as a special case, People can be read by email as well as ID:
    steve = Person.objects.get(email='steve@example.org')

Update
------

Note that “update” means to push an update to ProsperWorks using your local
data, rather than to refresh local data using ProsperWorks. In this example,
Steve is fetched from ProsperWorks and given a new title. Hey, congrats on the
promotion Steve.

.. code-block:: python

    from prospyr import Person

    steve = Person.objects.get(id=1)
    steve.title = 'Chairman'
    steve.update()
    >>> True

Delete
------

When Steve has reached the end of his useful lifespan, he can be deleted too.

.. code-block:: python

    from prospyr import Person

    steve = Person.objects.get(id=1)
    steve.delete()
    >>> True

Ordering
--------

Resource collections can be ordered. Check the `ProsperWorks API documentation
<https://www.prosperworks.com/developer_api/>`_ to learn which fields can be
ordered. However, Prospyr does check that the fields you argue are correct.

.. code-block:: python

    from prospyr import Person

    # oldest first
    rs = Person.objects.order_by('date_modified')

    # newest first (note the hyphen)
    rs = Person.objects.order_by('-date_modified')

    # At this stage, no requests have been made. Results are lazily evaluated
    # and paging is handled transparently.

    # The results can be indexed and sliced like a Python list. Doing so forces
    # evaluation. The below causes the first page of results to be fetched.
    rs[0]
    >>> <Person: Steve Cognito>

    # No request is required here, as the Bones was on the first page requested
    # above. The default page size is 200.
    rs[1]
    >>> <Person: Bones Johannson>

    # This result is on the second page, so another request is fired.
    rs[200]
    >>> <Person: Alfons Tundra>

Once ``ResultSet`` instances have been evaluated they are cached for their
lifetime. However, the ``filter()`` and ``order_by()`` methods return new
``ResultSet`` instances which require fresh evaluation. While you are dealing
with a single ``ResultSet``, it is safe to iterate and slice it as many times
as necessary.


Filtering
---------

Resource collections can be filtered. Check the `ProsperWorks API documentation
<https://www.prosperworks.com/developer_api/>`_ to learn which filters can be
used. Prospyr does *not* currently validate your filter arguments, and note
that ProsperWorks does not either; if you make an invalid filter argument,
results will be returned as though you had not filtered at all.

Multiple filters are logically ANDed together. A single call to ``filter()``
with many parameters is equivalent to many calls with single parameters.


.. code-block:: python

    from prospyr import Company

    active = Company.objects.filter(minimum_interaction_count=10)
    active_in_china = active.filter(country='CN')

    # this is equivalent
    active_in_china = Company.objects.filter(
        minimum_interaction_count=10,
        country='CN'
    )

As with ordering, filtered results are evaluated lazily and then cached
indefinitely. Re-ordering or re-filtering results in a new ``ResultSet`` which
requires fresh evaluation.

ProsperWorks' “Secondary Resources”, such as Pipeline Stages, cannot be
filtered or ordered. These resources use ``ListSet`` rather than ``ResultSet``
instances; these only support the ``all()`` method:

.. code-block:: python

    from prospyr import PipelineStage

    PipelineStage.objects.all()
    >>> <ListSet: Qualifying, Quoted, ...>


Account
-------

The ``Account`` resource represents the ProsperWorks account which you are
currently working with. The name of the account can be read like so:

.. code-block:: python

    from prospyr import Account

    account = Account.objects.get()
    account.name
    >>> 'So-and-so Company'


Collection Error Handling
-------------------------

Prospyr validates data delivered from ProsperWorks when building representative
Python objects for local use. Because there are no documented details on the
validation that ProsperWorks itself uses, Prospyr's validation rules are
sometimes incorrect or more strict than necessary. The author suspects that
sometimes ProsperWorks also delivers data that is simply invalid.

This can cause exceptions to be raised when iterating over result sets (e.g.
``for person in Person.objects.all()...``) which prevent the remainder of the
collection from being accessed.

To make your life easier while such a mismatch is corrected in Prospyr, you can
choose to have these validation errors collected instead of being raised:

.. code-block:: python

    from prospyr import Person

    errs = []
    for person in Person.objects.store_invalid(errs).all():
        # ...

    if errs:
        # handle errors

The argument to ``store_invalid`` must, like a list, have a working ``append``
method. It will be filled with ``ValidationError`` instances which each have
``errors``, ``raw_data`` and ``resource_cls`` attributes.

If your use–case allows you to correct the problem in ``raw_data``, you can
recover like so:

.. code-block:: python

    for err in errs:
        good_data = make_corrections(err.raw_data)
        instance = err.resource_cls.from_api_data(good_data)


Tests
=====

.. code-block:: sh

    pip install -r dev-requirements

    # test using the current python interpreter
    make test

    # test with all supported interpreters
    tox



            

Raw data

            {
    "maintainer": "", 
    "docs_url": null, 
    "requires_python": "", 
    "maintainer_email": "", 
    "cheesecake_code_kwalitee_id": null, 
    "coveralis": false, 
    "keywords": "ProsperWorks", 
    "upload_time": "2017-01-12 09:52:02", 
    "author": "Ben Graham", 
    "home_page": "https://github.com/salespreso/prospyr/", 
    "github_user": "salespreso", 
    "download_url": "https://pypi.python.org/packages/96/f4/02a10da947d987c6e58bdcd9a1ea0023ac9d408706f030c9203bea6cf98f/prospyr-0.7.0.tar.gz", 
    "platform": "", 
    "version": "0.7.0", 
    "cheesecake_documentation_id": null, 
    "description": "Prospyr\n#######\n\nA Python client library for ProsperWorks.\n\n.. image:: https://api.travis-ci.org/salespreso/prospyr.svg?branch=master\n   :target: https://travis-ci.org/salespreso/prospyr\n   :alt: Prospyr builds.\n\n.. image:: https://img.shields.io/codecov/c/github/salespreso/prospyr.svg\n   :target: https://codecov.io/github/salespreso/prospyr\n   :alt: Prospyr on Codecov.\n\n.. image:: https://landscape.io/github/salespreso/prospyr/master/landscape.svg?style=flat\n   :target: https://landscape.io/github/salespreso/prospyr/master\n   :alt: Code Health\n\n.. image:: https://badge.fury.io/py/prospyr.svg\n   :target: https://pypi.python.org/pypi/prospyr/\n   :alt: Prospyr on Pypi.\n\nProspyr runs on Python 2.7 or Python 3.4+. \n\nInstallation\n============\n\n.. code-block:: sh\n\n    pip install prospyr\n\nQuickstart\n==========\n\nIf you've used Django, Prospyr might feel strangely familiar.\n\n.. code-block:: python\n\n    from prospyr import connect, Person, Company\n\n    # see https://www.prosperworks.com/developer_api/token_generation to obtain\n    # a token.\n    cn = connect(email='user@domain.tld', token='1aefcc3...')\n\n    # collections can be ordered and sliced.\n    newest_person = Person.objects.order_by('-date_modified')[0]\n\n    # new records can be created.\n    art = Person(\n        name='Art Vandelay',\n        emails=[{'email': 'art@vandelayindustries.net', 'category': 'work'}]\n    )\n    art.create()  # Art is local-only until .create() is called\n\n    # related objects can be read and assigned\n    art.company = Company.objects.all()[0]\n    art.update()\n\n    # and deleting works too.\n    art.delete()\n\n\nResources\n=========\n\nThe following ProsperWorks resources are supported by Prospyr:\n\n- Account (read-only)\n- Activity (read\u2013only)\n- ActivityType\n- Company\n- CustomerSource (read\u2013only)\n- Identifier\n- Lead\n- LossReason (read\u2013only)\n- Opportunity\n- Person\n- Pipeline (read\u2013only)\n- PipelineStage (read\u2013only)\n- Task (read\u2013only)\n- User (read\u2013only)\n\nThe following resources are not supported, but will still appear when\nreferenced by the supported resources above. In this case, they come only with\nan ``id`` attribute.\n\n- Project\n\nNote you will receive errors trying to deal with the Lead resource if the Leads\nfeature is not enabled in your ProsperWorks account. You can change this at\nSettings / Customize ProsperWorks / Lead Management.\n\n\nUsage\n=====\n\nConnecting\n----------\n\nTo connect, you'll need an email and token per\n`token generation <https://www.prosperworks.com/developer_api/token_generation>`_.\n\n.. code-block:: python\n\n    from prospyr import connect\n\n    cn = connect(email='...', token='...')\n\nAll reads are cached per\u2013connection for five minutes. You can pass a custom\ncache instance when connecting to ProsperWorks to change this behaviour.\n\n.. code-block:: python\n\n    from prospyr import connect\n    from prospyr.cache import NoOpCache, InMemoryCache\n\n    # only cache the last request\n    cn = connect(email='...', token='...', cache=InMemoryCache(size=1))\n\n    # no caching\n    cn = connect(email='...', token='...', cache=NoOpCache())\n\nYou can also substitute your own custom cache here to use e.g. Redis or\nmemcached.\n\nProspyr also supports multiple named connections. Provide a ``name='...'``\nargument when calling ``connect()`` and refer to the connection when\ninteracting with the API later, e.g. ``Person.objects.get(id=1, using='...')``.\n\nCreate\n------\n\nYou can create new records in ProsperWorks.\n\n.. code-block:: python\n\n    from prospyr import Person\n\n    steve = Person(\n        name='Steve Cognito',\n        emails=[{'category': 'work', 'email': 'steve@example.org'}]\n    )\n\n    # steve only exists locally at this stage\n    steve.id\n    >>> None\n\n    # now he exists remotely too\n    steve.create()\n    >>> True\n    steve.id\n    >>> 1\n\nRead\n----\n\nThere are two ways to read a single record from ProsperWorks. A new instance\ncan be fetched using the resource's ``objects.get()`` method, or you can call\n``read()`` on an existing instance to have its attributes refreshed.\n\n.. code-block:: python\n\n    from prospyr import Person\n\n    # a new instance\n    steve = Person.objects.get(id=1)\n    steve.name\n    >>> 'Steve Cognito'\n\n    # update an existing instance\n    steve = Person(id=1)\n    steve.read()\n    >>> True\n    steve.name\n    >>> 'Steve Cognito'\n\n    # as a special case, People can be read by email as well as ID:\n    steve = Person.objects.get(email='steve@example.org')\n\nUpdate\n------\n\nNote that \u201cupdate\u201d means to push an update to ProsperWorks using your local\ndata, rather than to refresh local data using ProsperWorks. In this example,\nSteve is fetched from ProsperWorks and given a new title. Hey, congrats on the\npromotion Steve.\n\n.. code-block:: python\n\n    from prospyr import Person\n\n    steve = Person.objects.get(id=1)\n    steve.title = 'Chairman'\n    steve.update()\n    >>> True\n\nDelete\n------\n\nWhen Steve has reached the end of his useful lifespan, he can be deleted too.\n\n.. code-block:: python\n\n    from prospyr import Person\n\n    steve = Person.objects.get(id=1)\n    steve.delete()\n    >>> True\n\nOrdering\n--------\n\nResource collections can be ordered. Check the `ProsperWorks API documentation\n<https://www.prosperworks.com/developer_api/>`_ to learn which fields can be\nordered. However, Prospyr does check that the fields you argue are correct.\n\n.. code-block:: python\n\n    from prospyr import Person\n\n    # oldest first\n    rs = Person.objects.order_by('date_modified')\n\n    # newest first (note the hyphen)\n    rs = Person.objects.order_by('-date_modified')\n\n    # At this stage, no requests have been made. Results are lazily evaluated\n    # and paging is handled transparently.\n\n    # The results can be indexed and sliced like a Python list. Doing so forces\n    # evaluation. The below causes the first page of results to be fetched.\n    rs[0]\n    >>> <Person: Steve Cognito>\n\n    # No request is required here, as the Bones was on the first page requested\n    # above. The default page size is 200.\n    rs[1]\n    >>> <Person: Bones Johannson>\n\n    # This result is on the second page, so another request is fired.\n    rs[200]\n    >>> <Person: Alfons Tundra>\n\nOnce ``ResultSet`` instances have been evaluated they are cached for their\nlifetime. However, the ``filter()`` and ``order_by()`` methods return new\n``ResultSet`` instances which require fresh evaluation. While you are dealing\nwith a single ``ResultSet``, it is safe to iterate and slice it as many times\nas necessary.\n\n\nFiltering\n---------\n\nResource collections can be filtered. Check the `ProsperWorks API documentation\n<https://www.prosperworks.com/developer_api/>`_ to learn which filters can be\nused. Prospyr does *not* currently validate your filter arguments, and note\nthat ProsperWorks does not either; if you make an invalid filter argument,\nresults will be returned as though you had not filtered at all.\n\nMultiple filters are logically ANDed together. A single call to ``filter()``\nwith many parameters is equivalent to many calls with single parameters.\n\n\n.. code-block:: python\n\n    from prospyr import Company\n\n    active = Company.objects.filter(minimum_interaction_count=10)\n    active_in_china = active.filter(country='CN')\n\n    # this is equivalent\n    active_in_china = Company.objects.filter(\n        minimum_interaction_count=10,\n        country='CN'\n    )\n\nAs with ordering, filtered results are evaluated lazily and then cached\nindefinitely. Re-ordering or re-filtering results in a new ``ResultSet`` which\nrequires fresh evaluation.\n\nProsperWorks' \u201cSecondary Resources\u201d, such as Pipeline Stages, cannot be\nfiltered or ordered. These resources use ``ListSet`` rather than ``ResultSet``\ninstances; these only support the ``all()`` method:\n\n.. code-block:: python\n\n    from prospyr import PipelineStage\n\n    PipelineStage.objects.all()\n    >>> <ListSet: Qualifying, Quoted, ...>\n\n\nAccount\n-------\n\nThe ``Account`` resource represents the ProsperWorks account which you are\ncurrently working with. The name of the account can be read like so:\n\n.. code-block:: python\n\n    from prospyr import Account\n\n    account = Account.objects.get()\n    account.name\n    >>> 'So-and-so Company'\n\n\nCollection Error Handling\n-------------------------\n\nProspyr validates data delivered from ProsperWorks when building representative\nPython objects for local use. Because there are no documented details on the\nvalidation that ProsperWorks itself uses, Prospyr's validation rules are\nsometimes incorrect or more strict than necessary. The author suspects that\nsometimes ProsperWorks also delivers data that is simply invalid.\n\nThis can cause exceptions to be raised when iterating over result sets (e.g.\n``for person in Person.objects.all()...``) which prevent the remainder of the\ncollection from being accessed.\n\nTo make your life easier while such a mismatch is corrected in Prospyr, you can\nchoose to have these validation errors collected instead of being raised:\n\n.. code-block:: python\n\n    from prospyr import Person\n\n    errs = []\n    for person in Person.objects.store_invalid(errs).all():\n        # ...\n\n    if errs:\n        # handle errors\n\nThe argument to ``store_invalid`` must, like a list, have a working ``append``\nmethod. It will be filled with ``ValidationError`` instances which each have\n``errors``, ``raw_data`` and ``resource_cls`` attributes.\n\nIf your use\u2013case allows you to correct the problem in ``raw_data``, you can\nrecover like so:\n\n.. code-block:: python\n\n    for err in errs:\n        good_data = make_corrections(err.raw_data)\n        instance = err.resource_cls.from_api_data(good_data)\n\n\nTests\n=====\n\n.. code-block:: sh\n\n    pip install -r dev-requirements\n\n    # test using the current python interpreter\n    make test\n\n    # test with all supported interpreters\n    tox\n\n\n", 
    "tox": true, 
    "lcname": "prospyr", 
    "bugtrack_url": null, 
    "github": true, 
    "name": "prospyr", 
    "license": "MIT", 
    "travis_ci": true, 
    "github_project": "prospyr", 
    "summary": "ProsperWorks client library", 
    "split_keywords": [
        "prosperworks"
    ], 
    "author_email": "ben.graham@salespreso.com", 
    "urls": [
        {
            "has_sig": true, 
            "upload_time": "2017-01-12T09:52:00", 
            "comment_text": "", 
            "python_version": "py2.py3", 
            "url": "https://pypi.python.org/packages/c8/87/2c8ef192839078aee379eb58740592f588f93a835f6bc6c820245854c42a/prospyr-0.7.0-py2.py3-none-any.whl", 
            "md5_digest": "2a4119ba6d9327e85437f22594e8c5db", 
            "downloads": 0, 
            "filename": "prospyr-0.7.0-py2.py3-none-any.whl", 
            "packagetype": "bdist_wheel", 
            "path": "c8/87/2c8ef192839078aee379eb58740592f588f93a835f6bc6c820245854c42a/prospyr-0.7.0-py2.py3-none-any.whl", 
            "size": 25659
        }, 
        {
            "has_sig": true, 
            "upload_time": "2017-01-12T09:52:02", 
            "comment_text": "", 
            "python_version": "source", 
            "url": "https://pypi.python.org/packages/96/f4/02a10da947d987c6e58bdcd9a1ea0023ac9d408706f030c9203bea6cf98f/prospyr-0.7.0.tar.gz", 
            "md5_digest": "a6010e4c8b8bdf9f4f1e54b0e6f2b185", 
            "downloads": 0, 
            "filename": "prospyr-0.7.0.tar.gz", 
            "packagetype": "sdist", 
            "path": "96/f4/02a10da947d987c6e58bdcd9a1ea0023ac9d408706f030c9203bea6cf98f/prospyr-0.7.0.tar.gz", 
            "size": 18374
        }
    ], 
    "_id": null, 
    "cheesecake_installability_id": null
}