diff --git a/.codeboarding/Authentication & Configuration.md b/.codeboarding/Authentication & Configuration.md new file mode 100644 index 000000000..810af148b --- /dev/null +++ b/.codeboarding/Authentication & Configuration.md @@ -0,0 +1,205 @@ +```mermaid +graph LR + AuthenticationManager["AuthenticationManager"] + CredentialStoreInterface["CredentialStoreInterface"] + DockerContextManager["DockerContextManager"] + APIClient["APIClient"] + DockerAPIMixins["DockerAPIMixins"] + UtilityFunctions["UtilityFunctions"] + ErrorHandling["ErrorHandling"] + TransportAdapters["TransportAdapters"] + TLSConfiguration["TLSConfiguration"] + DockerTypes["DockerTypes"] + APIClient -- "configures" --> TransportAdapters + APIClient -- "depends on" --> UtilityFunctions + APIClient -- "integrates with" --> AuthenticationManager + APIClient -- "reports" --> ErrorHandling + DockerAPIMixins -- "leverages" --> AuthenticationManager + DockerAPIMixins -- "utilizes" --> UtilityFunctions + DockerAPIMixins -- "defines/raises" --> ErrorHandling + DockerAPIMixins -- "operates on" --> DockerTypes + AuthenticationManager -- "accesses" --> CredentialStoreInterface + AuthenticationManager -- "relies on" --> UtilityFunctions + AuthenticationManager -- "generates" --> ErrorHandling + CredentialStoreInterface -- "can raise" --> ErrorHandling + DockerContextManager -- "configures" --> TLSConfiguration + DockerContextManager -- "uses" --> UtilityFunctions + DockerContextManager -- "produces" --> ErrorHandling +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the core components involved in Docker client operations, focusing on authentication, configuration, and daemon communication. The `APIClient` serves as the primary interface, establishing connections via `TransportAdapters` and managing authentication through the `AuthenticationManager`, which interacts with `CredentialStoreInterface` for secure credential handling. Docker contexts, defining connection parameters, are managed by the `DockerContextManager`, which also handles `TLSConfiguration`. Various `DockerAPIMixins` extend the client's capabilities for specific Docker resources, utilizing `UtilityFunctions` for common tasks. The `ErrorHandling` component provides a centralized mechanism for reporting issues across the system. + +### AuthenticationManager +Manages Docker authentication configurations, including loading from files, parsing credentials, resolving authentication details for specific registries, and encoding/decoding authentication headers. It interacts with credential stores to retrieve and store sensitive information. + + +**Related Classes/Methods**: + +- `docker.auth.AuthConfig` (75:306) +- `docker.auth.AuthConfig:load_config` (144:189) +- `docker.auth.get_config_header` (37:56) +- `docker.auth.load_config` (348:349) +- `docker.auth.resolve_authconfig` (309:312) +- `docker.auth.encode_header` (327:329) +- `docker.auth.AuthConfig:parse_auth` (84:141) +- `docker.auth.AuthConfig:resolve_authconfig` (209:242) +- `docker.auth.AuthConfig:_resolve_authconfig_credstore` (244:270) +- `docker.auth.AuthConfig:_get_store_instance` (272:277) +- `docker.auth.AuthConfig:get_all_credentials` (285:303) +- `docker.auth.AuthConfig:add_auth` (305:306) +- `docker.auth.resolve_index_name` (30:34) +- `docker.auth.convert_to_hostname` (315:316) +- `docker.auth.decode_auth` (319:324) +- `docker.auth.parse_auth` (332:345) +- `docker.auth._load_legacy_config` (352:378) + + +### CredentialStoreInterface +Provides an abstraction layer for interacting with external Docker credential helper programs, allowing the retrieval, storage, and listing of authentication credentials. + + +**Related Classes/Methods**: + +- `docker.credentials.store.Store` (11:93) +- `docker.credentials.store.Store:get` (26:44) +- `docker.credentials.store.Store:store` (46:55) +- `docker.credentials.store.Store:erase` (57:63) +- `docker.credentials.store.Store:list` (65:69) + + +### DockerContextManager +Handles the lifecycle and management of Docker contexts, which define connection parameters and configurations for different Docker daemon endpoints. This includes creating, loading, saving, inspecting, and removing contexts, as well as managing associated TLS certificates. + + +**Related Classes/Methods**: + +- `docker.context.context.Context` (16:249) +- `docker.context.context.Context:__init__` (19:60) +- `docker.context.context.Context:set_endpoint` (62:73) +- `docker.context.context.Context:inspect` (75:76) +- `docker.context.context.Context:load_context` (79:90) +- `docker.context.context.Context:_load_meta` (93:118) +- `docker.context.context.Context:_load_certs` (120:144) +- `docker.context.context.Context:save` (146:171) +- `docker.context.context.Context:__str__` (182:183) +- `docker.context.context.Context:remove` (173:177) +- `docker.context.api.ContextAPI` (15:206) +- `docker.context.api.ContextAPI:create_context` (23:70) +- `docker.context.api.ContextAPI:get_context` (73:98) +- `docker.context.api.ContextAPI:contexts` (101:125) +- `docker.context.api.ContextAPI:get_current_context` (128:133) +- `docker.context.api.ContextAPI:set_current_context` (136:144) +- `docker.context.api.ContextAPI:remove_context` (147:177) +- `docker.context.api.ContextAPI:inspect_context` (180:206) +- `docker.context.config.get_context_host` (75:81) +- `docker.context.config.get_meta_dir` (57:61) +- `docker.context.config.get_meta_file` (64:65) +- `docker.context.config.get_tls_dir` (68:72) +- `docker.context.config.get_current_context_name` (12:21) +- `docker.context.config.write_context_name_to_docker_config` (24:46) + + +### APIClient +The core client component responsible for establishing and managing connections to the Docker daemon. It handles initial configuration loading, proxy settings, transport layer selection (Unix socket, Npipe, SSH), and server version negotiation. + + +**Related Classes/Methods**: + +- `docker.api.client.APIClient` (57:532) +- `docker.api.client.APIClient:__init__` (115:219) +- `docker.api.client.APIClient:reload_config` (518:532) +- `docker.api.client.APIClient._unmount` (501:503) +- `docker.api.client.APIClient._retrieve_server_version` (221:232) + + +### DockerAPIMixins +A collection of mixin classes that extend the core API client with specific functionalities for interacting with different Docker resources, such as daemon, build, plugin, service, and image operations. These mixins often integrate with authentication and utility functions. + + +**Related Classes/Methods**: + +- `docker.api.daemon.DaemonApiMixin:login` (97:152) +- `docker.api.build.BuildApiMixin:_set_auth_headers` (321:352) +- `docker.api.plugin.PluginApiMixin:pull_plugin` (106:141) +- `docker.api.plugin.PluginApiMixin:plugin_privileges` (155:181) +- `docker.api.plugin.PluginApiMixin:push_plugin` (185:205) +- `docker.api.plugin.PluginApiMixin:upgrade_plugin` (229:261) +- `docker.api.service.ServiceApiMixin:create_service` (116:189) +- `docker.api.service.ServiceApiMixin:update_service` (369:486) +- `docker.api.service.ServiceApiMixin.inspect_service` (193:219) +- `docker.api.service._check_api_features` (5:96) +- `docker.api.service._merge_task_template` (99:111) +- `docker.api.image.ImageApiMixin:inspect_distribution` (257:289) +- `docker.api.image.ImageApiMixin:pull` (351:434) +- `docker.api.image.ImageApiMixin:push` (436:500) + + +### UtilityFunctions +Provides a set of general-purpose helper functions used across the docker-py library for tasks such as configuration file discovery, proxy settings parsing, version comparison, and decorator application for API methods. + + +**Related Classes/Methods**: + +- `docker.utils.config.find_config_file` (13:30) +- `docker.utils.config.load_general_config` (51:66) +- `docker.utils.proxy.ProxyConfig.from_dict` (25:38) +- `docker.utils.utils.parse_host` (233:321) +- `docker.utils.utils.version_lt` (77:78) +- `docker.utils.utils.convert_service_networks` (209:220) +- `docker.utils.utils` (full file reference) +- `docker.utils.decorators.minimum_version` (24:34) +- `docker.utils.decorators.check_resource` (7:21) + + +### ErrorHandling +Centralized component for defining and raising specific exceptions related to Docker operations, configuration issues, authentication failures, and context management. + + +**Related Classes/Methods**: + +- `docker.errors.InvalidConfigFile` (108:109) +- `docker.errors.DockerException` (13:19) +- `docker.credentials.errors.CredentialsNotFound` (5:6) +- `docker.errors.ContextException` (196:201) +- `docker.errors.MissingContextParameter` (180:185) +- `docker.errors.ContextAlreadyExists` (188:193) +- `docker.errors.ContextNotFound` (204:209) +- `docker.errors.TLSParameterError` (120:128) +- `docker.errors.InvalidVersion` (100:101) + + +### TransportAdapters +Manages the underlying HTTP transport mechanisms for communicating with the Docker daemon, supporting various connection types like Unix sockets, named pipes (Npipe), and SSH. + + +**Related Classes/Methods**: + +- `docker.transport.unixconn.UnixHTTPAdapter` (45:86) +- `docker.transport.npipeconn.NpipeHTTPAdapter` (64:102) +- `docker.transport.sshconn.SSHHTTPAdapter` (159:250) + + +### TLSConfiguration +Handles the configuration and management of Transport Layer Security (TLS) settings for secure communication with the Docker daemon. + + +**Related Classes/Methods**: + +- `docker.tls.TLSConfig` (6:67) + + +### DockerTypes +Defines data structures and models for various Docker objects, such as service modes, used in API interactions. + + +**Related Classes/Methods**: + +- `docker.types.services.ServiceMode` (595:660) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Build System.md b/.codeboarding/Build System.md new file mode 100644 index 000000000..a0f29681f --- /dev/null +++ b/.codeboarding/Build System.md @@ -0,0 +1,111 @@ +```mermaid +graph LR + Build_System["Build System"] + Build_Context_Preparation["Build Context Preparation"] + Authentication_Management["Authentication Management"] + API_Versioning_and_Decorators["API Versioning and Decorators"] + Stream_Processing["Stream Processing"] + Error_Handling["Error Handling"] + Build_System -- "Orchestrates" --> Build_Context_Preparation + Build_System -- "Utilizes" --> Authentication_Management + Build_System -- "Processes Output Via" --> Stream_Processing + Build_System -- "Raises" --> Error_Handling + Build_System -- "Enforces Compatibility Via" --> API_Versioning_and_Decorators + Build_Context_Preparation -- "Uses" --> Fnmatch_Utilities +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the core components and their interactions within the `docker-py` library's build system. The primary flow revolves around the `Build System` component, which orchestrates the entire image building process. It relies on `Build Context Preparation` to create the necessary build context, `Authentication Management` for handling registry credentials, and `Stream Processing` to interpret the real-time output from the Docker daemon. `API Versioning and Decorators` ensure compatibility with different Docker API versions, while `Error Handling` provides structured error reporting for various build-related issues. + +### Build System +Manages the end-to-end process of building Docker images, including orchestrating context preparation, applying authentication, and processing build output streams. It serves as the primary interface for image creation within the `docker-py` library. + + +**Related Classes/Methods**: + +- `docker-py.docker.api.build.BuildApiMixin` (11:352) +- `docker-py.docker.api.build.BuildApiMixin:build` (12:275) +- `docker-py.docker.api.build.BuildApiMixin:_set_auth_headers` (321:352) +- `docker-py.docker.api.build.process_dockerfile` (355:382) +- `docker-py.docker.models.images.ImageCollection:build` (220:315) + + +### Build Context Preparation +Responsible for preparing the local build context for Docker image creation. This includes archiving the necessary files and directories, applying exclusion rules from `.dockerignore`, and ensuring the context is ready for transmission to the Docker daemon. + + +**Related Classes/Methods**: + +- `docker-py.docker.utils.build:create_archive` (70:120) +- `docker-py.docker.utils.build:exclude_paths` (41:55) +- `docker-py.docker.utils.build:tar` (22:38) +- `docker-py.docker.utils.build.PatternMatcher` (159:219) +- `docker-py.docker.utils.build.PatternMatcher:matches` (166:183) +- `docker-py.docker.utils.build.build_file_list` (58:67) +- `docker-py.docker.utils.build.mkbuildcontext` (123:139) +- `docker-py.docker.utils.fnmatch:fnmatch` (26:44) +- `docker-py.docker.utils.fnmatch:fnmatchcase` (47:60) +- `docker-py.docker.utils.fnmatch:translate` (63:115) + + +### Authentication Management +Handles the loading, parsing, and resolution of Docker authentication configurations. It provides mechanisms to retrieve credentials from various sources and format them for inclusion in API requests, particularly for pulling base images during a build. + + +**Related Classes/Methods**: + +- `docker-py.docker.auth:load_config` (348:349) +- `docker-py.docker.auth.AuthConfig` (75:306) +- `docker-py.docker.auth.AuthConfig.load_config` (144:189) +- `docker-py.docker.auth.AuthConfig.get_all_credentials` (285:303) +- `docker-py.docker.auth.AuthConfig._get_store_instance` (272:277) +- `docker-py.docker.auth.AuthConfig._resolve_authconfig_credstore` (244:270) +- `docker-py.docker.auth.convert_to_hostname` (315:316) +- `docker-py.docker.auth.encode_header` (327:329) +- `docker-py.docker.auth.resolve_authconfig` (309:312) +- `docker-py.docker.auth.decode_auth` (319:324) +- `docker-py.docker.auth.parse_auth` (332:345) +- `docker-py.docker.auth._load_legacy_config` (352:378) + + +### API Versioning and Decorators +Provides utilities for comparing Docker API versions and implements decorators to enforce minimum API versions for client methods. This ensures that API calls are compatible with the connected Docker daemon and handles version-specific behaviors. + + +**Related Classes/Methods**: + +- `docker-py.docker.utils.utils:version_lt` (77:78) +- `docker-py.docker.utils.utils:version_gte` (81:82) +- `docker-py.docker.utils.utils:compare_version` (49:74) +- `docker-py.docker.utils.decorators:minimum_version` (24:34) + + +### Stream Processing +Manages the parsing and handling of streaming data, particularly JSON streams, received from the Docker daemon. This component is crucial for processing real-time output during long-running operations like image builds, enabling progress reporting and error detection. + + +**Related Classes/Methods**: + +- `docker-py.docker.utils.json_stream:json_stream` (35:40) +- `docker-py.docker.utils.json_stream:split_buffer` (50:74) +- `docker-py.docker.utils.json_stream.stream_as_text` (9:19) +- `docker-py.docker.utils.json_stream.line_splitter` (43:47) + + +### Error Handling +Defines a hierarchy of custom exception classes used throughout the `docker-py` library. These exceptions represent specific error conditions encountered during interactions with the Docker daemon or due to invalid client-side operations, providing structured error reporting. + + +**Related Classes/Methods**: + +- `docker-py.docker.errors.InvalidVersion` (100:101) +- `docker-py.docker.errors.DockerException` (13:19) +- `docker-py.docker.errors.StreamParseError` (153:155) +- `docker-py.docker.errors.BuildError` (158:162) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Daemon & Exec Operations.md b/.codeboarding/Daemon & Exec Operations.md new file mode 100644 index 000000000..6d49bf8a9 --- /dev/null +++ b/.codeboarding/Daemon & Exec Operations.md @@ -0,0 +1,140 @@ +```mermaid +graph LR + Daemon_API_Handler["Daemon API Handler"] + Exec_API_Handler["Exec API Handler"] + Core_Docker_Client["Core Docker Client"] + General_Utilities["General Utilities"] + Authentication_Manager["Authentication Manager"] + Stream_Types["Stream Types"] + API_Error_Handling["API Error Handling"] + API_Decorators["API Decorators"] + Container_Object_Model["Container Object Model"] + Execution_Result_Model["Execution Result Model"] + Core_Docker_Client -- "delegates to" --> Daemon_API_Handler + Core_Docker_Client -- "delegates to" --> Exec_API_Handler + Daemon_API_Handler -- "uses" --> General_Utilities + Daemon_API_Handler -- "returns/uses" --> Stream_Types + Daemon_API_Handler -- "uses" --> Authentication_Manager + Exec_API_Handler -- "uses" --> API_Decorators + Exec_API_Handler -- "uses" --> General_Utilities + Exec_API_Handler -- "raises" --> API_Error_Handling + Exec_API_Handler -- "returns/uses" --> Stream_Types + Container_Object_Model -- "returns" --> Execution_Result_Model + Container_Object_Model -- "uses" --> Exec_API_Handler +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This component overview describes the structure and interactions of the Docker daemon and execution operations subsystem. It details how the core client interacts with dedicated API handlers for daemon-level information and container command execution, leveraging various utility and model components for authentication, data streaming, error handling, and object representation. + +### Daemon API Handler +Manages interactions with the Docker daemon for system-level information, real-time events, and user authentication. + + +**Related Classes/Methods**: + +- `docker.api.daemon.DaemonApiMixin` (7:181) +- `docker.api.daemon.DaemonApiMixin:info` (83:95) +- `docker.api.daemon.DaemonApiMixin:events` (24:81) +- `docker.api.daemon.DaemonApiMixin:login` (97:152) + + +### Exec API Handler +Provides functionalities for creating and starting execution commands within Docker containers. + + +**Related Classes/Methods**: + +- `docker.api.exec_api.ExecApiMixin` (5:176) +- `docker.api.exec_api.ExecApiMixin:exec_create` (7:78) +- `docker.api.exec_api.ExecApiMixin:exec_start` (118:176) + + +### Core Docker Client +The primary entry point for users to interact with the Docker API, abstracting underlying API calls and delegating to specific API handlers. + + +**Related Classes/Methods**: + +- `docker.client.DockerClient` (16:219) +- `docker.client.DockerClient:events` (184:185) +- `docker.client.DockerClient:info` (192:193) +- `docker.client.DockerClient:login` (196:197) + + +### General Utilities +A collection of helper functions for data manipulation, filtering, command parsing, environment formatting, and version comparisons. + + +**Related Classes/Methods**: + +- `docker.utils.utils` (1:206) +- `docker.utils.utils.datetime_to_timestamp` (405:408) +- `docker.utils.utils.convert_filters` (391:402) +- `docker.utils.utils.version_lt` (77:78) +- `docker.utils.utils.split_command` (486:487) +- `docker.utils.utils.format_environment` (490:498) + + +### Authentication Manager +Handles the loading, resolution, and management of Docker registry authentication configurations. + + +**Related Classes/Methods**: + +- `docker.auth.load_config` (348:349) +- `docker.auth.AuthConfig` (75:306) +- `docker.auth.AuthConfig.resolve_authconfig` (209:242) +- `docker.auth.AuthConfig.add_auth` (305:306) + + +### Stream Types +Defines specialized data structures for managing cancellable data streams, typically used for real-time event monitoring. + + +**Related Classes/Methods**: + +- `docker.types.daemon.CancellableStream` (8:71) + + +### API Error Handling +Provides specific error classes for handling exceptions related to Docker API version compatibility. + + +**Related Classes/Methods**: + +- `docker.errors.InvalidVersion` (100:101) + + +### API Decorators +Contains utility decorators used to apply common checks or transformations to API methods, such as resource validation. + + +**Related Classes/Methods**: + +- `docker.utils.decorators.check_resource` (7:21) + + +### Container Object Model +Represents a Docker container object and offers methods to perform operations directly on a container instance, like executing commands. + + +**Related Classes/Methods**: + +- `docker.models.containers.Container` (20:529) +- `docker.models.containers.Container:exec_run` (167:224) + + +### Execution Result Model +Encapsulates the outcome of an execution command performed within a Docker container. + + +**Related Classes/Methods**: + +- `docker.models.containers.ExecResult` (5:8) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Data Models & Utilities.md b/.codeboarding/Data Models & Utilities.md new file mode 100644 index 000000000..60657ce59 --- /dev/null +++ b/.codeboarding/Data Models & Utilities.md @@ -0,0 +1,261 @@ +```mermaid +graph LR + ClientCore["ClientCore"] + APIMixins["APIMixins"] + DockerDataTypes["DockerDataTypes"] + UtilityFunctions["UtilityFunctions"] + ErrorHandling["ErrorHandling"] + HighLevelModels["HighLevelModels"] + ClientCore -- "uses" --> UtilityFunctions + ClientCore -- "raises" --> ErrorHandling + ClientCore -- "uses" --> DockerDataTypes + APIMixins -- "uses" --> UtilityFunctions + APIMixins -- "creates/configures" --> DockerDataTypes + APIMixins -- "raises" --> ErrorHandling + DockerDataTypes -- "uses" --> UtilityFunctions + DockerDataTypes -- "raises" --> ErrorHandling + DockerDataTypes -- "uses" --> DockerDataTypes + UtilityFunctions -- "invokes" --> UtilityFunctions + UtilityFunctions -- "raises" --> ErrorHandling + HighLevelModels -- "uses" --> APIMixins + HighLevelModels -- "uses" --> DockerDataTypes + HighLevelModels -- "uses" --> UtilityFunctions + HighLevelModels -- "raises" --> ErrorHandling +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +The docker-py library provides a Pythonic interface to the Docker Engine API. The core functionality revolves around the ClientCore component, which establishes and manages connections to the Docker daemon. APIMixins then provide direct interaction with various Docker API endpoints, allowing for operations on containers, images, and volumes. DockerDataTypes define the structured data used for these API interactions, ensuring correct data formatting. UtilityFunctions offer a set of helper functions for common tasks like data parsing, version comparisons, and file handling, supporting both ClientCore and APIMixins. ErrorHandling centralizes custom exceptions for robust error management across the library. Finally, HighLevelModels build upon APIMixins to provide more abstract and user-friendly interfaces for common Docker operations. + +### ClientCore +Manages the fundamental connection and configuration with the Docker daemon, including TLS settings, context loading, and establishing communication channels (Unix sockets, Npipe, SSH). It also handles initial server version retrieval and proxy configurations. + + +**Related Classes/Methods**: + +- `docker.client.DockerClient:from_env` (48:100) +- `docker.tls.TLSConfig:__init__` (21:55) +- `docker.context.context.Context:_load_certs` (120:144) +- `docker.context.config:get_context_host` (75:81) +- `docker.api.client.APIClient:__init__` (115:219) +- `docker.api.client.APIClient:_stream_helper` (355:374) +- `docker.api.client.APIClient:_read_from_socket` (424:447) +- `docker.api.client.APIClient:_check_is_tty` (478:480) + + +### APIMixins +Provides a structured interface for interacting with various Docker API endpoints. These mixins encapsulate the logic for making API calls related to volumes, plugins, secrets, swarm, services, daemon, build, exec, network, config, containers, and images. + + +**Related Classes/Methods**: + +- `docker.api.volume.VolumeApiMixin:volumes` (5:36) +- `docker.api.volume.VolumeApiMixin:create_volume` (38:91) +- `docker.api.volume.VolumeApiMixin:prune_volumes` (119:138) +- `docker.api.volume.VolumeApiMixin:remove_volume` (140:163) +- `docker.api.plugin.PluginApiMixin:configure_plugin` (7:25) +- `docker.api.plugin.PluginApiMixin:create_plugin` (28:51) +- `docker.api.plugin.PluginApiMixin:disable_plugin` (54:69) +- `docker.api.plugin.PluginApiMixin:enable_plugin` (72:88) +- `docker.api.plugin.PluginApiMixin:inspect_plugin` (91:103) +- `docker.api.plugin.PluginApiMixin:plugins` (144:152) +- `docker.api.plugin.PluginApiMixin:push_plugin` (185:205) +- `docker.api.plugin.PluginApiMixin:remove_plugin` (209:225) +- `docker.api.plugin.PluginApiMixin:upgrade_plugin` (229:261) +- `docker.api.secret.SecretApiMixin:create_secret` (8:43) +- `docker.api.secret.SecretApiMixin:inspect_secret` (47:61) +- `docker.api.secret.SecretApiMixin:remove_secret` (65:81) +- `docker.api.secret.SecretApiMixin:secrets` (84:98) +- `docker.api.swarm.SwarmApiMixin:create_swarm_spec` (12:71) +- `docker.api.swarm.SwarmApiMixin:get_unlock_key` (74:81) +- `docker.api.swarm.SwarmApiMixin:init_swarm` (84:180) +- `docker.api.swarm.SwarmApiMixin:inspect_swarm` (183:195) +- `docker.api.swarm.SwarmApiMixin:inspect_node` (199:214) +- `docker.api.swarm.SwarmApiMixin:join_swarm` (217:265) +- `docker.api.swarm.SwarmApiMixin:leave_swarm` (268:293) +- `docker.api.swarm.SwarmApiMixin:nodes` (296:317) +- `docker.api.swarm.SwarmApiMixin:remove_node` (321:344) +- `docker.api.swarm.SwarmApiMixin:unlock_swarm` (347:380) +- `docker.api.swarm.SwarmApiMixin:update_node` (383:416) +- `docker.api.swarm.SwarmApiMixin:update_swarm` (419:462) +- `docker.api.service._check_api_features` (5:96) +- `docker.api.service.ServiceApiMixin:create_service` (116:189) +- `docker.api.service.ServiceApiMixin:inspect_service` (193:219) +- `docker.api.service.ServiceApiMixin:inspect_task` (223:238) +- `docker.api.service.ServiceApiMixin:remove_service` (242:260) +- `docker.api.service.ServiceApiMixin:services` (263:291) +- `docker.api.service.ServiceApiMixin:tasks` (344:365) +- `docker.api.service.ServiceApiMixin:update_service` (369:486) +- `docker.api.daemon.DaemonApiMixin:df` (9:22) +- `docker.api.daemon.DaemonApiMixin:events` (24:81) +- `docker.api.build.BuildApiMixin:build` (12:275) +- `docker.api.build.BuildApiMixin:prune_builds` (278:319) +- `docker.api.exec_api.ExecApiMixin:exec_create` (7:78) +- `docker.api.exec_api.ExecApiMixin:exec_start` (118:176) +- `docker.api.network.NetworkApiMixin:networks` (7:38) +- `docker.api.network.NetworkApiMixin:create_network` (40:152) +- `docker.api.network.NetworkApiMixin:prune_networks` (155:174) +- `docker.api.network.NetworkApiMixin:inspect_network` (189:212) +- `docker.api.network.NetworkApiMixin:disconnect_container_from_network` (256:277) +- `docker.api.config.ConfigApiMixin:create_config` (8:37) +- `docker.api.config.ConfigApiMixin:inspect_config` (41:55) +- `docker.api.config.ConfigApiMixin:remove_config` (59:75) +- `docker.api.config.ConfigApiMixin:configs` (78:92) +- `docker.api.container.ContainerApiMixin:attach` (16:67) +- `docker.api.container.ContainerApiMixin:commit` (115:150) +- `docker.api.container.ContainerApiMixin:containers` (152:219) +- `docker.api.container.ContainerApiMixin:create_container` (221:440) +- `docker.api.container.ContainerApiMixin:create_container_config` (442:443) +- `docker.api.container.ContainerApiMixin:create_container_from_config` (445:457) +- `docker.api.container.ContainerApiMixin:create_host_config` (459:617) +- `docker.api.container.ContainerApiMixin:create_networking_config` (619:643) +- `docker.api.container.ContainerApiMixin:create_endpoint_config` (645:679) +- `docker.api.container.ContainerApiMixin:diff` (682:699) +- `docker.api.container.ContainerApiMixin:export` (702:722) +- `docker.api.container.ContainerApiMixin:get_archive` (725:775) +- `docker.api.container.ContainerApiMixin:inspect_container` (778:795) +- `docker.api.container.ContainerApiMixin:kill` (798:818) +- `docker.api.container.ContainerApiMixin:logs` (821:901) +- `docker.api.container.ContainerApiMixin:pause` (904:917) +- `docker.api.container.ContainerApiMixin:port` (920:967) +- `docker.api.container.ContainerApiMixin:put_archive` (970:992) +- `docker.api.container.ContainerApiMixin:prune_containers` (995:1014) +- `docker.api.container.ContainerApiMixin:remove_container` (1017:1037) +- `docker.api.container.ContainerApiMixin:rename` (1040:1055) +- `docker.api.container.ContainerApiMixin:resize` (1058:1074) +- `docker.api.container.ContainerApiMixin:restart` (1077:1098) +- `docker.api.container.ContainerApiMixin:start` (1101:1136) +- `docker.api.container.ContainerApiMixin:stats` (1139:1184) +- `docker.api.container.ContainerApiMixin:stop` (1187:1212) +- `docker.api.container.ContainerApiMixin:top` (1215:1234) +- `docker.api.container.ContainerApiMixin:unpause` (1237:1246) +- `docker.api.container.ContainerApiMixin:update_container` (1250:1312) +- `docker.api.container.ContainerApiMixin:wait` (1315:1348) +- `docker.api.image.ImageApiMixin:images` (59:100) +- `docker.api.image.ImageApiMixin:load_image` (291:324) +- `docker.api.image.ImageApiMixin:prune_images` (327:349) +- `docker.api.image.ImageApiMixin:pull` (351:434) +- `docker.api.image.ImageApiMixin:push` (436:500) + + +### DockerDataTypes +Defines the Python classes and structures that represent various Docker objects and their configurations, such as container host configurations, network endpoint configurations, swarm specifications, and service definitions. These types are used to construct and validate data sent to the Docker API. + + +**Related Classes/Methods**: + +- `docker.tls.TLSConfig` (6:67) +- `docker.types.containers.HostConfig` (264:662) +- `docker.types.containers.LogConfig:__init__` (66:76) +- `docker.types.containers.Ulimit:__init__` (125:139) +- `docker.types.containers.DeviceRequest:__init__` (187:221) +- `docker.types.containers.HostConfig:__init__` (265:662) +- `docker.types.containers:host_config_version_error` (672:676) +- `docker.types.containers:host_config_incompatible_error` (682:685) +- `docker.types.containers.ContainerConfig:__init__` (689:790) +- `docker.types.swarm.SwarmSpec:__init__` (11:94) +- `docker.types.healthcheck.Healthcheck:__init__` (30:46) +- `docker.types.daemon.CancellableStream:close` (37:71) +- `docker.types.networks.EndpointConfig:__init__` (6:51) +- `docker.types.services.TaskTemplate:__init__` (37:57) +- `docker.types.services.ContainerSpec:__init__` (126:218) +- `docker.types.services.Mount:__init__` (249:306) +- `docker.types.services.Mount:parse_mount_string` (309:330) +- `docker.types.services.Resources:__init__` (350:369) +- `docker.types.services:_convert_generic_resources_dict` (372:395) +- `docker.types.services.UpdateConfig:__init__` (421:451) +- `docker.types.services.EndpointSpec:__init__` (555:559) +- `docker.types.services.ServiceMode:__init__` (608:640) +- `docker.types.services.SecretReference:__init__` (679:688) +- `docker.types.services.ConfigReference:__init__` (707:716) +- `docker.types.services.Placement:__init__` (735:752) +- `docker.types.services.PlacementPreference:__init__` (768:774) +- `docker.types.services.Privileges:__init__` (821:848) + + +### UtilityFunctions +A comprehensive collection of helper functions that provide common utilities across the docker-py library. This includes functions for parsing various data formats, comparing Docker API versions, handling file system operations for builds, managing network ports, and applying decorators for common checks. + + +**Related Classes/Methods**: + +- `docker.utils.utils` (10:500) +- `docker.utils.json_stream:json_stream` (35:40) +- `docker.utils.socket:read_exactly` (62:73) +- `docker.utils.socket:next_frame_header` (76:89) +- `docker.utils.socket:frames_iter` (92:103) +- `docker.utils.socket:frames_iter_no_tty` (106:124) +- `docker.utils.socket:frames_iter_tty` (127:137) +- `docker.utils.ports:add_port` (22:29) +- `docker.utils.ports:build_port_bindings` (32:37) +- `docker.utils.ports:split_port` (56:83) +- `docker.utils.fnmatch:fnmatch` (26:44) +- `docker.utils.fnmatch:fnmatchcase` (47:60) +- `docker.utils.decorators:check_resource` (7:21) +- `docker.utils.decorators:minimum_version` (24:34) +- `docker.utils.build:tar` (22:38) +- `docker.utils.build:exclude_paths` (41:55) +- `docker.utils.build:create_archive` (70:120) +- `docker.utils.build:normalize_slashes` (146:149) +- `docker.utils.build:walk` (152:154) +- `docker.utils.build.PatternMatcher:__init__` (160:164) +- `docker.utils.build.PatternMatcher:matches` (166:183) +- `docker.utils.build.PatternMatcher:walk` (185:219) +- `docker.utils.build.Pattern:__init__` (223:230) +- `docker.utils.build.Pattern:normalize` (233:257) +- `docker.utils.build.Pattern:match` (259:260) +- `docker.utils.proxy.ProxyConfig:from_dict` (25:38) +- `docker.utils.proxy.ProxyConfig:inject_proxy_environment` (56:69) +- `docker.utils.config:find_config_file` (13:30) +- `docker.utils.config:load_general_config` (51:66) +- `docker.utils.json_stream:json_stream` (35:40) +- `docker.utils.json_stream:split_buffer` (50:74) +- `docker.utils.utils:create_ipam_pool` (28:32) +- `docker.utils.utils:create_ipam_config` (35:39) +- `docker.utils.utils:version_lt` (77:78) +- `docker.utils.utils:version_gte` (81:82) +- `docker.utils.utils:convert_port_bindings` (113:123) +- `docker.utils.utils:parse_host` (233:321) +- `docker.utils.utils:parse_devices` (324:350) +- `docker.utils.utils:kwargs_from_env` (353:388) +- `docker.utils.utils:parse_bytes` (411:448) +- `docker.utils.utils:parse_env_file` (458:483) +- `docker.utils.utils:format_environment` (490:498) +- `docker.utils.utils:create_host_config` (513:517) + + +### ErrorHandling +Defines custom exceptions to manage and propagate specific errors encountered during Docker operations. This component centralizes error types, allowing for more granular error handling and clearer communication of issues within the library. + + +**Related Classes/Methods**: + +- `docker.errors.TLSParameterError` (120:128) +- `docker.errors.InvalidVersion` (100:101) +- `docker.errors.InvalidArgument` (112:113) +- `docker.errors.DockerException` (13:19) +- `docker.errors.NullResource` (131:132) +- `docker.errors.DeprecatedMethod` (116:117) +- `docker.errors.StreamParseError` (153:155) +- `docker.errors.ContainerError` (135:150) +- `docker.errors.BuildError` (158:162) + + +### HighLevelModels +Provides higher-level abstractions and convenience methods for managing Docker resources, building upon the lower-level API Mixins. These models simplify common operations like running containers, building images, and listing networks, offering a more object-oriented interface. + + +**Related Classes/Methods**: + +- `docker.models.containers.ContainerCollection:run` (535:912) +- `docker.models.containers:_create_container_args` (1123:1182) +- `docker.models.images.RegistryData:pull` (165:177) +- `docker.models.images.ImageCollection:build` (220:315) +- `docker.models.images.ImageCollection:pull` (415:475) +- `docker.models.networks.NetworkCollection:list` (185:214) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Docker Resource Management.md b/.codeboarding/Docker Resource Management.md new file mode 100644 index 000000000..55d920fca --- /dev/null +++ b/.codeboarding/Docker Resource Management.md @@ -0,0 +1,135 @@ +```mermaid +graph LR + DockerClient["DockerClient"] + ContainerManager["ContainerManager"] + ImageManager["ImageManager"] + NetworkManager["NetworkManager"] + VolumeManager["VolumeManager"] + SwarmManager["SwarmManager"] + ServiceManager["ServiceManager"] + PluginManager["PluginManager"] + SecretManager["SecretManager"] + ConfigManager["ConfigManager"] + DockerClient -- "manages" --> ContainerManager + DockerClient -- "manages" --> ImageManager + DockerClient -- "manages" --> NetworkManager + DockerClient -- "manages" --> VolumeManager + DockerClient -- "manages" --> SwarmManager + DockerClient -- "manages" --> ServiceManager + DockerClient -- "manages" --> PluginManager + DockerClient -- "manages" --> SecretManager + DockerClient -- "manages" --> ConfigManager +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the architecture of the Docker Resource Management subsystem within the `docker-py` library. The `DockerClient` acts as the central entry point, managing various Docker resources through dedicated manager components such as `ContainerManager`, `ImageManager`, `NetworkManager`, `VolumeManager`, `SwarmManager`, `ServiceManager`, `PluginManager`, `SecretManager`, and `ConfigManager`. Each manager component is responsible for the lifecycle and operations of its specific Docker resource type. + +### DockerClient +The primary interface for interacting with the Docker daemon. It provides access to various Docker resources (containers, images, networks, volumes, etc.) through dedicated collection objects. + + +**Related Classes/Methods**: + +- `docker.client.DockerClient` (16:219) + + +### ContainerManager +Handles operations related to Docker containers, including creation, listing, inspection, starting, stopping, removing, and executing commands within containers. It interacts with the Docker API for container-specific actions. + + +**Related Classes/Methods**: + +- `docker.api.container.ContainerApiMixin` (14:1348) +- `docker.models.containers.ContainerCollection` (532:1029) +- `docker.models.containers.Container` (20:529) + + +### ImageManager +Manages Docker images, supporting operations like building, pulling, pushing, listing, inspecting, and removing images. It interacts with the Docker API for image-specific actions and handles image-related data. + + +**Related Classes/Methods**: + +- `docker.api.image.ImageApiMixin` (10:572) +- `docker.models.images.ImageCollection` (217:495) +- `docker.models.images.Image` (13:139) +- `docker.models.images.RegistryData` (142:214) + + +### NetworkManager +Provides functionalities for managing Docker networks, including creating, listing, inspecting, and removing networks, as well as connecting and disconnecting containers from networks. + + +**Related Classes/Methods**: + +- `docker.api.network.NetworkApiMixin` (6:277) +- `docker.models.networks.NetworkCollection` (94:218) + + +### VolumeManager +Manages Docker volumes, enabling operations such as creating, listing, inspecting, and removing volumes. + + +**Related Classes/Methods**: + +- `docker.api.volume.VolumeApiMixin` (4:163) +- `docker.models.volumes.VolumeCollection` (28:99) + + +### SwarmManager +Facilitates the management of Docker Swarm, including initializing, joining, leaving, inspecting, and updating swarm nodes and the swarm itself. + + +**Related Classes/Methods**: + +- `docker.api.swarm.SwarmApiMixin` (10:462) +- `docker.models.swarm.Swarm` (7:190) + + +### ServiceManager +Handles Docker Swarm services, allowing for creation, listing, inspection, updating, and removal of services, as well as managing service tasks. + + +**Related Classes/Methods**: + +- `docker.api.service.ServiceApiMixin` (114:486) +- `docker.models.services.ServiceCollection` (146:284) +- `docker.models.services.Service` (9:143) + + +### PluginManager +Manages Docker plugins, supporting operations like configuring, creating, disabling, enabling, inspecting, pulling, pushing, and removing plugins. + + +**Related Classes/Methods**: + +- `docker.api.plugin.PluginApiMixin` (4:261) +- `docker.models.plugins.PluginCollection` (131:206) +- `docker.models.plugins.Plugin` (5:128) + + +### SecretManager +Manages Docker secrets, providing functionalities for creating, inspecting, and removing secrets within a Docker Swarm. + + +**Related Classes/Methods**: + +- `docker.api.secret.SecretApiMixin` (6:98) +- `docker.models.secrets.SecretCollection` (27:70) + + +### ConfigManager +Manages Docker configurations (configs), allowing for creation, inspection, and removal of configurations within a Docker Swarm. + + +**Related Classes/Methods**: + +- `docker.api.config.ConfigApiMixin` (6:92) +- `docker.models.configs.ConfigCollection` (27:70) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Error Handling.md b/.codeboarding/Error Handling.md new file mode 100644 index 000000000..9b13512b5 --- /dev/null +++ b/.codeboarding/Error Handling.md @@ -0,0 +1,288 @@ +```mermaid +graph LR + Error_Handling["Error Handling"] + TLS_and_Authentication["TLS and Authentication"] + Utility_Functions["Utility Functions"] + Docker_Context_Management["Docker Context Management"] + Docker_Type_Definitions["Docker Type Definitions"] + Docker_API_Client["Docker API Client"] + Volume_API["Volume API"] + Secret_API["Secret API"] + Swarm_API["Swarm API"] + Service_API["Service API"] + Build_API["Build API"] + Exec_API["Exec API"] + Network_API["Network API"] + Container_API["Container API"] + Image_API["Image API"] + High_Level_Models["High-Level Models"] + TLS_and_Authentication -- "raises" --> Error_Handling + Utility_Functions -- "raises" --> Error_Handling + Docker_Context_Management -- "raises" --> Error_Handling + Docker_Type_Definitions -- "raises" --> Error_Handling + Docker_API_Client -- "raises" --> Error_Handling + Volume_API -- "raises" --> Error_Handling + Secret_API -- "raises" --> Error_Handling + Swarm_API -- "raises" --> Error_Handling + Service_API -- "raises" --> Error_Handling + Build_API -- "raises" --> Error_Handling + Exec_API -- "raises" --> Error_Handling + Network_API -- "raises" --> Error_Handling + Container_API -- "raises" --> Error_Handling + Image_API -- "raises" --> Error_Handling + High_Level_Models -- "raises" --> Error_Handling + Docker_API_Client -- "uses" --> TLS_and_Authentication + Volume_API -- "utilizes" --> Docker_API_Client + Secret_API -- "utilizes" --> Docker_API_Client + Swarm_API -- "utilizes" --> Docker_API_Client + Service_API -- "utilizes" --> Docker_API_Client + Build_API -- "utilizes" --> Docker_API_Client + Exec_API -- "utilizes" --> Docker_API_Client + Network_API -- "utilizes" --> Docker_API_Client + Container_API -- "utilizes" --> Docker_API_Client + Image_API -- "utilizes" --> Docker_API_Client + High_Level_Models -- "utilizes" --> Docker_API_Client +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the architecture of the Docker SDK for Python, focusing on its core components and their interactions. The system is designed around a central `Docker API Client` that facilitates communication with the Docker daemon. Various API-specific components (e.g., `Volume API`, `Container API`) utilize this client to perform Docker operations. Error handling is centralized in the `Error Handling` component, which is raised by almost all other components to provide structured error reporting. High-level models offer a more user-friendly interface, abstracting away some of the lower-level API calls. Utility functions provide common helper methods, and TLS and authentication components ensure secure communication. Context management allows switching between different Docker environments. + +### Error Handling +This component centralizes the definition and creation of various exceptions and errors within the `docker` library. It provides specific error types for different failure scenarios, such as invalid parameters, API errors, and configuration issues, ensuring consistent error reporting across the system. + + +**Related Classes/Methods**: + +- `docker.errors.DockerException` (13:19) +- `docker.errors.create_api_error_from_http_exception` (22:39) +- `docker.errors.APIError` (42:89) +- `docker.errors.APIError.is_client_error` (81:84) +- `docker.errors.APIError.is_server_error` (86:89) +- `docker.errors.NotFound` (92:93) +- `docker.errors.ImageNotFound` (96:97) +- `docker.errors.InvalidVersion` (100:101) +- `docker.errors.InvalidRepository` (104:105) +- `docker.errors.InvalidConfigFile` (108:109) +- `docker.errors.InvalidArgument` (112:113) +- `docker.errors.DeprecatedMethod` (116:117) +- `docker.errors.TLSParameterError` (120:128) +- `docker.errors.NullResource` (131:132) +- `docker.errors.ContainerError` (135:150) +- `docker.errors.StreamParseError` (153:155) +- `docker.errors.BuildError` (158:162) +- `docker.errors.ImageLoadError` (165:166) +- `docker.errors.create_unexpected_kwargs_error` (169:177) +- `docker.errors.MissingContextParameter` (180:185) +- `docker.errors.ContextAlreadyExists` (188:193) +- `docker.errors.ContextException` (196:201) +- `docker.errors.ContextNotFound` (204:209) +- `docker.credentials.errors.StoreError` (1:2) +- `docker.credentials.errors.CredentialsNotFound` (5:6) +- `docker.utils.socket.SocketError` (17:18) +- `docker.types.containers.host_config_type_error` (665:669) +- `docker.types.containers.host_config_value_error` (678:679) +- `docker.types.containers.host_config_version_error` (672:676) +- `docker.types.containers.host_config_incompatible_error` (682:685) + + +### TLS and Authentication +This component manages secure communication configurations, including TLS parameters and user authentication details. It handles the parsing of authentication configurations and resolves repository authentication, ensuring secure access to Docker registries and daemons. + + +**Related Classes/Methods**: + +- `docker.tls.TLSConfig:__init__` (21:55) +- `docker.auth:resolve_` (full file reference) +- `docker.auth.AuthConfig:parse_auth` (84:141) +- `docker.auth.AuthConfig:_resolve_authconfig_credstore` (244:270) +- `docker.auth:_load_legacy_config` (352:378) +- `docker.credentials.store.Store:_execute` (71:93) +- `docker.credentials.errors:process_store_error` (13:17) + + +### Utility Functions +This component provides a collection of helper functions for common tasks such as socket operations, resource validation, version checking, JSON stream parsing, and various data parsing utilities. It aims to encapsulate reusable logic and simplify interactions with Docker-related data. + + +**Related Classes/Methods**: + +- `docker.utils.socket:read_exactly` (62:73) +- `docker.utils.decorators:check_resource` (7:21) +- `docker.utils.decorators:minimum_version` (24:34) +- `docker.utils.json_stream:split_buffer` (50:74) +- `docker.utils.utils:create_ipam_pool` (28:32) +- `docker.utils.utils:create_ipam_config` (35:39) +- `docker.utils.utils:parse_host` (233:321) +- `docker.utils.utils:parse_devices` (324:350) +- `docker.utils.utils:parse_bytes` (411:448) +- `docker.utils.utils:parse_env_file` (458:483) +- `docker.utils.utils:create_host_config` (513:517) + + +### Docker Context Management +This component is responsible for managing Docker contexts, which define connection parameters to Docker daemons. It provides functionalities to create, set, remove, and inspect contexts, allowing users to easily switch between different Docker environments. + + +**Related Classes/Methods**: + +- `docker.context.context.Context:__init__` (19:60) +- `docker.context.api.ContextAPI:create_context` (23:70) +- `docker.context.api.ContextAPI:set_current_context` (136:144) +- `docker.context.api.ContextAPI:remove_context` (147:177) +- `docker.context.api.ContextAPI:inspect_context` (180:206) + + +### Docker Type Definitions +This component defines various data structures and classes that represent Docker objects and configurations, such as host configurations, container configurations, swarm specifications, network endpoint configurations, and service-related types like mounts and update policies. It ensures proper data validation and structure for interacting with the Docker API. + + +**Related Classes/Methods**: + +- `docker.types.containers.HostConfig:__init__` (265:662) +- `docker.types.containers:host_config_version_error` (672:676) +- `docker.types.containers:host_config_incompatible_error` (682:685) +- `docker.types.containers.ContainerConfig:__init__` (689:790) +- `docker.types.swarm.SwarmSpec:__init__` (11:94) +- `docker.types.daemon.CancellableStream:close` (37:71) +- `docker.types.networks.EndpointConfig:__init__` (6:51) +- `docker.types.services.Mount:__init__` (249:306) +- `docker.types.services.Mount:parse_mount_string` (309:330) +- `docker.types.services:_convert_generic_resources_dict` (372:395) +- `docker.types.services.UpdateConfig:__init__` (421:451) +- `docker.types.services.ServiceMode:__init__` (608:640) +- `docker.types.services.PlacementPreference:__init__` (768:774) +- `docker.types.services.Privileges:__init__` (821:848) + + +### Docker API Client +This core component provides the low-level interface for interacting with the Docker daemon's API. It handles the establishment of connections, sending requests, and processing responses, including error handling and version compatibility checks. It serves as the foundation for all higher-level Docker operations. + + +**Related Classes/Methods**: + +- `docker.api.client.APIClient:__init__` (115:219) +- `docker.api.client.APIClient:_retrieve_server_version` (221:232) +- `docker.api.client.APIClient:_raise_for_status` (272:277) +- `docker.api.client.APIClient:_create_websocket_connection` (321:331) + + +### Volume API +This component provides methods for managing Docker volumes, including creating and removing them. It interacts with the Docker API Client to perform volume-related operations. + + +**Related Classes/Methods**: + +- `docker.api.volume.VolumeApiMixin:create_volume` (38:91) +- `docker.api.volume.VolumeApiMixin:remove_volume` (140:163) + + +### Secret API +This component provides methods for managing Docker secrets, including creating them. It interacts with the Docker API Client to perform secret-related operations. + + +**Related Classes/Methods**: + +- `docker.api.secret.SecretApiMixin:create_secret` (8:43) + + +### Swarm API +This component provides methods for managing Docker Swarm, including initializing, joining, unlocking, and updating swarm configurations. It interacts with the Docker API Client to perform swarm-related operations. + + +**Related Classes/Methods**: + +- `docker.api.swarm.SwarmApiMixin:init_swarm` (84:180) +- `docker.api.swarm.SwarmApiMixin:join_swarm` (217:265) +- `docker.api.swarm.SwarmApiMixin:unlock_swarm` (347:380) +- `docker.api.swarm.SwarmApiMixin:update_swarm` (419:462) + + +### Service API +This component provides methods for managing Docker services, including creating, inspecting, and listing them. It interacts with the Docker API Client and performs API feature checks. + + +**Related Classes/Methods**: + +- `docker.api.service:_check_api_features` (5:96) +- `docker.api.service.ServiceApiMixin:create_service` (116:189) +- `docker.api.service.ServiceApiMixin:inspect_service` (193:219) +- `docker.api.service.ServiceApiMixin:services` (263:291) + + +### Build API +This component provides methods for building Docker images and pruning build cache. It interacts with the Docker API Client to perform image build operations. + + +**Related Classes/Methods**: + +- `docker.api.build.BuildApiMixin:build` (12:275) +- `docker.api.build.BuildApiMixin:prune_builds` (278:319) + + +### Exec API +This component provides methods for executing commands inside running Docker containers. It interacts with the Docker API Client to perform exec operations. + + +**Related Classes/Methods**: + +- `docker.api.exec_api.ExecApiMixin:exec_create` (7:78) + + +### Network API +This component provides methods for managing Docker networks, including creating, inspecting, and disconnecting containers from networks. It interacts with the Docker API Client to perform network-related operations. + + +**Related Classes/Methods**: + +- `docker.api.network.NetworkApiMixin:create_network` (40:152) +- `docker.api.network.NetworkApiMixin:inspect_network` (189:212) +- `docker.api.network.NetworkApiMixin:disconnect_container_from_network` (256:277) + + +### Container API +This component provides methods for managing Docker containers, including creating, logging, starting, getting stats, updating, and waiting for containers. It interacts with the Docker API Client to perform container-related operations. + + +**Related Classes/Methods**: + +- `docker.api.container.ContainerApiMixin:create_container_from_config` (445:457) +- `docker.api.container.ContainerApiMixin:logs` (821:901) +- `docker.api.container.ContainerApiMixin:start` (1101:1136) +- `docker.api.container.ContainerApiMixin:stats` (1139:1184) +- `docker.api.container.ContainerApiMixin:update_container` (1250:1312) +- `docker.api.container.ContainerApiMixin:wait` (1315:1348) + + +### Image API +This component provides methods for managing Docker images, including importing, loading, and pulling images. It interacts with the Docker API Client to perform image-related operations. + + +**Related Classes/Methods**: + +- `docker.api.image.ImageApiMixin:import_image` (102:152) +- `docker.api.image.ImageApiMixin:load_image` (291:324) +- `docker.api.image.ImageApiMixin:pull` (351:434) + + +### High-Level Models +This component provides higher-level abstractions for Docker objects like containers, images, and services, simplifying common operations. These models often wrap the lower-level API client calls and provide more user-friendly interfaces. + + +**Related Classes/Methods**: + +- `docker.models.containers.Container:labels` (47:58) +- `docker.models.containers.ContainerCollection:run` (535:912) +- `docker.models.containers:_create_container_args` (1123:1182) +- `docker.models.images.Image:save` (80:120) +- `docker.models.images.RegistryData:has_platform` (179:209) +- `docker.models.images.ImageCollection:build` (220:315) +- `docker.models.images.ImageCollection:load` (383:413) +- `docker.models.services.Service:scale` (116:133) +- `docker.models.services:_get_create_service_kwargs` (342:390) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/High-Level Client.md b/.codeboarding/High-Level Client.md new file mode 100644 index 000000000..f38dfd9f3 --- /dev/null +++ b/.codeboarding/High-Level Client.md @@ -0,0 +1,88 @@ +```mermaid +graph LR + High_Level_Client["High-Level Client"] + Low_Level_API_Client["Low-Level API Client"] + Resource_Collections["Resource Collections"] + Client_Configuration_Utilities["Client Configuration Utilities"] + High_Level_Client -- "initializes and configures" --> Low_Level_API_Client + High_Level_Client -- "manages resources through" --> Resource_Collections + High_Level_Client -- "configures via" --> Client_Configuration_Utilities + Low_Level_API_Client -- "uses" --> Client_Configuration_Utilities + Resource_Collections -- "uses" --> Low_Level_API_Client +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This graph illustrates the core components of the `docker-py` library's client subsystem. The `High-Level Client` provides an intuitive object-oriented interface, acting as the primary entry point for user interactions. It delegates complex operations to the `Low-Level API Client` for direct communication with the Docker daemon and manages various Docker entities through `Resource Collections`. Client configuration, including environment variable parsing, authentication, and proxy settings, is handled by `Client Configuration Utilities`. + +### High-Level Client +Provides a user-friendly, object-oriented interface for interacting with the Docker daemon, abstracting the underlying API. It serves as the primary entry point for most user operations, delegating to the Low-Level API Client and managing resources via Resource Collections. + + +**Related Classes/Methods**: + +- `docker.client.DockerClient` (16:219) +- `docker.client.DockerClient:__init__` (44:45) +- `docker.client.DockerClient:from_env` (48:100) +- `docker.client.DockerClient:configs` (104:109) +- `docker.client.DockerClient:containers` (112:117) +- `docker.client.DockerClient:images` (120:125) +- `docker.client.DockerClient:networks` (128:133) +- `docker.client.DockerClient:nodes` (136:141) +- `docker.client.DockerClient:plugins` (144:149) +- `docker.client.DockerClient:secrets` (152:157) +- `docker.client.DockerClient:services` (160:165) +- `docker.client.DockerClient:swarm` (168:173) +- `docker.client.DockerClient:volumes` (176:181) +- `docker.client.DockerClient:events` (184:185) +- `docker.client.DockerClient:df` (188:189) +- `docker.client.DockerClient:info` (192:193) +- `docker.client.DockerClient:login` (196:197) +- `docker.client.DockerClient:ping` (200:201) +- `docker.client.DockerClient:version` (204:205) + + +### Low-Level API Client +The low-level API client responsible for direct communication with the Docker daemon. It handles the actual HTTP requests and responses, providing the core functionality that the High-Level Client builds upon by aggregating various API mixins. + + +**Related Classes/Methods**: + +- `docker.api.client.APIClient` (57:532) + + +### Resource Collections +A set of classes, each responsible for managing a specific type of Docker resource (e.g., configs, containers, images, networks, nodes, plugins, secrets, services, volumes). These classes provide methods for creating, listing, inspecting, and removing their respective resources, typically inheriting from a common Collection base class. + + +**Related Classes/Methods**: + +- `docker.models.resource.Collection` (51:92) +- `docker.models.resource.Model` (1:48) +- `docker.models.configs.ConfigCollection` (27:70) +- `docker.models.containers.ContainerCollection` (532:1029) +- `docker.models.images.ImageCollection` (217:495) +- `docker.models.networks.NetworkCollection` (94:218) +- `docker.models.nodes.NodeCollection` (64:107) +- `docker.models.plugins.PluginCollection` (131:206) +- `docker.models.secrets.SecretCollection` (27:70) +- `docker.models.services.ServiceCollection` (146:284) +- `docker.models.swarm.Swarm` (7:190) +- `docker.models.volumes.VolumeCollection` (28:99) + + +### Client Configuration Utilities +Contains helper functions and utilities primarily used for configuring the Docker client, such as parsing environment variables, handling authentication, and proxy settings. + + +**Related Classes/Methods**: + +- `docker.utils.utils.kwargs_from_env` (353:388) +- `docker.auth.AuthConfig` (75:306) +- `docker.utils.proxy.ProxyConfig` (4:77) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Low-Level API Client.md b/.codeboarding/Low-Level API Client.md new file mode 100644 index 000000000..34747def1 --- /dev/null +++ b/.codeboarding/Low-Level API Client.md @@ -0,0 +1,116 @@ +```mermaid +graph LR + API_Client_Core["API Client Core"] + Error_Handling["Error Handling"] + Configuration_Utilities["Configuration & Utilities"] + Transport_Adapters["Transport Adapters"] + Authentication["Authentication"] + API_Mixins["API Mixins"] + API_Client_Core -- "initializes with and uses" --> Configuration_Utilities + API_Client_Core -- "uses" --> Transport_Adapters + API_Client_Core -- "uses" --> Authentication + API_Client_Core -- "raises and handles" --> Error_Handling + API_Client_Core -- "invokes methods from" --> API_Mixins +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +The Low-Level API Client subsystem in docker-py provides the core functionality for direct HTTP communication with the Docker daemon. It manages the entire lifecycle of requests, from connection establishment and dispatching (GET, POST, PUT, DELETE) to response processing and error handling. The system also integrates various API mixins to extend its capabilities for specific Docker resources like containers, images, and networks. Configuration loading, authentication, and different transport mechanisms (Unix sockets, named pipes, SSH) are also handled within this subsystem to ensure robust and flexible communication with the Docker daemon. + +### API Client Core +The central component for interacting with the Docker daemon. It handles connection establishment, request dispatching (GET, POST, PUT, DELETE), response processing, and streaming. It also manages server version compatibility and configuration reloading. + + +**Related Classes/Methods**: + +- `docker.api.client.APIClient` (57:532) +- `docker.api.client.APIClient:__init__` (115:219) +- `docker.api.client.APIClient:_retrieve_server_version` (221:232) +- `docker.api.client.APIClient:_post` (241:242) +- `docker.api.client.APIClient:_get` (245:246) +- `docker.api.client.APIClient:_put` (249:250) +- `docker.api.client.APIClient:_delete` (253:254) +- `docker.api.client.APIClient:_raise_for_status` (272:277) +- `docker.api.client.APIClient:_result` (279:287) +- `docker.api.client.APIClient:_post_json` (289:303) +- `docker.api.client.APIClient:_attach_websocket` (313:319) +- `docker.api.client.APIClient:_create_websocket_connection` (321:331) +- `docker.api.client.APIClient:_get_raw_response_socket` (333:353) +- `docker.api.client.APIClient:_stream_helper` (355:374) +- `docker.api.client.APIClient:_multiplexed_buffer_helper` (376:390) +- `docker.api.client.APIClient:_multiplexed_response_stream_helper` (392:411) +- `docker.api.client.APIClient:_stream_raw_result` (413:422) +- `docker.api.client.APIClient:_read_from_socket` (424:447) +- `docker.api.client.APIClient:_check_is_tty` (478:480) +- `docker.api.client.APIClient:_get_result` (482:483) +- `docker.api.client.APIClient:_get_result_tty` (485:499) +- `docker.api.client.APIClient:reload_config` (518:532) +- `docker.api.client.APIClient._set_request_timeout` (234:238) +- `docker.api.client.APIClient._unmount` (501:503) +- `docker.api.client.APIClient._url` (256:270) +- `docker.api.client.APIClient._attach_params` (305:310) + + +### Error Handling +This component is responsible for defining and raising specific exceptions related to Docker operations and for converting HTTP errors into more meaningful Docker exceptions. + + +**Related Classes/Methods**: + +- `docker.errors.TLSParameterError` (120:128) +- `docker.errors.DockerException` (13:19) +- `docker.errors.InvalidVersion` (100:101) +- `docker.errors.create_api_error_from_http_exception` (22:39) + + +### Configuration & Utilities +Provides various utility functions for loading configurations (general, proxy, authentication), parsing host information, handling JSON streams, managing sockets, and applying decorators for resource checks. + + +**Related Classes/Methods**: + +- `docker.utils.config.load_general_config` (51:66) +- `docker.utils.proxy.ProxyConfig.from_dict` (25:38) +- `docker.utils.utils.parse_host` (233:321) +- `docker.utils.utils.version_lt` (77:78) +- `docker.utils.json_stream.json_stream` (35:40) +- `docker.utils.socket.frames_iter` (92:103) +- `docker.utils.socket.demux_adaptor` (177:187) +- `docker.utils.socket.consume_socket_output` (140:174) +- `docker.utils.decorators.check_resource` (7:21) + + +### Transport Adapters +Handles the low-level communication with the Docker daemon over different transport mechanisms, such as Unix sockets, named pipes (Npipe), and SSH. + + +**Related Classes/Methods**: + +- `docker.transport.unixconn.UnixHTTPAdapter` (45:86) +- `docker.transport.npipeconn.NpipeHTTPAdapter` (64:102) +- `docker.transport.sshconn.SSHHTTPAdapter` (159:250) + + +### Authentication +Manages the loading and handling of Docker authentication configurations. + + +**Related Classes/Methods**: + +- `docker.auth.load_config` (348:349) + + +### API Mixins +Provides specific API functionalities related to the Docker daemon and containers, which are then integrated into the main API client. + + +**Related Classes/Methods**: + +- `docker.api.daemon.DaemonApiMixin.version` (168:181) +- `docker.api.container.ContainerApiMixin.inspect_container` (778:795) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/Transport Layer.md b/.codeboarding/Transport Layer.md new file mode 100644 index 000000000..3c7339faa --- /dev/null +++ b/.codeboarding/Transport Layer.md @@ -0,0 +1,133 @@ +```mermaid +graph LR + NpipeSocket["NpipeSocket"] + NpipeHTTPConnectionPool["NpipeHTTPConnectionPool"] + NpipeHTTPAdapter["NpipeHTTPAdapter"] + UnixHTTPConnectionPool["UnixHTTPConnectionPool"] + UnixHTTPAdapter["UnixHTTPAdapter"] + SSHSocket["SSHSocket"] + SSHConnectionPool["SSHConnectionPool"] + SSHHTTPAdapter["SSHHTTPAdapter"] + BaseHTTPAdapter["BaseHTTPAdapter"] + NpipeHTTPConnectionPool -- "utilizes" --> NpipeSocket + NpipeHTTPAdapter -- "creates" --> NpipeHTTPConnectionPool + UnixHTTPAdapter -- "creates" --> UnixHTTPConnectionPool + SSHConnectionPool -- "utilizes" --> SSHSocket + SSHHTTPAdapter -- "creates" --> SSHConnectionPool + NpipeHTTPAdapter -- "inherits from" --> BaseHTTPAdapter + UnixHTTPAdapter -- "inherits from" --> BaseHTTPAdapter + SSHHTTPAdapter -- "inherits from" --> BaseHTTPAdapter +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +This overview details the Transport Layer subsystem of docker-py, which is responsible for handling low-level communication protocols to connect to the Docker daemon. It supports Npipe, Unix sockets, and SSH, managing HTTP connection pooling and socket operations across these different transport mechanisms. + +### NpipeSocket +This component provides a partial implementation of the socket API over Windows named pipes. It is designed to be used as a client socket, handling connections, sending, and receiving data over named pipes. It manages the underlying Windows pipe handle and provides methods for basic socket operations like connect, send, recv, and close. + + +**Related Classes/Methods**: + +- `docker.transport.npipesocket.NpipeSocket` (29:203) +- `docker.transport.npipesocket.NpipeSocket:connect` (52:81) +- `docker.transport.npipesocket.NpipeSocket:connect_ex` (84:85) +- `docker.transport.npipesocket.NpipeSocket:dup` (93:94) +- `docker.transport.npipesocket.NpipeSocket:makefile` (111:117) +- `docker.transport.npipesocket.NpipeSocket:recvfrom` (125:127) +- `docker.transport.npipesocket.NpipeSocket:recvfrom_into` (130:131) +- `docker.transport.npipesocket.NpipeSocket:sendall` (172:173) +- `docker.transport.npipesocket.NpipeSocket:sendto` (176:178) +- `docker.transport.npipesocket.NpipeSocket:setblocking` (180:183) +- `docker.transport.npipesocket.NpipeSocket:shutdown` (202:203) + + +### NpipeHTTPConnectionPool +This component manages a pool of NpipeHTTPConnection instances. It's responsible for creating new connections when needed and reusing existing ones to optimize performance and resource utilization when communicating with a named pipe endpoint. It overrides urllib3's default connection pooling behavior to specifically handle named pipe connections. + + +**Related Classes/Methods**: + +- `docker.transport.npipeconn.NpipeHTTPConnectionPool` (29:61) +- `docker.transport.npipeconn.NpipeHTTPConnectionPool:_new_conn` (37:40) +- `docker.transport.npipeconn.NpipeHTTPConnectionPool:_get_conn` (45:61) + + +### NpipeHTTPAdapter +This component is a Requests adapter that integrates named pipe communication into the Requests library. It provides a mechanism to obtain connections from the NpipeHTTPConnectionPool and handles the URL scheme for named pipes (npipe://) to route requests appropriately. + + +**Related Classes/Methods**: + +- `docker.transport.npipeconn.NpipeHTTPAdapter` (64:102) +- `docker.transport.npipeconn.NpipeHTTPAdapter:get_connection` (82:94) + + +### UnixHTTPConnectionPool +This component is responsible for managing a pool of HTTP connections over Unix sockets. It creates and reuses UnixHTTPConnection instances for efficient communication with services exposed via Unix domain sockets. + + +**Related Classes/Methods**: + +- `docker.transport.unixconn.UnixHTTPConnectionPool` (30:42) +- `docker.transport.unixconn.UnixHTTPConnectionPool:_new_conn` (39:42) + + +### UnixHTTPAdapter +This component is a Requests adapter that integrates Unix socket communication into the Requests library. It obtains connections from the UnixHTTPConnectionPool and handles the URL scheme for Unix sockets. + + +**Related Classes/Methods**: + +- `docker.transport.unixconn.UnixHTTPAdapter` (45:86) +- `docker.transport.unixconn.UnixHTTPAdapter:get_connection` (66:78) + + +### SSHSocket +This component provides a socket-like interface for SSH connections. It handles sending and receiving data over an SSH channel, abstracting the underlying SSH protocol details. + + +**Related Classes/Methods**: + +- `docker.transport.sshconn.SSHSocket` (20:95) +- `docker.transport.sshconn.SSHSocket:sendall` (71:72) +- `docker.transport.sshconn.SSHSocket:send` (74:75) +- `docker.transport.sshconn.SSHSocket:makefile` (83:88) + + +### SSHConnectionPool +This component manages a pool of SSHConnection instances. It's responsible for creating new SSH connections and reusing existing ones to optimize performance when communicating over SSH. + + +**Related Classes/Methods**: + +- `docker.transport.sshconn.SSHConnectionPool` (120:156) +- `docker.transport.sshconn.SSHConnectionPool:_new_conn` (133:134) +- `docker.transport.sshconn.SSHConnectionPool:_get_conn` (139:156) + + +### SSHHTTPAdapter +This component is a Requests adapter that integrates SSH communication into the Requests library. It handles the initialization of Paramiko client, establishes SSH connections, and obtains connections from the SSHConnectionPool to route HTTP requests over SSH. + + +**Related Classes/Methods**: + +- `docker.transport.sshconn.SSHHTTPAdapter` (159:250) +- `docker.transport.sshconn.SSHHTTPAdapter:__init__` (165:183) +- `docker.transport.sshconn.SSHHTTPAdapter:get_connection` (220:245) +- `docker.transport.sshconn.SSHHTTPAdapter:close` (247:250) + + +### BaseHTTPAdapter +This is a base class for HTTP adapters in the Requests library, providing common functionality for handling HTTP connections and requests. It serves as an abstraction layer for different transport mechanisms. + + +**Related Classes/Methods**: + +- `docker.transport.basehttpadapter.BaseHTTPAdapter` (4:13) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file diff --git a/.codeboarding/on_boarding.md b/.codeboarding/on_boarding.md new file mode 100644 index 000000000..06d27ef89 --- /dev/null +++ b/.codeboarding/on_boarding.md @@ -0,0 +1,171 @@ +```mermaid +graph LR + High_Level_Client["High-Level Client"] + Low_Level_API_Client["Low-Level API Client"] + Docker_Resource_Management["Docker Resource Management"] + Daemon_Exec_Operations["Daemon & Exec Operations"] + Build_System["Build System"] + Authentication_Configuration["Authentication & Configuration"] + Transport_Layer["Transport Layer"] + Error_Handling["Error Handling"] + Data_Models_Utilities["Data Models & Utilities"] + High_Level_Client -- "uses" --> Low_Level_API_Client + High_Level_Client -- "manages" --> Docker_Resource_Management + High_Level_Client -- "accesses" --> Daemon_Exec_Operations + Low_Level_API_Client -- "uses for communication" --> Transport_Layer + Low_Level_API_Client -- "uses for authentication/config" --> Authentication_Configuration + Low_Level_API_Client -- "raises" --> Error_Handling + Low_Level_API_Client -- "uses" --> Data_Models_Utilities + Docker_Resource_Management -- "makes API calls to" --> Low_Level_API_Client + Docker_Resource_Management -- "uses" --> Data_Models_Utilities + Docker_Resource_Management -- "raises" --> Error_Handling + Docker_Resource_Management -- "uses for pull/push" --> Authentication_Configuration + Daemon_Exec_Operations -- "makes API calls to" --> Low_Level_API_Client + Daemon_Exec_Operations -- "uses" --> Data_Models_Utilities + Daemon_Exec_Operations -- "raises" --> Error_Handling + Daemon_Exec_Operations -- "uses for login" --> Authentication_Configuration + Build_System -- "makes API calls to" --> Low_Level_API_Client + Build_System -- "raises" --> Error_Handling + Build_System -- "uses" --> Data_Models_Utilities + Build_System -- "uses for auth headers" --> Authentication_Configuration + Authentication_Configuration -- "uses config from" --> Data_Models_Utilities + Authentication_Configuration -- "raises" --> Error_Handling + Transport_Layer -- "raises" --> Error_Handling + Data_Models_Utilities -- "raises" --> Error_Handling + click High_Level_Client href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/docker-py/High-Level Client.md" "Details" + click Low_Level_API_Client href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/docker-py/Low-Level API Client.md" "Details" + click Docker_Resource_Management href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/docker-py/Docker Resource Management.md" "Details" + click Daemon_Exec_Operations href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/docker-py/Daemon & Exec Operations.md" "Details" + click Build_System href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/docker-py/Build System.md" "Details" + click Authentication_Configuration href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/docker-py/Authentication & Configuration.md" "Details" + click Transport_Layer href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/docker-py/Transport Layer.md" "Details" + click Error_Handling href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/docker-py/Error Handling.md" "Details" + click Data_Models_Utilities href "https://github.com/CodeBoarding/GeneratedOnBoardings/blob/main/docker-py/Data Models & Utilities.md" "Details" +``` +[![CodeBoarding](https://img.shields.io/badge/Generated%20by-CodeBoarding-9cf?style=flat-square)](https://github.com/CodeBoarding/GeneratedOnBoardings)[![Demo](https://img.shields.io/badge/Try%20our-Demo-blue?style=flat-square)](https://www.codeboarding.org/demo)[![Contact](https://img.shields.io/badge/Contact%20us%20-%20contact@codeboarding.org-lightgrey?style=flat-square)](mailto:contact@codeboarding.org) + +## Component Details + +The `docker-py` library provides a comprehensive Python interface for interacting with the Docker daemon. It is structured into a high-level client for ease of use and a low-level API client for direct communication. The system manages various Docker resources like containers, images, networks, and volumes, and handles advanced features such as Swarm, services, plugins, secrets, and configurations. It includes robust mechanisms for authentication, credential management, Docker context handling, and image building. Underlying these functionalities are a flexible transport layer supporting different communication protocols and a dedicated error handling system, all supported by a rich set of data models and utility functions. + +### High-Level Client +Provides a user-friendly, object-oriented interface for interacting with the Docker daemon, abstracting the underlying API. It serves as the primary entry point for most user operations. + + +**Related Classes/Methods**: + +- `docker-py.docker.client.DockerClient` (16:219) +- `docker-py.docker.client.DockerClient:__init__` (44:45) +- `docker-py.docker.client.DockerClient:from_env` (48:100) + + +### Low-Level API Client +Handles direct HTTP communication with the Docker daemon, managing requests, responses, and error handling. It serves as the core communication layer and integrates various API mixins. + + +**Related Classes/Methods**: + +- `docker-py.docker.api.client.APIClient` (57:532) +- `docker-py.docker.api.client.APIClient:__init__` (115:219) +- `docker-py.docker.api.client.APIClient:_post` (241:242) + + +### Docker Resource Management +Encompasses the API mixins and object models for managing the lifecycle and operations of various Docker resources like containers, images, networks, volumes, swarm, services, plugins, secrets, and configurations. + + +**Related Classes/Methods**: + +- `docker-py.docker.api.container.ContainerApiMixin` (14:1348) +- `docker-py.docker.models.containers.ContainerCollection` (532:1029) +- `docker-py.docker.api.image.ImageApiMixin` (10:572) +- `docker-py.docker.models.images.ImageCollection` (217:495) +- `docker-py.docker.api.network.NetworkApiMixin` (6:277) +- `docker-py.docker.models.networks.NetworkCollection` (94:218) +- `docker-py.docker.api.volume.VolumeApiMixin` (4:163) +- `docker-py.docker.models.volumes.VolumeCollection` (28:99) +- `docker-py.docker.api.swarm.SwarmApiMixin` (10:462) +- `docker-py.docker.models.swarm.Swarm` (7:190) +- `docker-py.docker.api.service.ServiceApiMixin` (114:486) +- `docker-py.docker.models.services.ServiceCollection` (146:284) +- `docker-py.docker.api.plugin.PluginApiMixin` (4:261) +- `docker-py.docker.models.plugins.PluginCollection` (131:206) +- `docker-py.docker.api.secret.SecretApiMixin` (6:98) +- `docker-py.docker.models.secrets.SecretCollection` (27:70) +- `docker-py.docker.api.config.ConfigApiMixin` (6:92) +- `docker-py.docker.models.configs.ConfigCollection` (27:70) + + +### Daemon & Exec Operations +Provides functionalities for general Docker daemon operations (e.g., info, events, login) and executing commands within running containers. + + +**Related Classes/Methods**: + +- `docker-py.docker.api.daemon.DaemonApiMixin` (7:181) +- `docker-py.docker.api.daemon.DaemonApiMixin:info` (83:95) +- `docker-py.docker.api.exec_api.ExecApiMixin` (5:176) +- `docker-py.docker.api.exec_api.ExecApiMixin:exec_create` (7:78) + + +### Build System +Manages the process of building Docker images from Dockerfiles, including context archiving, file exclusion, and authentication for base image pulls. + + +**Related Classes/Methods**: + +- `docker-py.docker.api.build.BuildApiMixin` (11:352) +- `docker-py.docker.api.build.BuildApiMixin:build` (12:275) +- `docker-py.docker.utils.build.create_archive` (70:120) + + +### Authentication & Configuration +Manages Docker registry authentication, credential storage, Docker context profiles (connection settings), and general configuration file loading and parsing. + + +**Related Classes/Methods**: + +- `docker-py.docker.auth.AuthConfig` (75:306) +- `docker-py.docker.auth.AuthConfig:load_config` (144:189) +- `docker-py.docker.credentials.store.Store` (11:93) +- `docker-py.docker.context.context.Context` (16:249) +- `docker-py.docker.context.api.ContextAPI` (15:206) +- `docker-py.docker.utils.config:load_general_config` (51:66) + + +### Transport Layer +Handles low-level communication protocols for connecting to the Docker daemon, supporting Npipe, Unix sockets, and SSH. It manages HTTP connection pooling and socket operations. + + +**Related Classes/Methods**: + +- `docker-py.docker.transport.npipesocket.NpipeSocket` (29:203) +- `docker-py.docker.transport.unixconn.UnixHTTPAdapter` (45:86) +- `docker-py.docker.transport.sshconn.SSHHTTPAdapter` (159:250) + + +### Error Handling +Defines and manages custom exceptions specific to Docker operations, providing a structured way to report and handle various error conditions encountered during API interactions or client-side processing. + + +**Related Classes/Methods**: + +- `docker-py.docker.errors.APIError` (42:89) +- `docker-py.docker.errors.DockerException` (13:19) + + +### Data Models & Utilities +Provides structured data models for various Docker API objects and configurations, along with a collection of general-purpose helper functions for data parsing, environment variable handling, version comparisons, and stream processing. + + +**Related Classes/Methods**: + +- `docker-py.docker.tls.TLSConfig` (6:67) +- `docker-py.docker.types.containers.HostConfig` (264:662) +- `docker-py.docker.utils.utils` (10:500) +- `docker-py.docker.utils.json_stream:json_stream` (35:40) + + + + +### [FAQ](https://github.com/CodeBoarding/GeneratedOnBoardings/tree/main?tab=readme-ov-file#faq) \ No newline at end of file