Configuration and Section

Configuration and Section are two types you’ll have to mainly deal with.

class uwsgiconf.config.Section(name: str = None, *, runtime_dir: str = None, project_name: str = None, strict_config: bool = None, style_prints: bool = False, embedded_plugins: Union[Callable, List[str]] = None, **kwargs)

Configuration section.

Options within configuration section are gathered into groups:

  • alarms
  • caching
  • master_process
  • workers
  • etc.

Next to all public methods of groups are for setting configuration parameters. Such methods return section object to allow chaining.

You can pass options group basic parameters into (the following are all the same):

  • set_basic_params() as in section.workers.set_basic_params(count=3)

  • __call__ as in section.workers(count=3)

  • section initializer using params_ prefixed group name:

    Section(
        params_workers=dict(count=3),
    )
    
Parameters:
  • name – Configuration section name.
  • runtime_dir

    Directory to store runtime files. See .replace_placeholders()

    Note

    This can be used to store PID files, sockets, master FIFO, etc.

  • project_name – Project name (alias) to be used to differentiate projects. See .replace_placeholders().
  • strict_config

    Enable strict configuration parsing. If any unknown option is encountered in a configuration file, an error is shown and uWSGI quits.

    To use placeholder variables when using strict mode, use the set-placeholder option.

  • style_prints – Enables styling (e.g. colouring) for print_ family methods. Could be nice for console and distracting in logs.
  • embedded_plugins

    List of embedded plugins. Plugins from that list will be considered already loaded so uwsgiconf won’t instruct uWSGI to load it if required.

    See .embedded_plugins_presets for shortcuts.

    Note

    • If you installed uWSGI using PyPI package there should already be basic plugins embedded.
    • If using Ubuntu distribution you have to install plugins as separate packages.
alarms

alias of uwsgiconf.options.alarms.Alarms

applications

alias of uwsgiconf.options.applications.Applications

caching

alias of uwsgiconf.options.caching.Caching

cheapening

alias of uwsgiconf.options.workers_cheapening.Cheapening

empire

alias of uwsgiconf.options.empire.Empire

locks

alias of uwsgiconf.options.locks.Locks

logging

alias of uwsgiconf.options.logging.Logging

main_process

alias of uwsgiconf.options.main_process.MainProcess

master_process

alias of uwsgiconf.options.master_process.MasterProcess

monitoring

alias of uwsgiconf.options.monitoring.Monitoring

networking

alias of uwsgiconf.options.networking.Networking

queue

alias of uwsgiconf.options.queue.Queue

routing

alias of uwsgiconf.options.routing.Routing

spooler

alias of uwsgiconf.options.spooler.Spooler

statics

alias of uwsgiconf.options.statics.Statics

subscriptions

alias of uwsgiconf.options.subscriptions.Subscriptions

workers

alias of uwsgiconf.options.workers.Workers

python

alias of uwsgiconf.options.python.Python

class embedded_plugins_presets

These are plugin presets that can be used as embedded_plugins values.

BASIC = ['ping', 'cache', 'nagios', 'rrdtool', 'carbon', 'rpc', 'corerouter', 'fastrouter', 'http', 'ugreen', 'signal', 'syslog', 'rsyslog', 'logsocket', 'router_uwsgi', 'router_redirect', 'router_basicauth', 'zergpool', 'redislog', 'mongodblog', 'router_rewrite', 'router_http', 'logfile', 'router_cache', 'rawrouter', 'router_static', 'sslrouter', 'spooler', 'cheaper_busyness', 'symcall', 'transformation_tofile', 'transformation_gzip', 'transformation_chunked', 'transformation_offload', 'router_memcached', 'router_redis', 'router_hash', 'router_expires', 'router_metrics', 'transformation_template', 'stats_pusher_socket', 'router_fcgi']

Basic set of embedded plugins. This set is used in uWSGI package from PyPI.

static PROBE(uwsgi_binary: str = None)

This preset allows probing real uWSGI to get actual embedded plugin list.

replace_placeholders(value: Union[str, List[str], None]) → Union[str, List[str], None]

Replaces placeholders that can be used e.g. in filepaths.

Supported placeholders:
  • {project_runtime_dir}
  • {project_name}
  • {runtime_dir}
Parameters:value
project_name

Project name (alias) to be used to differentiate projects. See .replace_placeholders().

get_runtime_dir(*, default: bool = True) → str

Directory to store runtime files. See .replace_placeholders()

Note

This can be used to store PID files, sockets, master FIFO, etc.

Parameters:default – Whether to return [system] default if not set.
set_runtime_dir(value) → TypeSection

Sets user-defined runtime directory value.

Parameters:value (str) –
as_configuration(**kwargs) → uwsgiconf.config.Configuration

Returns configuration object including only one (this very) section.

Parameters:kwargs – Configuration objects initializer arguments.
print_plugins() → TypeSection

Print out enabled plugins.

print_stamp() → TypeSection

Prints out a stamp containing useful information, such as what and when has generated this configuration.

print_out(value: Any, *, indent: str = None, format_options: Union[dict, str] = None, asap: bool = False) → TypeSection

Prints out the given value.

Parameters:
  • value
  • indent
  • format_options – text color
  • asap – Print as soon as possible.
