pyrelukko.relukko_client module¶

PyRelukko main module with the Relukko client.

class pyrelukko.relukko_client.RelukkoClient(base_url, api_key, **kwargs)¶

Bases: object

RelukkuClient¶

The RelukkoClient class provides a convenient and efficient way to interact with the Relukko API, allowing you to manage locks, acquire and release locks, and perform other operations related to the Relukko backend. The client handles the underlying HTTP requests and responses, providing a simple and intuitive interface for working with the Relukko API.

Kwargs¶

The methods __init__() and reconfigure_relukko() pass through the kwargs to underlying libraries, following a non-exhaustive selection of kwargs which are passed further and understood.

kwarg	Used in	Comments
check_hostname	SSLContext	[1]
hostname_checks_common_name	SSLContext	[1]
verify_mode	SSLContext	[1]
verify_flags	SSLContext	[1]
options	SSLContext	[1]
cafile	SSLContext	[1], [5], [10]
capath	SSLContext	[1], [5], [10]
cadata	SSLContext	[1], [5], [10]
tries	pyrelukko.retry	[2]
delay	pyrelukko.retry	[2]
backoff	pyrelukko.retry	[2]
max_delay	pyrelukko.retry	[2]
exceptions	pyrelukko.retry	[2]
total	urllib3.util.Retry	[3]
connect	urllib3.util.Retry	[3]
read	urllib3.util.Retry	[3]
redirect	urllib3.util.Retry	[3]
status	urllib3.util.Retry	[3]
other	urllib3.util.Retry	[3]
backoff_factor	urllib3.util.Retry	[3]
backoff_max	urllib3.util.Retry	[3]
backoff_jitter	urllib3.util.Retry	[3]
raise_on_redirect	urllib3.util.Retry	[3]
raise_on_status	urllib3.util.Retry	[3]
headers	requests.Session	[4], [7]
cookies	requests.Session	[4]
auth	requests.Session	[4]
proxies	requests.Session	[4], (6]
hooks	requests.Session	[4]
params	requests.Session	[4]
verify	requests.Session	[4], [9], (10]
cert	requests.Session	[4], [9], (10]
adapters	requests.Session	[4], (8]
stream	requests.Session	[4]
trust_env	requests.Session	[4], [6]
max_redirects	requests.Session	[4]
acquire_wait_for_timeout	pyrelukko.relukko_client	.
acquire_modulo	pyrelukko.relukko_client	.
disable_websocket	pyrelukko.relukko_client	.
raise_when_acquire_fails	pyrelukko.relukko_client	[11]
ws_ping_interval	pyrelukko.relukko_client	.
ws_ping_timeout	pyrelukko.relukko_client	.
ws_wait_for_timeout	pyrelukko.relukko_client	.

[1] TLS settings only used for the WebSockets, not for the HTTP requests! See: SSLContext
[2] See: Retry
[3] See: urllib3.util.Retry
[4] See: Request Sessions
[5] Used in: load_verify_locations
[6] Proxies only work for the HTTP requests! But not for the WebSockets used to monitor for deletions! So will probably not work as expected.
[7] This overwrites the header entry set for the API-KEY! Ensure to add it yourself (X-api-Key)!
[8] Interferes with the “Retry” from urllib3!
[9] TLS settings only used for the HTTP requests, not for the WebSockets!
[10] Also takes the environment variables REQUESTS_CA_BUNDLE or CURL_CA_BUNDLE into account! But the arguments take precedence over the environment variables. For HTTP requests use of the variables see SSL Cert Verification The behavior for the WebSockets should be the same.
[11] Do not change! It will break things.

Relukko DTO¶

The Relukko JSON DTO:

{
  "id": "950daa20-a814-451e-9407-ec496cf9c136",
  "lock_name": "eb3a4185-185b-4ac6-a63d-5d1f20e55134",
  "creator": "Demo Creator",
  "ip": "10.89.0.6",
  "expires_at": "2024-10-31T20:14:43.9313Z",
  "created_at": "2024-10-31T20:04:43.9313Z",
  "updated_at": "2024-10-31T20:04:43.9313Z"
}

