Changes for refinitiv-data.config.json file

Changes to explain how to open session using the 'official' json config file or alternative credentials store e.g. a .env file)

Author: umernalla

.gitignore

@@ -133,3 +133,4 @@ Configuration/refinitiv-data.config.json
 old/credentials.ipynb
 Configuration/refinitiv-data.config.json
 Configuration/refinitiv-data.config.json
+Configuration/refinitiv-data.config.json

Quick Start/1.0 - Sessions.ipynb

@@ -8,14 +8,14 @@
     "# Refinitiv Data Library for Python\n",
     "## Define and Open a session\n",
     "\n",
-    "Depending on the Credentials and Refinitiv Products/Services you have access to, you need define & open either a PlatformSession or DesktopSession: \n",
+    "Depending on the Credentials and Refinitiv Products/Services you have access to, you need define & open either a Platform Session or Desktop Session: \n",
     "\n",
-    " - **PlatformSession:** Used to connect to the Refinitiv Data Platform (RDP) directly or via a local (deployed) Real-time Distribution System(RTDS). The PlatformSession requires RDP credentials (machine account) or connection details of your local platform (IP of the local server and DACS user name).\n",
+    " - **Platform Session:** Used to connect to the Refinitiv Data Platform (RDP) directly or via a local (deployed) Real-time Distribution System(RTDS). The PlatformSession requires RDP credentials (machine account) or connection details of your local platform (IP of the local server and DACS user name).\n",
     "  - When the PlatformSession is used with RDP credentials only, it retrieves both streaming data and non-streaming data from the Refinitiv Data Platform.\n",
     "  - When the PlatformSession is used with connection details of your local deployed platform, it retrieves streaming data only from your local platform.  \n",
     "   \n",
     "   \n",
-    " - **DesktopSession:** This type of session is used to connect RDP either via Eikon or via the Refinitiv Workspace. Eikon or the Refinitiv Workspace must be run **on the same PC** as your Python code.\n",
+    " - **Desktop Session:** This type of session is used to connect RDP either via Eikon or via the Refinitiv Workspace. Eikon or the Refinitiv Workspace must be run **on the same PC** as your Python code.\n",
     " \n",
     "You will also require an App Key that uniquely identifies your application. Please refer to the Refinitiv Data Libraries Quick Start guide's **Access Credentials** section for instructions on creating an App Key."
    ]
