or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

Files

docs

containers.mdimages.mdindex.mdnetworking.mdswarm.mdutilities.md

utilities.mddocs/

0

# Configuration and Utilities

1

2

Comprehensive utility functions, type classes, and configuration helpers that support Docker-py's core functionality. Includes data conversion utilities, authentication management, TLS configuration, and transport adapters for specialized connection types.

3

4

## Capabilities

5

6

### Configuration Creation Utilities

7

8

Helper functions for building complex Docker API configurations with proper validation and formatting.

9

10

```python { .api }

11

def create_host_config(binds=None, port_bindings=None, lxc_conf=None,

12

publish_all_ports=False, links=None, privileged=False,

13

dns=None, dns_search=None, volumes_from=None,

14

network_mode=None, restart_policy=None, cap_add=None,

15

cap_drop=None, devices=None, extra_hosts=None,

16

read_only=None, pid_mode=None, ipc_mode=None,

17

security_opt=None, ulimits=None, log_config=None,

18

mem_limit=None, memswap_limit=None, cpu_shares=None,

19

cpuset_cpus=None, cpuset_mems=None, **kwargs):

20

"""

21

Create host configuration for containers.

22

23

Parameters:

24

- binds (dict|list): Volume bindings

25

- port_bindings (dict): Port bindings mapping

26

- lxc_conf (dict): LXC configuration options

27

- publish_all_ports (bool): Publish all exposed ports to random host ports

28

- links (list): Container links (deprecated)

29

- privileged (bool): Run container in privileged mode

30

- dns (list): Custom DNS servers

31

- dns_search (list): Custom DNS search domains

32

- volumes_from (list): Mount volumes from other containers

33

- network_mode (str): Network mode ('bridge', 'host', 'none', etc.)

34

- restart_policy (dict): Restart policy configuration

35

- cap_add (list): Linux capabilities to add

36

- cap_drop (list): Linux capabilities to drop

37

- devices (list): Device mappings

38

- extra_hosts (list): Extra host entries for /etc/hosts

39

- read_only (bool): Mount root filesystem as read-only

40

- pid_mode (str): PID namespace mode

41

- ipc_mode (str): IPC namespace mode

42

- security_opt (list): Security options

43

- ulimits (list): Resource limits (Ulimit objects)

44

- log_config (LogConfig): Logging configuration

45

- mem_limit (int|str): Memory limit

46

- memswap_limit (int|str): Memory + swap limit

47

- cpu_shares (int): CPU shares (relative weight)

48

- cpuset_cpus (str): CPUs to use

49

- cpuset_mems (str): Memory nodes to use

50

51

Returns:

52

dict: Host configuration dictionary

53

"""

54

55

def create_container_config(image, command=None, hostname=None, user=None,

56

detach=False, stdin_open=False, tty=False,

57

mem_limit=None, ports=None, environment=None,

58

dns=None, volumes=None, volumes_from=None,

59

network_disabled=False, name=None, entrypoint=None,

60

cpu_shares=None, working_dir=None, domainname=None,

61

memswap_limit=None, cpuset=None, host_config=None,

62

mac_address=None, labels=None, volume_driver=None,

63

stop_signal=None, networking_config=None, **kwargs):

64

"""

65

Create container configuration dictionary.

66

67

Parameters:

68

- image (str): Image name or ID

69

- command (str|list): Command to run

70

- hostname (str): Container hostname

71

- user (str): Username or UID

72

- detach (bool): Run in detached mode

73

- stdin_open (bool): Keep STDIN open

74

- tty (bool): Allocate pseudo-TTY

75

- mem_limit (int|str): Memory limit

76

- ports (list): Ports to expose

77

- environment (dict|list): Environment variables

78

- dns (list): DNS servers

79

- volumes (list): Volume mount points

80

- volumes_from (list): Volumes from other containers

81

- network_disabled (bool): Disable networking

82

- name (str): Container name

83

- entrypoint (str|list): Override default entrypoint

84

- cpu_shares (int): CPU shares

85

- working_dir (str): Working directory

86

- domainname (str): Domain name

87

- memswap_limit (int): Memory + swap limit

88

- cpuset (str): CPUs to use

89

- host_config (dict): Host configuration

90

- mac_address (str): MAC address

91

- labels (dict): Container labels

92

- volume_driver (str): Volume driver

93

- stop_signal (str): Stop signal

94

- networking_config (dict): Network configuration

95

96

Returns:

97

dict: Container configuration dictionary

98

"""

99

100

def create_networking_config(endpoints_config=None):

101

"""

102

Create networking configuration for containers.

103

104

Parameters:

105

- endpoints_config (dict): Endpoint configurations by network name

106

107

Returns:

108

dict: Networking configuration dictionary

109

"""

110

111

def create_endpoint_config(version, aliases=None, links=None,

112

ipv4_address=None, ipv6_address=None,

113

link_local_ips=None):

114

"""

115

Create endpoint configuration for network connections.

116

117

Parameters:

118

- version (str): API version

119

- aliases (list): Network-scoped aliases

120

- links (list): Container links (deprecated)

121

- ipv4_address (str): Static IPv4 address

122

- ipv6_address (str): Static IPv6 address

123

- link_local_ips (list): Link-local IP addresses

124

125

Returns:

126

dict: Endpoint configuration dictionary

127

"""

128

```

