<commit_before>===============
Getting started
===============

Now it's time to begin doing some work with Cloudant and Python.  For working
code samples of any of the API's please go to our test suite.

.. toctree::
   :maxdepth: 2

***********
Connections
***********

In order to manage a connection you must first initialize the connection by 
constructing either a ``Cloudant`` or ``CouchDB`` client.  Since connecting to 
the Cloudant managed service provides extra end points as compared to a CouchDB 
server, we provide the two different client implementations in order to 
connect to the desired database service.  Once the client is constructed, 
you follow that up by connecting to the server, performing your tasks, and
then disconnecting from the server.

Later in the `Context managers`_ section we will see how to 
simplify this process through the use of the Python *with* statement.

Note: If you require retrying requests after an HTTP 429 error, the
``Replay429Adapter`` can be added when constructing a ``Cloudant``
client and configured with an initial back off and retry count.

Note: Currently, the connect and read timeout will wait forever for
a HTTP connection or a response on all requests.  A timeout can be
set using the ``timeout`` argument when constructing a client.

Connecting with a client
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    # Use CouchDB to create a CouchDB client
    # from cloudant.client import CouchDB
    # client = CouchDB(USERNAME, PASSWORD, url='http://127.0.0.1:5984')

    # Use Cloudant to create a Cloudant client using account
    from cloudant.client import Cloudant
    client = Cloudant(USERNAME, PASSWORD, account=ACCOUNT_NAME, connect=True)
    # or using url
    # client = Cloudant(USERNAME, PASSWORD, url='https://acct.cloudant.com')

    # or with a 429 replay adapter that includes configured retries and initial backoff
    # client = Cloudant(USERNAME, PASSWORD, account=ACCOUNT_NAME,
    #                   adapter=Replay429Adapter(retries=10, initialBackoff=0.01))

    # or with a connect and read timeout of 5 minutes
    # client = Cloudant(USERNAME, PASSWORD, account=ACCOUNT_NAME,
    #                   timeout=300)

    # Perform client tasks...
    session = client.session()
    print('Username: {0}'.format(session['userCtx']['name']))
    print('Databases: {0}'.format(client.all_dbs()))

    # Disconnect from the server
    client.disconnect()

**************
Authentication
**************

When constructing a ``Cloudant`` client, you can authenticate using the
`cookie authentication <http://guide.couchdb.org/editions/1/en/security.html#cookies>`_ functionality.
The server will always attempt to automatically renew the cookie
shortly before its expiry. However, if the client does not send a
request to the server during this renewal window and
``auto_renew=False`` then the cookie is not renewed.

Using ``auto_renew=True`` will attempt to renew the cookie at
any point during the lifetime of the session when either of the
following statements hold true:

- The server returns a ``credentials_expired`` error message.
- The server returns a ``401 Unauthorized`` status code.
- The server returns a ``403 Forbidden`` status code.

.. code-block:: python

    # Create client using auto_renew to automatically renew expired cookie auth
    client = Cloudant(USERNAME, PASSWORD, url='https://acct.cloudant.com',
                     connect=True,
                     auto_renew=True)


************************************
Identity and Access Management (IAM)
************************************

IBM Cloud Identity & Access Management enables you to securely authenticate
users and control access to all cloud resources consistently in the IBM Bluemix
Cloud Platform.

See `IBM Cloud Identity and Access Management <https://console.bluemix.net/docs/services/Cloudant/guides/iam.html#ibm-cloud-identity-and-access-management>`_
for more information.

You can easily connect to your Cloudant account using an IAM API key:

.. code-block:: python

    # Authenticate using an IAM API key
    client = Cloudant.iam(ACCOUNT_NAME, API_KEY, connect=True)


****************
Resource sharing
****************

The ``Cloudant`` or ``CouchDB`` client objects make HTTP calls using the ``requests`` library.
``requests`` uses the `urllib3 <https://pypi.python.org/pypi/urllib3>`_ library which features
connection pooling and thread safety.

Connection pools can be managed by using the ``requests`` library's
`HTTPAdapter <https://github.com/kennethreitz/requests/blob/master/requests/adapters.py#L78>`_<commit_msg>Add IAM_TOKEN_URL env var note to docs/getting_started.rst<commit_after>===============
Getting started
===============

Now it's time to begin doing some work with Cloudant and Python.  For working
code samples of any of the API's please go to our test suite.

.. toctree::
   :maxdepth: 2

