The uwsgi Python module

The uWSGI server automagically adds a uwsgi module into your Python apps.

This is useful for configuring the uWSGI server, use its internal functions and get statistics. Also useful for detecting whether you’re actually running under uWSGI; if you attempt to import uwsgi and receive an ImportError you’re not running under uWSGI.

Note

Many of these functions are currently woefully undocumented.

Module-level globals

uwsgi.numproc

The number of processes/workers currently running.

uwsgi.buffer_size

The current configured buffer size in bytes.

uwsgi.started_on(int)

The Unix timestamp of uWSGI’s startup.

uwsgi.fastfuncs

This is the dictionary used to define FastFuncs.

uwsgi.applist

This is the list of applications currently configured.

uwsgi.applications

This is the dynamic applications dictionary.

See also

Application dictionary

uwsgi.message_manager_marshal

The callable to run when the uWSGI server receives a marshalled message.

uwsgi.magic_table

The magic table of configuration placeholders.

uwsgi.opt

The current configuration options, including any custom placeholders.

Cache functions

uwsgi.cache_get(key[, cache_name])

Get a value from the cache.

Parameters

  • key – The cache key to read.

  • cache_name – The name of the cache in multiple cache mode (can be in the form name@address). Optional.

uwsgi.cache_set(key, value[, expire, cache_name])

Set a value in the cache. If the key is already set but not expired, it doesn’t set anything.

Parameters

  • key – The cache key to write.

  • value – The cache value to write.

  • expire – Expiry time of the value, in seconds.

  • cache_name – The name of the cache in multiple cache mode (can be in the form name@address). Optional.

uwsgi.cache_update(key, value[, expire, cache_name])

Update a value in the cache. This always sets the key, whether it was already set before or not and whether it has expired or not.

Parameters

  • key – The cache key to write.

  • value – The cache value to write.

  • expire – Expiry time of the value, in seconds.

  • cache_name – The name of the cache in multiple cache mode (can be in the form name@address). Optional.

uwsgi.cache_del(key[, cache_name])

Delete the given cached value from the cache.

Parameters

  • key – The cache key to delete.

  • cache_name – The name of the cache in multiple cache mode (can be in the form name@address). Optional.

uwsgi.cache_exists(key[, cache_name])

Quickly check whether there is a value in the cache associated with the given key.

Parameters

  • key – The cache key to check.

  • cache_name – The name of the cache in multiple cache mode (can be in the form name@address). Optional.

uwsgi.cache_clear()

Queue functions

uwsgi.queue_get()
uwsgi.queue_set()
uwsgi.queue_last()
uwsgi.queue_push()
uwsgi.queue_pull()
uwsgi.queue_pop()
uwsgi.queue_slot()
uwsgi.queue_pull_slot()

SNMP functions

uwsgi.snmp_set_community(str)
Parameters

str – The string containing the new community value.

Sets the SNMP community string.

uwsgi.snmp_set_counter32(oidnum, value)
uwsgi.snmp_set_counter64(oidnum, value)
uwsgi.snmp_set_gauge(oidnum, value)
Parameters

  • oidnum – An integer containing the oid number target.

  • value – An integer containing the new value of the counter or gauge.

Sets the counter or gauge to a specific value.

uwsgi.snmp_incr_counter32(oidnum, value)
uwsgi.snmp_incr_counter64(oidnum, value)
uwsgi.snmp_incr_gauge(oidnum, value)
uwsgi.snmp_decr_counter32(oidnum, value)
uwsgi.snmp_decr_counter64(oidnum, value)
uwsgi.snmp_decr_gauge(oidnum, value)
Parameters

  • oidnum – An integer containing the oid number target.

  • value – An integer containing the amount to increase or decrease the counter or gauge. If not specified the default is 1.

Increases or decreases the counter or gauge by a specific amount.

Note

uWSGI OID tree starts at 1.3.6.1.4.1.35156.17

Spooler functions

uwsgi.send_to_spooler(message_dict=None, spooler=None, priority=None, at=None, body=None, **kwargs)
Parameters

  • message_dict – The message (string keys, string values) to spool. Either this, or **kwargs may be set.

  • spooler – The spooler (id or directory) to use.

  • priority – The priority of the message. Larger = less important.

  • at – The minimum UNIX timestamp at which this message should be processed.

  • body – A binary (bytestring) body to add to the message, in addition to the message dictionary itself. Its value will be available in the key body in the message.

Send data to the The uWSGI Spooler. Also known as spool().

Note

Any of the keyword arguments may also be passed in the message dictionary. This means they’re reserved words, in a way…

uwsgi.set_spooler_frequency(seconds)

Set how often the spooler runs.

uwsgi.spooler_jobs()
uwsgi.spooler_pid()
uwsgi.spooler_get_task(path)
Parameters

path – The relative or absolute path to the task to read

Advanced methods