129

130

### Data Conversion Functions

131

132

Functions for converting data between different formats required by the Docker API.

133

134

```python { .api }

135

def convert_port_bindings(port_bindings):

136

"""

137

Convert port bindings to Docker API format.

138

139

Parameters:

140

- port_bindings (dict): Port bindings mapping

141

142

Returns:

143

dict: Formatted port bindings for API

144

"""

145

146

def convert_volume_binds(binds):

147

"""

148

Convert volume bindings to Docker API format.

149

150

Parameters:

151

- binds (dict|list): Volume bindings

152

153

Returns:

154

list: Formatted volume bindings for API

155

"""

156

157

def convert_filters(filters):

158

"""

159

Convert filter dictionary to Docker API format.

160

161

Parameters:

162

- filters (dict): Filter conditions

163

164

Returns:

165

str: JSON-encoded filters for API

166

"""

167

168

def format_environment(environment):

169

"""

170

Format environment variables for Docker API.

171

172

Parameters:

173

- environment (dict|list): Environment variables

174

175

Returns:

176

list: Formatted environment variables

177

"""

178

```

179

180

### Parsing Functions

181

182

Functions for parsing various Docker-related data formats and specifications.

183

184

```python { .api }

185

def parse_repository_tag(repo_name):

186

"""

187

Parse repository name and tag from image specification.

188

189

Parameters:

190

- repo_name (str): Repository name with optional tag

191

192

Returns:

193

tuple: (repository, tag) where tag defaults to 'latest'

194

"""

195

196

def parse_host(addr, is_win32=False, tls=False):

197

"""

198

Parse Docker host address into connection components.

199

200

Parameters:

201

- addr (str): Docker host address (tcp://, unix://, npipe://)

202

- is_win32 (bool): Windows platform flag

203

- tls (bool): TLS enabled flag

204

205

Returns:

206

tuple: (protocol, host, port, base_url)

207

"""

208

209

def parse_devices(devices):

210

"""

211

Parse device specifications into Docker API format.

212

213

Parameters:

214

- devices (list): Device specifications

215

216

Returns:

217

list: Formatted device mappings

218

"""

219

220

def parse_bytes(s):

221

"""

222

Parse byte size string into integer bytes.

223

224

Parameters:

225

- s (str): Size string (e.g., '512m', '1g', '2048k')

226

227

Returns:

228

int: Size in bytes

229

"""

230

231

def parse_env_file(env_file):

232

"""

233

Parse environment file into environment variables.

234

235

Parameters:

236

- env_file (str): Path to environment file

237

238

Returns:

239

dict: Environment variables from file

240

"""

241

242

def split_command(command):

243

"""

244

Split command string into array of arguments.

245

246

Parameters:

247

- command (str): Command string

248

249

Returns:

250

list: Command arguments array

251

"""

252

253

def normalize_links(links):

254

"""

255

Normalize container links to standard format.

256

257

Parameters:

258

- links (list): Container links

259

260

Returns:

261

list: Normalized link specifications

262

"""

263

```