print_variables() → TypeSection

Prints out magic variables available in config files alongside with their values and descriptions. May be useful for debugging.

http://uwsgi-docs.readthedocs.io/en/latest/Configuration.html#magic-variables

set_plugins_params(*, plugins: Union[List[str], List[uwsgiconf.base.OptionsGroup], str, uwsgiconf.base.OptionsGroup] = None, search_dirs: Union[str, List[str]] = None, autoload: bool = None, required: bool = False) → TypeSection

Sets plugin-related parameters.

Parameters:
  • plugins – uWSGI plugins to load
  • search_dirs – Directories to search for uWSGI plugins.
  • autoload – Try to automatically load plugins when unknown options are found.
  • required – Load uWSGI plugins and exit on error.
set_fallback(target: Union[str, Section]) → TypeSection

Sets a fallback configuration for section.

Re-exec uWSGI with the specified config when exit code is 1.

Parameters:target – File path or Section to include.
set_placeholder(key: str, value: str) → TypeSection

Placeholders are custom magic variables defined during configuration time.

Note

These are accessible, like any uWSGI option, in your application code via .runtime.platform.uwsgi.config.

Parameters:
  • key
  • value
env(key: str, value: Any = None, *, unset: bool = False, asap: bool = False, update_local: bool = False) → TypeSection

Processes (sets/unsets) environment variable.

If is not given in set mode value will be taken from current env.

Parameters:
  • key
  • value
  • unset – Whether to unset this variable.
  • asap – If True env variable will be set as soon as possible.
  • update_local – Whether we need to set this value for local environment too. This could be useful in embedded mode.
include(target: Union[Section, List[Section], str, List[str]]) → TypeSection

Includes target contents into config.

Parameters:target – File path or Section to include.
classmethod derive_from(section: TypeSection, *, name: str = None) → TypeSection

Creates a new section based on the given.

Parameters:
  • section – Section to derive from,
  • name – New section name.
class vars

The following variables also known as magic variables could be used as option values where appropriate.

VERSION = '%V'

uWSGI version number

FORMAT_ESCAPE = '%['

ANSI escape 033. useful for printing colors

CONF_CURRENT_SECTION = '%x'

The current section identifier, eg. conf.ini:section.

CONF_NAME_ORIGINAL = '%o'

The original conf filename, as specified on the command line

TIMESTAMP_STARTUP_S = '%t'

Unix time s, gathered at instance startup.

TIMESTAMP_STARTUP_MS = '%T'

Unix time ms, gathered at instance startup

DIR_VASSALS = '%v'

Vassals directory - pwd.

HOST_NAME = '%h'

Host name.

CPU_CORES = '%k'

Detected CPU count.

USER_ID = '%u'

User ID.

USER_NAME = '%U'

User name.

GROUP_ID = '%g'

Use group ID.

GROUP_NAME = '%G'

Use group name.

classmethod get_descriptions() → Dict[str, str]

Returns variable to description mapping.

classmethod bootstrap(dsn: Union[str, List[str]], *, allow_shared_sockets: bool = None, **init_kwargs) → TypeSection

Constructs a section object performing it’s basic (default) configuration.

Parameters:
  • dsn

    Data source name, e.g: * http://127.0.0.1:8000 * https://127.0.0.1:443?cert=/here/there.crt&key=/that/my.key

    Note

    Some schemas: fastcgi, http, https, raw, scgi, shared, udp, uwsgi, suwsgi, zeromq

  • allow_shared_sockets – Allows using shared sockets to bind to privileged ports. If not provided automatic mode is enabled: shared are allowed if current user is not root.
  • init_kwargs – Additional initialization keyword arguments accepted by section type.
class uwsgiconf.config.Configuration(sections: List[uwsgiconf.config.Section] = None, *, autoinclude_sections: bool = False, alias: str = None)

Configuration is comprised from one or more Sections and could be represented in format natively supported by uWSGI.

Parameters:
  • sections – If not provided, empty section will be automatically generated.
  • autoinclude_sections – Whether to include in the first sections all subsequent sections.
  • alias – Configuration alias. This will be used in tofile as file name.
format(*, do_print: bool = False, stamp: bool = True, formatter: str = 'ini') → Union[str, List[str]]

Applies formatting to configuration.

Parameters:
  • do_print – Whether to print out formatted config.
  • stamp – Whether to add stamp data to the first configuration section.
  • formatter – Formatter alias to format options. Default: ini.
print_ini() → Union[str, List[str]]

Print out this configuration as .ini.

tofile(filepath: Union[str, pathlib.Path] = None) → str

Saves configuration into a file and returns its path.

Convenience method.

Parameters:filepath – Filepath to save configuration into. If not provided a temporary file will be automatically generated.
uwsgiconf.config.configure_uwsgi(configurator_func: Callable) → Optional[List[uwsgiconf.config.Configuration]]

Allows configuring uWSGI using Configuration objects returned by the given configuration function.

Returns a list with detected configurations or None if called from within uWSGI (e.g. when trying to load WSGI application).

# In configuration module, e.g `uwsgicfg.py`

from uwsgiconf.config import configure_uwsgi

configure_uwsgi(get_configurations)
Parameters:configurator_func – Function which return a list on configurations.
Raises:ConfigurationError