Reference

door.doors module

door.doors defines the doors.

class door.doors.AcquirableDoor(_resource_or_handle: _T | Handle[_T], _primitive: Acquirable)

Bases: Door[_T]

The class for acquirable doors.

This class is designed to be used for threading and multiprocessing.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

>>> @dataclass
... class Resource:
...     key: str = 'value'
...
>>> resource = Resource()
>>> resource
Resource(key='value')
>>> resource.key
'value'

>>> from door.threading2 import AcquirableDoor
>>> door = AcquirableDoor(resource)
>>> with door() as proxy:
...     proxy.key
...     proxy.key = 'VALUE'
...     proxy.key
...
'value'
'VALUE'

>>> proxy.key
Traceback (most recent call last):
    ...
ValueError: no read permission
>>> proxy.key = 'value'
Traceback (most recent call last):
    ...
ValueError: no write permission

>>> resource
Resource(key='VALUE')
>>> resource.key
'VALUE'
class door.doors.AsyncAcquirableDoor(_resource_or_handle: _T | Handle[_T], _primitive: Acquirable)

Bases: Door[_T]

The class for asynchronous acquirable doors.

This class is designed to be used for asynchronous prgramming.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

class door.doors.AsyncSAcquirableDoor(_resource_or_handle: _T | Handle[_T], _primitive: SAcquirable)

Bases: Door[_T]

The class for asynchronous shared acquirable doors.

This class is designed to be used for asynchronous prgramming.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

read() → AsyncIterator[_T]

Return the asynchronous context manager for the resource in read mode.

After the resource is released, the resource becomes inaccessible.

Returns:

The context manager for the resource.

write() → AsyncIterator[_T]

Return the asynchronous context manager for the resource in write (and read) mode.

After the resource is released, the resource becomes inaccessible.

Returns:

The context manager for the resource.

class door.doors.AsyncSWaitableDoor(_resource_or_handle: _T | Handle[_T], _primitive: SWaitable)

Bases: AsyncSAcquirableDoor[_T]

The class for asynchronous shared waitable doors.

This class is designed to be used for asynchronous prgramming.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

async notify_all_read() → None

Notify all for reading.

Returns:

None.

async notify_all_write() → None

Notify all for writing.

Returns:

None.

async notify_read() → None

Notify one for reading.

Returns:

None.

async notify_write() → None

Notify one for writing.

Returns:

None.

async wait_read() → None

Wait for reading.

Returns:

None.

async wait_write() → None

Wait for writing.

Returns:

None.

class door.doors.AsyncWaitableDoor(_resource_or_handle: _T | Handle[_T], _primitive: Waitable)

Bases: AsyncAcquirableDoor[_T]

The class for asynchronous waitable doors.

This class is designed to be used for asynchronous prgramming.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

async notify() → None

Notify one.

Returns:

None.

async notify_all() → None

Notify all.

Returns:

None.

async wait() → None

Wait.

Returns:

None.

class door.doors.Door(_resource_or_handle: _T | Handle[_T])

Bases: Generic[_T], ABC

The abstract base class for doors.

This class is designed to be used for threading, asynchronous programming, and multiprocessing.

class door.doors.HandledDoor(_resource_or_handle: _T | Handle[_T])

Bases: Door[_T], ABC

The abstract base class for handled doors.

This class is designed to be used for multiprocessing.

class door.doors.SAcquirableDoor(_resource_or_handle: _T | Handle[_T], _primitive: SAcquirable)

Bases: Door[_T]

The class for shared acquirable doors.

This class is designed to be used for threading and multiprocessing.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

>>> @dataclass
... class Resource:
...     key: str = 'value'
...
>>> resource = Resource()
>>> resource
Resource(key='value')
>>> resource.key
'value'

>>> from door.threading2 import SAcquirableDoor
>>> door = SAcquirableDoor(resource)
>>> with door.read() as proxy:
...     proxy.key
...
'value'

>>> with door.read() as proxy:
...     proxy.key = 'VALUE'
...
Traceback (most recent call last):
    ...
ValueError: no write permission

>>> with door.write() as proxy:
...     proxy.key
...     proxy.key = 'VALUE'
...     proxy.key
...
'value'
'VALUE'