uwsgi.send_message()

Send a generic message using The uwsgi Protocol.

Note

Until version 2f970ce58543278c851ff30e52758fd6d6e69fdc this function was called send_uwsgi_message().

uwsgi.route()
uwsgi.send_multi_message()

Send a generic message to multiple recipients using The uwsgi Protocol.

Note

Until version 2f970ce58543278c851ff30e52758fd6d6e69fdc this function was called send_multi_uwsgi_message().

See also

Clustering for examples

uwsgi.accepting(accepting=True)

Set the accepting flag of the current worker to the value. This is required when using `Overriding Workers`_ and touch-chain-reload at the same time.

See also

Overriding Workers

uwsgi.reload()

Gracefully reload the uWSGI server stack.

See also

Reload

uwsgi.stop()
uwsgi.workers() → dict

Get a statistics dictionary of all the workers for the current server. A dictionary is returned.

uwsgi.masterpid() → int

Return the process identifier (PID) of the uWSGI master process.

uwsgi.total_requests() → int

Returns the total number of requests managed so far by the pool of uWSGI workers.

uwsgi.get_option()

Also available as getoption().

uwsgi.set_option()

Also available as setoption().

uwsgi.sorry_i_need_to_block()
uwsgi.request_id()
uwsgi.worker_id()
uwsgi.mule_id()
uwsgi.log()
uwsgi.log_this_request()
uwsgi.set_logvar()
uwsgi.get_logvar()
uwsgi.disconnect()
uwsgi.grunt()
uwsgi.lock(locknum=0)
Parameters

locknum – The lock number to lock. Lock 0 is always available.

uwsgi.is_locked()
uwsgi.unlock(locknum=0)
Parameters

locknum – The lock number to unlock. Lock 0 is always available.

uwsgi.cl()
uwsgi.setprocname()
uwsgi.listen_queue()
uwsgi.register_signal(num, who, function)
Parameters

  • num – the signal number to configure

  • who –

    a magic string that will set which process/processes receive the signal.

    • worker/worker0 will send the signal to the first available worker. This is the default if you specify an empty string.

    • workers will send the signal to every worker.

    • workerN (N > 0) will send the signal to worker N.

    • mule/mule0 will send the signal to the first available mule. (See uWSGI Mules)

    • mules will send the signal to all mules

    • muleN (N > 0) will send the signal to mule N.

    • cluster will send the signal to all the nodes in the cluster. Warning: not implemented.

    • subscribed will send the signal to all subscribed nodes. Warning: not implemented.

    • spooler will send the signal to the spooler.

    cluster and subscribed are special, as they will send the signal to the master of all cluster/subscribed nodes. The other nodes will have to define a local handler though, to avoid a terrible signal storm loop.

  • function – A callable that takes a single numeric argument.

uwsgi.signal(num)
Parameters

num – the signal number to raise

uwsgi.signal_wait([signum])

Block the process/thread/async core until a signal is received. Use signal_received to get the number of the signal received. If a registered handler handles a signal, signal_wait will be interrupted and the actual handler will handle the signal.

Parameters

signum – Optional - the signal to wait for

uwsgi.signal_registered()
uwsgi.signal_received()

Get the number of the last signal received. Used in conjunction with signal_wait.

uwsgi.add_file_monitor()
uwsgi.add_timer(signum, seconds)
Parameters

  • signum – The signal number to raise.

  • seconds – The interval at which to raise the signal.

uwsgi.add_probe()
uwsgi.add_rb_timer(signum, seconds[, iterations=0])

Add an user-space (red-black tree backed) timer.

Parameters

  • signum – The signal number to raise.

  • seconds – The interval at which to raise the signal.

  • iterations – How many times to raise the signal. 0 (the default) means infinity.

uwsgi.add_cron(signal, minute, hour, day, month, weekday)

For the time parameters, you may use the syntax -n to denote “every n”. For instance hour=-2 would declare the signal to be sent every other hour.

Parameters

  • signal – The signal number to raise.

  • minute – The minute on which to run this event.

  • hour – The hour on which to run this event.

  • day – The day on which to run this event. This is “OR”ed with weekday.

  • month – The month on which to run this event.

  • weekday – The weekday on which to run this event. This is “OR”ed with day. (In accordance with the POSIX standard, 0 is Sunday, 6 is Monday)

uwsgi.register_rpc()
uwsgi.rpc()
uwsgi.rpc_list()
uwsgi.call()
uwsgi.sendfile()
uwsgi.set_warning_message()
uwsgi.mem()
uwsgi.has_hook()
uwsgi.logsize()
uwsgi.send_multicast_message()
uwsgi.cluster_nodes()
uwsgi.cluster_node_name()
uwsgi.cluster()
uwsgi.cluster_best_node()
uwsgi.connect()
uwsgi.connection_fd()
uwsgi.is_connected()
uwsgi.send()
uwsgi.recv()
uwsgi.recv_block()
uwsgi.recv_frame()
uwsgi.close()
uwsgi.i_am_the_spooler()
uwsgi.fcgi()
uwsgi.parsefile()
uwsgi.embedded_data(symbol_name)
Parameters

