Greenstalk

https://greenstalk.readthedocs.io/en/stable/
Admin
Greenstalk is a Python client library for communicating with the beanstalkd work queue.
Tokens:8,550
Snippets:96
Trust Score:9.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Greenstalk via pip

Source: https://greenstalk.readthedocs.io/en/stable/install.html

Install the Greenstalk Python client library from PyPI using pip.

```bash
pip install greenstalk
```

--------------------------------

### Install beanstalkd on Debian/Ubuntu

Source: https://greenstalk.readthedocs.io/en/stable/install.html

Install the Beanstalkd server on Debian or Ubuntu using apt.

```bash
sudo apt install beanstalkd
```

--------------------------------

### Install beanstalkd on macOS with Homebrew

Source: https://greenstalk.readthedocs.io/en/stable/install.html

Install the Beanstalkd server on macOS using Homebrew.

```bash
brew install beanstalkd
```

--------------------------------

### Consumer: deserialize JSON payload

Source: https://greenstalk.readthedocs.io/en/stable/_sources/overview.rst.txt

Consumer example showing how to reserve a job, deserialize its JSON body, and use the payload.

```python3
job = client.reserve()
payload = json.loads(job.body)
send_registration_email(payload['user_id'])
```

--------------------------------

### Producer: serialize JSON payload

Source: https://greenstalk.readthedocs.io/en/stable/_sources/overview.rst.txt

Producer example showing how to serialize a user registration email payload as JSON and put it into the queue.

```python3
payload = {'user_id': user_id}
body = json.dumps(payload)
client.put(body)
```

--------------------------------

### Client.peek_ready()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Returns the next ready job in the currently used tube.

```APIDOC
## Method: peek_ready()

### Description
Returns the next ready job in the currently used tube.

### Signature
`peek_ready() -> Job[TBody]`
```

--------------------------------

### Create Client with TCP host and port

Source: https://greenstalk.readthedocs.io/en/stable/_sources/overview.rst.txt

Create a Client that connects to the server on the specified host and port.

```pycon3
>>> client = greenstalk.Client(('127.0.0.1', 11300))
```

--------------------------------

### Client.use()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Changes the currently used tube.

```APIDOC
## Method: use()

### Description
Changes the currently used tube.

### Signature
`use(tube: str) -> None`

### Parameters
- **tube** - The tube to use.
```

--------------------------------

### Import greenstalk

Source: https://greenstalk.readthedocs.io/en/stable/_sources/overview.rst.txt

Import the greenstalk library to begin using the client.

```pycon3
>>> import greenstalk
```

--------------------------------

### Create Client with Unix domain socket

Source: https://greenstalk.readthedocs.io/en/stable/_sources/overview.rst.txt

Create a Client that connects to the server via a Unix domain socket path.

```pycon3
>>> client = greenstalk.Client('/var/run/beanstalkd/socket')
```

--------------------------------

### Producer: Insert a job into a queue

Source: https://greenstalk.readthedocs.io/en/stable/index.html

Shows how to create a Greenstalk client and put a job with the body 'hello' into the default tube. The client is used as a context manager to ensure proper connection handling.

```python
import greenstalk

with greenstalk.Client(('127.0.0.1', 11300)) as client:
    client.put('hello')

```

--------------------------------

### using()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Returns the tube currently being used by the client.

```APIDOC
## using()

### Description
Returns the tube currently being used by the client.

### Method
using()

### Returns
str - The tube currently being used by the client.
```

--------------------------------

### Client.kick()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

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.

```APIDOC
## Method: kick()

### Description
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.

### Signature
`kick(bound: int) -> int`

### Parameters
- **bound** - The maximum number of jobs to kick.
```

--------------------------------

### watching()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

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

```APIDOC
## watching()

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

### Method
watching()

### Returns
List[str] - A list of tubes currently being watched by the client.
```

--------------------------------

### Client.peek()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Returns a job by ID.