>>> proxy.key
Traceback (most recent call last):
    ...
ValueError: no read permission
>>> proxy.key = 'value'
Traceback (most recent call last):
    ...
ValueError: no write permission

>>> resource
Resource(key='VALUE')
>>> resource.key
'VALUE'
read() → Iterator[_T]

Return the context manager for the resource in read mode.

After the resource is released, the resource becomes inaccessible.

Returns:

The context manager for the resource.

write() → Iterator[_T]

Return the context manager for the resource in write (and read) mode.

After the resource is released, the resource becomes inaccessible.

Returns:

The context manager for the resource.

class door.doors.SWaitableDoor(_resource_or_handle: _T | Handle[_T], _primitive: SWaitable)

Bases: SAcquirableDoor[_T]

The class for shared waitable doors.

This class is designed to be used for threading and multiprocessing.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

notify_all_read() → None

Notify all for reading.

Returns:

None.

notify_all_write() → None

Notify all for writing.

Returns:

None.

notify_read() → None

Notify one for reading.

Returns:

None.

notify_write() → None

Notify one for writing.

Returns:

None.

wait_read() → None

Wait for reading.

Returns:

None.

wait_write() → None

Wait for writing.

Returns:

None.

class door.doors.UnhandledDoor(_resource_or_handle: _T | Handle[_T])

Bases: Door[_T], ABC

The abstract base class for unhandled doors.

This class is designed to be used for threading and asynchronous prgramming.

class door.doors.WaitableDoor(_resource_or_handle: _T | Handle[_T], _primitive: Waitable)

Bases: AcquirableDoor[_T]

The class for waitable doors.

This class is designed to be used for threading and multiprocessing.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

notify() → None

Notify one.

Returns:

None.

notify_all() → None

Notify all.

Returns:

None.

wait() → None

Wait.

Returns:

None.

door.primitives module

door.primitives defines the primitives.

class door.primitives.Acquirable(*args, **kwargs)

Bases: Protocol

A protocol for acquirable primitives.

acquire() → Any

Acquire the primitive.

release() → Any

Release the primitive.

class door.primitives.AsyncRSLock(_r: Acquirable, _g: Acquirable)

Bases: object

The class for asynchronous read-preferring shared locks.

This class is designed to be used for asynchronous prgramming.

The implementations in this library is read-preferring and follow the pseudocode in Concurrent Programming: Algorithms, Principles, and Foundations by Michel Raynal.

async acquire_read() → None
async acquire_write() → None
async release_read() → None
async release_write() → None
class door.primitives.AsyncSCondition(_s: SAcquirable, _a: Waitable)

Bases: object

The class for asynchronous shared condition variables.

This class is designed to be used for asynchronous prgramming.

async acquire_read() → None
async acquire_write() → None
async notify_all_read() → None
async notify_all_write() → None
async notify_read() → None
async notify_write() → None
async release_read() → None
async release_write() → None
async wait_read() → None
async wait_write() → None
class door.primitives.AsyncWSLock(_g: Waitable)

Bases: object

The class for asynchronous write-preferring shared locks.

This class is designed to be used for asynchronous prgramming.

async acquire_read() → None
async acquire_write() → None
async release_read() → None
async release_write() → None
class door.primitives.RSLock(_r: Acquirable, _g: Acquirable)

Bases: object

The class for read-preferring shared locks.

This class is designed to be used for threading and multiprocessing.

The implementations in this library is read-preferring and follow the pseudocode in Concurrent Programming: Algorithms, Principles, and Foundations by Michel Raynal.

acquire_read() → None
acquire_write() → None
release_read() → None
release_write() → None
class door.primitives.SAcquirable(*args, **kwargs)

Bases: Protocol

A protocol for shared acquiarables.

acquire_read() → Any

Acquire the primitive for reading.

acquire_write() → Any

Acquire the primitive for writing (and reading).

release_read() → Any

Release the primitive for reading.

release_write() → Any

Release the primitive for writing (and reading).

class door.primitives.SCondition(_s: SAcquirable, _a: Waitable)

Bases: object

