secret-garden

A better way to manage your dotenv variables

Installation

• You can use your most preferred package manager to install the package

  pip install secret-garden or poetry add secret-garden ...

Table of Contents

1. Usage

   • loading from a file
   • loading from the environment namespace
   • loading from a file using the environment namespace as an alternative

2. Examples

   • Using a file
     • env
     • json
     • toml
     • yaml
   • Using the environment namespace

3. Objects

   • load
   • load_file
   • load_space

4. Upcoming Features

Usage

You can put your variables in a file or use the environment namespace

Loading from a file

Create a file using one of the following formats and add your variables:

• .env

• .json

• .yaml

• .toml

  Note: When using the .env file, the variables should be declared as python variables

Use the load_file function to load the variables, specifying the format of the file

from secret_garden import load_file
load_file('path/to/your/file', format_='<your_format>')

Pass the globals dictionary if you want to load the variables into the global namespace

from secret_garden import load_file
load_file(
    'path/to/your/file',
    format_='<your_format>',
    globals_=globals()
)

Loading from the environment namespace

Add your variables into the environment namespace

export STR_VAR="string"
export INT_VAR=1
export FLOAT_VAR='1.0'
export BOOL_VAR=True
export LIST_VAR="['item1', 'item2']"
export DICT_VAR="{'key1': 'value1', 'key2': 'value2'}"

Use the load_space function to load the variables

from secret_garden import load_space
load_space(['STR_VAR', 'INT_VAR', 'FLOAT_VAR', 'BOOL_VAR', 'LIST_VAR', 'DICT_VAR'])

Pass the globals dictionary if you want to load the variables into the global namespace

from secret_garden import load_space
load_space(
    ['STR_VAR', 'INT_VAR', 'FLOAT_VAR', 'BOOL_VAR', 'LIST_VAR', 'DICT_VAR'],
    globals_=globals()
)

Loading from a file using the environment namespace as an alternative

• This is done using the load function by declaring in order:

  1. the path to the file containing the variables
  2. the variables to be included from the environment namespace

• If both path and include are provided, the variables are loaded from the file and the include argument is ignored.

  from secret_garden import load
  load(
      "/path/to/your/file", # path to the file containing the variables
      ["VAR1", "VAR2"], # this will be ignored
      format_ = 'env',
      globals_ = None, 
  )
  

• If path does not exist, the variables are loaded from the environment namespace. The include argument is used to know which variables to get from the environment namespace.

  from secret_garden import load
  load(
      "/path/to/the/non-existent/file", # path to the non-existent file
      ["VAR1", "VAR2"], # variables to be included from the environment namespace
      format_ = 'env',
      globals_ = None, 
  )
  

Examples

Using a file

env

• Add your variables into the .env file

  STR_VAR="string"
  INT_VAR=1
  FLOAT_VAR=1.0
  BOOL_VAR=True
  LIST_VAR=['item1', 'item2']
  DICT_VAR={'key1': 'value1', 'key2': 'value2'}
  

• Use the load_file function to load the variables

  from secret_garden import load_file
  load_file('path/to/your/file.env', format_='env')
  

• Using the globals_ parameter

  from secret_garden import load_file
  load_file(
      'path/to/your/.env',
      format_='env',
      globals_=globals()
  )
  

json

• Add your variables into the .json file

  {
      "STR_VAR": "string",
      "INT_VAR": 1,
      "FLOAT_VAR": 1.0,
      "BOOL_VAR": true,
      "LIST_VAR": ["item1", "item2"],
      "DICT_VAR": {"key1": "value1", "key2": "value2"}
  }
  

• Use the load_file function to load the variables

  from secret_garden import load_file
  load_file('path/to/your/file.json', format_='json')
  

• Using the globals_ parameter

  from secret_garden import load_file
  load_file(
      'path/to/your/file.json',
      format_='json',
      globals_=globals()
  )
  

toml

• Add your variables into the .toml file

  STR_VAR = "string"
  INT_VAR = 1
  FLOAT_VAR = 1.0
  BOOL_VAR = true
  LIST_VAR = ["item1", "item2"]
  DICT_VAR = {key1 = "value1", key2 = "value2"}
  

• Use the load_file function to load the variables

  from secret_garden import load_file
  load_file('path/to/your/file.toml', format_='toml')
  

• Using the globals_ parameter

  from secret_garden import load_file
  load_file(
      'path/to/your/file.toml',
      format_='toml',
      globals_=globals()
  )
  

yaml

• Add your variables into the .yaml file

  STR_VAR: string
  INT_VAR: 1
  FLOAT_VAR: 1.0
  BOOL_VAR: true
  LIST_VAR:
      - item1
      - item2
  DICT_VAR:
      key1: value1
      key2: value2
  

• Use the load_file function to load the variables

  from secret_garden import load_file
  load_file('path/to/your/file.yaml', format_='yaml')
  

• Using the globals_ parameter

  from secret_garden import load_file
  load_file(
      'path/to/your/file.yaml',
      format_='yaml',
      globals_=globals()
  )
  

Using the environment namespace

• Add your variables into the environment namespace

  export STR_VAR="string"
  export INT_VAR=1
  export FLOAT_VAR=1.0
  export BOOL_VAR=True
  export LIST_VAR="['item1', 'item2']"
  export DICT_VAR="{'key1': 'value1', 'key2': 'value2'}"
  

• Use the load_space function to load the variables

  from secret_garden import load_space
  load_space(['STR_VAR', 'INT_VAR', 'FLOAT_VAR', 'BOOL_VAR', 'LIST_VAR', 'DICT_VAR'])
  

• Using the globals_ parameter

  from secret_garden import load_space
  load_space(
      ['STR_VAR', 'INT_VAR', 'FLOAT_VAR', 'BOOL_VAR', 'LIST_VAR', 'DICT_VAR'],
      globals_=globals()
  )
  

Objects

• load

  load(
      path_or_include: Path | PathLike | str | list[str], # path to the file or a list of variables to be included from the environment namespace
      format_: str = 'environ', # the format of the file if path_or_include is a path
      globals_: dict = None, # the execution global namespace to load the variables into
  )
  

  If both path and include are provided, the variables are loaded from the file and the include argument is ignored

  If path does not exist, the variables are loaded from the environment namespace and the include argument is used to filter the variables.

  • path (Path | PathLike | str): The path to the file containing the environment variables
  • include (list[str]): The variables to include when loading from the environment namespace
  • format_ - Format of the file containing the variables.It can be one of the following:
    • 'env' - Variables are declared as python variables
    • 'environ' - Variables are declared as environment variables where value are in quotes
    • 'json'
    • 'yaml'
    • 'toml'
  • globals_ - If not provided, variables will returned as a dictionary

• load_file

  load_file(
      path: str, # path to the file
      format_: str = 'environ', # the format of the file
      globals_: dict = None, # the execution global namespace to load the variables into
  )
  

  • path - The path to the file containing the variables
  • format_ - Format of the file containing the variables.It can be one of the following:
    • 'env' - Variables are declared as python variables
    • 'json'
    • 'yaml'
    • 'toml'
  • globals_ - If not provided, variables will returned as a dictionary

• load_space

  load_space(
      include: list, # a list of variables to be included from the environment namespace
      globals_: dict = None, # the execution global namespace to load the variables into
  )
  

  • include - A list of variables to be included from the environment namespace
  • globals_ - If not provided, variables will returned as a dictionary

Upcoming Features

• Support for multiline declaration in the 'env' and 'environ' formats

• Support for nested dictionary and list types in the 'env' and 'environ' formats