Block (low-level) API

The Block API provides objects to programatically generate nginx configurations.

Example:

>>> from nginx.config.api import Config, Section, Location
>>> events = Section('events', worker_connections='1024')
>>> http = Section('http', include='../conf/mime.types')
>>> http.sections.add(
...     Section(
...         'server',
...         Location(
...             '/foo',
...             proxy_pass='upstream',
...         ),
...         server_name='_',
...     )
... )
>>> nginx = Config(
...     events,
...     http,
...     worker_processes='auto',
...     daemon='on',
...     error_log='var/error.log',
... )
>>> print(nginx)

error_log var/error.log;
worker_processes auto;
daemon on;
http {
    include ../conf/mime.types;
    server {
        server_name _;
        location /foo {
            proxy_pass upstream;
        }
    }
}
events {
    worker_connections 1024;
}

class nginx.config.api.EmptyBlock(*sections, **options)

An unnamed block of options and/or sections.

Empty blocks are useful for representing groups of options.

For example, you can use them to represent options with non-unique keys:

Example:

>>> from nginx.config.helpers import duplicate_options
>>> dupes = duplicate_options('key', ['value', 'other_value', 'third_value'])
>>> type(dupes)
nginx.config.api.blocks.EmptyBlock
>>> print(dupes)

key third_value;
key value;
key other_value;

class nginx.config.api.Block(name, *sections, **options)

A block represent a named section of an Nginx config, such as ‘http’, ‘server’ or ‘location’

Using this object is as simple as providing a name and any sections or options, which can be other Block objects or option objects.

Example:

>>> from nginx.config.api import Block
>>> http = Block('http', option='value')
>>> print(http)

    http {
        option value;
    }

class nginx.config.api.Location(location, *args, **kwargs)

A Location is just a named block with “location” prefixed

class nginx.config.api.KeyOption(name)

A KeyOption represents a directive with no value.

For example: http://nginx.org/en/docs/http/ngx_http_core_module.html#internal

class nginx.config.api.KeyValueOption(name, value='')

A key/value directive. This covers most directives available for Nginx

class nginx.config.api.KeyMultiValueOption(name, value='')

A key with multiple space delimited options.

For example: http://nginx.org/en/docs/http/ngx_http_log_module.html#access_log

Example:

>>> from nginx.config.api.options import KeyMultiValueOption
>>> a_log = KeyMultiValueOption('access_log', ['/path/to/log.gz', 'combined', 'gzip', 'flush=5m'])
>>> print(a_log)

access_log /path/to/log.gz combined gzip flush=5m;

class nginx.config.api.Comment(offset='', comment='', **kwargs)

A simple comment object.

nginx.config.api.Config

alias of EmptyBlock

nginx.config.api.Section

alias of Block