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.