Examples/4-Session/EX-4.01.01-Sessions.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----\n",
    "<img src=\"../../files/refinitiv.png\" width=\"20%\" style=\"vertical-align: top;\">\n",
    "\n",
    "# Data Library for Python\n",
    "\n",
    "----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Session layer\n",
    "Before you can retreive any data with the Refinitiv Data Library, your must open a data session to manage your connection to the Refinitv Data Platform. Depending on the way you intend to access the platform you must open either a Platform Session (for direct connection) or a Desktop Session (for a connection via Workspace or via CodeBook). This notebook demonstrates different options to create and open Refinitiv Data Library sessions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Learn more\n",
    "\n",
    "To learn more about the Refinitiv Data Library for Python please join the Refinitiv Developer Community. By [registering](https://developers.refinitiv.com/iam/register) and [logging](https://developers.refinitiv.com/content/devportal/en_us/initCookie.html) into the Refinitiv Developer Community portal you will have free access to a number of learning materials like \n",
    " [Quick Start guides](https://developers.refinitiv.com/en/api-catalog/refinitiv-data-platform/refinitiv-data-library-for-python/quick-start), \n",
    " [Tutorials](https://developers.refinitiv.com/en/api-catalog/refinitiv-data-platform/refinitiv-data-library-for-python/learning), \n",
    " [Documentation](https://developers.refinitiv.com/en/api-catalog/refinitiv-data-platform/refinitiv-data-library-for-python/docs)\n",
    " and much more.\n",
    "\n",
    "#### Getting Help and Support\n",
    "\n",
    "If you have any questions regarding using the API, please post them on \n",
    "the [Refinitiv Data Q&A Forum](https://community.developers.refinitiv.com/spaces/321/index.html). \n",
    "The Refinitiv Developer Community will be happy to help. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Set the configuration file location\n",
    "For a better ease of use, you have the option to set initialization parameters of the Refinitiv Data Library in the _refinitiv-data.config.json_ configuration file. This file must be located beside your notebook, in your user folder or in a folder defined by the _RD_LIB_CONFIG_PATH_ environment variable. The _RD_LIB_CONFIG_PATH_ environment variable is the option used by this series of examples. The following code sets this environment variable.      "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "os.environ[\"RD_LIB_CONFIG_PATH\"] = \"../../Configuration\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Some Imports to start with"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import refinitiv.data as rd\n",
    "from refinitiv.data import session\n",
    "import datetime"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## User details and other information\n",
    "Please set the following variables with your user information and environment details "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "APP_KEY = 'YOUR APP KEY GOES HERE!'\n",
    "RDP_LOGIN                   = 'YOUR RDP LOGIN OR MACHINE GOES HERE!'\n",
    "RDP_PASSWORD                = 'YOUR RDP PASSWORD GOES HERE!'\n",
    "REALTIME_DISTRIBUTION_SERVICE_HOST      = 'ADS IP'\n",
    "REALTIME_DISTRIBUTION_SERVICE_USER_NAME = 'DACS USER NAME'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The different types of data sessions\n",
    "\n",
    "Depending on the access point your application uses to connect to the Refinitiv Data Platform, it has to create and open either a Platform session or a Desktop session: \n",
    "\n",
    " - **Platform session:** This type of session is used to connect to the Refinitiv Data Platform either directly or via a local Refinitiv's Real-Time Distribution System. The Platform session requires Refinitiv Data Platform credentials (either a user account or a machine account) or connection details for your local Real-Time Distribution System (IP of the system and DACS user name) or both.\n",
    "    - When the Platform session is used with Refinitiv Data Platform credentials only, it retrieves both streaming data and non-streaming data from the Refinitiv Data Platform.\n",
    "    - When the Platform session is used with connection details of your Real-Time Distribution System only, it is able to retrieve streaming data only.\n",
    "    - When the Platform session is used with both Refinitiv Data Platform credentials and connection details of your Real-Time Distribution System, it retrieves streaming data from the Real-Time Distribution System and non-streaming data from the Refinitiv Data Platform.\n",
    " - **Desktop session:** This type of session is used to connect the Refinitiv Data Platform either via Eikon, via Refinitiv Workspace or via CodeBook. It requires either Eikon Desktop or Workspace Desktop to be running alongside your Python script.\n",
    " \n",
    "These 2 types of session also require an App Key that uniquely identifies your application. Please refer to the Refinitiv Data Libraries Quick Start guide to learn how to create an App Key for your application."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Managing data sessions using the \"Access\" layer\n",
    "\n",
    "The Access of the library provides you with two functions - open_session() and close_session() - that greatly simplify data session management. These functions are based on the Session layer described later in this notebook and they rely on the information contained in the configuration of the library. Depending on your use case, you can either rely on the default configuration of the library (Workspace Desktop use case or CodeBook use case), or you can define your own configuration file to define any specific parameters for you session (Refinitiv Data Platform use case or Real-Time Distribution System use case)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Opening a session \n",
    "\n",
    "The open_session() function creates and open a session based on the information contained in the configuration of the library. By default, it creates a Desktop Session that works out of the box with Refinitiv Workspace and CodeBook. If you need a Platform Session instead or if you need to set specific parameters for your session, you must create a refinitiv-data.config.json to define the session type you need and its parameters. The open_session() function will read this configuration file and create the session of your choice. \n",
    "\n",
    "_**Note:** With Eikon and Workspace versions prior to February 2022, the refinitiv-data.config.json configuration file is required for both Platform sessions and Desktop sessions. When used with a Desktop session, this file must contain your App Key._\n",
    "\n",
    "Once the session created, open_session() registers it as the default session of the library. Meaning that this session will be used by all the other part of the library unless you explicitely specify different session. When open_session() is called several times, the latest created session becomes the default session."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Open the default session\n",
    "\n",
    "This call opens the default session defined in the configuration of the library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<refinitiv.data.session.Definition object at 0x7f88ec116250 {name='workspace'}>"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "rd.open_session()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Open the default with a specific App Key  \n",
    "\n",
    "This call opens a session indentified by its name. This session must be defined in the configuration of the library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<refinitiv.data.session.Definition object at 0x7f88eacc28d0 {name='workspace'}>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "rd.open_session(app_key = APP_KEY)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Open a session by name \n",
    "\n",
    "This call opens a session indentified by its name. This session must be defined in the configuration of the library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<refinitiv.data.session.platform.Definition object at 0x7f88ec10d750 {session_name='rdp'}>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "rd.open_session('platform.rdp')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Open a session defined in a custom configuration file \n",
    "\n",
    "This call opens the default session as defined in the configuration file passed as parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<refinitiv.data.session.platform.Definition object at 0x7fd235bbea90 {session_name='my-custom-session'}>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "rd.open_session(config_name='../../Configuration/refinitiv-data.custom.config.json')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Close the default session \n",
    "\n",
    "This call closes the default session of the library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "rd.close_session()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Close a specific session "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<OpenState.Closed: 1>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Create 2 sessions\n",
    "desktop_session = rd.open_session('desktop.workspace')\n",
    "platform_session = rd.open_session('platform.rdp') # platform_session becomes the default session because it is the last created session \n",
    "\n",
    "# Close the default session that is platform_session\n",
    "rd.close_session()\n",
    "\n",
    "# Close desktop_session. This must be done explicitely because desktop_session is not the default session\n",
    "desktop_session.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Managing data sessions using the \"Session\" layer\n",
    "\n",
    "The \"Session\" layer offers you more control for session management and does not necessarily require a configuration file. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Managing sessions based on a config file"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Create the default session\n",
    "\n",
    "This call creates the default session defined in the configuration of the library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "session = rd.session.Definition().get_session()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Create a desktop session by name\n",
    "\n",
    "This call creates the desktop session named \"workspace\" as defined in the configuration of the library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "session = rd.session.desktop.Definition(\"workspace\").get_session()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Create a platform session by name\n",
    "\n",
    "This call creates the Platform session named \"rdp\" as defined in the configuration of the library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "session = rd.session.platform.Definition(\"rdp\").get_session()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Create a session by full name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "session = rd.session.Definition('desktop.workspace').get_session()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Set the default session"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "rd.session.set_default(session)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Get the default session"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "session = rd.session.get_default()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Managing sessions without any config file"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Create a Desktop session using with an App Key\n",
    "For a connection via Refinitiv Workspace, Eikon or CodeBook "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "session = rd.session.desktop.Definition(app_key = APP_KEY).get_session()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Create a Platform session using with an App Key and GrantPassword\n",
    "For a direct connection to the Refinitiv Data Platform"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "session = rd.session.platform.Definition(\n",
    "    app_key = APP_KEY, \n",
    "    grant = rd.session.platform.GrantPassword(\n",
    "        username = RDP_LOGIN, \n",
    "        password = RDP_PASSWORD\n",
    "    )\n",
    ").get_session()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Create a Platform session using with an App Key and deployed_platform parameters \n",
    "For a direct connection to a Refinitiv Realtime Distribution System (a.k.a.TREP)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "session = rd.session.platform.Definition(\n",
    "    app_key = APP_KEY, \n",
    "    deployed_platform_host = REALTIME_DISTRIBUTION_SERVICE_HOST,\n",
    "    deployed_platform_username = REALTIME_DISTRIBUTION_SERVICE_USER_NAME\n",
    ").get_session()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Create a Platform session using with an App Key, a GrantPassword and deployed_platform parameters \n",
    "For a connection to the Refinitiv Data Platform and a connection to a Refinitiv Realtime Distribution System. With this configuration, streaming data is retrieved from the Refinitiv Realtime Distribution System while non-streaming data is retrieved from the Refinitiv Data Platform."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "session = rd.session.platform.Definition(\n",
    "    app_key = APP_KEY, \n",
    "    grant = rd.session.platform.GrantPassword(\n",
    "        username = RDP_LOGIN, \n",
    "        password = RDP_PASSWORD\n",
    "    ),\n",
    "    deployed_platform_host = REALTIME_DISTRIBUTION_SERVICE_HOST,\n",
    "    deployed_platform_username = REALTIME_DISTRIBUTION_SERVICE_USER_NAME\n",
    ").get_session()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Open the session"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<OpenState.Open: 3>"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "session.open()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Check the open state"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<OpenState.Open: 3>"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "session.open_state"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Close the session"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<OpenState.Closed: 1>"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "session.close()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}