API Reference

class greenstalk.Client(address, encoding='utf-8', use='default', watch='default')

A client implementing the beanstalk protocol. Upon creation a connection with beanstalkd is established and tubes are initialized.

Parameters:
  • address (Union[Tuple[str, int], str]) – A socket address pair (host, port) or a Unix domain socket path.
  • encoding (Optional[str]) – The encoding used to encode and decode job bodies.
  • use (str) – The tube to use after connecting.
  • watch (Union[str, Iterable[str]]) – The tubes to watch after connecting. The default tube will be ignored if it’s not included.
close()

Closes the connection to beanstalkd. The client instance should not be used after calling this method.

Return type:None
put(body, priority=65536, delay=0, ttr=60)

Inserts a job into the currently used tube and returns the job ID.

Parameters:
  • body (Union[bytes, str]) – The data representing the job.
  • priority (int) – An integer between 0 and 4,294,967,295 where 0 is the most urgent.
  • delay (int) – The number of seconds to delay the job for.
  • ttr (int) – The maximum number of seconds the job can be reserved for before timing out.
Return type:

int

use(tube)

Changes the currently used tube.

Parameters:tube (str) – The tube to use.
Return type:None
reserve(timeout=None)

Reserves a job from a tube on the watch list, giving this client exclusive access to it for the TTR. Returns the reserved job.

This blocks until a job is reserved unless a timeout is given, which will raise a TimedOutError if a job cannot be reserved within that time.

Parameters:timeout (Optional[int]) – The maximum number of seconds to wait.
Return type:Job
reserve_job(id)

Reserves a job by ID, giving this client exclusive access to it for the TTR. Returns the reserved job.

A NotFoundError is raised if a job with the specified ID could not be reserved.

Parameters:id (int) – The ID of the job to reserve.
Return type:Job
delete(job)

Deletes a job.

Parameters:job (Union[Job, int]) – The job or job ID to delete.
Return type:None
release(job, priority=65536, delay=0)

Releases a reserved job.

Parameters:
  • job (Job) – The job to release.
  • priority (int) – An integer between 0 and 4,294,967,295 where 0 is the most urgent.
  • delay (int) – The number of seconds to delay the job for.
Return type:

None

bury(job, priority=65536)

Buries a reserved job.

Parameters:
  • job (Job) – The job to bury.
  • priority (int) – An integer between 0 and 4,294,967,295 where 0 is the most urgent.
Return type:

None

touch(job)

Refreshes the TTR of a reserved job.

Parameters:job (Job) – The job to touch.
Return type:None
watch(tube)

Adds a tube to the watch list. Returns the number of tubes this client is watching.

Parameters:tube (str) – The tube to watch.
Return type:int
ignore(tube)

Removes a tube from the watch list. Returns the number of tubes this client is watching.

Parameters:tube (str) – The tube to ignore.
Return type:int
peek(id)

Returns a job by ID.

Parameters:id (int) – The ID of the job to peek.
Return type:Job
peek_ready()

Returns the next ready job in the currently used tube.

Return type:Job
peek_delayed()

Returns the next available delayed job in the currently used tube.

Return type:Job
peek_buried()

Returns the oldest buried job in the currently used tube.

Return type:Job
kick(bound)

Moves delayed and buried jobs into the ready queue and returns the number of jobs effected.

Only jobs from the currently used tube are moved.

A kick will only move jobs in a single state. If there are any buried jobs, only those will be moved. Otherwise delayed jobs will be moved.

Parameters:bound (int) – The maximum number of jobs to kick.
Return type:int
kick_job(job)

Moves a delayed or buried job into the ready queue.

Parameters:job (Union[Job, int]) – The job or job ID to kick.
Return type:None
stats_job(job)

Returns job statistics.

Parameters:job (Union[Job, int]) – The job or job ID to return statistics for.
Return type:Dict[str, Union[str, int]]
stats_tube(tube)

Returns tube statistics.

Parameters:tube (str) – The tube to return statistics for.
Return type:Dict[str, Union[str, int]]
stats()

Returns system statistics.

Return type:Dict[str, Union[str, int]]
tubes()

Returns a list of all existing tubes.

Return type:List[str]
using()

Returns the tube currently being used by the client.

Return type:str
watching()

Returns a list of tubes currently being watched by the client.

Return type:List[str]
pause_tube(tube, delay)

Prevents jobs from being reserved from a tube for a period of time.

Parameters:
  • tube (str) – The tube to pause.
  • delay (int) – The number of seconds to pause the tube for.
Return type:

None

class greenstalk.Job(id, body)

A job returned from the server.

class greenstalk.Error

Base class for non-connection related exceptions. Connection related issues use the built-in ConnectionError.

class greenstalk.UnknownResponseError(status, values)

The server sent a response that this client does not understand.

class greenstalk.BeanstalkdError

Base class for error messages returned from the server.

class greenstalk.BadFormatError

The client sent a malformed command.

class greenstalk.BuriedError(values=None)

The server ran out of memory trying to grow the priority queue and had to bury the job.

class greenstalk.DeadlineSoonError

The client has a reserved job timing out within the next second.

class greenstalk.DrainingError

The client tried to insert a job while the server was in drain mode.

class greenstalk.ExpectedCrlfError

The client sent a job body without a trailing CRLF.

class greenstalk.InternalError

The server detected an internal error.

class greenstalk.JobTooBigError

The client attempted to insert a job larger than max-job-size.

class greenstalk.NotFoundError

For the delete, release, bury, and kick commands, it means that the job does not exist or is not reserved by the client.

For the peek commands, it means the requested job does not exist or that there are no jobs in the requested state.

class greenstalk.NotIgnoredError

The client attempted to ignore the only tube on its watch list.

class greenstalk.OutOfMemoryError

The server could not allocate enough memory for a job.

class greenstalk.TimedOutError

A job could not be reserved within the specified timeout.

class greenstalk.UnknownCommandError

The client sent a command that the server does not understand.