The class for shared condition variables.

This class is designed to be used for threading and multiprocessing.

acquire_read() → None
acquire_write() → None
notify_all_read() → None
notify_all_write() → None
notify_read() → None
notify_write() → None
release_read() → None
release_write() → None
wait_read() → None
wait_write() → None
class door.primitives.SWaitable(*args, **kwargs)

Bases: SAcquirable, Protocol

A protocol for shared waitable primitives.

notify_all_read() → Any

Notify all for reading.

notify_all_write() → Any

Notify all for writing.

notify_read() → Any

Notify one for reading.

notify_write() → Any

Notify one for writing.

wait_read() → Any

Wait for reading.

wait_write() → Any

Wait for writing.

class door.primitives.WSLock(_g: Waitable)

Bases: object

The class for write-preferring shared locks.

This class is designed to be used for threading and multiprocessing.

acquire_read() → None
acquire_write() → None
release_read() → None
release_write() → None
class door.primitives.Waitable(*args, **kwargs)

Bases: Acquirable, Protocol

A protocol for waitable primitives.

notify() → Any

Notify one.

notify_all() → Any

Notify all.

wait() → Any

Wait.

door.asyncio2 module

door.asyncio2 defines utilities for asynchronous programming.

class door.asyncio2.AcquirableDoor(_resource_or_handle: ~door.doors._T | ~door.utilities.Handle[~door.doors._T], _primitive: ~door.primitives.Acquirable = <factory>)

Bases: UnhandledDoor[_T], AsyncAcquirableDoor[_T]

The class for asynchronous acquirable doors.

This class is designed to be used for asynchronous programming.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

class door.asyncio2.RSCondition(_s: ~door.primitives.SAcquirable = <factory>, _a: ~door.primitives.Waitable = <factory>)

Bases: AsyncSCondition

The class for asynchronous read-preferring shared condition variables.

This class is designed to be used for asynchronous programming.

class door.asyncio2.RSLock(_r: ~door.primitives.Acquirable = <factory>, _g: ~door.primitives.Acquirable = <factory>)

Bases: AsyncRSLock

The class for asynchronous read-preferring shared locks.

This class is designed to be used for asynchronous programming.

The implementations in this library is read-preferring and follow the pseudocode in Concurrent Programming: Algorithms, Principles, and Foundations by Michel Raynal.

class door.asyncio2.SAcquirableDoor(_resource_or_handle: ~door.doors._T | ~door.utilities.Handle[~door.doors._T], _primitive: ~door.primitives.SAcquirable = <factory>)

Bases: UnhandledDoor[_T], AsyncSAcquirableDoor[_T]

The class for asynchronous shared acquirable doors.

This class is designed to be used for asynchronous programming.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

class door.asyncio2.SWaitableDoor(_resource_or_handle: ~door.doors._T | ~door.utilities.Handle[~door.doors._T], _primitive: ~door.primitives.SWaitable = <factory>)

Bases: UnhandledDoor[_T], AsyncSWaitableDoor[_T]

The class for asynchronous shared waitable doors.

This class is designed to be used for asynchronous programming.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

class door.asyncio2.WSCondition(_s: ~door.primitives.SAcquirable = <factory>, _a: ~door.primitives.Waitable = <factory>)

Bases: AsyncSCondition

The class for asynchronous write-preferring shared condition variables.

This class is designed to be used for asynchronous programming.

class door.asyncio2.WSLock(_g: ~door.primitives.Waitable = <factory>)

Bases: AsyncWSLock

The class for asynchronous write-preferring shared locks.

This class is designed to be used for asynchronous programming.

class door.asyncio2.WaitableDoor(_resource_or_handle: ~door.doors._T | ~door.utilities.Handle[~door.doors._T], _primitive: ~door.primitives.Waitable = <factory>)

Bases: UnhandledDoor[_T], AsyncWaitableDoor[_T]

The class for asynchronous waitable doors.

This class is designed to be used for asynchronous programming.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

door.multiprocessing2 module

door.multiprocessing2 defines utilities for multiprocessing.

