pystalk documentation

pystalk is a simple Python module for interacting with the beanstalk task queueing daemon. It doesn’t provide much magic, but is suitable for building all sorts of functionality on top of.

This work is available under the terms of the ISC License.


class pystalk.BeanstalkClient(host, port=11300, socket_timeout=None, auto_decode=False)

Simple wrapper around the Beanstalk API.

  • host (str) – Hostname or IP address to connect to
  • port (int) – Port to connect to
  • socket_timeout (float) – Timeout to set on the socket.
  • auto_decode (bool) – Attempt to decode job bodies as UTF-8 when reading them

Doesn’t provide any fanciness for writing consumers or producers. Just lets you invoke methods to call beanstalk functions.


Setting socket timeout to a value lower than the value you pass to blocking functions like reserve_job() will cause errors!

bury_job(job_id, pri=65536)

Mark the given job_id as buried. The job must have been previously reserved by this connection

  • job_id – Job to bury
  • pri (int) – Priority for the newly-buried job. If not passed, will keep its current priority

Close any open connection to the Beanstalk server.

This object is still safe to use after calling close() ; it will automatically reconnect


Delete the given job id. The job must have been previously reserved by this connection


Remove the given tube from the watchlist.

Parameters:tube – Name of tube to remove from the watchlist

If all tubes are ignore() d, beanstalk will auto-add “default” to the watchlist to prevent the list from being empty. See watch() for more unformation.


Kick some number of jobs from the buried queue onto the ready queue.

Parameters:num_jobs (int) – Number of jobs to kick

If not that many jobs are in the buried queue, it will kick as many as it can.


Return a list of tubes that this beanstalk instance knows about

Return type:list of tubes
pause_tube(tube, delay=3600)

Pause a tube for some number of seconds, preventing it from issuing jobs.

Parameters:delay (int) – Time to pause for, in seconds

There is no way to permanently pause a tube; passing 0 for delay actually un-pauses the tube.

See also



Peek at the top job on the buried queue


Peek at buried jobs in sequence


Peek at the job job on the delayed queue


Peek at delayed jobs in sequence


Peek at the job job on the ready queue.

Return type:Job
put_job(data, pri=65536, delay=0, ttr=120)

Insert a new job into the queue.

  • data (Text (either str which will be encoded as utf-8, or bytes which are already utf-8) – Job body
  • pri (int) – Priority for the job
  • delay (int) – Delay in seconds before the job should be placed on the ready queue
  • ttr (int) – Time to reserve (how long a worker may work on this job before we assume the worker is blocked and give the job to another worker
release_job(job_id, pri=65536, delay=0)

Put a job back on the queue to be processed (indicating that you’ve aborted it)

  • job_id – Job ID to return
  • pri (int) – New priority (if not passed, will use old priority)
  • delay (int) – New delay for job (if not passed, will use 0)

Reserve jobs as an iterator. Ends iteration when there are no more jobs immediately available


Reserve a job for this connection. Blocks for TIMEOUT secionds and raises TIMED_OUT if no job was available

Parameters:timeout (int) – Time to wait for a job, in seconds.

Return a dictionary with a bunch of instance-wide statistics

Return type:dict

Fetch statistics about a single job

Return type:dict

Fetch statistics about a single tube

Parameters:tube_name – Tube to fetch stats about
Return type:dict

Unpause a tube which was previously paused with pause_tube().

See also



Start producing jobs into the given tube.

Parameters:tube – Name of the tube to USE

Subsequent calls to :func:put_job()` insert jobs into this tube.


Add the given tube to the watchlist.

Parameters:tube – Name of the tube to add to the watchlist

Note: Initially, all connections are watching a tube named “default”. If you manually call watch(), we will un-watch the “default” tube. To keep it in your list, first call watch() with the other tubes, then call :func:`watch() with “default”.

exception pystalk.BeanstalkError(message)

Common error raised when something goes wron with beanstalk

Indices and tables