Configuration and Section

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

class uwsgiconf.config.Section(name=None, runtime_dir=None, project_name=None, strict_config=None, style_prints=False, embedded_plugins=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:

Parameters:
  • strict_config (bool) –

    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.

  • name (str|unicode) – Configuration section name.
  • runtime_dir (str|unicode) –

    Directory to store runtime files. See .replace_placeholders()

    Note

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

  • project_name (str|unicode) – Project name (alias) to be used to differentiate projects. See .replace_placeholders().
  • style_prints (bool) – Enables styling (e.g. colouring) for print_ family methods. Could be nice for console and distracting in logs.
  • embedded_plugins (list|callable) –

    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=None)

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

replace_placeholders(value)

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

Supported placeholders:
  • {project_runtime_dir}
  • {project_name}
  • {runtime_dir}
Parameters:value (str|unicode|list[str|unicode]|None) –
Return type:None|str|unicode|list[str|unicode]
project_name

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

Return type:str|unicode
get_runtime_dir(default=True)

Directory to store runtime files. See .replace_placeholders()

Note

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

Parameters:default (bool) – Whether to return [system] default if not set.
Return type:str|unicode
set_runtime_dir(value)

Sets user-defined runtime directory value.

Parameters:value (str|unicode) –
set_basic_params(strict_config=None, **kwargs)
Return type:Section
as_configuration(**kwargs)

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

Parameters:kwargs – Configuration objects initializer arguments.
Return type:Configuration
print_plugins()

Print out enabled plugins.

print_stamp()

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

print_out(value, indent=None, format_options=None, asap=False)

Prints out the given value.

Parameters:
  • value
  • indent (str|unicode) –
  • format_options (dict|str|unicode) – text color
  • asap (bool) – Print as soon as possible.
print_variables()

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=None, search_dirs=None, autoload=None, required=False)

Sets plugin-related parameters.

Parameters:
  • plugins (list|str|unicode|OptionsGroup|list[OptionsGroup]) – uWSGI plugins to load
  • search_dirs (list|str|unicode) – Directories to search for uWSGI plugins.
  • autoload (bool) – Try to automatically load plugins when unknown options are found.
  • required (bool) – Load uWSGI plugins and exit on error.
set_fallback(target)

Sets a fallback configuration for section.

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

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

Placeholders are custom magic variables defined during configuration time.

Note

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

Parameters:
  • key (str|unicode) –
  • value (str|unicode) –
env(key, value=None, unset=False, asap=False)

Processes (sets/unsets) environment variable.

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

Parameters:
  • key (str|unicode) –
  • value
  • unset (bool) – Whether to unset this variable.
  • asap (bool) – If True env variable will be set as soon as possible.
include(target)

Includes target contents into config.

Parameters:target (str|unicode|Section|list) – File path or Section to include.
classmethod derive_from(section, name=None)

Creates a new section based on the given.

Parameters:
  • section (Section) – Section to derive from,
  • name (str|unicode) – New section name.
Return type:

Section

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()

Returns variable to description mapping.

Return type:dict
class uwsgiconf.config.Configuration(sections=None, autoinclude_sections=False, alias=None)

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

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

Applies formatting to configuration.

Currently formats to .ini

Parameters:
  • do_print (bool) – Whether to print out formatted config.
  • stamp (bool) – Whether to add stamp data to the first configuration section.
Return type:

str|unicode

print_ini()

Print out this configuration as .ini.

Return type:str|unicode
tofile(filepath=None)

Saves configuration into a file and returns its path.

Convenience method.

Parameters:filepath (str|unicode) – Filepath to save configuration into. If not provided a temporary file will be automatically generated.
Return type:str|unicode
uwsgiconf.config.configure_uwsgi(configurator_func)

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

Parameters:configurator_func (callable) – Function which return a list on configurations.
Return type:list|None
Returns:A list with detected configurations or None if called from within uWSGI (e.g. when trying to load WSGI application).
Raises:ConfigurationError