class door.multiprocessing2.AcquirableDoor(_resource_or_handle: ~door.doors._T | ~door.utilities.Handle[~door.doors._T], _primitive: ~door.primitives.Acquirable = <factory>)

Bases: HandledDoor[_T], AcquirableDoor[_T]

The class for acquirable doors.

This class is designed to be used for multiprocessing.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

class door.multiprocessing2.RSCondition(_s: ~door.primitives.SAcquirable = <factory>, _a: ~door.primitives.Waitable = <factory>)

Bases: SCondition

The class for read-preferring shared condition variables.

This class is designed to be used for multiprocessing.

class door.multiprocessing2.RSLock(_r: ~door.primitives.Acquirable = <factory>, _g: ~door.primitives.Acquirable = <factory>)

Bases: RSLock

The class for read-preferring shared locks.

This class is designed to be used for multiprocessing.

The implementations in this library is read-preferring and follow the pseudocode in Concurrent Programming: Algorithms, Principles, and Foundations by Michel Raynal.

class door.multiprocessing2.SAcquirableDoor(_resource_or_handle: ~door.doors._T | ~door.utilities.Handle[~door.doors._T], _primitive: ~door.primitives.SAcquirable = <factory>)

Bases: HandledDoor[_T], SAcquirableDoor[_T]

The class for shared acquirable doors.

This class is designed to be used for multiprocessing.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

class door.multiprocessing2.SWaitableDoor(_resource_or_handle: ~door.doors._T | ~door.utilities.Handle[~door.doors._T], _primitive: ~door.primitives.SWaitable = <factory>)

Bases: HandledDoor[_T], SWaitableDoor[_T]

The class for shared waitable doors.

This class is designed to be used for multiprocessing.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

class door.multiprocessing2.WSCondition(_s: ~door.primitives.SAcquirable = <factory>, _a: ~door.primitives.Waitable = <factory>)

Bases: SCondition

The class for write-preferring shared condition variables.

This class is designed to be used for multiprocessing.

class door.multiprocessing2.WSLock(_g: ~door.primitives.Waitable = <factory>)

Bases: WSLock

The class for write-preferring shared locks.

This class is designed to be used for multiprocessing.

class door.multiprocessing2.WaitableDoor(_resource_or_handle: ~door.doors._T | ~door.utilities.Handle[~door.doors._T], _primitive: ~door.primitives.Waitable = <factory>)

Bases: HandledDoor[_T], WaitableDoor[_T]

The class for waitable doors.

This class is designed to be used for multiprocessing.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

door.threading2 module

door.threading2 defines utilities for threading.

class door.threading2.AcquirableDoor(_resource_or_handle: ~door.doors._T | ~door.utilities.Handle[~door.doors._T], _primitive: ~door.primitives.Acquirable = <factory>)

Bases: UnhandledDoor[_T], AcquirableDoor[_T]

The class for acquirable doors.

This class is designed to be used for threading.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

class door.threading2.RSCondition(_s: ~door.primitives.SAcquirable = <factory>, _a: ~door.primitives.Waitable = <factory>)

Bases: SCondition

The class for read-preferring shared condition variables.

This class is designed to be used for threading.

class door.threading2.RSLock(_r: ~door.primitives.Acquirable = <factory>, _g: ~door.primitives.Acquirable = <factory>)

Bases: RSLock

The class for read-preferring shared locks.

This class is designed to be used for threading.

The implementations in this library is read-preferring and follow the pseudocode in Concurrent Programming: Algorithms, Principles, and Foundations by Michel Raynal.

class door.threading2.SAcquirableDoor(_resource_or_handle: ~door.doors._T | ~door.utilities.Handle[~door.doors._T], _primitive: ~door.primitives.SAcquirable = <factory>)

Bases: UnhandledDoor[_T], SAcquirableDoor[_T]

The class for shared acquirable doors.

This class is designed to be used for threading.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

class door.threading2.SWaitableDoor(_resource_or_handle: ~door.doors._T | ~door.utilities.Handle[~door.doors._T], _primitive: ~door.primitives.SWaitable = <factory>)

Bases: UnhandledDoor[_T], SWaitableDoor[_T]

The class for shared waitable doors.

This class is designed to be used for threading.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

