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.startedon(_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.cacheget(_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.cacheset(_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.cacheupdate(_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.cachedel(_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.cacheexists(_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.snmpset_community(_str)

Parameters:str – The string containing the new community value.

Sets the SNMP community string.

• uwsgi.snmpset_counter32(_oidnum, value)

• uwsgi.snmpset_counter64(_oidnum, value)

• uwsgi.snmpset_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.snmpincr_counter32(_oidnum, value)

• uwsgi.snmpincr_counter64(_oidnum, value)

• uwsgi.snmpincr_gauge(_oidnum, value)

• uwsgi.snmpdecr_counter32(_oidnum, value)

• uwsgi.snmpdecr_counter64(_oidnum, value)

• uwsgi.snmpdecr_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.sendto_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.setspooler_frequency(_seconds)
• Set how often the spooler runs.

• uwsgi.spooler_jobs()

• uwsgi.spooler_pid()

• uwsgi.spoolerget_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 isrequired when using Overriding Workers_ and touch-chain-reload atthe 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.registersignal(_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.signalwait([_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.addtimer(_signum, seconds)

Parameters:

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

• uwsgi.add_probe()

• uwsgi.addrb_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.addcron(_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.embeddeddata(_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.mulemsg(_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.farmmsg(_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.asyncsleep(_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.waitfd_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.waitfd_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.sharedarearead(_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.sharedareawrite(_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.sharedareareadbyte(_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.sharedareawritebyte(_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.sharedareareadlong(_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.sharedareawritelong(_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.sharedareainclong(_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.erlangsend_message(_node, process_name, message)

• uwsgi.erlangregister_process(_process_name, callable)

• uwsgi.erlangrecv_message(_node)

• uwsgi.erlangconnect(_address)

Returns:File descriptor or -1 on error

• uwsgi.erlangrpc(_node, module, function, argument)