ansible-collections/community.docker
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.docker.git synced 2026-07-29 11:55:04 +00:00
Code Packages Projects Releases Wiki Activity

Add typing information, 2/n (#1178)

Browse Source 
* Add typing to Docker Stack modules. Clean modules up.

* Add typing to Docker Swarm modules.

* Add typing to unit tests.

* Add more typing.

* Add ignore.txt entries.
This commit is contained in:
Felix Fontein
2025-10-25 01:16:04 +02:00
committed by GitHub
parent 3350283bcc
commit 6ad4bfcd40
84 changed files with 1496 additions and 1161 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/module_utils/_api/_import_helper.py
+3 -3
View File
@@ -67,7 +67,7 @@ except ImportError:
pass
class FakeURLLIB3:
def __init__(self):
def __init__(self) -> None:
self._collections = self
self.poolmanager = self
self.connection = self
@@ -81,14 +81,14 @@ except ImportError:
)
class FakeURLLIB3Connection:
def __init__(self):
def __init__(self) -> None:
self.HTTPConnection = _HTTPConnection # pylint: disable=invalid-name
urllib3 = FakeURLLIB3()
urllib3_connection = FakeURLLIB3Connection()
def fail_on_missing_imports():
def fail_on_missing_imports() -> None:
if REQUESTS_IMPORT_ERROR is not None:
from .errors import MissingRequirementException # pylint: disable=cyclic-import
plugins/module_utils/_api/api/client.py
+50 -39
View File
@@ -55,6 +55,7 @@ from ..utils.socket import consume_socket_output, demux_adaptor, frames_iter
if t.TYPE_CHECKING:
from requests import Response
from requests.adapters import BaseAdapter
from ..._socket_helper import SocketLike
@@ -258,23 +259,23 @@ class APIClient(_Session):
return kwargs
@update_headers
def _post(self, url: str, **kwargs):
def _post(self, url: str, **kwargs: t.Any) -> Response:
return self.post(url, **self._set_request_timeout(kwargs))
@update_headers
def _get(self, url: str, **kwargs):
def _get(self, url: str, **kwargs: t.Any) -> Response:
return self.get(url, **self._set_request_timeout(kwargs))
@update_headers
def _head(self, url: str, **kwargs):
def _head(self, url: str, **kwargs: t.Any) -> Response:
return self.head(url, **self._set_request_timeout(kwargs))
@update_headers
def _put(self, url: str, **kwargs):
def _put(self, url: str, **kwargs: t.Any) -> Response:
return self.put(url, **self._set_request_timeout(kwargs))
@update_headers
def _delete(self, url: str, **kwargs):
def _delete(self, url: str, **kwargs: t.Any) -> Response:
return self.delete(url, **self._set_request_timeout(kwargs))
def _url(self, pathfmt: str, *args: str, versioned_api: bool = True) -> str:
@@ -343,7 +344,7 @@ class APIClient(_Session):
return response.text
def _post_json(
self, url: str, data: dict[str, str | None] | t.Any, **kwargs
self, url: str, data: dict[str, str | None] | t.Any, **kwargs: t.Any
) -> Response:
# Go <1.1 cannot unserialize null to a string
# so we do this disgusting thing here.
@@ -556,22 +557,30 @@ class APIClient(_Session):
"""
socket = self._get_raw_response_socket(response)
gen: t.Generator = frames_iter(socket, tty)
gen = frames_iter(socket, tty)
if demux:
# The generator will output tuples (stdout, stderr)
gen = (demux_adaptor(*frame) for frame in gen)
demux_gen: t.Generator[tuple[bytes | None, bytes | None]] = (
demux_adaptor(*frame) for frame in gen
)
if stream:
return demux_gen
try:
# Wait for all the frames, concatenate them, and return the result
return consume_socket_output(demux_gen, demux=True)
finally:
response.close()
else:
# The generator will output strings
gen = (data for (dummy, data) in gen)
if stream:
return gen
try:
# Wait for all the frames, concatenate them, and return the result
return consume_socket_output(gen, demux=demux)
finally:
response.close()
mux_gen: t.Generator[bytes] = (data for (dummy, data) in gen)
if stream:
return mux_gen
try:
# Wait for all the frames, concatenate them, and return the result
return consume_socket_output(mux_gen, demux=False)
finally:
response.close()
def _disable_socket_timeout(self, socket: SocketLike) -> None:
"""Depending on the combination of python version and whether we are
@@ -637,11 +646,11 @@ class APIClient(_Session):
return self._multiplexed_response_stream_helper(res)
return sep.join(list(self._multiplexed_buffer_helper(res)))
def _unmount(self, *args) -> None:
def _unmount(self, *args: t.Any) -> None:
for proto in args:
self.adapters.pop(proto)
def get_adapter(self, url: str):
def get_adapter(self, url: str) -> BaseAdapter:
try:
return super().get_adapter(url)
except _InvalidSchema as e:
@@ -696,19 +705,19 @@ class APIClient(_Session):
else:
log.debug("No auth config found")
def get_binary(self, pathfmt: str, *args: str, **kwargs) -> bytes:
def get_binary(self, pathfmt: str, *args: str, **kwargs: t.Any) -> bytes:
return self._result(
self._get(self._url(pathfmt, *args, versioned_api=True), **kwargs),
get_binary=True,
)
def get_json(self, pathfmt: str, *args: str, **kwargs) -> t.Any:
def get_json(self, pathfmt: str, *args: str, **kwargs: t.Any) -> t.Any:
return self._result(
self._get(self._url(pathfmt, *args, versioned_api=True), **kwargs),
get_json=True,
)
def get_text(self, pathfmt: str, *args: str, **kwargs) -> str:
def get_text(self, pathfmt: str, *args: str, **kwargs: t.Any) -> str:
return self._result(
self._get(self._url(pathfmt, *args, versioned_api=True), **kwargs)
)
@@ -718,7 +727,7 @@ class APIClient(_Session):
pathfmt: str,
*args: str,
chunk_size: int = DEFAULT_DATA_CHUNK_SIZE,
**kwargs,
**kwargs: t.Any,
) -> t.Generator[bytes]:
res = self._get(
self._url(pathfmt, *args, versioned_api=True), stream=True, **kwargs
@@ -726,23 +735,25 @@ class APIClient(_Session):
self._raise_for_status(res)
return self._stream_raw_result(res, chunk_size=chunk_size, decode=False)
def delete_call(self, pathfmt: str, *args: str, **kwargs) -> None:
def delete_call(self, pathfmt: str, *args: str, **kwargs: t.Any) -> None:
self._raise_for_status(
self._delete(self._url(pathfmt, *args, versioned_api=True), **kwargs)
)
def delete_json(self, pathfmt: str, *args: str, **kwargs) -> t.Any:
def delete_json(self, pathfmt: str, *args: str, **kwargs: t.Any) -> t.Any:
return self._result(
self._delete(self._url(pathfmt, *args, versioned_api=True), **kwargs),
get_json=True,
)
def post_call(self, pathfmt: str, *args: str, **kwargs) -> None:
def post_call(self, pathfmt: str, *args: str, **kwargs: t.Any) -> None:
self._raise_for_status(
self._post(self._url(pathfmt, *args, versioned_api=True), **kwargs)
)
def post_json(self, pathfmt: str, *args: str, data: t.Any = None, **kwargs) -> None:
def post_json(
self, pathfmt: str, *args: str, data: t.Any = None, **kwargs: t.Any
) -> None:
self._raise_for_status(
self._post_json(
self._url(pathfmt, *args, versioned_api=True), data, **kwargs
@@ -750,7 +761,7 @@ class APIClient(_Session):
)
def post_json_to_binary(
self, pathfmt: str, *args: str, data: t.Any = None, **kwargs
self, pathfmt: str, *args: str, data: t.Any = None, **kwargs: t.Any
) -> bytes:
return self._result(
self._post_json(
@@ -760,7 +771,7 @@ class APIClient(_Session):
)
def post_json_to_json(
self, pathfmt: str, *args: str, data: t.Any = None, **kwargs
self, pathfmt: str, *args: str, data: t.Any = None, **kwargs: t.Any
) -> t.Any:
return self._result(
self._post_json(
@@ -770,7 +781,7 @@ class APIClient(_Session):
)
def post_json_to_text(
self, pathfmt: str, *args: str, data: t.Any = None, **kwargs
self, pathfmt: str, *args: str, data: t.Any = None, **kwargs: t.Any
) -> str:
return self._result(
self._post_json(
@@ -784,7 +795,7 @@ class APIClient(_Session):
*args: str,
data: t.Any = None,
headers: dict[str, str] | None = None,
**kwargs,
**kwargs: t.Any,
) -> SocketLike:
headers = headers.copy() if headers else {}
headers.update(
@@ -813,7 +824,7 @@ class APIClient(_Session):
stream: t.Literal[True],
tty: bool = True,
demux: t.Literal[False] = False,
**kwargs,
**kwargs: t.Any,
) -> t.Generator[bytes]: ...
@t.overload
@@ -826,7 +837,7 @@ class APIClient(_Session):
stream: t.Literal[True],
tty: t.Literal[True] = True,
demux: t.Literal[True],
**kwargs,
**kwargs: t.Any,
) -> t.Generator[tuple[bytes, None]]: ...
@t.overload
@@ -839,7 +850,7 @@ class APIClient(_Session):
stream: t.Literal[True],
tty: t.Literal[False],
demux: t.Literal[True],
**kwargs,
**kwargs: t.Any,
) -> t.Generator[tuple[bytes, None] | tuple[None, bytes]]: ...
@t.overload
@@ -852,7 +863,7 @@ class APIClient(_Session):
stream: t.Literal[False],
tty: bool = True,
demux: t.Literal[False] = False,
**kwargs,
**kwargs: t.Any,
) -> bytes: ...
@t.overload
@@ -865,7 +876,7 @@ class APIClient(_Session):
stream: t.Literal[False],
tty: t.Literal[True] = True,
demux: t.Literal[True],
**kwargs,
**kwargs: t.Any,
) -> tuple[bytes, None]: ...
@t.overload
@@ -878,7 +889,7 @@ class APIClient(_Session):
stream: t.Literal[False],
tty: t.Literal[False],
demux: t.Literal[True],
**kwargs,
**kwargs: t.Any,
) -> tuple[bytes, bytes]: ...
def post_json_to_stream(
@@ -890,7 +901,7 @@ class APIClient(_Session):
stream: bool = False,
demux: bool = False,
tty: bool = False,
**kwargs,
**kwargs: t.Any,
) -> t.Any:
headers = headers.copy() if headers else {}
headers.update(
@@ -912,7 +923,7 @@ class APIClient(_Session):
demux=demux,
)
def post_to_json(self, pathfmt: str, *args: str, **kwargs) -> t.Any:
def post_to_json(self, pathfmt: str, *args: str, **kwargs: t.Any) -> t.Any:
return self._result(
self._post(self._url(pathfmt, *args, versioned_api=True), **kwargs),
get_json=True,
plugins/module_utils/_api/auth.py
+6 -4
View File
@@ -106,7 +106,7 @@ class AuthConfig(dict):
@classmethod
def parse_auth(
cls, entries: dict[str, dict[str, t.Any]], raise_on_error=False
cls, entries: dict[str, dict[str, t.Any]], raise_on_error: bool = False
) -> dict[str, dict[str, t.Any]]:
"""
Parses authentication entries
@@ -294,7 +294,7 @@ class AuthConfig(dict):
except StoreError as e:
raise errors.DockerException(f"Credentials store error: {e}")
def _get_store_instance(self, name: str):
def _get_store_instance(self, name: str) -> Store:
if name not in self._stores:
self._stores[name] = Store(name, environment=self._credstore_env)
return self._stores[name]
@@ -326,8 +326,10 @@ class AuthConfig(dict):
def resolve_authconfig(
authconfig, registry: str | None = None, credstore_env: dict[str, str] | None = None
):
authconfig: AuthConfig | dict[str, t.Any],
registry: str | None = None,
credstore_env: dict[str, str] | None = None,
) -> dict[str, t.Any] | None:
if not isinstance(authconfig, AuthConfig):
authconfig = AuthConfig(authconfig, credstore_env)
return authconfig.resolve_authconfig(registry)
plugins/module_utils/_api/context/config.py
+1 -1
View File
@@ -89,7 +89,7 @@ def get_meta_dir(name: str | None = None) -> str:
return meta_dir
def get_meta_file(name) -> str:
def get_meta_file(name: str) -> str:
return os.path.join(get_meta_dir(name), METAFILE)
plugins/module_utils/_api/errors.py
+8 -1
View File
@@ -18,6 +18,10 @@ from ansible.module_utils.common.text.converters import to_native
from ._import_helper import HTTPError as _HTTPError
if t.TYPE_CHECKING:
from requests import Response
class DockerException(Exception):
"""
A base class from which all other exceptions inherit.
@@ -55,7 +59,10 @@ class APIError(_HTTPError, DockerException):
"""
def __init__(
self, message: str | Exception, response=None, explanation: str | None = None
self,
message: str | Exception,
response: Response | None = None,
explanation: str | None = None,
) -> None:
# requests 1.2 supports response as a keyword argument, but
# requests 1.1 does not
plugins/module_utils/_api/transport/npipeconn.py
+13 -2
View File
@@ -11,6 +11,7 @@
from __future__ import annotations
import typing as t
from queue import Empty
from .. import constants
@@ -19,6 +20,12 @@ from .basehttpadapter import BaseHTTPAdapter
from .npipesocket import NpipeSocket
if t.TYPE_CHECKING:
from collections.abc import Mapping
from requests import PreparedRequest
RecentlyUsedContainer = urllib3._collections.RecentlyUsedContainer
@@ -91,7 +98,9 @@ class NpipeHTTPAdapter(BaseHTTPAdapter):
)
super().__init__()
def get_connection(self, url: str | bytes, proxies=None) -> NpipeHTTPConnectionPool:
def get_connection(
self, url: str | bytes, proxies: Mapping[str, str] | None = None
) -> NpipeHTTPConnectionPool:
with self.pools.lock:
pool = self.pools.get(url)
if pool:
@@ -104,7 +113,9 @@ class NpipeHTTPAdapter(BaseHTTPAdapter):
return pool
def request_url(self, request, proxies) -> str:
def request_url(
self, request: PreparedRequest, proxies: Mapping[str, str] | None
) -> str:
# The select_proxy utility in requests errors out when the provided URL
# does not have a hostname, like is the case when using a UNIX socket.
# Since proxies are an irrelevant notion in the case of UNIX sockets
plugins/module_utils/_api/transport/npipesocket.py
+29 -14
View File
@@ -64,7 +64,7 @@ class NpipeSocket:
implemented.
"""
def __init__(self, handle=None) -> None:
def __init__(self, handle: t.Any | None = None) -> None:
self._timeout = win32pipe.NMPWAIT_USE_DEFAULT_WAIT
self._handle = handle
self._address: str | None = None
@@ -74,15 +74,17 @@ class NpipeSocket:
def accept(self) -> t.NoReturn:
raise NotImplementedError()
def bind(self, address) -> t.NoReturn:
def bind(self, address: t.Any) -> t.NoReturn:
raise NotImplementedError()
def close(self) -> None:
if self._handle is None:
raise ValueError("Handle not present")
self._handle.Close()
self._closed = True
@check_closed
def connect(self, address, retry_count: int = 0) -> None:
def connect(self, address: str, retry_count: int = 0) -> None:
try:
handle = win32file.CreateFile(
address,
@@ -116,11 +118,11 @@ class NpipeSocket:
self._address = address
@check_closed
def connect_ex(self, address) -> None:
def connect_ex(self, address: str) -> None:
self.connect(address)
@check_closed
def detach(self):
def detach(self) -> t.Any:
self._closed = True
return self._handle
@@ -134,16 +136,18 @@ class NpipeSocket:
def getsockname(self) -> str | None:
return self._address
def getsockopt(self, level, optname, buflen=None) -> t.NoReturn:
def getsockopt(
self, level: t.Any, optname: t.Any, buflen: t.Any = None
) -> t.NoReturn:
raise NotImplementedError()
def ioctl(self, control, option) -> t.NoReturn:
def ioctl(self, control: t.Any, option: t.Any) -> t.NoReturn:
raise NotImplementedError()
def listen(self, backlog) -> t.NoReturn:
def listen(self, backlog: t.Any) -> t.NoReturn:
raise NotImplementedError()
def makefile(self, mode: str, bufsize: int | None = None):
def makefile(self, mode: str, bufsize: int | None = None) -> t.IO[bytes]:
if mode.strip("b") != "r":
raise NotImplementedError()
rawio = NpipeFileIOBase(self)
@@ -153,6 +157,8 @@ class NpipeSocket:
@check_closed
def recv(self, bufsize: int, flags: int = 0) -> str:
if self._handle is None:
raise ValueError("Handle not present")
dummy_err, data = win32file.ReadFile(self._handle, bufsize)
return data
@@ -169,6 +175,8 @@ class NpipeSocket:
@check_closed
def recv_into(self, buf: Buffer, nbytes: int = 0) -> int:
if self._handle is None:
raise ValueError("Handle not present")
readbuf = buf if isinstance(buf, memoryview) else memoryview(buf)
event = win32event.CreateEvent(None, True, True, None)
@@ -188,6 +196,8 @@ class NpipeSocket:
@check_closed
def send(self, string: Buffer, flags: int = 0) -> int:
if self._handle is None:
raise ValueError("Handle not present")
event = win32event.CreateEvent(None, True, True, None)
try:
overlapped = pywintypes.OVERLAPPED()
@@ -210,7 +220,7 @@ class NpipeSocket:
self.connect(address)
return self.send(string)
def setblocking(self, flag: bool):
def setblocking(self, flag: bool) -> None:
if flag:
return self.settimeout(None)
return self.settimeout(0)
@@ -228,16 +238,16 @@ class NpipeSocket:
def gettimeout(self) -> int | float | None:
return self._timeout
def setsockopt(self, level, optname, value) -> t.NoReturn:
def setsockopt(self, level: t.Any, optname: t.Any, value: t.Any) -> t.NoReturn:
raise NotImplementedError()
@check_closed
def shutdown(self, how) -> None:
def shutdown(self, how: t.Any) -> None:
return self.close()
class NpipeFileIOBase(io.RawIOBase):
def __init__(self, npipe_socket) -> None:
def __init__(self, npipe_socket: NpipeSocket | None) -> None:
self.sock = npipe_socket
def close(self) -> None:
@@ -245,7 +255,10 @@ class NpipeFileIOBase(io.RawIOBase):
self.sock = None
def fileno(self) -> int:
return self.sock.fileno()
if self.sock is None:
raise RuntimeError("socket is closed")
# TODO: This is definitely a bug, NpipeSocket.fileno() does not exist!
return self.sock.fileno() # type: ignore
def isatty(self) -> bool:
return False
@@ -254,6 +267,8 @@ class NpipeFileIOBase(io.RawIOBase):
return True
def readinto(self, buf: Buffer) -> int:
if self.sock is None:
raise RuntimeError("socket is closed")
return self.sock.recv_into(buf)
def seekable(self) -> bool:
plugins/module_utils/_api/transport/sshconn.py
+17 -14
View File
@@ -35,7 +35,7 @@ else:
PARAMIKO_IMPORT_ERROR = None # pylint: disable=invalid-name
if t.TYPE_CHECKING:
from collections.abc import Buffer
from collections.abc import Buffer, Mapping
RecentlyUsedContainer = urllib3._collections.RecentlyUsedContainer
@@ -67,7 +67,7 @@ class SSHSocket(socket.socket):
preexec_func = None
if not constants.IS_WINDOWS_PLATFORM:
def f():
def f() -> None:
signal.signal(signal.SIGINT, signal.SIG_IGN)
preexec_func = f
@@ -100,13 +100,13 @@ class SSHSocket(socket.socket):
self.proc.stdin.flush()
return written
def sendall(self, data: Buffer, *args, **kwargs) -> None:
def sendall(self, data: Buffer, *args: t.Any, **kwargs: t.Any) -> None:
self._write(data)
def send(self, data: Buffer, *args, **kwargs) -> int:
def send(self, data: Buffer, *args: t.Any, **kwargs: t.Any) -> int:
return self._write(data)
def recv(self, n: int, *args, **kwargs) -> bytes:
def recv(self, n: int, *args: t.Any, **kwargs: t.Any) -> bytes:
if not self.proc:
raise RuntimeError(
"SSH subprocess not initiated. connect() must be called first."
@@ -114,7 +114,7 @@ class SSHSocket(socket.socket):
assert self.proc.stdout is not None
return self.proc.stdout.read(n)
def makefile(self, mode: str, *args, **kwargs) -> t.IO: # type: ignore
def makefile(self, mode: str, *args: t.Any, **kwargs: t.Any) -> t.IO: # type: ignore
if not self.proc:
self.connect()
assert self.proc is not None
@@ -138,7 +138,7 @@ class SSHConnection(urllib3_connection.HTTPConnection):
def __init__(
self,
*,
ssh_transport=None,
ssh_transport: paramiko.Transport | None = None,
timeout: int | float = 60,
host: str,
) -> None:
@@ -146,18 +146,19 @@ class SSHConnection(urllib3_connection.HTTPConnection):
self.ssh_transport = ssh_transport
self.timeout = timeout
self.ssh_host = host
self.sock: paramiko.Channel | SSHSocket | None = None
def connect(self) -> None:
if self.ssh_transport:
sock = self.ssh_transport.open_session()
sock.settimeout(self.timeout)
sock.exec_command("docker system dial-stdio")
channel = self.ssh_transport.open_session()
channel.settimeout(self.timeout)
channel.exec_command("docker system dial-stdio")
self.sock = channel
else:
sock = SSHSocket(self.ssh_host)
sock.settimeout(self.timeout)
sock.connect()
self.sock = sock
self.sock = sock
class SSHConnectionPool(urllib3.connectionpool.HTTPConnectionPool):
@@ -172,7 +173,7 @@ class SSHConnectionPool(urllib3.connectionpool.HTTPConnectionPool):
host: str,
) -> None:
super().__init__("localhost", timeout=timeout, maxsize=maxsize)
self.ssh_transport = None
self.ssh_transport: paramiko.Transport | None = None
self.timeout = timeout
if ssh_client:
self.ssh_transport = ssh_client.get_transport()
@@ -276,7 +277,9 @@ class SSHHTTPAdapter(BaseHTTPAdapter):
if self.ssh_client:
self.ssh_client.connect(**self.ssh_params)
def get_connection(self, url: str | bytes, proxies=None) -> SSHConnectionPool:
def get_connection(
self, url: str | bytes, proxies: Mapping[str, str] | None = None
) -> SSHConnectionPool:
if not self.ssh_client:
return SSHConnectionPool(
ssh_client=self.ssh_client,
plugins/module_utils/_api/transport/ssladapter.py
+2 -2
View File
@@ -33,7 +33,7 @@ class SSLHTTPAdapter(BaseHTTPAdapter):
def __init__(
self,
assert_hostname: bool | None = None,
**kwargs,
**kwargs: t.Any,
) -> None:
self.assert_hostname = assert_hostname
super().__init__(**kwargs)
@@ -51,7 +51,7 @@ class SSLHTTPAdapter(BaseHTTPAdapter):
self.poolmanager = PoolManager(**kwargs)
def get_connection(self, *args, **kwargs) -> urllib3.ConnectionPool:
def get_connection(self, *args: t.Any, **kwargs: t.Any) -> urllib3.ConnectionPool:
"""
Ensure assert_hostname is set correctly on our pool
plugins/module_utils/_api/transport/unixconn.py
+19 -7
View File
@@ -19,12 +19,20 @@ from .._import_helper import HTTPAdapter, urllib3, urllib3_connection
from .basehttpadapter import BaseHTTPAdapter
if t.TYPE_CHECKING:
from collections.abc import Mapping
from requests import PreparedRequest
from ..._socket_helper import SocketLike
RecentlyUsedContainer = urllib3._collections.RecentlyUsedContainer
class UnixHTTPConnection(urllib3_connection.HTTPConnection):
def __init__(
self, base_url: str | bytes, unix_socket, timeout: int | float = 60
self, base_url: str | bytes, unix_socket: str, timeout: int | float = 60
) -> None:
super().__init__("localhost", timeout=timeout)
self.base_url = base_url
@@ -43,7 +51,7 @@ class UnixHTTPConnection(urllib3_connection.HTTPConnection):
if header == "Connection" and "Upgrade" in values:
self.disable_buffering = True
def response_class(self, sock, *args, **kwargs) -> t.Any:
def response_class(self, sock: SocketLike, *args: t.Any, **kwargs: t.Any) -> t.Any:
# FIXME: We may need to disable buffering on Py3,
# but there's no clear way to do it at the moment. See:
# https://github.com/docker/docker-py/issues/1799
@@ -88,12 +96,16 @@ class UnixHTTPAdapter(BaseHTTPAdapter):
self.socket_path = socket_path
self.timeout = timeout
self.max_pool_size = max_pool_size
self.pools = RecentlyUsedContainer(
pool_connections, dispose_func=lambda p: p.close()
)
def f(p: t.Any) -> None:
p.close()
self.pools = RecentlyUsedContainer(pool_connections, dispose_func=f)
super().__init__()
def get_connection(self, url: str | bytes, proxies=None) -> UnixHTTPConnectionPool:
def get_connection(
self, url: str | bytes, proxies: Mapping[str, str] | None = None
) -> UnixHTTPConnectionPool:
with self.pools.lock:
pool = self.pools.get(url)
if pool:
@@ -106,7 +118,7 @@ class UnixHTTPAdapter(BaseHTTPAdapter):
return pool
def request_url(self, request, proxies) -> str:
def request_url(self, request: PreparedRequest, proxies: Mapping[str, str]) -> str:
# The select_proxy utility in requests errors out when the provided URL
# does not have a hostname, like is the case when using a UNIX socket.
# Since proxies are an irrelevant notion in the case of UNIX sockets
plugins/module_utils/_api/types/daemon.py
+11 -5
View File
@@ -18,7 +18,13 @@ from .._import_helper import urllib3
from ..errors import DockerException
class CancellableStream:
if t.TYPE_CHECKING:
from requests import Response
_T = t.TypeVar("_T")
class CancellableStream(t.Generic[_T]):
"""
Stream wrapper for real-time events, logs, etc. from the server.
@@ -30,14 +36,14 @@ class CancellableStream:
>>> events.close()
"""
def __init__(self, stream, response) -> None:
def __init__(self, stream: t.Generator[_T], response: Response) -> None:
self._stream = stream
self._response = response
def __iter__(self) -> t.Self:
return self
def __next__(self):
def __next__(self) -> _T:
try:
return next(self._stream)
except urllib3.exceptions.ProtocolError as exc:
@@ -56,7 +62,7 @@ class CancellableStream:
# find the underlying socket object
# based on api.client._get_raw_response_socket
sock_fp = self._response.raw._fp.fp
sock_fp = self._response.raw._fp.fp # type: ignore
if hasattr(sock_fp, "raw"):
sock_raw = sock_fp.raw
@@ -74,7 +80,7 @@ class CancellableStream:
"Cancellable streams not supported for the SSH protocol"
)
else:
sock = sock_fp._sock
sock = sock_fp._sock # type: ignore
if hasattr(urllib3.contrib, "pyopenssl") and isinstance(
sock, urllib3.contrib.pyopenssl.WrappedSocket
plugins/module_utils/_api/utils/fnmatch.py
+1 -1
View File
@@ -37,7 +37,7 @@ def _purge() -> None:
_cache.clear()
def fnmatch(name: str, pat: str):
def fnmatch(name: str, pat: str) -> bool:
"""Test whether FILENAME matches PATTERN.
Patterns are Unix shell style:
plugins/module_utils/_api/utils/ports.py
+1 -1
View File
@@ -108,7 +108,7 @@ def port_range(
def split_port(
port: str,
port: str | int,
) -> tuple[list[str], list[str] | list[tuple[str, str | None]] | None]:
port = str(port)
match = PORT_SPEC.match(port)
plugins/module_utils/_api/utils/proxy.py
+13 -1
View File
@@ -11,6 +11,8 @@
from __future__ import annotations
import typing as t
from .utils import format_environment
@@ -67,7 +69,17 @@ class ProxyConfig(dict):
env["no_proxy"] = env["NO_PROXY"] = self.no_proxy
return env
def inject_proxy_environment(self, environment: list[str]) -> list[str]:
@t.overload
def inject_proxy_environment(self, environment: list[str]) -> list[str]: ...
@t.overload
def inject_proxy_environment(
self, environment: list[str] | None
) -> list[str] | None: ...
def inject_proxy_environment(
self, environment: list[str] | None
) -> list[str] | None:
"""
Given a list of strings representing environment variables, prepend the
environment variables corresponding to the proxy settings.
plugins/module_utils/_api/utils/socket.py
+44 -19
View File
@@ -22,7 +22,9 @@ from ..transport.npipesocket import NpipeSocket
if t.TYPE_CHECKING:
from collections.abc import Iterable
from collections.abc import Iterable, Sequence
from ..._socket_helper import SocketLike
STDOUT = 1
@@ -38,14 +40,14 @@ class SocketError(Exception):
NPIPE_ENDED = 109
def read(socket, n: int = 4096) -> bytes | None:
def read(socket: SocketLike, n: int = 4096) -> bytes | None:
"""
Reads at most n bytes from socket
"""
recoverable_errors = (errno.EINTR, errno.EDEADLK, errno.EWOULDBLOCK)
if not isinstance(socket, NpipeSocket):
if not isinstance(socket, NpipeSocket): # type: ignore[unreachable]
if not hasattr(select, "poll"):
# Limited to 1024
select.select([socket], [], [])
@@ -66,7 +68,7 @@ def read(socket, n: int = 4096) -> bytes | None:
return None # TODO ???
except Exception as e:
is_pipe_ended = (
isinstance(socket, NpipeSocket)
isinstance(socket, NpipeSocket) # type: ignore[unreachable]
and len(e.args) > 0
and e.args[0] == NPIPE_ENDED
)
@@ -77,7 +79,7 @@ def read(socket, n: int = 4096) -> bytes | None:
raise
def read_exactly(socket, n: int) -> bytes:
def read_exactly(socket: SocketLike, n: int) -> bytes:
"""
Reads exactly n bytes from socket
Raises SocketError if there is not enough data
@@ -91,7 +93,7 @@ def read_exactly(socket, n: int) -> bytes:
return data
def next_frame_header(socket) -> tuple[int, int]:
def next_frame_header(socket: SocketLike) -> tuple[int, int]:
"""
Returns the stream and size of the next frame of data waiting to be read
from socket, according to the protocol defined here:
@@ -107,7 +109,7 @@ def next_frame_header(socket) -> tuple[int, int]:
return (stream, actual)
def frames_iter(socket, tty: bool) -> t.Generator[tuple[int, bytes]]:
def frames_iter(socket: SocketLike, tty: bool) -> t.Generator[tuple[int, bytes]]:
"""
Return a generator of frames read from socket. A frame is a tuple where
the first item is the stream number and the second item is a chunk of data.
@@ -120,7 +122,7 @@ def frames_iter(socket, tty: bool) -> t.Generator[tuple[int, bytes]]:
return frames_iter_no_tty(socket)
def frames_iter_no_tty(socket) -> t.Generator[tuple[int, bytes]]:
def frames_iter_no_tty(socket: SocketLike) -> t.Generator[tuple[int, bytes]]:
"""
Returns a generator of data read from the socket when the tty setting is
not enabled.
@@ -141,7 +143,7 @@ def frames_iter_no_tty(socket) -> t.Generator[tuple[int, bytes]]:
yield (stream, result)
def frames_iter_tty(socket) -> t.Generator[bytes]:
def frames_iter_tty(socket: SocketLike) -> t.Generator[bytes]:
"""
Return a generator of data read from the socket when the tty setting is
enabled.
@@ -155,20 +157,42 @@ def frames_iter_tty(socket) -> t.Generator[bytes]:
@t.overload
def consume_socket_output(frames, demux: t.Literal[False] = False) -> bytes: ...
@t.overload
def consume_socket_output(frames, demux: t.Literal[True]) -> tuple[bytes, bytes]: ...
def consume_socket_output(
frames: Sequence[bytes] | t.Generator[bytes], demux: t.Literal[False] = False
) -> bytes: ...
@t.overload
def consume_socket_output(
frames, demux: bool = False
frames: (
Sequence[tuple[bytes | None, bytes | None]]
| t.Generator[tuple[bytes | None, bytes | None]]
),
demux: t.Literal[True],
) -> tuple[bytes, bytes]: ...
@t.overload
def consume_socket_output(
frames: (
Sequence[bytes]
| Sequence[tuple[bytes | None, bytes | None]]
| t.Generator[bytes]
| t.Generator[tuple[bytes | None, bytes | None]]
),
demux: bool = False,
) -> bytes | tuple[bytes, bytes]: ...
def consume_socket_output(frames, demux: bool = False) -> bytes | tuple[bytes, bytes]:
def consume_socket_output(
frames: (
Sequence[bytes]
| Sequence[tuple[bytes | None, bytes | None]]
| t.Generator[bytes]
| t.Generator[tuple[bytes | None, bytes | None]]
),
demux: bool = False,
) -> bytes | tuple[bytes, bytes]:
"""
Iterate through frames read from the socket and return the result.
@@ -183,12 +207,13 @@ def consume_socket_output(frames, demux: bool = False) -> bytes | tuple[bytes, b
if demux is False:
# If the streams are multiplexed, the generator returns strings, that
# we just need to concatenate.
return b"".join(frames)
return b"".join(frames) # type: ignore
# If the streams are demultiplexed, the generator yields tuples
# (stdout, stderr)
out: list[bytes | None] = [None, None]
for frame in frames:
frame: tuple[bytes | None, bytes | None]
for frame in frames: # type: ignore
# It is guaranteed that for each frame, one and only one stream
# is not None.
if frame == (None, None):
@@ -202,7 +227,7 @@ def consume_socket_output(frames, demux: bool = False) -> bytes | tuple[bytes, b
if out[1] is None:
out[1] = frame[1]
else:
out[1] += frame[1]
out[1] += frame[1] # type: ignore[operator]
return tuple(out) # type: ignore
plugins/module_utils/_api/utils/utils.py
+12 -5
View File
@@ -46,7 +46,7 @@ URLComponents = collections.namedtuple(
)
def decode_json_header(header: str) -> dict[str, t.Any]:
def decode_json_header(header: str | bytes) -> dict[str, t.Any]:
data = base64.b64decode(header).decode("utf-8")
return json.loads(data)
@@ -143,7 +143,12 @@ def convert_port_bindings(
def convert_volume_binds(
binds: list[str] | Mapping[str | bytes, dict[str, str | bytes] | bytes | str | int],
binds: (
list[str]
| Mapping[
str | bytes, dict[str, str | bytes] | dict[str, str] | bytes | str | int
]
),
) -> list[str]:
if isinstance(binds, list):
return binds # type: ignore
@@ -403,7 +408,9 @@ def kwargs_from_env(
return params
def convert_filters(filters: Mapping[str, bool | str | list[str]]) -> str:
def convert_filters(
filters: Mapping[str, bool | str | int | list[int] | list[str] | list[str | int]],
) -> str:
result = {}
for k, v in filters.items():
if isinstance(v, bool):
@@ -495,8 +502,8 @@ def split_command(command: str) -> list[str]:
return shlex.split(command)
def format_environment(environment: Mapping[str, str | bytes]) -> list[str]:
def format_env(key, value):
def format_environment(environment: Mapping[str, str | bytes | None]) -> list[str]:
def format_env(key: str, value: str | bytes | None) -> str:
if value is None:
return key
if isinstance(value, bytes):
plugins/module_utils/_common.py
+3 -5
View File
@@ -91,7 +91,7 @@ if not HAS_DOCKER_PY:
# No Docker SDK for Python. Create a place holder client to allow
# instantiation of AnsibleModule and proper error handing
class Client: # type: ignore # noqa: F811, pylint: disable=function-redefined
def __init__(self, **kwargs):
def __init__(self, **kwargs: t.Any) -> None:
pass
class APIError(Exception): # type: ignore # noqa: F811, pylint: disable=function-redefined
@@ -226,7 +226,7 @@ class AnsibleDockerClientBase(Client):
f"Docker API version is {self.docker_api_version_str}. Minimum version required is {min_docker_api_version}."
)
def log(self, msg: t.Any, pretty_print: bool = False):
def log(self, msg: t.Any, pretty_print: bool = False) -> None:
pass
# if self.debug:
# from .util import log_debug
@@ -609,7 +609,7 @@ class AnsibleDockerClientBase(Client):
return new_tag, old_tag == new_tag
def inspect_distribution(self, image: str, **kwargs) -> dict[str, t.Any]:
def inspect_distribution(self, image: str, **kwargs: t.Any) -> dict[str, t.Any]:
"""
Get image digest by directly calling the Docker API when running Docker SDK < 4.0.0
since prior versions did not support accessing private repositories.
@@ -629,7 +629,6 @@ class AnsibleDockerClientBase(Client):
class AnsibleDockerClient(AnsibleDockerClientBase):
def __init__(
self,
argument_spec: dict[str, t.Any] | None = None,
@@ -651,7 +650,6 @@ class AnsibleDockerClient(AnsibleDockerClientBase):
option_minimal_versions_ignore_params: Sequence[str] | None = None,
fail_results: dict[str, t.Any] | None = None,
):
# Modules can put information in here which will always be returned
# in case client.fail() is called.
self.fail_results = fail_results or {}
plugins/module_utils/_common_api.py
+2 -2
View File
@@ -146,7 +146,7 @@ class AnsibleDockerClientBase(Client):
f"Docker API version is {self.docker_api_version_str}. Minimum version required is {min_docker_api_version}."
)
def log(self, msg: t.Any, pretty_print: bool = False):
def log(self, msg: t.Any, pretty_print: bool = False) -> None:
pass
# if self.debug:
# from .util import log_debug
@@ -295,7 +295,7 @@ class AnsibleDockerClientBase(Client):
),
}
def depr(*args, **kwargs):
def depr(*args: t.Any, **kwargs: t.Any) -> None:
self.deprecate(*args, **kwargs)
update_tls_hostname(
plugins/module_utils/_common_cli.py
+8 -9
View File
@@ -82,7 +82,7 @@ class AnsibleDockerClientBase:
def __init__(
self,
common_args,
common_args: dict[str, t.Any],
min_docker_api_version: str | None = None,
needs_api_version: bool = True,
) -> None:
@@ -91,15 +91,15 @@ class AnsibleDockerClientBase:
self._environment["DOCKER_TLS_HOSTNAME"] = common_args["tls_hostname"]
if common_args["api_version"] and common_args["api_version"] != "auto":
self._environment["DOCKER_API_VERSION"] = common_args["api_version"]
self._cli = common_args.get("docker_cli")
if self._cli is None:
cli = common_args.get("docker_cli")
if cli is None:
try:
self._cli = get_bin_path("docker")
cli = get_bin_path("docker")
except ValueError:
self.fail(
"Cannot find docker CLI in path. Please provide it explicitly with the docker_cli parameter"
)
self._cli = cli
self._cli_base = [self._cli]
docker_host = common_args["docker_host"]
if not docker_host and not common_args["cli_context"]:
@@ -149,7 +149,7 @@ class AnsibleDockerClientBase:
"Internal error: cannot have needs_api_version=False with min_docker_api_version not None"
)
def log(self, msg: str, pretty_print: bool = False):
def log(self, msg: str, pretty_print: bool = False) -> None:
pass
# if self.debug:
# from .util import log_debug
@@ -227,7 +227,7 @@ class AnsibleDockerClientBase:
return rc, result, stderr
@abc.abstractmethod
def fail(self, msg: str, **kwargs) -> t.NoReturn:
def fail(self, msg: str, **kwargs: t.Any) -> t.NoReturn:
pass
@abc.abstractmethod
@@ -395,7 +395,6 @@ class AnsibleModuleDockerClient(AnsibleDockerClientBase):
fail_results: dict[str, t.Any] | None = None,
needs_api_version: bool = True,
) -> None:
# Modules can put information in here which will always be returned
# in case client.fail() is called.
self.fail_results = fail_results or {}
@@ -463,7 +462,7 @@ class AnsibleModuleDockerClient(AnsibleDockerClientBase):
)
return rc, stdout, stderr
def fail(self, msg: str, **kwargs) -> t.NoReturn:
def fail(self, msg: str, **kwargs: t.Any) -> t.NoReturn:
self.fail_results.update(kwargs)
self.module.fail_json(msg=msg, **sanitize_result(self.fail_results))
plugins/module_utils/_compose_v2.py
+2 -2
View File
@@ -971,7 +971,7 @@ class BaseComposeManager(DockerBaseClass):
stderr: str | bytes,
ignore_service_pull_events: bool = False,
ignore_build_events: bool = False,
):
) -> None:
result["changed"] = result.get("changed", False) or has_changes(
events,
ignore_service_pull_events=ignore_service_pull_events,
@@ -989,7 +989,7 @@ class BaseComposeManager(DockerBaseClass):
stdout: str | bytes,
stderr: bytes,
rc: int,
):
) -> bool:
return update_failed(
result,
events,
plugins/module_utils/_copy.py
+4 -2
View File
@@ -330,6 +330,8 @@ def stat_file(
client._raise_for_status(response)
header = response.headers.get("x-docker-container-path-stat")
try:
if header is None:
raise ValueError("x-docker-container-path-stat header not present")
stat_data = json.loads(base64.b64decode(header))
except Exception as exc:
raise DockerUnexpectedError(
@@ -482,14 +484,14 @@ def fetch_file(
shutil.copyfileobj(in_f, out_f)
return in_path
def process_symlink(in_path, member) -> str:
def process_symlink(in_path: str, member: tarfile.TarInfo) -> str:
if os.path.exists(b_out_path):
os.unlink(b_out_path)
os.symlink(member.linkname, b_out_path)
return in_path
def process_other(in_path, member) -> str:
def process_other(in_path: str, member: tarfile.TarInfo) -> str:
raise DockerFileCopyError(
f'Remote file "{in_path}" is not a regular file or a symbolic link'
)
plugins/module_utils/_module_container/base.py
+9 -5
View File
@@ -193,7 +193,9 @@ class OptionGroup:
) -> None:
if preprocess is None:
def preprocess(module, values):
def preprocess(
module: AnsibleModule, values: dict[str, t.Any]
) -> dict[str, t.Any]:
return values
self.preprocess = preprocess
@@ -207,8 +209,8 @@ class OptionGroup:
self.ansible_required_by = ansible_required_by or {}
self.argument_spec: dict[str, t.Any] = {}
def add_option(self, *args, **kwargs) -> OptionGroup:
option = Option(*args, owner=self, **kwargs)
def add_option(self, name: str, **kwargs: t.Any) -> OptionGroup:
option = Option(name, owner=self, **kwargs)
if not option.not_a_container_option:
self.options.append(option)
self.all_options.append(option)
@@ -788,7 +790,7 @@ def _preprocess_mounts(
) -> dict[str, t.Any]:
last: dict[str, str] = {}
def check_collision(t, name):
def check_collision(t: str, name: str) -> None:
if t in last:
if name == last[t]:
module.fail_json(
@@ -1069,7 +1071,9 @@ def _preprocess_ports(
return values
def _compare_platform(option: Option, param_value: t.Any, container_value: t.Any):
def _compare_platform(
option: Option, param_value: t.Any, container_value: t.Any
) -> bool:
if option.comparison == "ignore":
return True
try:
plugins/module_utils/_module_container/docker_api.py
+9 -2
View File
@@ -872,7 +872,7 @@ class DockerAPIEngine(Engine[AnsibleDockerClient]):
image: dict[str, t.Any] | None,
values: dict[str, t.Any],
host_info: dict[str, t.Any] | None,
):
) -> dict[str, t.Any]:
if len(options) != 1:
raise AssertionError(
"host_config_value can only be used for a single option"
@@ -1961,7 +1961,14 @@ def _update_value_restart(
}
def _get_values_ports(module, container, api_version, options, image, host_info):
def _get_values_ports(
module: AnsibleModule,
container: dict[str, t.Any],
api_version: LooseVersion,
options: list[Option],
image: dict[str, t.Any] | None,
host_info: dict[str, t.Any] | None,
) -> dict[str, t.Any]:
host_config = container["HostConfig"]
config = container["Config"]
plugins/module_utils/_module_container/module.py
+4 -4
View File
@@ -292,7 +292,7 @@ class ContainerManager(DockerBaseClass, t.Generic[Client]):
if self.module.params[param] is None:
self.module.params[param] = value
def fail(self, *args, **kwargs) -> t.NoReturn:
def fail(self, *args: str, **kwargs: t.Any) -> t.NoReturn:
# mypy doesn't know that Client has fail() method
raise self.client.fail(*args, **kwargs) # type: ignore
@@ -714,7 +714,7 @@ class ContainerManager(DockerBaseClass, t.Generic[Client]):
container_image: dict[str, t.Any] | None,
image: dict[str, t.Any] | None,
host_info: dict[str, t.Any] | None,
):
) -> None:
assert container.raw is not None
container_values = engine.get_value(
self.module,
@@ -767,12 +767,12 @@ class ContainerManager(DockerBaseClass, t.Generic[Client]):
# Since the order does not matter, sort so that the diff output is better.
if option.name == "expected_mounts":
# For selected values, use one entry as key
def sort_key_fn(x):
def sort_key_fn(x: dict[str, t.Any]) -> t.Any:
return x["target"]
else:
# We sort the list of dictionaries by using the sorted items of a dict as its key.
def sort_key_fn(x):
def sort_key_fn(x: dict[str, t.Any]) -> t.Any:
return sorted(
(a, to_text(b, errors="surrogate_or_strict"))
for a, b in x.items()
plugins/module_utils/_socket_handler.py
+8 -2
View File
@@ -26,6 +26,7 @@ from ansible_collections.community.docker.plugins.module_utils._socket_helper im
if t.TYPE_CHECKING:
from collections.abc import Callable
from types import TracebackType
from ansible.module_utils.basic import AnsibleModule
@@ -70,7 +71,12 @@ class DockerSocketHandlerBase:
def __enter__(self) -> t.Self:
return self
def __exit__(self, type_, value, tb) -> None:
def __exit__(
self,
type_: t.Type[BaseException] | None,
value: BaseException | None,
tb: TracebackType | None,
) -> None:
self._selector.close()
def set_block_done_callback(
@@ -210,7 +216,7 @@ class DockerSocketHandlerBase:
stdout = []
stderr = []
def append_block(stream_id, data):
def append_block(stream_id: int, data: bytes) -> None:
if stream_id == docker_socket.STDOUT:
stdout.append(data)
elif stream_id == docker_socket.STDERR:
plugins/module_utils/_swarm.py
+1 -2
View File
@@ -28,7 +28,6 @@ from ansible_collections.community.docker.plugins.module_utils._version import (
class AnsibleDockerSwarmClient(AnsibleDockerClient):
def get_swarm_node_id(self) -> str | None:
"""
Get the 'NodeID' of the Swarm node or 'None' if host is not in Swarm. It returns the NodeID
@@ -281,7 +280,7 @@ class AnsibleDockerSwarmClient(AnsibleDockerClient):
def get_node_name_by_id(self, nodeid: str) -> str:
return self.get_node_inspect(nodeid)["Description"]["Hostname"]
def get_unlock_key(self) -> str | None:
def get_unlock_key(self) -> dict[str, t.Any] | None:
if self.docker_py_version < LooseVersion("2.7.0"):
return None
return super().get_unlock_key()
plugins/module_utils/_util.py
+9 -3
View File
@@ -23,6 +23,12 @@ if t.TYPE_CHECKING:
from ansible.module_utils.basic import AnsibleModule
from ._common import AnsibleDockerClientBase as CADCB
from ._common_api import AnsibleDockerClientBase as CAPIADCB
from ._common_cli import AnsibleDockerClientBase as CCLIADCB
Client = t.Union[CADCB, CAPIADCB, CCLIADCB]
DEFAULT_DOCKER_HOST = "unix:///var/run/docker.sock"
DEFAULT_TLS = False
@@ -119,7 +125,7 @@ def sanitize_result(data: t.Any) -> t.Any:
return data
def log_debug(msg: t.Any, pretty_print: bool = False):
def log_debug(msg: t.Any, pretty_print: bool = False) -> None:
"""Write a log message to docker.log.
If ``pretty_print=True``, the message will be pretty-printed as JSON.
@@ -325,7 +331,7 @@ class DifferenceTracker:
def sanitize_labels(
labels: dict[str, t.Any] | None,
labels_field: str,
client=None,
client: Client | None = None,
module: AnsibleModule | None = None,
) -> None:
def fail(msg: str) -> t.NoReturn:
@@ -371,7 +377,7 @@ def clean_dict_booleans_for_docker_api(
which is the expected format of filters which accept lists such as labels.
"""
def sanitize(value):
def sanitize(value: t.Any) -> str:
if value is True:
return "true"
if value is False: