diff --git a/docs/guide/environmental_variables.rst b/docs/guide/environmental_variables.rst index aa8bbaf..b81197a 100644 --- a/docs/guide/environmental_variables.rst +++ b/docs/guide/environmental_variables.rst @@ -1,44 +1,46 @@ -Environmental Variables +Environment Variables ======================= -Best practice holds that variables should be passed to graphs via environmental variables. +Best practice holds that variables should be passed to graphs via environment variables. Doing this is important for keeping sensitive data out of the code - such as an API token or username and password used to access a database. Not only is this approach more secure, it also makes graphs more flexible by allowing adjustments -for a variety of environments and contexts. Importantly, environmental variables +for a variety of environments and contexts. Importantly, environment variables are also the means by-which arguments can be passed to graphs. -Passing / Setting Environmental Variables +Passing / Setting Environment Variables :::::::::::::::::::::::::::::::::::::::::::: -The recommended way to set environmental variables for a given graph is simply to use +The recommended way to set environment variables for a given graph is simply to use the optional ``--env`` argument when running bonobo from the shell (bash, command prompt, etc). ``--env`` (or ``-e`` for short) should then be followed by the variable name and value using the -syntax `VAR_NAME=VAR_VALUE`. Multiple environmental variables can be passed by using +syntax `VAR_NAME=VAR_VALUE`. Multiple environment variables can be passed by using multiple ``--env`` / ``-e`` flags. Example: .. code-block:: bash - # Using one environmental variable: + # Using one environment variable via --env flag: bonobo run csvsanitizer --env SECRET_TOKEN=secret123 - # Using multiple environmental variables: + # Using multiple environment variables via -e (env) flag: bonobo run csvsanitizer -e SRC_FILE=inventory.txt -e DST_FILE=inventory_processed.csv + + # Using one environment variable in bash (*bash only): + SECRET_TOKEN=secret123 bonobo run csvsanitizer -If you're naming something which is configurable, that is will need to be instantiated or called to obtain something that -can be used as a graph node, then use camelcase names: + # Using multiple environment variables in bash (*bash only): + SRC_FILE=inventory.txt DST_FILE=inventory_processed.csv bonobo run csvsanitizer - -Accessing Environmental Variables from within the Graph Context +Accessing Environment Variables from within the Graph Context ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: -Environmental variables, whether global or only for the scope of the graph, +Environment variables, whether global or only for the scope of the graph, can be can be accessed using any of the normal means. It is important to note that whether set globally for the system or just for the graph context, -environmental variables are accessed by bonobo in the same way. In the example +environment variables are accessed by bonobo in the same way. In the example below the database user and password are accessed via the ``os`` module's ``getenv`` function and used to get data from the database.