Skip locking¶

Do the following to acquire the lock by hand and skip the actual locking:

Create the needed lock (or locks) by hand from the Web UI.
Set the expire time far in the future from the Web UI.
Set the environment variable RELUKKO_TRUST_ME_IT_IS_LOCKED to an value, e.g. yes.
Start your coding session with debug runs.
Once you are done, unset the environment variable and delete the lock from the Web UI.

Initializes a new instance of the Relukko API client.

Initializes a new instance of the Relukko API client with the specified base URL and API key. The kwargs parameter can be used to specify additional configuration options for the client.

The kwargs offers additional configuration options for the Relukko API client. See the chapter Kwargs for possible values.

param base_url:: The base URL of the Relukko API.
type base_url:: Union[Url, str]
param api_key:: The API key for the Relukko API.
type api_key:: str

acquire_relukko(lock_name, creator, max_run_time)¶

Acquires a lock in Relukko.

Attempts to acquire a lock with the specified name. If the lock is successfully acquired, the function returns a Relukko DTO object containing information about the lock. If the lock cannot be acquired within the specified max_run_time, the function returns None.

acquire_relukko() is a blocking operation that continuously attempts to obtain the specified lock until it succeeds or the configured timeout is reached. While waiting, it performs periodic retry attempts and, when possible, establishes an optional WebSocket connection to the Relukko backend to receive immediate notifications of lock state changes. If a relevant change occurs — such as any lock being deleted — the function promptly retries acquisition without waiting for the next scheduled attempt. WebSocket usage is best-effort and may be unavailable in certain environments (e.g., when routed through proxies), in which case the function falls back to regular polling.

Parameters:

lock_name (str) – The name of the lock.
creator (Union[str, None]) – Optional name of the lock creator.
max_run_time (int) – How long to maximal try to get the lock in seconds.

Returns:

The DTO of the created/acquired lock. Returns None if acquisition times out.

Return type:

Union[RelukkoDTO, Dict, None, Exception]

add_to_expires_at_time(lock_id)¶

Extends a lock’s expiration time by adding 5 minutes to its current expiration timestamp.

This function provides a mechanism to incrementally extend a lock’s lifetime based on its existing expiration time rather than the current system time. Unlike the keep_alive* methods which reset expiration relative to the current time, this method adds a fixed 5-minute interval directly to the lock’s current expires_at value. This approach is particularly useful when you want to extend a lock’s duration while preserving the original timing relationship, such as when multiple extensions need to accumulate or when coordinating with other time-dependent operations.

Parameters:: lock_id (str) – The unique identifier of the lock to extend.
Returns:: A Relukko DTO object of the updated lock on success, or Dict with status code and error message if lock not found or JSON parsing fails.
Return type:: Union[RelukkoDTO, Dict]

add_to_expires_at_time_put(lock_id, seconds)¶

Extends a lock’s expiration time by adding a custom number of seconds to its current expiration timestamp.

This function provides granular control over cumulative lock lifetime extensions by allowing the caller to specify an exact number of seconds to add to the lock’s existing expires_at value. Unlike keep_alive_put() which sets expiration relative to the current system time (NOW()), this method adds the specified interval directly to the lock’s current expiration timestamp, enabling predictable, accumulating extensions that preserve the original timing relationship.

Parameters:

lock_id (str) – The unique identifier of the lock to extend.
seconds (int) – The number of seconds to add to the lock’s expiration time.

Returns:

A Relukko DTO object of the updated lock on success, or Dict with status code and error message if lock not found or JSON parsing fails.

Return type:

Union[RelukkoDTO, Dict]

delete_relukko(lock_id)¶

Releases a lock by deleting it from Relukko.