264

265

### Build and Archive Utilities

266

267

Functions for creating build contexts, tar archives, and handling Dockerfiles.

268

269

```python { .api }

270

def mkbuildcontext(dockerfile):

271

"""

272

Create build context from Dockerfile content.

273

274

Parameters:

275

- dockerfile (str): Dockerfile content

276

277

Returns:

278

file: File-like object containing build context

279

"""

280

281

def tar(path, exclude=None, dockerfile=None, fileobj=None, gzip=False):

282

"""

283

Create tar archive from directory path.

284

285

Parameters:

286

- path (str): Directory path to archive

287

- exclude (list): Patterns to exclude (from .dockerignore)

288

- dockerfile (str): Custom Dockerfile content

289

- fileobj (file): File-like object to write to

290

- gzip (bool): Use gzip compression

291

292

Returns:

293

file: Tar archive file-like object

294

"""

295

296

def exclude_paths(root, patterns, dockerfile=None):

297

"""

298

Get list of paths that should be excluded from build context.

299

300

Parameters:

301

- root (str): Root directory path

302

- patterns (list): Exclusion patterns from .dockerignore

303

- dockerfile (str): Dockerfile name

304

305

Returns:

306

set: Set of paths to exclude

307

"""

308

```

309

310

### Version Comparison Utilities

311

312

Functions for comparing Docker API versions.

313

314

```python { .api }

315

def compare_version(v1, v2):

316

"""

317

Compare two Docker API version strings.

318

319

Parameters:

320

- v1 (str): First version

321

- v2 (str): Second version

322

323

Returns:

324

int: -1 if v1 < v2, 0 if equal, 1 if v1 > v2

325

"""

326

327

def version_lt(v1, v2):

328

"""

329

Check if version v1 is less than v2.

330

331

Parameters:

332

- v1 (str): First version

333

- v2 (str): Second version

334

335

Returns:

336

bool: True if v1 < v2

337

"""

338

339

def version_gte(v1, v2):

340

"""

341

Check if version v1 is greater than or equal to v2.

342

343

Parameters:

344

- v1 (str): First version

345

- v2 (str): Second version

346

347

Returns:

348

bool: True if v1 >= v2

349

"""

350

```

351

352

### Environment and Configuration

353

354

Functions for working with Docker environment configuration.

355

356

```python { .api }

357

def kwargs_from_env(ssl_version=None, assert_hostname=None, environment=None):

358

"""

359

Get Docker client configuration from environment variables.

360

361

Parameters:

362

- ssl_version (str): SSL version for TLS connections

363

- assert_hostname (bool): Verify hostname in TLS certificates

364

- environment (dict): Environment variables dict (defaults to os.environ)

365

366

Returns:

367

dict: Client configuration parameters

368

"""

369

370

def datetime_to_timestamp(dt):

371

"""

372

Convert datetime object to Unix timestamp.

373

374

Parameters:

375

- dt (datetime): Datetime object

376

377

Returns:

378

int: Unix timestamp

379

"""

380

381

def decode_json_header(header):

382

"""

383

Decode base64 JSON header.

384

385

Parameters:

386

- header (str): Base64-encoded JSON header

387

388

Returns:

389

dict: Decoded JSON data

390

"""

391

```

392

393

## Authentication Functions

394

395

Docker registry authentication utilities for managing credentials and login tokens.

396

397

