examples/credential_handling.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Credential Handling\n",
    "\n",
    "The premium and enterprise Search APIs use different authentication methods and we attempt to provide a seamless way to handle authentication for all customers. We know credentials can be tricking or annoying - please read this in its entirety.\n",
    "\n",
    "\n",
    "Premium clients will require the `bearer_token` and `endpoint` fields; Enterprise clients require `username`, `password`, and `endpoint`.\n",
    "If you do not specify the `account_type`, we attempt to discern the account type and declare a warning about this behavior.\n",
    "\n",
    "For premium search products, we are using app-only authentication and the bearer tokens are not delivered with an expiration time. You can provide either:\n",
    "- your application key and secret (the library will handle bearer-token authentication)\n",
    "- a bearer token that you get yourself\n",
    "\n",
    "Many developers might find providing your application key and secret more straightforward and letting this library manage your bearer token generation for you. Please see [here](https://developer.twitter.com/en/docs/basics/authentication/overview/application-only) for an overview of the premium authentication method.\n",
    "\n",
    "We support both YAML-file based methods and environment variables for storing credentials, and provide flexible handling with sensible defaults.\n",
    "\n",
    "\n",
    "## YAML method\n",
    "\n",
    "For premium customers, the simplest credential file should look like this:\n",
    "\n",
    "```yaml\n",
    "\n",
    "search_tweets_api:\n",
    "  account_type: premium\n",
    "  endpoint: <FULL_URL_OF_ENDPOINT>\n",
    "  consumer_key: <CONSUMER_KEY>\n",
    "  consumer_secret: <CONSUMER_SECRET>\n",
    "```\n",
    "\n",
    "For enterprise customers, the simplest credential file should look like this:\n",
    "\n",
    "```yaml\n",
    "\n",
    "search_tweets_api:\n",
    "  account_type: enterprise\n",
    "  endpoint: <FULL_URL_OF_ENDPOINT>\n",
    "  username: <USERNAME>\n",
    "  password: <PW>\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, this library expects this file at `\"~/.twitter_keys.yaml\"`, but you can pass the relevant location as needed, either with the ``--credential-file`` flag for the command-line app or as demonstrated below in a Python program.\n",
    "\n",
    "Both above examples require no special command-line arguments or in-program arguments.  The credential parsing methods, unless otherwise specified, will look for a YAML key called `search_tweets_api`.\n",
    "\n",
    "\n",
    "For developers who have multiple endpoints and/or search products, you can keep all credentials in the same file and specify specific keys to use. `--credential-file-key` specifies this behavior in the command line app. An example:\n",
    "\n",
    "\n",
    "```yaml\n",
    "\n",
    "search_tweets_30_day_dev:\n",
    "  account_type: premium\n",
    "  endpoint: <FULL_URL_OF_ENDPOINT>\n",
    "  consumer_key: <KEY>\n",
    "  consumer_secret: <SECRET>\n",
    "  (optional) bearer_token: <TOKEN>\n",
    "  \n",
    "  \n",
    "search_tweets_30_day_prod:\n",
    "  account_type: premium\n",
    "  endpoint: <FULL_URL_OF_ENDPOINT>\n",
    "  bearer_token: <TOKEN>\n",
    "  \n",
    "search_tweets_fullarchive_dev:\n",
    "  account_type: premium\n",
    "  endpoint: <FULL_URL_OF_ENDPOINT>\n",
    "  bearer_token: <TOKEN>\n",
    "\n",
    "search_tweets_fullarchive_prod:\n",
    "  account_type: premium\n",
    "  endpoint: <FULL_URL_OF_ENDPOINT>\n",
    "  bearer_token: <TOKEN>\n",
    "  \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Environment Variables\n",
    "\n",
    "If you want or need to pass credentials via environment variables, you can set the appropriate variables for your product of the following: \n",
    "\n",
    "```\n",
    "export SEARCHTWEETS_ENDPOINT=\n",
    "export SEARCHTWEETS_USERNAME=\n",
    "export SEARCHTWEETS_PASSWORD=\n",
    "export SEARCHTWEETS_BEARER_TOKEN=\n",
    "export SEARCHTWEETS_ACCOUNT_TYPE=\n",
    "export SEARCHTWEETS_CONSUMER_KEY=\n",
    "export SEARCHTWEETS_CONSUMER_SECRET=\n",
    "```\n",
    "\n",
    "The `load_credentials` function will attempt to find these variables if it cannot load fields from the YAML file, and it will **overwrite any credentials from the YAML file that are present as environment variables** if they have been parsed. This behavior can be changed by setting the `load_credentials` parameter `env_overwrite` to `False`.\n",
    "\n",
    "\n",
    "The following cells demonstrates credential handling in the Python library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "from searchtweets import load_credentials"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'username': '<MY_USERNAME>',\n",
       " 'password': '<MY_PASSWORD>',\n",
       " 'endpoint': '<MY_ENDPOINT>'}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "load_credentials(filename=\"./search_tweets_creds_example.yaml\",\n",
    "                 yaml_key=\"search_tweets_ent_example\",\n",
    "                 env_overwrite=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'bearer_token': '<A_VERY_LONG_MAGIC_STRING>',\n",
       " 'endpoint': 'https://api.twitter.com/1.1/tweets/search/30day/dev.json',\n",
       " 'extra_headers_dict': None}"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "load_credentials(filename=\"./search_tweets_creds_example.yaml\",\n",
    "                 yaml_key=\"search_tweets_premium_example\",\n",
    "                 env_overwrite=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Environment Variable Overrides\n",
    "\n",
    "If we set our environment variables, the program will look for them regardless of a YAML file's validity or existence."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "cannot read file nothing_here.yaml\n",
      "Error parsing YAML file; searching for valid environment variables\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'username': '<ENV_USERNAME>',\n",
       " 'password': '<ENV_PW>',\n",
       " 'endpoint': '<https://endpoint>'}"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import os\n",
    "os.environ[\"SEARCHTWEETS_USERNAME\"] = \"<ENV_USERNAME>\"\n",
    "os.environ[\"SEARCHTWEETS_PASSWORD\"] = \"<ENV_PW>\"\n",
    "os.environ[\"SEARCHTWEETS_ENDPOINT\"] = \"<https://endpoint>\"\n",
    "\n",
    "load_credentials(filename=\"nothing_here.yaml\", yaml_key=\"no_key_here\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Command-line app\n",
    "\n",
    "the flags:\n",
    "\n",
    "- `--credential-file <FILENAME>`\n",
    "- `--credential-file-key <KEY>`\n",
    "- `--env-overwrite`\n",
    "\n",
    "are used to control credential behavior from the command-line app. "
   ]
  },
  {
   "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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}