Configuration and Section¶

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

Configuration¶

Configuration(
    sections: list[Section] | None = None, 
    autoinclude_sections: bool = False, 
    alias: str | None = None
)

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

Functions¶

format¶

.format(
    do_print: bool = False,  # (1)!
    stamp: bool = True,  # (2)!
    formatter: str = 'ini',  # (3)!
) -> Strlist

Whether to print out formatted config.
Whether to add stamp data to the first configuration section.
Formatter alias to format options. Default: ini.

Applies formatting to configuration.

print_ini¶

.print_ini() -> Strlist

Print out this configuration as .ini.

tofile¶

.tofile(
    filepath: Strpath = None,  # (1)!
) -> Path

Filepath to save configuration into. If not provided a temporary file will be automatically generated.

Saves configuration into a file and returns its path.

Convenience method.

----¶

Section¶

Section(
    name: str | None = None, 
    runtime_dir: Strpath = None, 
    project_name: str | None = None, 
    strict_config: bool | None = None, 
    style_prints: bool = False, 
    embedded_plugins: Callable | list[str] | None = None, 
    **kwargs
)

OptionsGroup

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:

    .. code-block:: python

        Section(
            params_workers=dict(count=3),
        )

Attributes¶

alarms¶

.alarms: Alarms = Options(Alarms)

Alarms options group.

applications¶

.applications: Applications = Options(Applications)

Applications options group.

caching¶

.caching: Caching = Options(Caching)

Caching options group.

cheapening¶

.cheapening: Cheapening = Options(Cheapening)

Cheapening options group.

empire¶

.empire: Empire = Options(Empire)

Emperor and vassals options group.

locks¶

.locks: Locks = Options(Locks)

Locks options group.

logging¶

.logging: Logging = Options(Logging)

Logging options group.

main_process¶

.main_process: MainProcess = Options(MainProcess)

Main process options group.

master_process¶

.master_process: MasterProcess = Options(MasterProcess)

Master process options group.

monitoring¶

.monitoring: Monitoring = Options(Monitoring)

Monitoring options group.

networking¶

.networking: Networking = Options(Networking)

Networking options group.

project_name ¶

.project_name()

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

python¶

.python: Python = Options(Python)

Python options group.

queue¶

.queue: Queue = Options(Queue)

Queue options group.

routing¶

.routing: Routing = Options(Routing)

Routing related options group.

spooler¶

.spooler: Spooler = Options(Spooler)

Spooler options group.

statics¶

.statics: Statics = Options(Statics)

Static file serving options group.

subscriptions¶

.subscriptions: Subscriptions = Options(Subscriptions)

Subscription services options group.

workers¶

.workers: Workers = Options(Workers)

Workers options group.

Functions¶

as_configuration¶

.as_configuration(
    **kwargs,  # (1)!
) -> Configuration

Configuration objects initializer arguments.

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

bootstrap ¶

.bootstrap(
    dsn: Strlist,  # (1)!
    allow_shared_sockets: bool | None = None,  # (2)!
    **init_kwargs: Any,  # (3)!
) -> TypeSection

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
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.
Additional initialization keyword arguments accepted by section type.

Constructs a section object performing its basic (default) configuration.

derive_from ¶

.derive_from(
    section: TypeSection,  # (1)!
    name: str | None = None,  # (2)!
) -> TypeSection

Section to derive from,
New section name.

Creates a new section based on the given.

env¶

.env(
    key: str, 
    value: Any = None, 
    unset: bool = False,  # (1)!
    asap: bool = False,  # (2)!
    update_local: bool = False,  # (3)!
) -> TypeSection

Whether to unset this variable.
If True env variable will be set as soon as possible.
Whether we need to set this value for local environment too. This could be useful in embedded mode.

Processes (sets/unsets) environment variable.

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

get_runtime_dir¶

.get_runtime_dir(
    default: bool = True,  # (1)!
) -> Path

Whether to return [system] default if not set.

Directory to store runtime files. See .replace_placeholders()

Note

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

include¶

.include(
    target: Union[Section,  list[Section],  str,  list[str]],  # (1)!
) -> TypeSection

File path or Section to include.

Includes target contents into config.

print_out¶

.print_out(
    value: Any, 
    indent: str | None = None, 
    format_options: dict | str | None = None,  # (1)!
    asap: bool = False,  # (2)!
) -> TypeSection

text color
Print as soon as possible.

Prints out the given value.

print_plugins¶

.print_plugins() -> TypeSection

Print out enabled plugins.

print_stamp¶

.print_stamp() -> TypeSection

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

print_variables¶

.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

replace_placeholders¶

.replace_placeholders(value: Strlist | Pathlist | None) -> Strlist | None

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

Supported placeholders: * {project_runtime_dir} * {project_name} * {runtime_dir}

set_fallback¶

.set_fallback(
    target: Union[str,  Section],  # (1)!
) -> TypeSection

File path or Section to include.

Sets a fallback configuration for section.

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

set_placeholder¶

.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.

set_plugins_params¶

.set_plugins_params(
    plugins: list[str] | list[OptionsGroup] | str | OptionsGroup = None,  # (1)!
    search_dirs: Strlist = None,  # (2)!
    autoload: bool | None = None,  # (3)!
    required: bool = False,  # (4)!
) -> TypeSection

uWSGI plugins to load
Directories to search for uWSGI plugins.
Try to automatically load plugins when unknown options are found.
Load uWSGI plugins and exit on error.

Sets plugin-related parameters.

set_runtime_dir¶

.set_runtime_dir(value: Strpath) -> TypeSection

Sets user-defined runtime directory value.

Classes¶

embedded_plugins_presets¶

.embedded_plugins_presets()

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

BASIC¶

.BASIC: ClassVar[list[str]] = [plugin.strip() for plugin in (
    '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').split(',')]

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

PROBE ¶

.PROBE()

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

vars¶

.vars()

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

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

CONF_CURRENT_SECTION¶

.CONF_CURRENT_SECTION = '%x'

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

CONF_NAME_ORIGINAL¶

.CONF_NAME_ORIGINAL = '%o'

The original conf filename, as specified on the command line

CPU_CORES¶

.CPU_CORES = '%k'

Detected CPU count.

DIR_VASSALS¶

.DIR_VASSALS = '%v'

Vassals directory - pwd.

FORMAT_ESCAPE¶

.FORMAT_ESCAPE = '%['

ANSI escape \033. useful for printing colors

GROUP_ID¶

.GROUP_ID = '%g'

Use group ID.

GROUP_NAME¶

.GROUP_NAME = '%G'

Use group name.

HOST_NAME¶

.HOST_NAME = '%h'

Host name.

TIMESTAMP_STARTUP_MS¶

.TIMESTAMP_STARTUP_MS = '%T'

Unix time ms, gathered at instance startup

TIMESTAMP_STARTUP_S¶

.TIMESTAMP_STARTUP_S = '%t'

Unix time s, gathered at instance startup.

USER_ID¶

.USER_ID = '%u'

User ID.

USER_NAME¶

.USER_NAME = '%U'

User name.

VERSION¶

.VERSION = '%V'

uWSGI version number

get_descriptions ¶

.get_descriptions() -> dict[str, str]

Returns variable to description mapping.