string – The symbol name to extract.

Extracts a symbol from the uWSGI binary image.

See also

Embedding an application in uWSGI

uwsgi.extract()
uwsgi.mule_msg(string[, id])
Parameters

  • string – The bytestring message to send.

  • id – Optional - the mule ID to receive the message. If you do not specify an ID, the message will go to the first available programmed mule.

Send a message to a mule.

uwsgi.farm_msg(farm_name, string)
Parameters

  • farm_name – The name of the farm to send the message to.

  • string – The bytestring message to send.

Send a message to a mule farm.

uwsgi.mule_get_msg()
Returns

A mule message, once one is received.

Block until a mule message is received and return it. This can be called from multiple threads in the same programmed mule.

uwsgi.farm_get_msg()
Returns

A mule message, once one is received.

Block until a mule message is received and return it. Only messages sent to the mule’s configured farm will be received. This can be called from multiple threads in the same programmed mule.

uwsgi.in_farm()
Returns

True if the mule is a member of a farm, False otherwise.

Return type

bool

Indicate whether the mule is a member of a farm.

uwsgi.ready()
uwsgi.set_user_harakiri()

Async functions

uwsgi.async_sleep(seconds)

Suspend handling the current request for seconds seconds and pass control to the next async core.

Parameters

seconds – Sleep time, in seconds.

uwsgi.async_connect()
uwsgi.async_send_message()
uwsgi.green_schedule()
uwsgi.suspend()

Suspend handling the current request and pass control to the next async core clamoring for attention.

uwsgi.wait_fd_read(fd[, timeout])

Suspend handling the current request until there is something to be read on file descriptor fd. May be called several times before yielding/suspending to add more file descriptors to the set to be watched.

Parameters

  • fd – File descriptor number.

  • timeout – Optional timeout (infinite if omitted).

uwsgi.wait_fd_write(fd[, timeout])

Suspend handling the current request until there is nothing more to be written on file descriptor fd. May be called several times to add more file descriptors to the set to be watched.

Parameters

  • fd – File descriptor number.

  • timeout – Optional timeout (infinite if omitted).

SharedArea functions

See also

SharedArea – share memory pages between uWSGI components

uwsgi.sharedarea_read(pos, len) → bytes

Read a byte string from the uWSGI SharedArea – share memory pages between uWSGI components.

Parameters

  • pos – Starting position to read from.

  • len – Number of bytes to read.

Returns

Bytes read, or None if the shared area is not enabled or the read request is invalid.

uwsgi.sharedarea_write(pos, str) → long

Write a byte string into the uWSGI SharedArea – share memory pages between uWSGI components.

Parameters

  • pos – Starting position to write to.

  • str – Bytestring to write.

Returns

Number of bytes written, or None if the shared area is not enabled or the write could not be fully finished.

uwsgi.sharedarea_readbyte(pos) → int

Read a single byte from the uWSGI SharedArea – share memory pages between uWSGI components.

Parameters

pos – The position to read from.

Returns

Bytes read, or None if the shared area is not enabled or the read request is invalid.

uwsgi.sharedarea_writebyte(pos, val) → int

Write a single byte into the uWSGI SharedArea – share memory pages between uWSGI components.

Parameters

  • pos – The position to write the value to.

  • val (integer) – The value to write.

Returns

The byte written, or None if the shared area is not enabled or the write request is invalid.

uwsgi.sharedarea_readlong(pos) → int

Read a 64-bit (8-byte) long from the uWSGI SharedArea – share memory pages between uWSGI components.

Parameters

pos – The position to read from.

Returns

The value read, or None if the shared area is not enabled or the read request is invalid.

uwsgi.sharedarea_writelong(pos, val) → int

Write a 64-bit (8-byte) long into the uWSGI SharedArea – share memory pages between uWSGI components.

Parameters

  • pos – The position to write the value to.

  • val (long) – The value to write.

Returns

The value written, or None if the shared area is not enabled or the write request is invalid.

uwsgi.sharedarea_inclong(pos) → int

Atomically increment a 64-bit long value in the uWSGI SharedArea – share memory pages between uWSGI components.

Parameters

pos – The position of the value.

Returns

The new value at the given position, or None if the shared area is not enabled or the read request is invalid.

Erlang functions

uwsgi.erlang_send_message(node, process_name, message)
uwsgi.erlang_register_process(process_name, callable)
uwsgi.erlang_recv_message(node)
uwsgi.erlang_connect(address)
Returns

File descriptor or -1 on error

uwsgi.erlang_rpc(node, module, function, argument)