containers

Model and Manager for Container resources.

class Container(attrs: Mapping[str, Any] | None = None, client: APIClient | None = None, collection: Manager | None = None)

Bases: PodmanResource

Details and configuration for a container managed by the Podman service.

Initialize base class for PodmanResource’s.

Parameters:

• attrs – Mapping of attributes for resource from Podman service.

• client – Configured connection to a Podman service.

• collection – Manager of this category of resource, named collection for compatibility

attach(**kwargs) → str | Iterator[str]

Attach to container’s tty.

Keyword Arguments:

• stdout (bool) – Include stdout. Default: True

• stderr (bool) – Include stderr. Default: True

• stream (bool) – Return iterator of string(s) vs single string. Default: False

• logs (bool) – Include previous container output. Default: False

Raises:

NotImplementedError – method not implemented.

attach_socket(**kwargs)

Not Implemented.

Raises:

NotImplementedError – method not implemented.

commit(repository: str = None, tag: str = None, **kwargs) → Image

Save container to given repository.

Parameters:

• repository – Where to save Image

• tag – Tag to push with Image

Keyword Arguments:

• author (str) – Name of commit author

• changes (List[str]) – Instructions to apply during commit

• comment (str) – Commit message to include with Image, overrides keyword message

• conf (dict[str, Any]) – Ignored.

• format (str) – Format of the image manifest and metadata

• message (str) – Commit message to include with Image

• pause (bool) – Pause the container before committing it

diff() → List[Dict[str, int]]

Report changes of a container’s filesystem.

Raises:

APIError – when service reports an error

exec_run(cmd: str | List[str], stdout: bool = True, stderr: bool = True, stdin: bool = False, tty: bool = False, privileged: bool = False, user=None, detach: bool = False, stream: bool = False, socket: bool = False, environment: Mapping[str, str] | List[str] = None, workdir: str = None, demux: bool = False) → Tuple[int | None, Iterator[bytes] | Any | Tuple[bytes, bytes]]

Run given command inside container and return results.

Parameters:

• cmd – Command to be executed

• stdout – Attach to stdout. Default: True

• stderr – Attach to stderr. Default: True

• stdin – Attach to stdin. Default: False

• tty – Allocate a pseudo-TTY. Default: False

• privileged – Run as privileged.

• user – User to execute command as. Default: root

• detach – If true, detach from the exec command. Default: False

• stream – Stream response data. Default: False

• socket – Return the connection socket to allow custom read/write operations. Default: False

• environment – A dictionary or a List[str] in the following format [“PASSWORD=xxx”] or {“PASSWORD”: “xxx”}.

• workdir – Path to working directory for this exec session

• demux – Return stdout and stderr separately

Returns:

First item is the command response code Second item is the requests response content

Raises:

• NotImplementedError – method not implemented.

• APIError – when service reports error

export(chunk_size: int = 2097152) → Iterator[bytes]

Download container’s filesystem contents as a tar archive.

Parameters:

chunk_size – <= number of bytes to return for each iteration of the generator.

Yields:

tarball in size/chunk_size chunks

Raises:

• NotFound – when container has been removed from service

• APIError – when service reports an error

get_archive(path: str, chunk_size: int = 2097152) → Tuple[Iterable, Dict[str, Any]]

Download a file or folder from the container’s filesystem.

Parameters:

• path – Path to file or folder.

• chunk_size – <= number of bytes to return for each iteration of the generator.

Returns:

First item is a raw tar data stream. Second item is a dict containing os.stat() information on the specified path.

inspect() → Dict

Inspect a container.

Raises:

APIError – when service reports an error

kill(signal: str | int | None = None) → None

Send signal to container.

Raises:

APIError – when service reports an error

logs(**kwargs) → bytes | Iterator[bytes]

Get logs from the container.

Keyword Arguments:

• stdout (bool) – Include stdout. Default: True

