client

Client for connecting to Podman service.

class PodmanClient(**kwargs)[source]

Bases: AbstractContextManager

Client to connect to a Podman service.

Examples

with PodmanClient(base_url=”ssh://root@api.example:22/run/podman/podman.sock?secure=True”,

identity=”~alice/.ssh/api_ed25519”)

Initialize PodmanClient.

Keyword Arguments:

  • base_url (str) – Full URL to Podman service. See examples.

  • version (str) – API version to use. Default: auto, use version from server

  • timeout (int) – Timeout for API calls, in seconds. Default: socket._GLOBAL_DEFAULT_TIMEOUT.

  • tls – Ignored. SSH connection configuration delegated to SSH Host configuration.

  • user_agent (str) – User agent for service connections. Default: PodmanPy/<Code Version>

  • credstore_env (Mapping[str, str]) – Dict containing environment for credential store

  • use_ssh_client (True) – Always shell out to SSH client for SSH Podman service connections.

  • max_pool_size (int) – Number of connections to save in pool

  • connection (str) – Identifier of connection to use from XDG_CONFIG_HOME/containers/containers.conf

  • identity (str) – Provide SSH key to authenticate SSH connection.

Examples

base_url:

  • http+ssh://<user>@<host>[:port]</run/podman/podman.sock>[?secure=True]

  • http+unix://</run/podman/podman.sock>

  • tcp://<localhost>[:<port>]

close()[source]

Release PodmanClient Resources.

df() → Dict[str, Any][source]

Disk usage by Podman resources.

Returns:

Keyed by resource categories and their data usage.

Return type:

dict

events(*args, **kwargs)[source]

Report on networks.

Parameters:

  • decode – When True, decode stream into dict’s. Default: False

  • filters – Criteria for including events.

  • since – Get events newer than this time.

  • until – Get events older than this time.

Yields:

When decode is True, Iterator[Dict[str, Any]]

When decode is False, Iterator[str]

classmethod from_env(version: str = 'auto', timeout: int | None = None, max_pool_size: int | None = None, ssl_version: int | None = None, assert_hostname: bool = False, environment: Dict[str, str] | None = None, credstore_env: Dict[str, str] | None = None, use_ssh_client: bool = True) → PodmanClient[source]

Returns connection to service using environment variables and parameters.

Environment variables:

  • DOCKER_HOST, CONTAINER_HOST: URL to Podman service

  • DOCKER_TLS_VERIFY, CONTAINER_TLS_VERIFY: Verify host against CA certificate

  • DOCKER_CERT_PATH, CONTAINER_CERT_PATH: Path to TLS certificates for host connection

Parameters:

  • version – API version to use. Default: auto, use version from server

  • timeout – Timeout for API calls, in seconds.

  • max_pool_size – Number of connections to save in pool.

  • ssl_version – SSH configuration delegated to SSH client configuration. Ignored.

  • assert_hostname – Ignored.

  • environment – Dict containing input environment. Default: os.environ

  • credstore_env – Dict containing environment for credential store

  • use_ssh_client – Use system ssh client rather than ssh module. Always, True.

Returns:

Client used to communicate with a Podman service.

Raises:

ValueError when required environment variable is not set –

info(*args, **kwargs)[source]

Returns information on Podman service.

login(*args, **kwargs)[source]

Log into Podman service.

Parameters:

  • username – Registry username

  • password – Registry plaintext password

  • email – Registry account email address

  • registry – URL for registry access. For example,

  • reauth – Ignored: If True, refresh existing authentication. Default: False

  • dockercfg_path – Ignored: Path to custom configuration file. https://quay.io/v2

ping() → bool[source]

Returns True if service responded with OK.

version(*args, **kwargs)[source]

Get version information from service.

Keyword Arguments:

api_version (bool) – When True include API version

property configs

Swarm not supported.

Raises:

NotImplemented – Swarm not supported by Podman service

property containers: ContainersManager

Returns Manager for operations on containers stored by a Podman service.

property images: ImagesManager

Returns Manager for operations on images stored by a Podman service.

property manifests: ManifestsManager

Returns Manager for operations on manifests maintained by a Podman service.

property networks: NetworksManager

Returns Manager for operations on networks maintained by a Podman service.

property nodes

Swarm not supported.

Raises:

NotImplemented – Swarm not supported by Podman service

property pods: PodsManager

Returns Manager for operations on pods maintained by a Podman service.

property secrets

Returns Manager for operations on secrets maintained by a Podman service.

property services

Swarm not supported.

Raises:

NotImplemented – Swarm not supported by Podman service

property swarm

Swarm not supported.

Raises:

NotImplemented – Swarm not supported by Podman service

property system
property volumes: VolumesManager

Returns Manager for operations on volumes maintained by a Podman service.

from_env(version: str = 'auto', timeout: int | None = None, max_pool_size: int | None = None, ssl_version: int | None = None, assert_hostname: bool = False, environment: Dict[str, str] | None = None, credstore_env: Dict[str, str] | None = None, use_ssh_client: bool = True) → PodmanClient

Returns connection to service using environment variables and parameters.

Environment variables:

  • DOCKER_HOST, CONTAINER_HOST: URL to Podman service

  • DOCKER_TLS_VERIFY, CONTAINER_TLS_VERIFY: Verify host against CA certificate

  • DOCKER_CERT_PATH, CONTAINER_CERT_PATH: Path to TLS certificates for host connection

Parameters:

  • version – API version to use. Default: auto, use version from server

  • timeout – Timeout for API calls, in seconds.

  • max_pool_size – Number of connections to save in pool.

  • ssl_version – SSH configuration delegated to SSH client configuration. Ignored.

  • assert_hostname – Ignored.

  • environment – Dict containing input environment. Default: os.environ

  • credstore_env – Dict containing environment for credential store

  • use_ssh_client – Use system ssh client rather than ssh module. Always, True.

Returns:

Client used to communicate with a Podman service.

Raises:

ValueError when required environment variable is not set –