```APIDOC
## Method: peek()

### Description
Returns a job by ID.

### Signature
`peek(id: int) -> Job[TBody]`

### Parameters
- **id** - The ID of the job to peek.
```

--------------------------------

### Create Greenstalk Client with TCP host and port

Source: https://greenstalk.readthedocs.io/en/stable/overview.html

Creates a Client that immediately connects to the server on the given host and port. The default host/port shown is 127.0.0.1:11300.

```python
>>> client = greenstalk.Client(('127.0.0.1', 11300))

```

--------------------------------

### tubes()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Returns a list of all existing tubes on the server.

```APIDOC
## tubes()

### Description
Returns a list of all existing tubes on the server.

### Method
tubes()

### Returns
List[str] - A list of all existing tubes.
```

--------------------------------

### Consumer: Reserve and delete jobs

Source: https://greenstalk.readthedocs.io/en/stable/index.html

Demonstrates a consumer loop that reserves a job, prints its body, and deletes it. The client is used as a context manager and the loop runs indefinitely until interrupted.

```python
import greenstalk

with greenstalk.Client(('127.0.0.1', 11300)) as client:
    while True:
        job = client.reserve()
        print(job.body)
        client.delete(job)

```

--------------------------------

### Client.watch()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

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

```APIDOC
## Method: watch()

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

### Signature
`watch(tube: str) -> int`

### Parameters
- **tube** - The tube to watch.
```

--------------------------------

### stats()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Returns system statistics from the beanstalkd server.

```APIDOC
## stats()

### Description
Returns system statistics from the beanstalkd server.

### Method
stats()

### Returns
Stats - System statistics.
```

--------------------------------

### Create Greenstalk Client with Unix domain socket path

Source: https://greenstalk.readthedocs.io/en/stable/overview.html

Pass the socket path instead of a host/port tuple when the server listens on a Unix domain socket.

```python
>>> client = greenstalk.Client('/var/run/beanstalkd/socket')

```

--------------------------------

### Client.touch()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Refreshes the TTR of a reserved job.

```APIDOC
## Method: touch()

### Description
Refreshes the TTR of a reserved job.

### Signature
`touch(job: Job[TBody]) -> None`

### Parameters
- **job** - The job to touch.
```

--------------------------------

### Client.stats_tube()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Returns tube statistics.

```APIDOC
## Method: stats_tube()

### Description
Returns tube statistics.

### Signature
`stats_tube(tube: str) -> StatsTube`

### Parameters
- **tube** - The tube to return statistics for.
```

--------------------------------

### Client.kick_job()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Moves a delayed or buried job into the ready queue.

```APIDOC
## Method: kick_job()

### Description
Moves a delayed or buried job into the ready queue.

### Signature
`kick_job(job: Job[TBody] | int) -> None`

### Parameters
- **job** - The job or job ID to kick.
```

--------------------------------

### Client.bury()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Buries a reserved job.

```APIDOC
## Method: bury()

### Description
Buries a reserved job.

### Signature
`bury(job: Job[TBody], priority: int = 65536) -> None`

### Parameters
- **job** - The job to bury.
- **priority** - An integer between 0 and 4,294,967,295 where 0 is the most urgent.
```

--------------------------------

### Client.peek_delayed()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

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

```APIDOC
## Method: peek_delayed()

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

### Signature
`peek_delayed() -> Job[TBody]`
```

--------------------------------

### Client.put()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

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

```APIDOC
## Method: put()

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

### Signature
`put(body: TBody, priority: int = 65536, delay: int = 0, ttr: int = 60) -> int`

### 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.
```

--------------------------------

### Client.reserve()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

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.

```APIDOC
## Method: reserve()

### Description
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.

### Signature
`reserve(timeout: int | None = None) -> Job[TBody]`

### Parameters
- **timeout** - The maximum number of seconds to wait.
```

--------------------------------

### Exceptions

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Custom exceptions raised by the Greenstalk client.