```python { .api }

398

def resolve_repository_name(repo_name):

399

"""

400

Parse repository name and determine registry.

401

402

Parameters:

403

- repo_name (str): Repository name

404

405

Returns:

406

tuple: (registry_name, repository_name)

407

"""

408

409

def resolve_authconfig(authconfig, registry=None):

410

"""

411

Resolve authentication configuration for a registry.

412

413

Parameters:

414

- authconfig (dict): Authentication configurations

415

- registry (str): Registry URL

416

417

Returns:

418

dict: Authentication configuration for registry

419

"""

420

421

def load_config(config_path=None):

422

"""

423

Load Docker configuration file.

424

425

Parameters:

426

- config_path (str): Path to config file (defaults to ~/.docker/config.json)

427

428

Returns:

429

dict: Docker configuration data

430

"""

431

432

def encode_header(auth_config):

433

"""

434

Encode authentication configuration for HTTP header.

435

436

Parameters:

437

- auth_config (dict): Authentication configuration

438

439

Returns:

440

str: Base64-encoded authentication header

441

"""

442

443

def get_config_header(client, registry):

444

"""

445

Get authentication header for registry from client configuration.

446

447

Parameters:

448

- client: Docker client instance

449

- registry (str): Registry URL

450

451

Returns:

452

str: Authentication header value

453

"""

454

```

455

456

## TLS Configuration

457

458

Comprehensive TLS/SSL configuration for secure Docker daemon connections.

459

460

```python { .api }

461

class TLSConfig:

462

def __init__(self, client_cert=None, ca_cert=None, verify=None,

463

ssl_version=None, assert_hostname=None, assert_fingerprint=None):

464

"""

465

Create TLS configuration for Docker client.

466

467

Parameters:

468

- client_cert (tuple): (cert_file, key_file) for client authentication

469

- ca_cert (str): Path to CA certificate file

470

- verify (bool|str): Verify server certificate (True/False or CA path)

471

- ssl_version (int): SSL version constant

472

- assert_hostname (bool): Verify hostname in certificate

473

- assert_fingerprint (str): Expected certificate fingerprint

474

"""

475

476

def configure_client(self, client):

477

"""

478

Configure requests client for TLS connections.

479

480

Parameters:

481

- client: Requests session client

482

483

Returns:

484

None

485

"""

486

487

# Properties

488

cert: tuple # Client certificate tuple

489

ca_cert: str # CA certificate path

490

verify: bool|str # Certificate verification setting

491

ssl_version: int # SSL version

492

assert_hostname: bool # Hostname verification

493

assert_fingerprint: str # Certificate fingerprint

494

```

495

496

## Transport Adapters

497

498

Specialized HTTP adapters for different connection types and platforms.

499

500

### UnixAdapter

501

502

HTTP adapter for Unix socket connections on Linux/macOS systems.

503

504

```python { .api }

505

class UnixAdapter:

506

def __init__(self, socket_url, timeout=60, num_pools=25):

507

"""

508

Create Unix socket HTTP adapter.

509

510

Parameters:

511

- socket_url (str): Unix socket URL

512

- timeout (int): Connection timeout

513

- num_pools (int): Connection pool size

514

"""

515

516

class UnixHTTPConnection:

517

"""HTTP connection over Unix socket"""

518

519

class UnixHTTPConnectionPool:

520

"""Connection pool for Unix socket connections"""

521

```

522

523

### NpipeAdapter (Windows)

524

525

HTTP adapter for Windows named pipes.

526

527

```python { .api }

528

class NpipeAdapter:

529

def __init__(self, socket_url, timeout=60, num_pools=25):

530

"""

531

Create named pipe HTTP adapter (Windows only).

532

533

Parameters:

534

- socket_url (str): Named pipe URL

535

- timeout (int): Connection timeout

536

- num_pools (int): Connection pool size

537

"""

538

```

539

540

### SSLAdapter

541

542

HTTPS adapter with configurable SSL/TLS settings.

543

544

```python { .api }

545

class SSLAdapter:

546

def __init__(self, ssl_version=None, assert_hostname=None,

547

assert_fingerprint=None, **kwargs):

548

"""

549

Create SSL/TLS HTTP adapter.

550

551

Parameters:

552

- ssl_version (int): SSL version to use

553

- assert_hostname (bool): Verify hostname

554

- assert_fingerprint (str): Expected certificate fingerprint

555

"""

556

```

557

558

## Decorator Functions

559

560

Decorators for API method enhancement and validation.

561

562