@@ -25,24 +25,26 @@
    "id": "c77f2e4c-c19f-4a6c-ac1e-31d1678a28b4",
    "metadata": {},
    "source": [
-    "## Set the configuration file location\n",
-    "For ease of use, we offer the option of setting various initialization parameters of the Refinitiv Data Library in the _refinitiv-data.config.json_ configuration file. \n",
+    "## Set the location of the configuration file\n",
+    "For ease of use, you can set various initialization parameters of the RD Library in the **_refinitiv-data.config.json_** configuration file - as detailed in the next section below.\n",
     "\n",
-    "Typically you would place this file in the same folder as your Notebook or Python script.\n",
-    "Alternatively, you can place the file in an alternative folder as specified using the _RD_LIB_CONFIG_PATH_ environment variable. \n",
+    "Typically you may place this file in the same folder as your Notebook or Python script.\n",
+    "Alternatively, you can place the file in an folder of your choice and specify the location using the _RD_LIB_CONFIG_PATH_ environment variable. \n",
     "\n",
-    "As these tutorial Notebooks are in Categorised sub-folders and to avoid the need for multiple config files (in each folder), we will use the _RD_LIB_CONFIG_PATH_ environment variable to point to a single instance of the config file in the top-level ***Configuration*** folder."
+    "As these tutorial Notebooks are in Categorised sub-folders and to avoid the need for multiple config files (in each sub-folder), we will use the _RD_LIB_CONFIG_PATH_ environment variable to point to a single instance of the config file in the top-level ***Configuration*** folder.\n",
+    "\n",
+    "Before proceeding, please **ensure you have entered your credentials** into the config file in the ***Configuration*** folder."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "id": "4c9f9a18-4960-43bf-aeeb-9a60ce748084",
    "metadata": {},
    "outputs": [],
    "source": [
     "import os\n",
-    "os.environ[\"RD_LIB_CONFIG_PATH\"] = \"../../../Configuration\""
+    "os.environ[\"RD_LIB_CONFIG_PATH\"] = \"../Configuration\""
    ]
   },
   {
@@ -69,18 +71,21 @@
    "metadata": {},
    "source": [
     "## Using the 'refinitiv-data.config.json' file\n",
-    "The Refinitiv data library config file has a default name of **'refinitiv-data.config.json'** allows you to specify session related parameters such as:\n",
-    "* the default session to use\n",
-    "* credentials\n",
-    "* connectivity parameters  \n",
-    "\n",
-    "for the various session types.   \n",
+    "Using the Refinitiv data library config file allows you to specify various parameters such as:\n",
+    "* Default session\n",
+    "* Credentials\n",
+    "* Connectivity parameters  \n",
+    "* Logging related:   \n",
+    "  - Enable or Disable console/file logging\n",
+    "  - Log Level\n",
+    "  - Filename\n",
     "\n",
     "### Easiest way to Create & Open a Session\n",
     "\n",
-    "Using the config file, where possible, provides the simplest approach to creating and opening sessions.  \n",
+    "Using the above json config file, where possible, provides the simplest approach to creating and opening sessions.  \n",
     "For example, assuming you have \n",
-    "* a '*refinitiv-data.config.json*' in the current working directory \n",
+    "* a '*refinitiv-data.config.json*' in the ***Configuration*** directory \n",
+    "* **populated the file with your credentials**\n",
     "* and specified a 'default' session in the config file    \n",
     "\n",
     "you can create and open the default session as follows:"
@@ -121,15 +126,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "rd.open_session(name='platform.deployed')"
+    "rd.open_session(name='platform.rdp')"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "6917355d-c1f3-4df8-a5d5-368e7dea0d02",
    "metadata": {},
    "source": [
-    "The above would open a session based on the parameters specified in the '*\"platform.deployed\"* section of the json file."
+    "The above would open a session based on the parameters specified in the '*\"platform.rdp\"* section of the json file."
    ]
   },
   {
@@ -139,7 +144,7 @@
    "source": [
     "#### Open a session defined in a custom configuration file \n",
     "As well as the default config filename of **'refinitiv-data.config.json'**, you can also use a custom file to specify the config.   \n",
-    "The following call opens the default session as defined in your custom configuration file - with the filename passed as a parameter."
+    "The following call opens the default session as defined in a custom configuration file - with the filename passed as a parameter."
    ]
   },
   {
@@ -149,7 +154,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "rd.open_session(config_name=\"../Configuration/refinitiv-data.config.json\")"
+    "rd.open_session(config_name=\"../Configuration/refinitiv-data.custom.config.json\")"
    ]
   },
   {
@@ -158,7 +163,7 @@
    "metadata": {},
    "source": [
     "<br>      \n",
-    "Alternatively, if you do not wish to use the refinitiv-data config file, you can define sessions by specifying the parameters and session type explicitly - as shown below.\n",
+    "Alternatively, if you do not wish to use a refinitiv-data config file, you can define sessions by specifying the parameters and session type explicitly - as shown below.\n",
     "\n",
     "## Define the session using your own credentials store\n",
     "Sessions can be created by explicitly passing in your credentials/connectivity parameters.\n",
@@ -169,7 +174,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "af7ee821-4413-4754-9f38-c3a22725a962",
+   "id": "3a5a7542-833e-421f-b5f3-a7d54701e169",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -180,6 +185,35 @@
     "REALTIME_DISTRIBUTION_SERVICE_USER_NAME = 'YOUR_USER_NAME_ON_YOUR_RTDS_HOST' "
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "3b0f1e3f-c16f-4618-87be-ee422b7a50e1",
+   "metadata": {},
+   "source": [
+    "\n",
+    "However, if you choose not use the refinitiv-data config file - rather than hardcoding parameters in your code, you may prefer to keep your credentials in a .env file (or some other external store) - to avoid accidentally exposing your credentials when sharing code.  \n",
+    "A empty .env file has been included in this ***Quick Start*** folder.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6685af34-58f9-4cff-85b6-c646a83a0595",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# OR \n",
+    "# Load credentials from a .env file (+ override any OS system env vars of the same name)\n",
+    "from dotenv import load_dotenv\n",
+    "# change the path to the location of your .env file\n",
+    "load_dotenv(dotenv_path='c:/Refinitiv/.env',override=True)\n",
+    "APP_KEY                     = os.getenv('APP_KEY')       # As created using the AppKey generator\n",
+    "RDP_LOGIN                   = os.getenv('RDP_LOGIN')     # e.g. 'GE-A-01234567-8-9101'\n",
+    "RDP_PASSWORD                = os.getenv('RDP_PASSWORD')  # the long password set via the link in the Machine Account Welcome Email\n",
+    "REALTIME_DISTRIBUTION_SERVICE_HOST = os.getenv('DEPLOYED_PLATFORM_HOST')      # ADS hostname:PORT or IP:PORT e.g. 'myADS:15000'\n",
+    "REALTIME_DISTRIBUTION_SERVICE_USER_NAME = os.getenv('DEPLOYED_PLATFORM_USER_NAME') # Your DACS User name"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "54ce2f53",