```APIDOC
## Exceptions

### Description
Custom exceptions raised by the Greenstalk client.

### Exceptions
- **Error** - Base error class.
- **BeanstalkdError** - General Beanstalkd error.
- **NotFoundError** - Job or tube not found.
- **TimedOutError** - Operation timed out.
- **DeadlineSoonError** - Deadline soon.
- **NotIgnoredError** - Tube not ignored.
- **BuriedError** - Job was buried. Contains the job ID.
- **DrainingError** - Server is draining.
- **JobTooBigError** - Job body too large.
- **OutOfMemoryError** - Server out of memory.
- **InternalError** - Internal server error.
- **BadFormatError** - Bad request format.
- **ExpectedCrlfError** - Expected CRLF.
- **UnknownCommandError** - Unknown command.
- **UnknownResponseError** - Unknown response. Contains status and values.
```

--------------------------------

### Client.release()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Releases a reserved job.

```APIDOC
## Method: release()

### Description
Releases a reserved job.

### Signature
`release(job: Job[TBody], priority: int = 65536, delay: int = 0) -> None`

### 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.
```

--------------------------------

### Client.stats_job()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Returns job statistics.

```APIDOC
## Method: stats_job()

### Description
Returns job statistics.

### Signature
`stats_job(job: Job[TBody] | int) -> StatsJob`

### Parameters
- **job** - The job or job ID to return statistics for.
```

--------------------------------

### Put a job

Source: https://greenstalk.readthedocs.io/en/stable/_sources/overview.rst.txt

Insert a job using the put method. The job body is the only required argument. The method returns the job ID.

```pycon3
>>> client.put('hello')
1
```

--------------------------------

### Client

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Client for interacting with a Beanstalkd server. Provides methods for putting, reserving, and managing jobs.

```APIDOC
## Client

### Description
Client for interacting with a Beanstalkd server.

### Methods
- **close()** - Close the connection.
- **put()** - Put a job into the queue.
- **use()** - Select the tube to use for putting jobs.
- **reserve()** - Reserve a job from the queue.
- **reserve_job()** - Reserve a specific job by ID.
- **delete()** - Delete a job.
- **release()** - Release a reserved job back to the queue.
- **bury()** - Bury a job.
- **touch()** - Touch a reserved job to prevent it from timing out.
- **watch()** - Watch a tube for jobs.
- **ignore()** - Ignore a tube.
- **peek()** - Peek at a job by ID.
- **peek_ready()** - Peek at the next ready job.
- **peek_delayed()** - Peek at the next delayed job.
- **peek_buried()** - Peek at the next buried job.
- **kick()** - Kick jobs back into the ready queue.
- **kick_job()** - Kick a specific job.
- **stats_job()** - Get statistics for a job.
- **stats_tube()** - Get statistics for a tube.
- **stats()** - Get overall statistics.
- **tubes()** - List all tubes.
- **using()** - Get the tube currently being used.
- **watching()** - Get the list of tubes being watched.
- **pause_tube()** - Pause a tube.
```

--------------------------------

### greenstalk.Job

Source: https://greenstalk.readthedocs.io/en/stable/api.html

A job returned from the server. Contains an id and a body.

```APIDOC
## Class: greenstalk.Job

### Description
A job returned from the server.

### Constructor
`greenstalk.Job(_id: int, _body: TBody)`

### Attributes
- **id** (int) - A server-generated unique identifier assigned to the job on creation.
- **body** (TBody) - 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.ignore()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

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

```APIDOC
## Method: ignore()

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

### Signature
`ignore(tube: str) -> int`

### Parameters
- **tube** - The tube to ignore.
```

--------------------------------

### Reserve a job

Source: https://greenstalk.readthedocs.io/en/stable/_sources/overview.rst.txt

Consume a job using the reserve method. It blocks until a job is reserved unless a timeout is given. The reserved job exposes its id and body.

```pycon3
>>> job = client.reserve()
>>> job.id
1
>>> job.body
'hello'
```

--------------------------------

### Client.delete()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Deletes a job.

```APIDOC
## Method: delete()