```python { .api }

563

def check_resource(f):

564

"""

565

Decorator to extract resource ID from function arguments.

566

567

Parameters:

568

- f (function): Function to decorate

569

570

Returns:

571

function: Decorated function

572

"""

573

574

def minimum_version(version):

575

"""

576

Decorator to require minimum Docker API version.

577

578

Parameters:

579

- version (str): Minimum required API version

580

581

Returns:

582

function: Decorator function

583

"""

584

585

def update_headers(f):

586

"""

587

Decorator to automatically add authentication headers.

588

589

Parameters:

590

- f (function): Function to decorate

591

592

Returns:

593

function: Decorated function

594

"""

595

```

596

597

## Socket Utilities

598

599

Low-level socket operations for Docker API communication.

600

601

```python { .api }

602

def read(socket, n=4096):

603

"""

604

Read bytes from socket with error handling.

605

606

Parameters:

607

- socket: Socket object

608

- n (int): Number of bytes to read

609

610

Returns:

611

bytes: Data read from socket

612

"""

613

614

def read_exactly(socket, n):

615

"""

616

Read exact number of bytes from socket.

617

618

Parameters:

619

- socket: Socket object

620

- n (int): Exact number of bytes to read

621

622

Returns:

623

bytes: Exactly n bytes of data

624

"""

625

626

def next_frame_size(socket):

627

"""

628

Get size of next frame from multiplexed stream.

629

630

Parameters:

631

- socket: Socket object

632

633

Returns:

634

int: Size of next frame

635

"""

636

637

def frames_iter(socket):

638

"""

639

Iterator over frames from multiplexed socket stream.

640

641

Parameters:

642

- socket: Socket object

643

644

Yields:

645

bytes: Frame data

646

"""

647

648

class SocketError(Exception):

649

"""Exception for socket operation errors"""

650

```

651

652

## Port Utilities

653

654

Functions for handling Docker port specifications and bindings.

655

656

```python { .api }

657

def split_port(port):

658

"""

659

Parse port specification string.

660

661

Parameters:

662

- port (str): Port specification (e.g., '8080:80/tcp')

663

664

Returns:

665

tuple: (host_port, container_port, protocol)

666

"""

667

668

def build_port_bindings(ports):

669

"""

670

Build port bindings dictionary from port list.

671

672

Parameters:

673

- ports (list): List of port specifications

674

675

Returns:

676

dict: Port bindings mapping

677

"""

678

```

679

680

## Usage Examples

681

682

### Using Configuration Helpers

683

684

```python

685

import docker

686

from docker.types import LogConfig, Ulimit

687

688

client = docker.Client()

689

690

# Create comprehensive host configuration

691

host_config = client.create_host_config(

692

# Volume bindings

693

binds={

694

'/host/data': {'bind': '/container/data', 'mode': 'rw'},

695

'/host/logs': {'bind': '/container/logs', 'mode': 'rw'}

696

},

697

698

# Port bindings

699

port_bindings={

700

'8080/tcp': 8080,

701

'9000/tcp': ('127.0.0.1', 9000)

702

},

703

704

# Resource limits

705

mem_limit='512m',

706

cpu_shares=512,

707

ulimits=[

708

Ulimit(name='nofile', soft=1024, hard=2048),

709

Ulimit(name='nproc', soft=128, hard=256)

710

],

711

712

# Security settings

713

privileged=False,

714

cap_add=['NET_ADMIN'],

715

cap_drop=['MKNOD'],

716

717

# Network settings

718

dns=['8.8.8.8', '8.8.4.4'],

719

extra_hosts=['api.example.com:192.168.1.100'],

720

721

# Logging configuration

722

log_config=LogConfig(

723

type=LogConfig.types.JSON,

724

config={'max-size': '10m', 'max-file': '3'}

725

),

726

727

# Restart policy

728

restart_policy={'Name': 'unless-stopped'}

729

)

730

731

# Create container with configuration

732

container = client.create_container(

733

image='myapp:latest',

734

command=['python', 'app.py'],

735

environment={'ENV': 'production'},

736

host_config=host_config,

737

labels={'app': 'myservice', 'version': '1.0'}

738

)

739

```

740

741

### Working with Authentication

742

743