• stderr (bool) – Include stderr. Default: True

• stream (bool) – Return generator of strings as the response. Default: False

• timestamps (bool) – Show timestamps in output. Default: False

• tail (Union[str, int]) – Output specified number of lines at the end of logs. Integer representing the number of lines to display, or the string all. Default: all

• since (Union[datetime, int]) – Show logs since a given datetime or integer epoch (in seconds)

• follow (bool) – Follow log output. Default: False

• until (Union[datetime, int]) – Show logs that occurred before the given datetime or integer epoch (in seconds)

pause() → None

Pause processes within the container.

put_archive(path: str, data: bytes = None) → bool

Upload tar archive containing a file or folder to be written into container.

Parameters:

• path – File to write data into

• data – Contents to write to file, when None path will be read on client to build tarfile.

Returns:

True when successful

Raises:

APIError – when server reports error

reload() → None

Refresh this object’s data from the service.

remove(**kwargs) → None

Delete container.

Keyword Arguments:

• v (bool) – Delete associated volumes as well.

• link (bool) – Ignored.

• force (bool) – Kill a running container before deleting.

rename(name: str) → None

Rename container.

Container updated in-situ to avoid reload().

Parameters:

name – New name for container.

resize(height: int = None, width: int = None) → None

Resize the tty session.

Parameters:

• height – New height of tty session.

• width – New width of tty session.

restart(**kwargs) → None

Restart processes in container.

Keyword Arguments:

timeout (int) – Seconds to wait for container to stop before killing container.

start(**kwargs) → None

Start processes in container.

Keyword Arguments:

detach_keys – Override the key sequence for detaching a container (Podman only)

stats(**kwargs) → bytes | Dict[str, Any] | Iterator[bytes] | Iterator[Dict[str, Any]]

Return statistics for container.

Keyword Arguments:

• decode (bool) – If True and stream is True, stream will be decoded into dict’s. Default: False.

• stream (bool) – Stream statistics until cancelled. Default: True.

Raises:

APIError – when service reports an error

stop(**kwargs) → None

Stop container.

Keyword Arguments:

• all (bool) – When True, stop all containers. Default: False (Podman only)

• ignore (bool) – When True, ignore error if container already stopped (Podman only)

• timeout (int) – Number of seconds to wait on container to stop before killing it.

top(**kwargs) → Iterator[Dict[str, Any]] | Dict[str, Any]

Report on running processes in the container.

Keyword Arguments:

• ps_args (str) – When given, arguments will be passed to ps

• stream (bool) – When True, repeatedly return results. Default: False

Raises:

• NotFound – when the container no longer exists

• APIError – when the service reports an error

unpause() → None

Unpause processes in container.

update(**kwargs)

Update resource configuration of the containers.

Raises:

NotImplementedError – Podman service unsupported operation.

wait(**kwargs) → int

Block until the container enters given state.

Keyword Arguments:

• condition (Union[str, List[str]]) – Container state on which to release. One or more of: “configured”, “created”, “running”, “stopped”, “paused”, “exited”, “removing”, “stopping”.

• interval (int) – Time interval to wait before polling for completion.

Returns:

“Error” key has a dictionary value with the key “Message”.

Raises:

• NotFound – when Container not found

• ReadTimeoutError – when timeout is exceeded

• APIError – when service returns an error

property id

Returns the identifier for the object.

Type:

str

property image

Returns Image object used to create Container.

Type:

podman.domain.images.Image

property labels

Returns labels associated with container.

Type:

dict[str, str]

property name

Returns container’s name.

Type:

str

property ports

Return ports exposed by container.

Type:

dict[str, int]

property short_id

Returns truncated identifier. ‘sha256’ preserved when included in the id.

No attempt is made to ensure the returned value is semantically meaningful for all resources.

Type:

str

property status

Returns status of container.

Type:

Literal[“running”, “stopped”, “exited”, “unknown”]