This function permanently removes a lock from the Relukko system, releasing the exclusive access to the resource it was protecting. In distributed systems, proper lock deletion is critical to prevent resource starvation and ensure other processes can acquire locks when needed. This method should be called when an operation has completed its work with a protected resource or when explicit lock release is required before the natural expiration time.

Parameters:: lock_id (str) – The unique identifier of the lock to delete.
Returns:: A Relukko DTO object of the deleted lock on success, or Dict with status code and error message if lock not found or JSON parsing fails.
Return type:: Union[RelukkoDTO, Dict]

get_lock(lock_id)¶

Retrieves a single lock from Relukko by ID.

Parameters:: lock_id (str) – The ID of the lock to retrieve.
Returns:: A Relukko DTO object of the retrieved lock on success, or Dict with status code and error message if lock not found.
Return type:: Union[RelukkoDTO, Dict]

get_locks()¶

Retrieves a list of all locks from Relukko.

Returns:: A list of lock objects (Relukko DTO), each representing a single lock on success, or Dict with status code and error message.
Return type:: List[Dict]

keep_relukko_alive(lock_id)¶

Maintains an active lock in Relukko by sending a keep-alive signal.

This function extends the lifetime of an existing lock by 5 minutes from current time. This method prevents the lock from expiring. Use it to signal that the lock holder is still active and requires continued exclusive access to the locked resource.

Parameters:: lock_id (str) – The unique identifier of the lock to keep alive.
Returns:: A Relukko DTO object of the updated lock on success, or Dict with status code and error message if lock not found or JSON parsing fails.
Return type:: Union[RelukkoDTO, Dict]

keep_relukko_alive_put(lock_id, seconds)¶

Extends a lock’s expiration time by a custom number of seconds in Relukko.

This function provides granular control over lock lifetime extension by allowing the caller to specify an exact number of seconds to keep the lock from expiring. Unlike the keep_relukko_alive variant which uses a fixed 5-minute extension, this method enables dynamic lock duration management based on the specific requirements of the holder of the lock. Use it to signal that the lock holder is still active for the next X seconds and requires continued exclusive access to the locked resource.

Parameters:

lock_id (str) – The unique identifier of the lock to extend.
seconds (int) – The number of seconds to add to the lock’s expiration time.

Returns:

A Relukko DTO object of the updated lock on success, or Dict with status code and error message if lock not found or JSON parsing fails.

Return type:

Union[RelukkoDTO, Dict]

reconfigure_relukko(base_url=None, api_key=None, **kwargs)¶

Reconfigures the Relukko API client with new settings.

Reconfigures the Relukko API client with new settings, such as the base URL and API key. The function takes two optional parameters: base_url and api_key, which can be used to update the client’s configuration. If no value is provided for one of these fields, the existing value will be retained.

The kwargs offers additional configuration options for the Relukko API client. See the chapter Kwargs for possible values.

Parameters:

base_url (Union[Url, str], optional) – The new base URL for the Relukko API client (optional).
api_key (str, optional) – The new API key for the Relukko API client (optional).

update_relukko(lock_id, creator=None, expires_at=None)¶

Updates an existing lock in Relukko.

Updates the creator and/or expires_at of an existing lock. If no value is provided for one of these fields, the existing value will be retained.

Parameters:

lock_id (str) – The ID of the lock to update.
creator (str, optional) – The new creator name for the lock, defaults to None.
expires_at (datetime, optional.) – The new expiration date and time for the lock, defaults to None.

Raises:

ValueError – If the provided value for expires_at is not a datetime object.

Returns:

The updated Relukko DTO on success, or Dict with status code and error message if lock not found or JSON parsing fails.

Return type:

Union[RelukkoDTO, Dict]

Parameters:

base_url (Url | str)
api_key (str)

exception pyrelukko.relukko_client.RelukkoDoRetry¶

Bases: Exception

Exception thrown on some errors which we still want to retry