***********
Connections
***********

In order to manage a connection you must first initialize the connection by 
constructing either a ``Cloudant`` or ``CouchDB`` client.  Since connecting to 
the Cloudant managed service provides extra end points as compared to a CouchDB 
server, we provide the two different client implementations in order to 
connect to the desired database service.  Once the client is constructed, 
you follow that up by connecting to the server, performing your tasks, and
then disconnecting from the server.

Later in the `Context managers`_ section we will see how to 
simplify this process through the use of the Python *with* statement.

Note: If you require retrying requests after an HTTP 429 error, the
``Replay429Adapter`` can be added when constructing a ``Cloudant``
client and configured with an initial back off and retry count.

Note: Currently, the connect and read timeout will wait forever for
a HTTP connection or a response on all requests.  A timeout can be
set using the ``timeout`` argument when constructing a client.

Connecting with a client
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    # Use CouchDB to create a CouchDB client
    # from cloudant.client import CouchDB
    # client = CouchDB(USERNAME, PASSWORD, url='http://127.0.0.1:5984')

    # Use Cloudant to create a Cloudant client using account
    from cloudant.client import Cloudant
    client = Cloudant(USERNAME, PASSWORD, account=ACCOUNT_NAME, connect=True)
    # or using url
    # client = Cloudant(USERNAME, PASSWORD, url='https://acct.cloudant.com')

    # or with a 429 replay adapter that includes configured retries and initial backoff
    # client = Cloudant(USERNAME, PASSWORD, account=ACCOUNT_NAME,
    #                   adapter=Replay429Adapter(retries=10, initialBackoff=0.01))

    # or with a connect and read timeout of 5 minutes
    # client = Cloudant(USERNAME, PASSWORD, account=ACCOUNT_NAME,
    #                   timeout=300)

    # Perform client tasks...
    session = client.session()
    print('Username: {0}'.format(session['userCtx']['name']))
    print('Databases: {0}'.format(client.all_dbs()))

    # Disconnect from the server
    client.disconnect()

**************
Authentication
**************

When constructing a ``Cloudant`` client, you can authenticate using the
`cookie authentication <http://guide.couchdb.org/editions/1/en/security.html#cookies>`_ functionality.
The server will always attempt to automatically renew the cookie
shortly before its expiry. However, if the client does not send a
request to the server during this renewal window and
``auto_renew=False`` then the cookie is not renewed.

Using ``auto_renew=True`` will attempt to renew the cookie at
any point during the lifetime of the session when either of the
following statements hold true:

- The server returns a ``credentials_expired`` error message.
- The server returns a ``401 Unauthorized`` status code.
- The server returns a ``403 Forbidden`` status code.

.. code-block:: python

    # Create client using auto_renew to automatically renew expired cookie auth
    client = Cloudant(USERNAME, PASSWORD, url='https://acct.cloudant.com',
                     connect=True,
                     auto_renew=True)


************************************
Identity and Access Management (IAM)
************************************

IBM Cloud Identity & Access Management enables you to securely authenticate
users and control access to all cloud resources consistently in the IBM Bluemix
Cloud Platform.

See `IBM Cloud Identity and Access Management <https://console.bluemix.net/docs/services/Cloudant/guides/iam.html#ibm-cloud-identity-and-access-management>`_
for more information.

The production IAM token service at *https://iam.bluemix.net/oidc/token* is used
by default. You can set an ``IAM_TOKEN_URL`` environment variable to override
this.

You can easily connect to your Cloudant account using an IAM API key:

.. code-block:: python

    # Authenticate using an IAM API key
    client = Cloudant.iam(ACCOUNT_NAME, API_KEY, connect=True)


****************
Resource sharing
****************

The ``Cloudant`` or ``CouchDB`` client objects make HTTP calls using the ``requests`` library.
``requests`` uses the `urllib3 <https://pypi.python.org/pypi/urllib3>`_ library which features
connection pooling and thread safety.

Connection pools can be managed by using the ``requests`` library's
`HTTPAdapter <https://github.com/kennethreitz/requests/blob/master/requests/adapters.py#L78>`_
{'fraction_non_alphanumeric': 0.11756599173115657, 'fraction_numerical': 0.009540973179264285, 'mean_word_length': 4.28515406162465, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 11, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '84415', 'n_tokens_mistral': 2605, 'n_tokens_neox': 2447, 'n_words': 1056}