Metadata-Version: 1.1
Name: neverbounce-sdk
Version: 1.0.5
Summary: Official Python SDK for the NeverBounce API
Home-page: https://github.com/NeverBounce/NeverBounceApi-Python
Author: NeverBounce Team
Author-email: support@neverbounce.com
License: MIT
Description: *********************
        NeverBounceApi-Python
        *********************
        
        .. image:: https://neverbounce-marketing.s3.amazonaws.com/neverbounce_color_600px.png
            :target: https://neverbounce.com
            :width: 600
            :align: center
            :alt: NeverBounce Logo
        
        |travisci| |codeclimate|
        
        Welcome to NeverBounce's Python SDK!  We hope that it will aid you in consuming
        our service.  Please report any bugs to the github issue tracker and make sure
        you read the documentation before use.
        
        .. pull-quote::
          This library is for use with NeverBounce's V4 API which is currently in beta
        
        Installation
        ------------
        
        The preferred method of installation is with ``pip`` in a virtual environment::
        
            pip install neverbounce_sdk
        
        If you must use ``easy_install``, you may.  If you'd like to install for local
        development::
        
            git clone git@github.com:NeverBounce/NeverBounceApi-Python.git
            cd NeverBounceApi-Python
            pip install -e .
        
        This will install ``neverbounce_sdk`` into the active environment in editable
        mode.
        
        
        Usage
        -----
        
        The NeverBounce Python SDK provides a simple interface by which to interact
        with NeverBounce's email verification API version 4.  To get up and running, make sure
        you have your API token on hand::
        
            import neverbounce_sdk
            api_key = 'my secret API token'
            client = neverbounce_sdk.client(api_key=api_key)
        
        And now you're ready to use the client.  You can check your account
        information::
        
            info = client.account_info()
            # info is {'billing_type': 'default', 'credits': 12345, ... }
        
        You can verify single emails::
        
            resp = client.single_verify('test@example.com')
            resp['result']              # 'invalid'
            resp['execution_time']      # 285
        
        And you can create, query the status of, and control email verification bulk
        jobs::
        
            emails = [
                {'email': 'tomato@veggies.com'},  # must have an 'email' key
                {'email': 'cucumber@veggies.com',
                'best_when': 'cold'},             # may contain "metadata"
            ]
            job = client.jobs_create(emails)
        
            # all state-changing methods return a status object
            resp = client.jobs_parse(job['id'], auto_start=False)
            assert resp['status'] == 'success'
        
            client.jobs_start(job['id'])
            progress = client.jobs_status(job['id'])
            print(progress)  # dict with keys 'job_status', 'started', 'percent_complete', etc
        
        When creating a job, you may attach "metadata" in the form of additional keys
        to each object (python ``dict``) included in the job input listing.  Note that
        these additional keys will be *broadcasted*; i.e., every row of the result set
        for the job will contain an entry for every key - if the value of the key was
        not specified in the input, it will be the empty string in the job processing's
        output.
        
        All API operations return dictionaries with information about the execution of
        the operation or the results of the operation, whichever is more appropriate.
        The only exceptions are the ``client.search`` and ``client.results`` functions.
        The response generated by these API endpoints is paginated; therefore these
        functions return custom iterators that allow you to iterate across the API's
        pagination::
        
            all_my_jobs = client.jobs_search()
            type(all_my_jobs)       # neverbounce_sdk.bulk.ResultIter
            for job in all_my_jobs:
                # process job
                # this loop will make API calls behind the scenes, so be careful!
                if all_my_jobs.page > 10:
                    break
        
        The ``ResultIter`` will pull down pages behind the scenes, so be careful!  A
        ``ResultIter`` will expose the raw API response as a ``data`` attribute, the
        current page number as ``page``, and the total number of pages as ``total_pages``,
        so you can use these attributes to implement finer-grained control over result
        iteration.  Additionally, the methods ``raw_search`` and ``raw_results`` of the
        client object will return the raw API response (this is the same as the ``data``
        attribute of the ``ResultIter`` object).
        
        Behind the scenes the client uses ``requests``, and if you would like to
        explicitly provide a ``requests.Session``, you may do so::
        
            from requests import Session
            api_key = 'my secret token'
            session = Session()
            client = neverbounce_sdk.client(api_key=api_key, session=session)
        
        And all outgoing HTTP requests will be routed through the session object's
        ``request`` method, taking advantage of ``requests.Session``'s connection pooling.
        You may provide any custom object that provides a ``request`` interface with the
        same signature as that provided by ``requests.Session`` and a ``close`` method.
        
        Finally, the client may be used a context manager.  If a session is provided,
        it will be used for all connections in the ``with`` block; if not, a session will
        be created.  Either way, a session associated with a client is **always**
        closed at the end of the context block. ::
        
            with neverbounce_sdk.client() as client:
                client.api_key = 'my secret token'
        
                # the client creates a session behind the scenes
                assert client.session is not None
        
                # do other stuff with the client
        
            # and then removes it at the end of the block
            assert client.session is None
        
        
        See Also
        --------
        
        Documentation for each function of the client object is available through
        Python's built-in ``help`` function, e.g.::
        
            >>> help(client.create)  # brings up a ton of information about the create
            ...                      # function's arguments and options
        
        Many of the inputs and outputs of the client object's functions map fairly
        closely to NeverBounce's raw v4 API, reading through the `official API
        docs<https://developers.neverbounce.com/v4.0/reference#account>` will be
        valuable in conjunction with using the built-in online help.
        
        .. |travisci| image:: https://travis-ci.org/NeverBounce/NeverBounceApi-Python.svg?branch=master
            :target: https://travis-ci.org/NeverBounce/NeverBounceApi-Python
            :alt: Build Status
        
        .. |codeclimate| image:: https://codeclimate.com/github/NeverBounce/NeverBounceApi-Python/badges/gpa.svg
            :target: https://codeclimate.com/github/NeverBounce/NeverBounceApi-Python
            :alt: Code Climate
        
Keywords: neverbounce,api,email,verification,cleaning
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Communications :: Email
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
