API Reference¶

Job¶

class greenstalk.Job(id: int, body: Union[bytes, str])¶

A job returned from the server.

id = None¶: A server-generated unique identifier assigned to the job on creation.

body = None¶: The content of the job. Also referred to as the message or payload. Producers and consumers need to agree on how these bytes are interpreted.

Client¶

class greenstalk.Client(address: Union[Tuple[str, int], str], encoding: Optional[str] = 'utf-8', use: str = 'default', watch: Union[str, Iterable[str]] = 'default')¶

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

Parameters:	address – A socket address pair (host, port) or a Unix domain socket path. encoding – The encoding used to encode and decode job bodies. use – The tube to use after connecting. watch – The tubes to watch after connecting. The `default` tube will be ignored if it’s not included.

close() → None¶: Closes the connection to beanstalkd. The client instance should not be used after calling this method.

put(body: Union[bytes, str], priority: int = 65536, delay: int = 0, ttr: int = 60) → int¶

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

Parameters:	body – The data representing the job. priority – An integer between 0 and 4,294,967,295 where 0 is the most urgent. delay – The number of seconds to delay the job for. ttr – The maximum number of seconds the job can be reserved for before timing out.

use(tube: str) → None¶

Changes the currently used tube.

Parameters:	tube – The tube to use.

reserve(timeout: Optional[int] = None) → greenstalk.Job¶

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 – The maximum number of seconds to wait.

reserve_job(id: int) → greenstalk.Job¶

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 – The ID of the job to reserve.

delete(job: Union[greenstalk.Job, int]) → None¶

Deletes a job.

Parameters:	job – The job or job ID to delete.

release(job: greenstalk.Job, priority: int = 65536, delay: int = 0) → None¶

Releases a reserved job.

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

bury(job: greenstalk.Job, priority: int = 65536) → None¶

Buries a reserved job.

Parameters:	job – The job to bury. priority – An integer between 0 and 4,294,967,295 where 0 is the most urgent.

touch(job: greenstalk.Job) → None¶

Refreshes the TTR of a reserved job.

Parameters:	job – The job to touch.

watch(tube: str) → int¶

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

Parameters:	tube – The tube to watch.

ignore(tube: str) → int¶

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

Parameters:	tube – The tube to ignore.

peek(id: int) → greenstalk.Job¶

Returns a job by ID.

Parameters:	id – The ID of the job to peek.

peek_ready() → greenstalk.Job¶: Returns the next ready job in the currently used tube.

peek_delayed() → greenstalk.Job¶: Returns the next available delayed job in the currently used tube.

peek_buried() → greenstalk.Job¶: Returns the oldest buried job in the currently used tube.

kick(bound: int) → int¶

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 – The maximum number of jobs to kick.

kick_job(job: Union[greenstalk.Job, int]) → None¶

Moves a delayed or buried job into the ready queue.

Parameters:	job – The job or job ID to kick.

stats_job(job: Union[greenstalk.Job, int]) → Dict[str, Union[str, int]]¶

Returns job statistics.

Parameters:	job – The job or job ID to return statistics for.

stats_tube(tube: str) → Dict[str, Union[str, int]]¶

Returns tube statistics.

Parameters:	tube – The tube to return statistics for.

stats() → Dict[str, Union[str, int]]¶: Returns system statistics.

tubes() → List[str]¶: Returns a list of all existing tubes.

using() → str¶: Returns the tube currently being used by the client.

watching() → List[str]¶: Returns a list of tubes currently being watched by the client.

pause_tube(tube: str, delay: int) → None¶

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

Parameters:	tube – The tube to pause. delay – The number of seconds to pause the tube for.

Exceptions¶

For completeness all errors that beanstalkd can return are listed here. BadFormatError and ExpectedCrlfError should be unreachable unless there’s a bug in this library.

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

class greenstalk.BeanstalkdError¶: Base class for error messages returned from the server.

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.TimedOutError¶: A job could not be reserved within the specified timeout.

class greenstalk.DeadlineSoonError¶: The client has a reserved job timing out within the next second.

class greenstalk.NotIgnoredError¶: The client attempted to ignore the only tube on its watch list.

class greenstalk.BuriedError(values: Optional[List[bytes]] = None)¶

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

This can be raised in response to a put or release command.

id = None¶: A server-generated unique identifier that was assigned to the buried job.

class greenstalk.DrainingError¶: The client tried to insert a job while the server was in drain mode.

class greenstalk.JobTooBigError¶: The client attempted to insert a job larger than max-job-size.

class greenstalk.OutOfMemoryError¶: The server could not allocate enough memory for a job.

class greenstalk.InternalError¶: The server detected an internal error.

class greenstalk.BadFormatError¶: The client sent a malformed command.

class greenstalk.ExpectedCrlfError¶: The client sent a job body without a trailing CRLF.

class greenstalk.UnknownCommandError¶: The client sent a command that the server does not understand.

class greenstalk.UnknownResponseError(status: bytes, values: List[bytes])¶

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

status = None¶: The status code of the response. Contains b'SOME_ERROR' for the response b'SOME_ERROR 1 2 3\r\n'.

values = None¶: The remaining split values after the status code. Contains [b'1', b'2', b'3'] for the response b'SOME_ERROR 1 2 3\r\n'.