Lockable Resources

jenkinsapi.lockable_resources.HTTP_STATUS_CODE_LOCKED = 423

Specific HTTP status code returned by API when resource is locked

class jenkinsapi.lockable_resources.LockableResource(parent: LockableResources, name: str)

Bases: object

Object representation of a lockable resource

property data: LockableResourceDict

is_free() → bool

Check if the resource is free for reservation

This is what the java plugin implementation checks internally

is_reserved() → bool

reserve() → None

unreserve() → None

class jenkinsapi.lockable_resources.LockableResourceDict

Bases: TypedDict

Dictionary representation of a lockable resource

This is exactly as returned by Jenkins API

buildName: str | None

description: str

ephemeral: bool

free: bool

labels: str

labelsAsList: List[str]

lockCause: str | None

locked: bool

name: str

note: str

properties: List[LockableResourcePropertyDict]

reserved: bool

reservedBy: str | None

reservedByEmail: str | None

reservedTimestamp: int | None

stolen: bool

class jenkinsapi.lockable_resources.LockableResourcePropertyDict

Bases: TypedDict

Property of a lockable resource, as returned by Jenkins API

name: str

value: str

class jenkinsapi.lockable_resources.LockableResources(jenkins_obj: Jenkins, poll=True, poll_after_post: bool = True)

Bases: JenkinsBase, Mapping[str, LockableResource]

Object representation of the lockable resource jenkins API

property data_dict: Dict[str, LockableResourceDict]

API data as a dict mapping name to LockableResourceDict

property data_list: List[LockableResourceDict]

API data as a list of LockableResourceDict

get_jenkins_obj() → Jenkins

is_free(name: str) → bool

is_reserved(name: str) → bool

jenkins: Jenkins

poll(tree=None) → None

poll_after_post: bool

If true then poll again after every successful post request

This ensure that resource properties are up-to-date after any changes. Setting this to False would require manual poll() calls but could be more efficient in advanced scenarios with careful usage.

reservation_by_label(label: str, retry: RetryConfig = SimpleRetryConfig(sleep_period=5, timeout=3600)) → LockedResourceReservation

reservation_by_name(name: str, retry: RetryConfig = SimpleRetryConfig(sleep_period=5, timeout=3600)) → LockedResourceReservation

reservation_by_name_list(name_list: List[str], retry: RetryConfig = SimpleRetryConfig(sleep_period=5, timeout=3600)) → LockedResourceReservation

reserve(name: str) → None

try_reserve(selector: ResourceSelector) → str | None

Try to reserve a resource that matches the given condition

Returns:

the name of the reserved resource on success

Returns:

None if all resources are busy

unreserve(name: str) → None

wait_reserve(selector: ResourceSelector, retry: RetryConfig = SimpleRetryConfig(sleep_period=5, timeout=3600)) → str

Wait for a resource that matches the given condition to become available

Returns:

the name of the reserved resource on success

Raises:

ResourceReservationTimeoutError – if no matching resources are found during the timeout period.

class jenkinsapi.lockable_resources.LockedResourceReservation(api: LockableResources, selector: ResourceSelector, retry: RetryConfig = SimpleRetryConfig(sleep_period=5, timeout=3600))

Bases: object

Context manager for locking a Jenkins resource

Creating this object does not lock the resource, it is only locked and unlocked on __enter__() and __exit__() methods.

Example:

reservation: LockedResourceReservation = init_reservation()
# .. possibly much later ...
print("Resource will be locked ...")
with reservation as locked_resource:
    name = locked_resource.locked_resource_name
    print(f"Resource currently locked: {name}")
print("Resource no longer locked")

If resources are busy this will retry until it will eventually succeed or time out.

Raises:

ResourceReservationTimeoutError – if reservation process times out

is_active() → bool

Check if the resource is currently locked

property locked_resource_name: str

Return the name of the locked resource

This throws an error if the resource is not currently locked.

retry: RetryConfig

class jenkinsapi.lockable_resources.ResourceLabelSelector(label: str)

Bases: ResourceSelector

Implementation of ResourceSelector that selects any resources with a given jenkins label

select(lockable_resources: LockableResources) → Iterator[str]

Iterate acceptable resource names

exception jenkinsapi.lockable_resources.ResourceLockedError

Bases: JenkinsAPIException

Raised when a resource is locked and cannot be reserved

class jenkinsapi.lockable_resources.ResourceNameListSelector(name_list: List[str])

Bases: ResourceSelector

Implementation of ResourceSelector that selects from a list of resources

select(lockable_resources: LockableResources) → Iterator[str]

Iterate acceptable resource names

class jenkinsapi.lockable_resources.ResourceNameSelector(name: str)

Bases: ResourceSelector

Implementation of ResourceSelector that selects a single resource by name

select(lockable_resources: LockableResources) → Iterator[str]

Iterate acceptable resource names

exception jenkinsapi.lockable_resources.ResourceReservationTimeoutError

Bases: JenkinsAPIException, TimeoutError

Raised when resource reservation times out

class jenkinsapi.lockable_resources.ResourceSelector

Bases: ABC

Base class for which iterates acceptable resources for a reservation

abstract select(lockable_resources: LockableResources) → Iterator[str]

Iterate acceptable resource names