<commit_before>Building a Python client to make REST API calls to the Sds Service
==================================================================

The sample code in this topic demonstrates how to invoke Sds REST APIs
using Python. By examining the code, you will see how to establish a connection 
to Sds, obtain an authorization token, create an SdsNamespace, SdsType, and SdsStream, 
and how to create, read, update, and delete values in Sds.

The sections that follow provide a brief description of the process from
beginning to end.

Python Version:
---------------

Two versions of the sample code are provided, one targets environments running Python 2.x 
and the other targets those running Python 3.x.  Please use the sample that is appropriate 
for your environment.  You can determine which version of Python you are running by typing 
the following at the command line:

.. code::

	python -V

The samples were built and tested against Python 3.6.4 and Python 2.7.14.  If you are using 
a different version you might encounter errors or unexepected behavior.    
	
To Run this Sample:
-------------------
1. Clone the GitHub repository
2. Open the folder with your favorite IDE
3. Update ``config.ini`` with the credentials provided by OSIsoft
4. Run ``program.py``

Establish a Connection
----------------------

The sample code uses the ``requests`` module, which 
exposes simple methods for specifying request types to a given
destination address. The client calls the requests method by passing a destination
URL, payload, and headers. The server's response is stored.

.. code:: python

    response = requests.post(url, data=payload, headers=client_headers)

