Outflow settings

An Outflow settings file is a list of uppercase variables that will be stored in the pipeline context. This document explains how settings work and which default settings are available.

The basics

A settings file is just a Python module with module-level variables.

Here is the default Outflow settings:

import os

from outflow.core.commands import RootCommand

ROOT_DIRECTORY = os.environ.get("PIPELINE_ROOT_DIRECTORY", None)

PLUGINS = [
    "outflow.management",
]

ROOT_COMMAND_CLASS = RootCommand

Because a settings file is a Python module, the following apply:

  • It doesn’t allow for Python syntax errors.

  • It can assign settings dynamically using normal Python syntax. For example:

MY_SETTING = [str(i) for i in range(30)]

It can import values from other settings files.

Designating the settings

When you use Outflow, the default settings module is the one located at the root of the pipeline folder.

But, you can specify which settings you’re using. Do this by using an environment variable, OUTFLOW_SETTINGS_MODULE, or using the CLI argument --settings.

In both cases, the value should be in Python path syntax, e.g. export OUTFLOW_SETTINGS_MODULE=my_project.my_settings or --settings my_project.my_settings. Note that the settings module should be on the Python import search path.

Default settings

An Outflow settings file doesn’t have to define any settings if it doesn’t need to. Each setting has a sensible default value. These defaults live in the module outflow/core/pipeline/default_settings.py.

Here’s the algorithm Outflow uses in compiling settings:

  • Load settings from default_settings.py.

  • Load settings from the specified settings file, overriding the default settings as necessary.

Note that a settings file should not import from default_settings, because that’s redundant.

Using settings in Python code

In your Outflow pipeline, use settings by importing the object outflow.core.pipeline.settings. Example:

from outflow.core.pipeline import settings

if len(settings.PLUGINS) > 3:
    # Do something
    pass

Or use the task context:

Task.as_task(with_context=True)
def MyTask(self):
    print(self.context.settings.PLUGINS)

Note that outflow.core.pipeline.settings isn’t a module – it’s an object. So importing individual settings is not possible:

from outflow.core.pipeline.settings import PLUGINS  # This won't work.

Also note that your code should not import from either default_settings or your own settings file. outflow.core.pipeline.settings abstracts the concepts of default settings and pipeline instance specific settings; it presents a single interface. It also decouples the code that uses settings from the location of your settings.

Altering settings at runtime

You shouldn’t alter settings in your applications at runtime. For example, don’t do this in a command:

from outflow.core.pipeline import settings

settings.PLUGINS = []   # Don't do this!

The only place you should assign to settings is in a settings file.

Available settings

For a full list of available settings, see the settings reference. (#TODO)

Creating your own settings

There’s nothing stopping you from creating your own settings, for your own Outflow pipeline, but follow these guidelines:

  • Setting names must be all uppercase.

  • Don’t reinvent an already-existing setting.

For settings that are sequences, Outflow itself uses lists, but this is only a convention.