### Description
Deletes a job.

### Signature
`delete(job: Job[TBody] | int) -> None`

### Parameters
- **job** - The job or job ID to delete.
```

--------------------------------

### Job

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Represents a job in the Beanstalkd queue. Contains the job ID and body.

```APIDOC
## Job

### Description
Represents a job in the Beanstalkd queue.

### Attributes
- **id** - The job ID.
- **body** - The job body.
```

--------------------------------

### greenstalk.Client

Source: https://greenstalk.readthedocs.io/en/stable/_sources/api.rst.txt

The main client class for interacting with a beanstalkd server. All operations for putting, reserving, and managing jobs are performed through this class.

```APIDOC
## Class: greenstalk.Client

### Description
The client class for connecting to and interacting with a beanstalkd server.

### Methods
Refer to the source documentation for the full list of members.
```

--------------------------------

### greenstalk.Job

Source: https://greenstalk.readthedocs.io/en/stable/_sources/api.rst.txt

Represents a job in the beanstalkd queue. The class is documented with autoclass and its members are included.

```APIDOC
## Class: greenstalk.Job

### Description
Represents a job in the beanstalkd work queue.

### Methods
Refer to the source documentation for the full list of members.
```

--------------------------------

### Client.reserve_job()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

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.

```APIDOC
## Method: reserve_job()

### Description
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.

### Signature
`reserve_job(id: int) -> Job[TBody]`

### Parameters
- **id** - The ID of the job to reserve.
```

--------------------------------

### Client.peek_buried()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

Returns the oldest buried job in the currently used tube.

```APIDOC
## Method: peek_buried()

### Description
Returns the oldest buried job in the currently used tube.

### Signature
`peek_buried() -> Job[TBody]`
```

--------------------------------

### Delete a job

Source: https://greenstalk.readthedocs.io/en/stable/_sources/overview.rst.txt

Tell the server that the job has been successfully completed using the delete method.

```pycon3
>>> client.delete(job)
```

--------------------------------

### greenstalk Exceptions

Source: https://greenstalk.readthedocs.io/en/stable/_sources/api.rst.txt

All error classes that can be raised by the greenstalk library. These correspond to the errors that beanstalkd can return.

```APIDOC
## Exceptions

### greenstalk.Error
Base class for all greenstalk errors.

### greenstalk.BeanstalkdError
Error returned by the beanstalkd server.

### greenstalk.NotFoundError
Raised when a job or tube is not found.

### greenstalk.TimedOutError
Raised when a reserve operation times out.

### greenstalk.DeadlineSoonError
Raised when a job's deadline is soon.

### greenstalk.NotIgnoredError
Raised when a job could not be ignored.

### greenstalk.BuriedError
Raised when a job is buried.

### greenstalk.DrainingError
Raised when the server is draining.

### greenstalk.JobTooBigError
Raised when a job is too big.

### greenstalk.OutOfMemoryError
Raised when the server is out of memory.

### greenstalk.InternalError
Raised on an internal server error.

### greenstalk.BadFormatError
Raised when the request format is bad.

### greenstalk.ExpectedCrlfError
Raised when a CRLF is expected.

### greenstalk.UnknownCommandError
Raised when an unknown command is sent.

### greenstalk.UnknownResponseError
Raised when an unknown response is received.
```

--------------------------------

### pause_tube(tube: str, delay: int)

Source: https://greenstalk.readthedocs.io/en/stable/api.html

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

```APIDOC
## pause_tube(tube: str, delay: int)

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

### Method
pause_tube(tube: str, delay: int)

### Parameters
- **tube** (str) - Required - The tube to pause.
- **delay** (int) - Required - The number of seconds to pause the tube for.

### Returns
None
```

--------------------------------

### Client.close()

Source: https://greenstalk.readthedocs.io/en/stable/api.html

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

```APIDOC
## Method: close()

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

### Signature
`close() -> None`
```
Tokens:
Raw