portalocker.types module

Shared type aliases and protocols used across portalocker’s public API.

These are pure typing constructs with no runtime behaviour of their own; they exist so the locking functions in portalocker.portalocker and portalocker.utils can share consistent, precise signatures.

portalocker.types.FileArgument

an already-open file object, anything exposing a fileno() method, or a bare file descriptor (int). The int case exists because fcntl.flock/msvcrt.locking() operate on raw file descriptors, which callers may already have without an open file object wrapping them.

Type:

The type accepted by the module-level lock()/unlock() functions

alias of IO[Any] | TextIOWrapper | int | HasFileno

class portalocker.types.FileOpenKwargs

Bases: TypedDict

Keyword arguments accepted by the built-in open().

Mirrors open()’s signature (minus file and mode) so helpers that accept a filename can forward arbitrary open-related keyword arguments straight through to the underlying open() call.

buffering: int | None

Buffering policy. 0 disables buffering (binary mode only), 1 selects line buffering (text mode), and any larger integer fixes the buffer size in bytes.

closefd: bool | None

Whether the underlying file descriptor is closed when the file object is closed. Must be True (the default) when a filename rather than a file descriptor was passed to open().

encoding: str | None

Text encoding to use; ignored in binary mode.

errors: str | None

How encoding/decoding errors are handled, e.g. ‘strict’ or ‘ignore’.

newline: str | None

Controls how universal newlines mode works, e.g. ‘’, ‘\n’, ‘\r’, or ‘\r\n’.

opener: Callable[[str, int], int] | None

A custom opener, called as opener(file, flags) to obtain the underlying file descriptor, used instead of the default os.open.

portalocker.types.Filename = str | pathlib._local.Path

either a plain string path or a pathlib.Path. Accepting both lets callers pass whichever they already have on hand without converting first.

Type:

A filename argument

class portalocker.types.HasFileno(*args, **kwargs)

Bases: Protocol

Structural protocol for objects exposing a fileno() method.

Exists so functions that ultimately call fcntl.flock can be typed against anything with a file descriptor - open files, sockets, and so on - without requiring those objects to share a common base class.

fileno()

Return the underlying file descriptor, as used by fcntl.flock.

Return type:

int

portalocker.types.IO

A file-like object already opened for reading or writing, in either text or binary mode.

alias of IO[str] | IO[bytes]

portalocker.types.Mode

Every mode string accepted by the built-in open(), spelled out explicitly - including the binary and legacy universal-newline (U) forms - so type checkers reject a typo’d mode string instead of letting it fail at runtime.

alias of Literal[‘r’, ‘rt’, ‘tr’, ‘w’, ‘wt’, ‘tw’, ‘a’, ‘at’, ‘ta’, ‘x’, ‘xt’, ‘tx’, ‘r+’, ‘+r’, ‘rt+’, ‘r+t’, ‘+rt’, ‘tr+’, ‘t+r’, ‘+tr’, ‘w+’, ‘+w’, ‘wt+’, ‘w+t’, ‘+wt’, ‘tw+’, ‘t+w’, ‘+tw’, ‘a+’, ‘+a’, ‘at+’, ‘a+t’, ‘+at’, ‘ta+’, ‘t+a’, ‘+ta’, ‘x+’, ‘+x’, ‘xt+’, ‘x+t’, ‘+xt’, ‘tx+’, ‘t+x’, ‘+tx’, ‘U’, ‘rU’, ‘Ur’, ‘rtU’, ‘rUt’, ‘Urt’, ‘trU’, ‘tUr’, ‘Utr’, ‘rb’, ‘br’, ‘wb’, ‘bw’, ‘ab’, ‘ba’, ‘xb’, ‘bx’, ‘rb+’, ‘r+b’, ‘+rb’, ‘br+’, ‘b+r’, ‘+br’, ‘wb+’, ‘w+b’, ‘+wb’, ‘bw+’, ‘b+w’, ‘+bw’, ‘ab+’, ‘a+b’, ‘+ab’, ‘ba+’, ‘b+a’, ‘+ba’, ‘xb+’, ‘x+b’, ‘+xb’, ‘bx+’, ‘b+x’, ‘+bx’, ‘rbU’, ‘rUb’, ‘Urb’, ‘brU’, ‘bUr’, ‘Ubr’]