```python

744

from docker.auth import auth

745

746

# Load Docker configuration

747

config = auth.load_config()

748

print(f"Loaded config with {len(config.get('auths', {}))} registries")

749

750

# Resolve authentication for specific registry

751

auth_config = auth.resolve_authconfig(

752

config.get('auths', {}),

753

'registry.example.com'

754

)

755

756

# Use authentication for image operations

757

client.pull(

758

'registry.example.com/private/image:latest',

759

auth_config=auth_config

760

)

761

762

# Manual authentication configuration

763

manual_auth = {

764

'username': 'myuser',

765

'password': 'mypass',

766

'serveraddress': 'https://registry.example.com'

767

}

768

769

# Encode for header use

770

auth_header = auth.encode_header(manual_auth)

771

```

772

773

### TLS Configuration

774

775

```python

776

from docker.tls import TLSConfig

777

import ssl

778

779

# Create TLS configuration for secure connection

780

tls_config = TLSConfig(

781

client_cert=('/path/to/client-cert.pem', '/path/to/client-key.pem'),

782

ca_cert='/path/to/ca.pem',

783

verify=True,

784

ssl_version=ssl.PROTOCOL_TLSv1_2,

785

assert_hostname=False

786

)

787

788

# Create client with TLS

789

client = docker.Client(

790

base_url='https://docker-daemon:2376',

791

tls=tls_config

792

)

793

794

# Verify connection

795

print(client.ping())

796

```

797

798

### Environment Configuration

799

800

```python

801

import os

802

from docker.utils.utils import kwargs_from_env

803

804

# Set environment variables

805

os.environ['DOCKER_HOST'] = 'tcp://192.168.1.100:2376'

806

os.environ['DOCKER_TLS_VERIFY'] = '1'

807

os.environ['DOCKER_CERT_PATH'] = '/path/to/certs'

808

809

# Get client configuration from environment

810

client_kwargs = kwargs_from_env()

811

print(f"Client config: {client_kwargs}")

812

813

# Create client from environment

814

client = docker.Client(**client_kwargs)

815

816

# Alternative: use from_env convenience function

817

client = docker.from_env()

818

```

819

820

### Advanced Parsing and Conversion

821

822

```python

823

from docker.utils.utils import (

824

parse_repository_tag, parse_bytes, convert_port_bindings,

825

convert_volume_binds, split_command

826

)

827

828

# Parse repository and tag

829

repo, tag = parse_repository_tag('nginx:1.21-alpine')

830

print(f"Repository: {repo}, Tag: {tag}")

831

832

# Parse byte sizes

833

memory_limit = parse_bytes('512m') # Returns 536870912

834

cpu_limit = parse_bytes('1g') # Returns 1073741824

835

836

# Convert port bindings

837

port_bindings = convert_port_bindings({

838

'8080/tcp': 8080,

839

'9000/tcp': ('0.0.0.0', 9000),

840

'3306/tcp': None # Random port

841

})

842

843

# Convert volume bindings

844

volume_binds = convert_volume_binds({

845

'/host/data': {'bind': '/app/data', 'mode': 'rw'},

846

'/host/config': {'bind': '/app/config', 'mode': 'ro'}

847

})

848

849

# Split command strings

850

cmd_array = split_command('python -m http.server 8000')

851

print(f"Command array: {cmd_array}")

852

```

853

854

### Build Context Creation

855

856

```python

857

from docker.utils.utils import tar, exclude_paths

858

import tempfile

859

860

# Create build context from directory

861

with tar('/path/to/build/context', gzip=True) as build_context:

862

# Build image using context

863

for line in client.build(

864

fileobj=build_context,

865

tag='myapp:latest',

866

custom_context=True,

867

stream=True,

868

decode=True

869

):

870

if 'stream' in line:

871

print(line['stream'].strip())

872

873

# Handle .dockerignore patterns

874

root_path = '/path/to/project'

875

dockerignore_patterns = [

876

'*.pyc',

877

'__pycache__/',

878

'.git/',

879

'node_modules/',

880

'*.log'

881

]

882

883

excluded_paths = exclude_paths(root_path, dockerignore_patterns)

884

print(f"Excluding {len(excluded_paths)} paths from build context")

885

```