-  *url* is the service endpoint (for example:
   ``https://dat-a.osisoft.com``). The connection is used by the
   ``SdsClient`` class.

Each call to the Sds REST API consists of an HTTP request along with a specific 
URL and HTTP method. The URL consists of the server name plus the extension that 
is specific to the call. Like all REST APIs, the Sds REST API maps HTTP
methods to CRUD operations as shown in the following table:

+---------------+------------------+--------------------+
| HTTP Method   | CRUD Operation   | Content Found In   |
+===============+==================+====================+
| POST          | Create           | Message body       |
+---------------+------------------+--------------------+
| GET           | Retrieve         | URL parameters     |
+---------------+------------------+--------------------+
| PUT           | Update           | Message body       |
+---------------+------------------+--------------------+
| DELETE        | Delete           | URL parameters     |
+---------------+------------------+--------------------+

Configure the Sample:
-----------------------

Included in the sample there is a configuration file with placeholders that 
need to be replaced with the proper values. They include information for 
authentication, connecting to the Sds Service, and pointing to a namespace.

The Sds Service is secured using Azure Active Directory. The sample application 
is an example of a *confidential client*. Confidential clients provide an application ID 
and secret that are authenticated against the directory. These are referred to as client 
IDs and client secrets, which are associated with a given tenant. They are created through 
the tenant's administration portal. The steps necessary to create a new client ID and secret 
are described below.

First, log on to the `Cloud Portal <https://cloud.osisoft.com>`__ with admin credentials 
and navigate to the ``Client Keys`` page under the ``Manage`` tab, which is situated along 
the top of the webpage. Two types of keys may be created. For a complete explanation of 
key roles look at the help bar on the right side of the page. This sample program covers 
data creation, deletion and retrieval, so an administration key must be used in the 
configuration file. Creating a new key is simple. Enter a name for the key, select 
``Administrator role``, then click ``Add Key``.

Next, view the key by clicking the small eye icon on the right of the created key, 
located in the list of available keys. A pop-up will appear with the tenant ID, client 
ID and client secret. These must replace the corresponding values in the sample's 
configuration file. 

Along with the client ID and secret values, add the tenant name to the authority value 
so authentication occurs against the correct tenant. The URL for the Sds Service 
connection must also be changed to reflect the destination address of the requests. 

Finally, a valid namespace ID for the tenant must be given. To create a 
namespace, click on the ``Manage`` tab then navigate to the ``Namespaces`` page. 
At the top the add button will create a new namespace after the required forms are 
completed. This namespace is now associated with the logged-in tenant and may be 
used in the sample.

The values to be replaced are in ``config.ini``:

.. code:: python

	[Configurations]
	Namespace = Samples

	[Access]
	Address = https://dat-a.osisoft.com
	Tenant = REPLACE_WITH_TENANT_ID
    ApiVersion = v1-preview

	[Credentials]
	Resource = https://sdshomeprod.onmicrosoft.com/ocsapi
	Authority = https://login.microsoftonline.com/<REPLACE_WITH_TENANT_ID>
	ClientId = REPLACE_WITH_APPLICATION_IDENTIFIER
	ClientSecret = REPLACE_WITH_APPLICATION_SECRET
<commit_msg>fix tab in py2 readme<commit_after>Building a Python client to make REST API calls to the Sds Service
==================================================================

The sample code in this topic demonstrates how to invoke Sds REST APIs
using Python. By examining the code, you will see how to establish a connection 
to Sds, obtain an authorization token, create an SdsNamespace, SdsType, and SdsStream, 
and how to create, read, update, and delete values in Sds.

The sections that follow provide a brief description of the process from
beginning to end.

Python Version:
---------------

Two versions of the sample code are provided, one targets environments running Python 2.x 
and the other targets those running Python 3.x.  Please use the sample that is appropriate 
for your environment.  You can determine which version of Python you are running by typing 
the following at the command line:

.. code::

	python -V

The samples were built and tested against Python 3.6.4 and Python 2.7.14.  If you are using 
a different version you might encounter errors or unexepected behavior.    
	
To Run this Sample:
-------------------
1. Clone the GitHub repository
2. Open the folder with your favorite IDE
3. Update ``config.ini`` with the credentials provided by OSIsoft
4. Run ``program.py``

Establish a Connection
----------------------

The sample code uses the ``requests`` module, which 
exposes simple methods for specifying request types to a given
destination address. The client calls the requests method by passing a destination
URL, payload, and headers. The server's response is stored.

.. code:: python

    response = requests.post(url, data=payload, headers=client_headers)

-  *url* is the service endpoint (for example:
   ``https://dat-a.osisoft.com``). The connection is used by the
   ``SdsClient`` class.

Each call to the Sds REST API consists of an HTTP request along with a specific 
URL and HTTP method. The URL consists of the server name plus the extension that 
is specific to the call. Like all REST APIs, the Sds REST API maps HTTP
methods to CRUD operations as shown in the following table:

+---------------+------------------+--------------------+
| HTTP Method   | CRUD Operation   | Content Found In   |
+===============+==================+====================+
| POST          | Create           | Message body       |
+---------------+------------------+--------------------+
| GET           | Retrieve         | URL parameters     |
+---------------+------------------+--------------------+
| PUT           | Update           | Message body       |
+---------------+------------------+--------------------+
| DELETE        | Delete           | URL parameters     |
+---------------+------------------+--------------------+

Configure the Sample:
-----------------------

Included in the sample there is a configuration file with placeholders that 
need to be replaced with the proper values. They include information for 
authentication, connecting to the Sds Service, and pointing to a namespace.

The Sds Service is secured using Azure Active Directory. The sample application 
is an example of a *confidential client*. Confidential clients provide an application ID 
and secret that are authenticated against the directory. These are referred to as client 
IDs and client secrets, which are associated with a given tenant. They are created through 
the tenant's administration portal. The steps necessary to create a new client ID and secret 
are described below.

First, log on to the `Cloud Portal <https://cloud.osisoft.com>`__ with admin credentials 
and navigate to the ``Client Keys`` page under the ``Manage`` tab, which is situated along 
the top of the webpage. Two types of keys may be created. For a complete explanation of 
key roles look at the help bar on the right side of the page. This sample program covers 
data creation, deletion and retrieval, so an administration key must be used in the 
configuration file. Creating a new key is simple. Enter a name for the key, select 
``Administrator role``, then click ``Add Key``.

Next, view the key by clicking the small eye icon on the right of the created key, 
located in the list of available keys. A pop-up will appear with the tenant ID, client 
ID and client secret. These must replace the corresponding values in the sample's 
configuration file. 

Along with the client ID and secret values, add the tenant name to the authority value 
so authentication occurs against the correct tenant. The URL for the Sds Service 
connection must also be changed to reflect the destination address of the requests. 

Finally, a valid namespace ID for the tenant must be given. To create a 
namespace, click on the ``Manage`` tab then navigate to the ``Namespaces`` page. 
At the top the add button will create a new namespace after the required forms are 
completed. This namespace is now associated with the logged-in tenant and may be 
used in the sample.

The values to be replaced are in ``config.ini``:

.. code:: python

	[Configurations]
	Namespace = Samples

	[Access]
	Address = https://dat-a.osisoft.com
	Tenant = REPLACE_WITH_TENANT_ID
    	ApiVersion = v1-preview

	[Credentials]
	Resource = https://sdshomeprod.onmicrosoft.com/ocsapi
	Authority = https://login.microsoftonline.com/<REPLACE_WITH_TENANT_ID>
	ClientId = REPLACE_WITH_APPLICATION_IDENTIFIER
	ClientSecret = REPLACE_WITH_APPLICATION_SECRET

{'fraction_non_alphanumeric': 0.1340957299640321, 'fraction_numerical': 0.002674536567370654, 'mean_word_length': 2.911976911976912, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, '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': '7582834', 'n_tokens_mistral': 2658, 'n_tokens_neox': 2537, 'n_words': 1434}