class door.threading2.WSCondition(_s: ~door.primitives.SAcquirable = <factory>, _a: ~door.primitives.Waitable = <factory>)

Bases: SCondition

The class for write-preferring shared condition variables.

This class is designed to be used for threading.

class door.threading2.WSLock(_g: ~door.primitives.Waitable = <factory>)

Bases: WSLock

The class for write-preferring shared locks.

This class is designed to be used for threading.

class door.threading2.WaitableDoor(_resource_or_handle: ~door.doors._T | ~door.utilities.Handle[~door.doors._T], _primitive: ~door.primitives.Waitable = <factory>)

Bases: UnhandledDoor[_T], WaitableDoor[_T]

The class for waitable doors.

This class is designed to be used for threading.

The door is initialized with the resource and corresponding primitive.

The door can give access to the resource based on the desired operation. When the user attempts to access the resource in a forbidden way or after its access is expired, an exception will be raised.

door.utilities module

door.utilities defines the utilities.

class door.utilities.Counter(*args, **kwargs)

Bases: Protocol

The protocol for counters.

decrement() → None

Decrement.

Returns:

None.

increment() → None

Increment.

Returns:

None.

class door.utilities.Handle(resource: dataclasses.InitVar[_T])

Bases: Generic[_T]

The class for handles.

All handles should be unlinked when no longer used by calling Handle.unlink() only once across all processes.

>>> handle = Handle([1, 2, 3])
>>> handle.get()
[1, 2, 3]
>>> handle.set(3)
>>> handle.get()
3
>>> handle.unlink()
NAME_MAX: ClassVar[int] = 255

The maximum size of the name.

get() → _T

Get the shared resource.

Returns:

The shared resource.

resource: dataclasses.InitVar[_T]

The shared resource.

set(value: _T) → None

Set the shared resource.

Parameters:

value – The new value.

Returns:

None.

Unlink the shared resource.

This must be called only once across all processes.

Returns:

None.

class door.utilities.IntCounter

Bases: Counter

The class for int counters.

This class is designed to be used for asynchronous programming.

decrement() → None

Decrement.

Returns:

None.

increment() → None

Increment.

Returns:

None.

class door.utilities.Proxy(resource_or_handle: dataclasses.InitVar[Union[_T, door.utilities.Handle[_T]]], _Proxy__mode: Mode)

Bases: Generic[_T]

The class for resource proxies.

>>> @dataclass
... class Resource:
...     key: Any = 'value'
...
>>> resource = Resource()
>>> resource
Resource(key='value')
>>> resource.key
'value'

>>> proxy = Proxy(resource, Proxy.Mode.READ)
>>> proxy.key
'value'
>>> proxy.key = 'VALUE'
Traceback (most recent call last):
    ...
ValueError: no write permission
>>> proxy.close()

>>> proxy = Proxy(resource, Proxy.Mode.WRITE)
>>> proxy.key = 'VALUE'
>>> proxy.key
Traceback (most recent call last):
    ...
ValueError: no read permission
>>> proxy.close()

>>> proxy = Proxy(resource, Proxy.Mode.READ | Proxy.Mode.WRITE)
>>> proxy.key
'VALUE'
>>> proxy.key = 'value'
>>> proxy.key
'value'
>>> proxy.close()

>>> proxy.key
Traceback (most recent call last):
    ...
ValueError: no read permission
>>> proxy.key = 'VALUE'
Traceback (most recent call last):
    ...
ValueError: no write permission

>>> resource
Resource(key='value')
>>> resource.key
'value'
class Mode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Flag

The flag for modes.

READ = 1
WRITE = 2
close() → None

Close.

Returns:

None.

open() → None

Close.

Returns:

None.

resource_or_handle: dataclasses.InitVar[Union[_T, door.utilities.Handle[_T]]]

The resource or handle.

class door.utilities.ValueCounter

Bases: Counter

The class for Value counters.

This class is designed to be used for multiprocessing.

decrement() → None

Decrement.

Returns:

None.

increment() → None

Increment.

Returns:

None.

async door.utilities.await_if_awaitable(awaitable: Any) → None

Await if awaitable.

Returns:

None.