fastled 1.3.4__py3-none-any.whl → 1.3.6__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
fastled/docker_manager.py CHANGED
@@ -1,1005 +1,1037 @@
1
- """
2
- New abstraction for Docker management with improved Ctrl+C handling.
3
- """
4
-
5
- import _thread
6
- import json
7
- import os
8
- import platform
9
- import subprocess
10
- import sys
11
- import threading
12
- import time
13
- import traceback
14
- import warnings
15
- from dataclasses import dataclass
16
- from datetime import datetime, timezone
17
- from pathlib import Path
18
-
19
- import docker
20
- from appdirs import user_data_dir
21
- from disklru import DiskLRUCache
22
- from docker.client import DockerClient
23
- from docker.errors import DockerException, ImageNotFound, NotFound
24
- from docker.models.containers import Container
25
- from docker.models.images import Image
26
- from filelock import FileLock
27
-
28
- from fastled.print_filter import PrintFilter, PrintFilterFastled
29
- from fastled.spinner import Spinner
30
-
31
- CONFIG_DIR = Path(user_data_dir("fastled", "fastled"))
32
- CONFIG_DIR.mkdir(parents=True, exist_ok=True)
33
- DB_FILE = CONFIG_DIR / "db.db"
34
- DISK_CACHE = DiskLRUCache(str(DB_FILE), 10)
35
- _IS_GITHUB = "GITHUB_ACTIONS" in os.environ
36
-
37
-
38
- # Docker uses datetimes in UTC but without the timezone info. If we pass in a tz
39
- # then it will throw an exception.
40
- def _utc_now_no_tz() -> datetime:
41
- now = datetime.now(timezone.utc)
42
- return now.replace(tzinfo=None)
43
-
44
-
45
- def _win32_docker_location() -> str | None:
46
- home_dir = Path.home()
47
- out = [
48
- "C:\\Program Files\\Docker\\Docker\\Docker Desktop.exe",
49
- f"{home_dir}\\AppData\\Local\\Docker\\Docker Desktop.exe",
50
- ]
51
- for loc in out:
52
- if Path(loc).exists():
53
- return loc
54
- return None
55
-
56
-
57
- def get_lock(image_name: str) -> FileLock:
58
- """Get the file lock for this DockerManager instance."""
59
- lock_file = CONFIG_DIR / f"{image_name}.lock"
60
- CONFIG_DIR.mkdir(parents=True, exist_ok=True)
61
- print(CONFIG_DIR)
62
- if not lock_file.parent.exists():
63
- lock_file.parent.mkdir(parents=True, exist_ok=True)
64
- out: FileLock
65
- out = FileLock(str(lock_file)) # type: ignore
66
- return out
67
-
68
-
69
- @dataclass
70
- class Volume:
71
- """
72
- Represents a Docker volume mapping between host and container.
73
-
74
- Attributes:
75
- host_path: Path on the host system (e.g., "C:\\Users\\username\\project")
76
- container_path: Path inside the container (e.g., "/app/data")
77
- mode: Access mode, "rw" for read-write or "ro" for read-only
78
- """
79
-
80
- host_path: str
81
- container_path: str
82
- mode: str = "rw"
83
-
84
- def to_dict(self) -> dict[str, dict[str, str]]:
85
- """Convert the Volume object to the format expected by Docker API."""
86
- return {self.host_path: {"bind": self.container_path, "mode": self.mode}}
87
-
88
- @classmethod
89
- def from_dict(cls, volume_dict: dict[str, dict[str, str]]) -> list["Volume"]:
90
- """Create Volume objects from a Docker volume dictionary."""
91
- volumes = []
92
- for host_path, config in volume_dict.items():
93
- volumes.append(
94
- cls(
95
- host_path=host_path,
96
- container_path=config["bind"],
97
- mode=config.get("mode", "rw"),
98
- )
99
- )
100
- return volumes
101
-
102
-
103
- # Override the default PrintFilter to use a custom one.
104
- def make_default_print_filter() -> PrintFilter:
105
- """Create a default PrintFilter instance."""
106
- return PrintFilterFastled()
107
-
108
-
109
- class RunningContainer:
110
- def __init__(
111
- self,
112
- container: Container,
113
- first_run: bool = False,
114
- filter: PrintFilter | None = None,
115
- ) -> None:
116
- self.filter = filter or make_default_print_filter()
117
- self.container = container
118
- self.first_run = first_run
119
- self.running = True
120
- self.thread = threading.Thread(target=self._log_monitor)
121
- self.thread.daemon = True
122
- self.thread.start()
123
-
124
- def _log_monitor(self):
125
- from_date = _utc_now_no_tz() if not self.first_run else None
126
- to_date = _utc_now_no_tz()
127
-
128
- while self.running:
129
- try:
130
- for log in self.container.logs(
131
- follow=False, since=from_date, until=to_date, stream=True
132
- ):
133
- # print(log.decode("utf-8"), end="")
134
- self.filter.print(log)
135
- time.sleep(0.1)
136
- from_date = to_date
137
- to_date = _utc_now_no_tz()
138
- except KeyboardInterrupt:
139
- print("Monitoring logs interrupted by user.")
140
- _thread.interrupt_main()
141
- break
142
- except Exception as e:
143
- print(f"Error monitoring logs: {e}")
144
- break
145
-
146
- def detach(self) -> None:
147
- """Stop monitoring the container logs"""
148
- self.running = False
149
- self.thread.join()
150
-
151
- def stop(self) -> None:
152
- """Stop the container"""
153
- self.container.stop()
154
- self.detach()
155
-
156
-
157
- def _hack_to_fix_mac(volumes: list[Volume] | None) -> list[Volume] | None:
158
- """Fixes the volume mounts on MacOS by removing the mode."""
159
- if volumes is None:
160
- return None
161
- if sys.platform != "darwin":
162
- # Only macos needs hacking.
163
- return volumes
164
-
165
- volumes = volumes.copy()
166
- # Work around a Docker bug on MacOS where the expected network socket to the
167
- # the host is not mounted correctly. This was actually fixed in recent versions
168
- # of docker client but there is a large chunk of Docker clients out there with
169
- # this bug in it.
170
- #
171
- # This hack is done by mounting the socket directly to the container.
172
- # This socket talks to the docker daemon on the host.
173
- #
174
- # Found here.
175
- # https://github.com/docker/docker-py/issues/3069#issuecomment-1316778735
176
- # if it exists already then return the input
177
- for volume in volumes:
178
- if volume.host_path == "/var/run/docker.sock":
179
- return volumes
180
- # ok it doesn't exist, so add it
181
- volumes.append(
182
- Volume(
183
- host_path="/var/run/docker.sock",
184
- container_path="/var/run/docker.sock",
185
- mode="rw",
186
- )
187
- )
188
- return volumes
189
-
190
-
191
- class DockerManager:
192
- def __init__(self) -> None:
193
- from docker.errors import DockerException
194
-
195
- self.is_suspended: bool = False
196
-
197
- try:
198
- self._client: DockerClient | None = None
199
- self.first_run = False
200
- except DockerException as e:
201
- stack = traceback.format_exc()
202
- warnings.warn(f"Error initializing Docker client: {e}\n{stack}")
203
- raise
204
-
205
- @property
206
- def client(self) -> DockerClient:
207
- if self._client is None:
208
- self._client = docker.from_env()
209
- return self._client
210
-
211
- @staticmethod
212
- def is_docker_installed() -> bool:
213
- """Check if Docker is installed on the system."""
214
- try:
215
- subprocess.run(["docker", "--version"], capture_output=True, check=True)
216
- print("Docker is installed.")
217
- return True
218
- except subprocess.CalledProcessError as e:
219
- print(f"Docker command failed: {str(e)}")
220
- return False
221
- except FileNotFoundError:
222
- print("Docker is not installed.")
223
- return False
224
-
225
- @staticmethod
226
- def ensure_linux_containers_for_windows() -> bool:
227
- """Ensure Docker is using Linux containers on Windows."""
228
- if sys.platform != "win32":
229
- return True # Only needed on Windows
230
-
231
- try:
232
- # Check if we're already in Linux container mode
233
- result = subprocess.run(
234
- ["docker", "info"], capture_output=True, text=True, check=True
235
- )
236
-
237
- if "linux" in result.stdout.lower():
238
- print("Already using Linux containers")
239
- return True
240
-
241
- if not _IS_GITHUB:
242
- answer = (
243
- input(
244
- "\nDocker on Windows must be in linux mode, this is a global change, switch? [y/n]"
245
- )
246
- .strip()
247
- .lower()[:1]
248
- )
249
- if answer != "y":
250
- return False
251
-
252
- print("Switching to Linux containers...")
253
- warnings.warn("Switching Docker to use Linux container context...")
254
-
255
- # Explicitly specify the Linux container context
256
- linux_context = "desktop-linux"
257
- subprocess.run(
258
- ["cmd", "/c", f"docker context use {linux_context}"],
259
- check=True,
260
- capture_output=True,
261
- )
262
-
263
- # Verify the switch worked
264
- verify = subprocess.run(
265
- ["docker", "info"], capture_output=True, text=True, check=True
266
- )
267
- if "linux" in verify.stdout.lower():
268
- print(
269
- f"Successfully switched to Linux containers using '{linux_context}' context"
270
- )
271
- return True
272
-
273
- warnings.warn(
274
- f"Failed to switch to Linux containers with context '{linux_context}': {verify.stdout}"
275
- )
276
- return False
277
-
278
- except subprocess.CalledProcessError as e:
279
- print(f"Failed to switch to Linux containers: {e}")
280
- if e.stdout:
281
- print(f"stdout: {e.stdout}")
282
- if e.stderr:
283
- print(f"stderr: {e.stderr}")
284
- return False
285
- except Exception as e:
286
- print(f"Unexpected error switching to Linux containers: {e}")
287
- return False
288
-
289
- @staticmethod
290
- def is_running() -> tuple[bool, Exception | None]:
291
- """Check if Docker is running by pinging the Docker daemon."""
292
-
293
- if not DockerManager.is_docker_installed():
294
- print("Docker is not installed.")
295
- return False, Exception("Docker is not installed.")
296
- try:
297
- # self.client.ping()
298
- client = docker.from_env()
299
- client.ping()
300
- print("Docker is running.")
301
- return True, None
302
- except DockerException as e:
303
- print(f"Docker is not running: {str(e)}")
304
- return False, e
305
- except Exception as e:
306
- print(f"Error pinging Docker daemon: {str(e)}")
307
- return False, e
308
-
309
- def start(self) -> bool:
310
- """Attempt to start Docker Desktop (or the Docker daemon) automatically."""
311
- print("Attempting to start Docker...")
312
-
313
- try:
314
- if sys.platform == "win32":
315
- docker_path = _win32_docker_location()
316
- if not docker_path:
317
- print("Docker Desktop not found.")
318
- return False
319
- subprocess.run(["start", "", docker_path], shell=True)
320
- elif sys.platform == "darwin":
321
- subprocess.run(["open", "-a", "Docker"])
322
- elif sys.platform.startswith("linux"):
323
- subprocess.run(["sudo", "systemctl", "start", "docker"])
324
- else:
325
- print("Unknown platform. Cannot auto-launch Docker.")
326
- return False
327
-
328
- # Wait for Docker to start up with increasing delays
329
- print("Waiting for Docker Desktop to start...")
330
- attempts = 0
331
- max_attempts = 20 # Increased max wait time
332
- while attempts < max_attempts:
333
- attempts += 1
334
- if self.is_running():
335
- print("Docker started successfully.")
336
- return True
337
-
338
- # Gradually increase wait time between checks
339
- wait_time = min(5, 1 + attempts * 0.5)
340
- print(
341
- f"Docker not ready yet, waiting {wait_time:.1f}s... (attempt {attempts}/{max_attempts})"
342
- )
343
- time.sleep(wait_time)
344
-
345
- print("Failed to start Docker within the expected time.")
346
- print(
347
- "Please try starting Docker Desktop manually and run this command again."
348
- )
349
- except KeyboardInterrupt:
350
- print("Aborted by user.")
351
- raise
352
- except Exception as e:
353
- print(f"Error starting Docker: {str(e)}")
354
- return False
355
-
356
- def has_newer_version(
357
- self, image_name: str, tag: str = "latest"
358
- ) -> tuple[bool, str]:
359
- """
360
- Check if a newer version of the image is available in the registry.
361
-
362
- Args:
363
- image_name: The name of the image to check
364
- tag: The tag of the image to check
365
-
366
- Returns:
367
- A tuple of (has_newer_version, message)
368
- has_newer_version: True if a newer version is available, False otherwise
369
- message: A message describing the result, including the date of the newer version if available
370
- """
371
- try:
372
- # Get the local image
373
- local_image = self.client.images.get(f"{image_name}:{tag}")
374
- local_image_id = local_image.id
375
- assert local_image_id is not None
376
-
377
- # Get the remote image data
378
- remote_image = self.client.images.get_registry_data(f"{image_name}:{tag}")
379
- remote_image_hash = remote_image.id
380
-
381
- # Check if we have a cached remote hash for this local image
382
- try:
383
- remote_image_hash_from_local_image = DISK_CACHE.get(local_image_id)
384
- except Exception:
385
- remote_image_hash_from_local_image = None
386
-
387
- # Compare the hashes
388
- if remote_image_hash_from_local_image == remote_image_hash:
389
- return False, f"Local image {image_name}:{tag} is up to date."
390
- else:
391
- # Get the creation date of the remote image if possible
392
- try:
393
- # Try to get detailed image info including creation date
394
- remote_image_details = self.client.api.inspect_image(
395
- f"{image_name}:{tag}"
396
- )
397
- if "Created" in remote_image_details:
398
- created_date = remote_image_details["Created"].split("T")[
399
- 0
400
- ] # Extract just the date part
401
- return (
402
- True,
403
- f"Newer version of {image_name}:{tag} is available (published on {created_date}).",
404
- )
405
- except Exception:
406
- pass
407
-
408
- # Fallback if we couldn't get the date
409
- return True, f"Newer version of {image_name}:{tag} is available."
410
-
411
- except ImageNotFound:
412
- return True, f"Image {image_name}:{tag} not found locally."
413
- except DockerException as e:
414
- return False, f"Error checking for newer version: {e}"
415
-
416
- def validate_or_download_image(
417
- self, image_name: str, tag: str = "latest", upgrade: bool = False
418
- ) -> bool:
419
- """
420
- Validate if the image exists, and if not, download it.
421
- If upgrade is True, will pull the latest version even if image exists locally.
422
- """
423
- ok = DockerManager.ensure_linux_containers_for_windows()
424
- if not ok:
425
- warnings.warn(
426
- "Failed to ensure Linux containers on Windows. This build may fail."
427
- )
428
- print(f"Validating image {image_name}:{tag}...")
429
- remote_image_hash_from_local_image: str | None = None
430
- remote_image_hash: str | None = None
431
-
432
- with get_lock(f"{image_name}-{tag}"):
433
- try:
434
- local_image = self.client.images.get(f"{image_name}:{tag}")
435
- print(f"Image {image_name}:{tag} is already available.")
436
-
437
- if upgrade:
438
- remote_image = self.client.images.get_registry_data(
439
- f"{image_name}:{tag}"
440
- )
441
- remote_image_hash = remote_image.id
442
-
443
- try:
444
- local_image_id = local_image.id
445
- assert local_image_id is not None
446
- remote_image_hash_from_local_image = DISK_CACHE.get(
447
- local_image_id
448
- )
449
- except KeyboardInterrupt:
450
- raise
451
- except Exception:
452
- remote_image_hash_from_local_image = None
453
- stack = traceback.format_exc()
454
- warnings.warn(
455
- f"Error getting remote image hash from local image: {stack}"
456
- )
457
- if remote_image_hash_from_local_image == remote_image_hash:
458
- print(f"Local image {image_name}:{tag} is up to date.")
459
- return False
460
-
461
- # Quick check for latest version
462
- with Spinner(f"Pulling newer version of {image_name}:{tag}..."):
463
- cmd_list = ["docker", "pull", f"{image_name}:{tag}"]
464
- cmd_str = subprocess.list2cmdline(cmd_list)
465
- print(f"Running command: {cmd_str}")
466
- subprocess.run(cmd_list, check=True)
467
- print(f"Updated to newer version of {image_name}:{tag}")
468
- local_image_hash = self.client.images.get(f"{image_name}:{tag}").id
469
- assert local_image_hash is not None
470
- if remote_image_hash is not None:
471
- DISK_CACHE.put(local_image_hash, remote_image_hash)
472
- return True
473
-
474
- except ImageNotFound:
475
- print(f"Image {image_name}:{tag} not found.")
476
- with Spinner("Loading "):
477
- # We use docker cli here because it shows the download.
478
- cmd_list = ["docker", "pull", f"{image_name}:{tag}"]
479
- cmd_str = subprocess.list2cmdline(cmd_list)
480
- print(f"Running command: {cmd_str}")
481
- subprocess.run(cmd_list, check=True)
482
- try:
483
- local_image = self.client.images.get(f"{image_name}:{tag}")
484
- local_image_hash = local_image.id
485
- print(f"Image {image_name}:{tag} downloaded successfully.")
486
- except ImageNotFound:
487
- warnings.warn(f"Image {image_name}:{tag} not found after download.")
488
- return True
489
-
490
- def tag_image(self, image_name: str, old_tag: str, new_tag: str) -> None:
491
- """
492
- Tag an image with a new tag.
493
- """
494
- image: Image = self.client.images.get(f"{image_name}:{old_tag}")
495
- image.tag(image_name, new_tag)
496
- print(f"Image {image_name}:{old_tag} tagged as {new_tag}.")
497
-
498
- def _container_configs_match(
499
- self,
500
- container: Container,
501
- command: str | None,
502
- volumes_dict: dict[str, dict[str, str]] | None,
503
- ports: dict[int, int] | None,
504
- ) -> bool:
505
- """Compare if existing container has matching configuration"""
506
- try:
507
- # Check if container is using the same image
508
- image = container.image
509
- assert image is not None
510
- container_image_id = image.id
511
- container_image_tags = image.tags
512
- assert container_image_id is not None
513
-
514
- # Simplified image comparison - just compare the IDs directly
515
- if not container_image_tags:
516
- print(f"Container using untagged image with ID: {container_image_id}")
517
- else:
518
- current_image = self.client.images.get(container_image_tags[0])
519
- if container_image_id != current_image.id:
520
- print(
521
- f"Container using different image version. Container: {container_image_id}, Current: {current_image.id}"
522
- )
523
- return False
524
-
525
- # Check command if specified
526
- if command and container.attrs["Config"]["Cmd"] != command.split():
527
- print(
528
- f"Command mismatch: {container.attrs['Config']['Cmd']} != {command}"
529
- )
530
- return False
531
-
532
- # Check volumes if specified
533
- if volumes_dict:
534
- container_mounts = (
535
- {
536
- m["Source"]: {"bind": m["Destination"], "mode": m["Mode"]}
537
- for m in container.attrs["Mounts"]
538
- }
539
- if container.attrs.get("Mounts")
540
- else {}
541
- )
542
-
543
- for host_dir, mount in volumes_dict.items():
544
- if host_dir not in container_mounts:
545
- print(f"Volume {host_dir} not found in container mounts.")
546
- return False
547
- if container_mounts[host_dir] != mount:
548
- print(
549
- f"Volume {host_dir} has different mount options: {container_mounts[host_dir]} != {mount}"
550
- )
551
- return False
552
-
553
- # Check ports if specified
554
- if ports:
555
- container_ports = (
556
- container.attrs["Config"]["ExposedPorts"]
557
- if container.attrs["Config"].get("ExposedPorts")
558
- else {}
559
- )
560
- container_port_bindings = (
561
- container.attrs["HostConfig"]["PortBindings"]
562
- if container.attrs["HostConfig"].get("PortBindings")
563
- else {}
564
- )
565
-
566
- for container_port, host_port in ports.items():
567
- port_key = f"{container_port}/tcp"
568
- if port_key not in container_ports:
569
- print(f"Container port {port_key} not found.")
570
- return False
571
- if not container_port_bindings.get(port_key, [{"HostPort": None}])[
572
- 0
573
- ]["HostPort"] == str(host_port):
574
- print(f"Port {host_port} is not bound to {port_key}.")
575
- return False
576
- except KeyboardInterrupt:
577
- raise
578
- except NotFound:
579
- print("Container not found.")
580
- return False
581
- except Exception as e:
582
- stack = traceback.format_exc()
583
- warnings.warn(f"Error checking container config: {e}\n{stack}")
584
- return False
585
- return True
586
-
587
- def run_container_detached(
588
- self,
589
- image_name: str,
590
- tag: str,
591
- container_name: str,
592
- command: str | None = None,
593
- volumes: list[Volume] | None = None,
594
- ports: dict[int, int] | None = None,
595
- remove_previous: bool = False,
596
- environment: dict[str, str] | None = None,
597
- ) -> Container:
598
- """
599
- Run a container from an image. If it already exists with matching config, start it.
600
- If it exists with different config, remove and recreate it.
601
-
602
- Args:
603
- volumes: List of Volume objects for container volume mappings
604
- ports: Dict mapping host ports to container ports
605
- Example: {8080: 80} maps host port 8080 to container port 80
606
- """
607
- volumes = _hack_to_fix_mac(volumes)
608
- # Convert volumes to the format expected by Docker API
609
- volumes_dict = None
610
- if volumes is not None:
611
- volumes_dict = {}
612
- for volume in volumes:
613
- volumes_dict.update(volume.to_dict())
614
-
615
- # Serialize the volumes to a json string
616
- if volumes_dict:
617
- volumes_str = json.dumps(volumes_dict)
618
- print(f"Volumes: {volumes_str}")
619
- print("Done")
620
- image_name = f"{image_name}:{tag}"
621
- try:
622
- container: Container = self.client.containers.get(container_name)
623
-
624
- if remove_previous:
625
- print(f"Removing existing container {container_name}...")
626
- container.remove(force=True)
627
- raise NotFound("Container removed due to remove_previous")
628
- # Check if configuration matches
629
- elif not self._container_configs_match(
630
- container, command, volumes_dict, ports
631
- ):
632
- print(
633
- f"Container {container_name} exists but with different configuration. Removing and recreating..."
634
- )
635
- container.remove(force=True)
636
- raise NotFound("Container removed due to config mismatch")
637
- print(f"Container {container_name} found with matching configuration.")
638
-
639
- # Existing container with matching config - handle various states
640
- if container.status == "running":
641
- print(f"Container {container_name} is already running.")
642
- elif container.status == "exited":
643
- print(f"Starting existing container {container_name}.")
644
- container.start()
645
- elif container.status == "restarting":
646
- print(f"Waiting for container {container_name} to restart...")
647
- timeout = 10
648
- container.wait(timeout=10)
649
- if container.status == "running":
650
- print(f"Container {container_name} has restarted.")
651
- else:
652
- print(
653
- f"Container {container_name} did not restart within {timeout} seconds."
654
- )
655
- container.stop(timeout=0)
656
- print(f"Container {container_name} has been stopped.")
657
- container.start()
658
- elif container.status == "paused":
659
- print(f"Resuming existing container {container_name}.")
660
- container.unpause()
661
- else:
662
- print(f"Unknown container status: {container.status}")
663
- print(f"Starting existing container {container_name}.")
664
- self.first_run = True
665
- container.start()
666
- except NotFound:
667
- print(f"Creating and starting {container_name}")
668
- out_msg = f"# Running in container: {command}"
669
- msg_len = len(out_msg)
670
- print("\n" + "#" * msg_len)
671
- print(out_msg)
672
- print("#" * msg_len + "\n")
673
- container = self.client.containers.run(
674
- image=image_name,
675
- command=command,
676
- name=container_name,
677
- detach=True,
678
- tty=True,
679
- volumes=volumes_dict,
680
- ports=ports, # type: ignore
681
- environment=environment,
682
- remove=True,
683
- )
684
- return container
685
-
686
- def run_container_interactive(
687
- self,
688
- image_name: str,
689
- tag: str,
690
- container_name: str,
691
- command: str | None = None,
692
- volumes: list[Volume] | None = None,
693
- ports: dict[int, int] | None = None,
694
- environment: dict[str, str] | None = None,
695
- ) -> None:
696
- # Convert volumes to the format expected by Docker API
697
- volumes = _hack_to_fix_mac(volumes)
698
- volumes_dict = None
699
- if volumes is not None:
700
- volumes_dict = {}
701
- for volume in volumes:
702
- volumes_dict.update(volume.to_dict())
703
- # Remove existing container
704
- try:
705
- container: Container = self.client.containers.get(container_name)
706
- container.remove(force=True)
707
- except NotFound:
708
- pass
709
- start_time = time.time()
710
- try:
711
- docker_command: list[str] = [
712
- "docker",
713
- "run",
714
- "-it",
715
- "--rm",
716
- "--name",
717
- container_name,
718
- ]
719
- if volumes_dict:
720
- for host_dir, mount in volumes_dict.items():
721
- docker_volume_arg = [
722
- "-v",
723
- f"{host_dir}:{mount['bind']}:{mount['mode']}",
724
- ]
725
- docker_command.extend(docker_volume_arg)
726
- if ports:
727
- for host_port, container_port in ports.items():
728
- docker_command.extend(["-p", f"{host_port}:{container_port}"])
729
- if environment:
730
- for env_name, env_value in environment.items():
731
- docker_command.extend(["-e", f"{env_name}={env_value}"])
732
- docker_command.append(f"{image_name}:{tag}")
733
- if command:
734
- docker_command.append(command)
735
- cmd_str: str = subprocess.list2cmdline(docker_command)
736
- print(f"Running command: {cmd_str}")
737
- subprocess.run(docker_command, check=False)
738
- except subprocess.CalledProcessError as e:
739
- print(f"Error running Docker command: {e}")
740
- diff = time.time() - start_time
741
- if diff < 5:
742
- raise
743
- sys.exit(1) # Probably a user exit.
744
-
745
- def attach_and_run(self, container: Container | str) -> RunningContainer:
746
- """
747
- Attach to a running container and monitor its logs in a background thread.
748
- Returns a RunningContainer object that can be used to stop monitoring.
749
- """
750
- if isinstance(container, str):
751
- container_name = container
752
- tmp = self.get_container(container)
753
- assert tmp is not None, f"Container {container_name} not found."
754
- container = tmp
755
-
756
- assert container is not None, "Container not found."
757
-
758
- print(f"Attaching to container {container.name}...")
759
-
760
- first_run = self.first_run
761
- self.first_run = False
762
-
763
- return RunningContainer(container, first_run)
764
-
765
- def suspend_container(self, container: Container | str) -> None:
766
- """
767
- Suspend (pause) the container.
768
- """
769
- if self.is_suspended:
770
- return
771
- if isinstance(container, str):
772
- container_name = container
773
- # container = self.get_container(container)
774
- tmp = self.get_container(container_name)
775
- if not tmp:
776
- print(f"Could not put container {container_name} to sleep.")
777
- return
778
- container = tmp
779
- assert isinstance(container, Container)
780
- try:
781
- if platform.system() == "Windows":
782
- container.pause()
783
- else:
784
- container.stop()
785
- container.remove()
786
- print(f"Container {container.name} has been suspended.")
787
- except KeyboardInterrupt:
788
- print(f"Container {container.name} interrupted by keyboard interrupt.")
789
- except Exception as e:
790
- print(f"Failed to suspend container {container.name}: {e}")
791
-
792
- def resume_container(self, container: Container | str) -> None:
793
- """
794
- Resume (unpause) the container.
795
- """
796
- container_name = "UNKNOWN"
797
- if isinstance(container, str):
798
- container_name = container
799
- container_or_none = self.get_container(container)
800
- if container_or_none is None:
801
- print(f"Could not resume container {container}.")
802
- return
803
- container = container_or_none
804
- container_name = container.name
805
- elif isinstance(container, Container):
806
- container_name = container.name
807
- assert isinstance(container, Container)
808
- if not container:
809
- print(f"Could not resume container {container}.")
810
- return
811
- try:
812
- assert isinstance(container, Container)
813
- container.unpause()
814
- print(f"Container {container.name} has been resumed.")
815
- except Exception as e:
816
- print(f"Failed to resume container {container_name}: {e}")
817
-
818
- def get_container(self, container_name: str) -> Container | None:
819
- """
820
- Get a container by name.
821
- """
822
- try:
823
- return self.client.containers.get(container_name)
824
- except NotFound:
825
- return None
826
-
827
- def is_container_running(self, container_name: str) -> bool:
828
- """
829
- Check if a container is running.
830
- """
831
- try:
832
- container = self.client.containers.get(container_name)
833
- return container.status == "running"
834
- except NotFound:
835
- print(f"Container {container_name} not found.")
836
- return False
837
-
838
- def build_image(
839
- self,
840
- image_name: str,
841
- tag: str,
842
- dockerfile_path: Path,
843
- build_context: Path,
844
- build_args: dict[str, str] | None = None,
845
- platform_tag: str = "",
846
- ) -> None:
847
- """
848
- Build a Docker image from a Dockerfile.
849
-
850
- Args:
851
- image_name: Name for the image
852
- tag: Tag for the image
853
- dockerfile_path: Path to the Dockerfile
854
- build_context: Path to the build context directory
855
- build_args: Optional dictionary of build arguments
856
- platform_tag: Optional platform tag (e.g. "-arm64")
857
- """
858
- if not dockerfile_path.exists():
859
- raise FileNotFoundError(f"Dockerfile not found at {dockerfile_path}")
860
-
861
- if not build_context.exists():
862
- raise FileNotFoundError(
863
- f"Build context directory not found at {build_context}"
864
- )
865
-
866
- print(f"Building Docker image {image_name}:{tag} from {dockerfile_path}")
867
-
868
- # Prepare build arguments
869
- buildargs = build_args or {}
870
- if platform_tag:
871
- buildargs["PLATFORM_TAG"] = platform_tag
872
-
873
- try:
874
- cmd_list = [
875
- "docker",
876
- "build",
877
- "-t",
878
- f"{image_name}:{tag}",
879
- ]
880
-
881
- # Add build args
882
- for arg_name, arg_value in buildargs.items():
883
- cmd_list.extend(["--build-arg", f"{arg_name}={arg_value}"])
884
-
885
- # Add dockerfile and context paths
886
- cmd_list.extend(["-f", str(dockerfile_path), str(build_context)])
887
-
888
- cmd_str = subprocess.list2cmdline(cmd_list)
889
- print(f"Running command: {cmd_str}")
890
-
891
- # Run the build command
892
- # cp = subprocess.run(cmd_list, check=True, capture_output=True)
893
- proc: subprocess.Popen = subprocess.Popen(
894
- cmd_list, stdout=subprocess.PIPE, stderr=subprocess.STDOUT
895
- )
896
- stdout = proc.stdout
897
- assert stdout is not None, "stdout is None"
898
- for line in iter(stdout.readline, b""):
899
- try:
900
- line_str = line.decode("utf-8")
901
- print(line_str, end="")
902
- except UnicodeDecodeError:
903
- print("Error decoding line")
904
- rtn = proc.wait()
905
- if rtn != 0:
906
- warnings.warn(
907
- f"Error building Docker image, is docker running? {rtn}, stdout: {stdout}, stderr: {proc.stderr}"
908
- )
909
- raise subprocess.CalledProcessError(rtn, cmd_str)
910
- print(f"Successfully built image {image_name}:{tag}")
911
-
912
- except subprocess.CalledProcessError as e:
913
- print(f"Error building Docker image: {e}")
914
- raise
915
-
916
- def purge(self, image_name: str) -> None:
917
- """
918
- Remove all containers and images associated with the given image name.
919
-
920
- Args:
921
- image_name: The name of the image to purge (without tag)
922
- """
923
- print(f"Purging all containers and images for {image_name}...")
924
-
925
- # Remove all containers using this image
926
- try:
927
- containers = self.client.containers.list(all=True)
928
- for container in containers:
929
- if any(image_name in tag for tag in container.image.tags):
930
- print(f"Removing container {container.name}")
931
- container.remove(force=True)
932
-
933
- except Exception as e:
934
- print(f"Error removing containers: {e}")
935
-
936
- # Remove all images with this name
937
- try:
938
- self.client.images.prune(filters={"dangling": False})
939
- images = self.client.images.list()
940
- for image in images:
941
- if any(image_name in tag for tag in image.tags):
942
- print(f"Removing image {image.tags}")
943
- self.client.images.remove(image.id, force=True)
944
- except Exception as e:
945
- print(f"Error removing images: {e}")
946
-
947
-
948
- def main() -> None:
949
- # Register SIGINT handler
950
- # signal.signal(signal.SIGINT, handle_sigint)
951
-
952
- docker_manager = DockerManager()
953
-
954
- # Parameters
955
- image_name = "python"
956
- tag = "3.10-slim"
957
- # new_tag = "my-python"
958
- container_name = "my-python-container"
959
- command = "python -m http.server"
960
- running_container: RunningContainer | None = None
961
-
962
- try:
963
- # Step 1: Validate or download the image
964
- docker_manager.validate_or_download_image(image_name, tag, upgrade=True)
965
-
966
- # Step 2: Tag the image
967
- # docker_manager.tag_image(image_name, tag, new_tag)
968
-
969
- # Step 3: Run the container
970
- container = docker_manager.run_container_detached(
971
- image_name, tag, container_name, command
972
- )
973
-
974
- # Step 4: Attach and monitor the container logs
975
- running_container = docker_manager.attach_and_run(container)
976
-
977
- # Wait for keyboard interrupt
978
- while True:
979
- time.sleep(0.1)
980
-
981
- except KeyboardInterrupt:
982
- print("\nStopping container...")
983
- if isinstance(running_container, RunningContainer):
984
- running_container.stop()
985
- container_or_none = docker_manager.get_container(container_name)
986
- if container_or_none is not None:
987
- docker_manager.suspend_container(container_or_none)
988
- else:
989
- warnings.warn(f"Container {container_name} not found.")
990
-
991
- try:
992
- # Suspend and resume the container
993
- container = docker_manager.get_container(container_name)
994
- assert container is not None, "Container not found."
995
- docker_manager.suspend_container(container)
996
-
997
- input("Press Enter to resume the container...")
998
-
999
- docker_manager.resume_container(container)
1000
- except Exception as e:
1001
- print(f"An error occurred: {e}")
1002
-
1003
-
1004
- if __name__ == "__main__":
1005
- main()
1
+ """
2
+ New abstraction for Docker management with improved Ctrl+C handling.
3
+ """
4
+
5
+ import _thread
6
+ import json
7
+ import os
8
+ import platform
9
+ import subprocess
10
+ import sys
11
+ import threading
12
+ import time
13
+ import traceback
14
+ import warnings
15
+ from dataclasses import dataclass
16
+ from datetime import datetime, timezone
17
+ from pathlib import Path
18
+
19
+ import docker
20
+ from appdirs import user_data_dir
21
+ from disklru import DiskLRUCache
22
+ from docker.client import DockerClient
23
+ from docker.errors import DockerException, ImageNotFound, NotFound
24
+ from docker.models.containers import Container
25
+ from docker.models.images import Image
26
+ from filelock import FileLock
27
+
28
+ from fastled.print_filter import PrintFilter, PrintFilterFastled
29
+ from fastled.spinner import Spinner
30
+
31
+ CONFIG_DIR = Path(user_data_dir("fastled", "fastled"))
32
+ CONFIG_DIR.mkdir(parents=True, exist_ok=True)
33
+ DB_FILE = CONFIG_DIR / "db.db"
34
+ DISK_CACHE = DiskLRUCache(str(DB_FILE), 10)
35
+ _IS_GITHUB = "GITHUB_ACTIONS" in os.environ
36
+ _DEFAULT_BUILD_DIR = "/js/.pio/build"
37
+
38
+
39
+ # Docker uses datetimes in UTC but without the timezone info. If we pass in a tz
40
+ # then it will throw an exception.
41
+ def _utc_now_no_tz() -> datetime:
42
+ now = datetime.now(timezone.utc)
43
+ return now.replace(tzinfo=None)
44
+
45
+
46
+ def set_ramdisk_size(size: str) -> None:
47
+ """Set the tmpfs size for the container."""
48
+ # This is a hack to set the tmpfs size from the environment variable.
49
+ # It should be set in the docker-compose.yml file.
50
+ # If not set, return 25MB.
51
+ try:
52
+ os.environ["TMPFS_SIZE"] = str(size)
53
+ except ValueError:
54
+ os.environ["TMPFS_SIZE"] = "0" # Defaults to off
55
+
56
+
57
+ def get_ramdisk_size() -> str | None:
58
+ """Get the tmpfs size for the container."""
59
+ # This is a hack to get the tmpfs size from the environment variable.
60
+ # It should be set in the docker-compose.yml file.
61
+ # If not set, return 25MB.
62
+ try:
63
+ return os.environ.get("TMPFS_SIZE", None)
64
+ except ValueError:
65
+ return None # Defaults to off
66
+
67
+
68
+ def _win32_docker_location() -> str | None:
69
+ home_dir = Path.home()
70
+ out = [
71
+ "C:\\Program Files\\Docker\\Docker\\Docker Desktop.exe",
72
+ f"{home_dir}\\AppData\\Local\\Docker\\Docker Desktop.exe",
73
+ ]
74
+ for loc in out:
75
+ if Path(loc).exists():
76
+ return loc
77
+ return None
78
+
79
+
80
+ def get_lock(image_name: str) -> FileLock:
81
+ """Get the file lock for this DockerManager instance."""
82
+ lock_file = CONFIG_DIR / f"{image_name}.lock"
83
+ CONFIG_DIR.mkdir(parents=True, exist_ok=True)
84
+ print(CONFIG_DIR)
85
+ if not lock_file.parent.exists():
86
+ lock_file.parent.mkdir(parents=True, exist_ok=True)
87
+ out: FileLock
88
+ out = FileLock(str(lock_file)) # type: ignore
89
+ return out
90
+
91
+
92
+ @dataclass
93
+ class Volume:
94
+ """
95
+ Represents a Docker volume mapping between host and container.
96
+
97
+ Attributes:
98
+ host_path: Path on the host system (e.g., "C:\\Users\\username\\project")
99
+ container_path: Path inside the container (e.g., "/app/data")
100
+ mode: Access mode, "rw" for read-write or "ro" for read-only
101
+ """
102
+
103
+ host_path: str
104
+ container_path: str
105
+ mode: str = "rw"
106
+
107
+ def to_dict(self) -> dict[str, dict[str, str]]:
108
+ """Convert the Volume object to the format expected by Docker API."""
109
+ return {self.host_path: {"bind": self.container_path, "mode": self.mode}}
110
+
111
+ @classmethod
112
+ def from_dict(cls, volume_dict: dict[str, dict[str, str]]) -> list["Volume"]:
113
+ """Create Volume objects from a Docker volume dictionary."""
114
+ volumes = []
115
+ for host_path, config in volume_dict.items():
116
+ volumes.append(
117
+ cls(
118
+ host_path=host_path,
119
+ container_path=config["bind"],
120
+ mode=config.get("mode", "rw"),
121
+ )
122
+ )
123
+ return volumes
124
+
125
+
126
+ # Override the default PrintFilter to use a custom one.
127
+ def make_default_print_filter() -> PrintFilter:
128
+ """Create a default PrintFilter instance."""
129
+ return PrintFilterFastled()
130
+
131
+
132
+ class RunningContainer:
133
+ def __init__(
134
+ self,
135
+ container: Container,
136
+ first_run: bool = False,
137
+ filter: PrintFilter | None = None,
138
+ ) -> None:
139
+ self.filter = filter or make_default_print_filter()
140
+ self.container = container
141
+ self.first_run = first_run
142
+ self.running = True
143
+ self.thread = threading.Thread(target=self._log_monitor)
144
+ self.thread.daemon = True
145
+ self.thread.start()
146
+
147
+ def _log_monitor(self):
148
+ from_date = _utc_now_no_tz() if not self.first_run else None
149
+ to_date = _utc_now_no_tz()
150
+
151
+ while self.running:
152
+ try:
153
+ for log in self.container.logs(
154
+ follow=False, since=from_date, until=to_date, stream=True
155
+ ):
156
+ # print(log.decode("utf-8"), end="")
157
+ self.filter.print(log)
158
+ time.sleep(0.1)
159
+ from_date = to_date
160
+ to_date = _utc_now_no_tz()
161
+ except KeyboardInterrupt:
162
+ print("Monitoring logs interrupted by user.")
163
+ _thread.interrupt_main()
164
+ break
165
+ except Exception as e:
166
+ print(f"Error monitoring logs: {e}")
167
+ break
168
+
169
+ def detach(self) -> None:
170
+ """Stop monitoring the container logs"""
171
+ self.running = False
172
+ self.thread.join()
173
+
174
+ def stop(self) -> None:
175
+ """Stop the container"""
176
+ self.container.stop()
177
+ self.detach()
178
+
179
+
180
+ def _hack_to_fix_mac(volumes: list[Volume] | None) -> list[Volume] | None:
181
+ """Fixes the volume mounts on MacOS by removing the mode."""
182
+ if volumes is None:
183
+ return None
184
+ if sys.platform != "darwin":
185
+ # Only macos needs hacking.
186
+ return volumes
187
+
188
+ volumes = volumes.copy()
189
+ # Work around a Docker bug on MacOS where the expected network socket to the
190
+ # the host is not mounted correctly. This was actually fixed in recent versions
191
+ # of docker client but there is a large chunk of Docker clients out there with
192
+ # this bug in it.
193
+ #
194
+ # This hack is done by mounting the socket directly to the container.
195
+ # This socket talks to the docker daemon on the host.
196
+ #
197
+ # Found here.
198
+ # https://github.com/docker/docker-py/issues/3069#issuecomment-1316778735
199
+ # if it exists already then return the input
200
+ for volume in volumes:
201
+ if volume.host_path == "/var/run/docker.sock":
202
+ return volumes
203
+ # ok it doesn't exist, so add it
204
+ volumes.append(
205
+ Volume(
206
+ host_path="/var/run/docker.sock",
207
+ container_path="/var/run/docker.sock",
208
+ mode="rw",
209
+ )
210
+ )
211
+ return volumes
212
+
213
+
214
+ class DockerManager:
215
+ def __init__(self) -> None:
216
+ from docker.errors import DockerException
217
+
218
+ self.is_suspended: bool = False
219
+
220
+ try:
221
+ self._client: DockerClient | None = None
222
+ self.first_run = False
223
+ except DockerException as e:
224
+ stack = traceback.format_exc()
225
+ warnings.warn(f"Error initializing Docker client: {e}\n{stack}")
226
+ raise
227
+
228
+ @property
229
+ def client(self) -> DockerClient:
230
+ if self._client is None:
231
+ self._client = docker.from_env()
232
+ return self._client
233
+
234
+ @staticmethod
235
+ def is_docker_installed() -> bool:
236
+ """Check if Docker is installed on the system."""
237
+ try:
238
+ subprocess.run(["docker", "--version"], capture_output=True, check=True)
239
+ print("Docker is installed.")
240
+ return True
241
+ except subprocess.CalledProcessError as e:
242
+ print(f"Docker command failed: {str(e)}")
243
+ return False
244
+ except FileNotFoundError:
245
+ print("Docker is not installed.")
246
+ return False
247
+
248
+ @staticmethod
249
+ def ensure_linux_containers_for_windows() -> bool:
250
+ """Ensure Docker is using Linux containers on Windows."""
251
+ if sys.platform != "win32":
252
+ return True # Only needed on Windows
253
+
254
+ try:
255
+ # Check if we're already in Linux container mode
256
+ result = subprocess.run(
257
+ ["docker", "info"], capture_output=True, text=True, check=True
258
+ )
259
+
260
+ if "linux" in result.stdout.lower():
261
+ print("Already using Linux containers")
262
+ return True
263
+
264
+ if not _IS_GITHUB:
265
+ answer = (
266
+ input(
267
+ "\nDocker on Windows must be in linux mode, this is a global change, switch? [y/n]"
268
+ )
269
+ .strip()
270
+ .lower()[:1]
271
+ )
272
+ if answer != "y":
273
+ return False
274
+
275
+ print("Switching to Linux containers...")
276
+ warnings.warn("Switching Docker to use Linux container context...")
277
+
278
+ # Explicitly specify the Linux container context
279
+ linux_context = "desktop-linux"
280
+ subprocess.run(
281
+ ["cmd", "/c", f"docker context use {linux_context}"],
282
+ check=True,
283
+ capture_output=True,
284
+ )
285
+
286
+ # Verify the switch worked
287
+ verify = subprocess.run(
288
+ ["docker", "info"], capture_output=True, text=True, check=True
289
+ )
290
+ if "linux" in verify.stdout.lower():
291
+ print(
292
+ f"Successfully switched to Linux containers using '{linux_context}' context"
293
+ )
294
+ return True
295
+
296
+ warnings.warn(
297
+ f"Failed to switch to Linux containers with context '{linux_context}': {verify.stdout}"
298
+ )
299
+ return False
300
+
301
+ except subprocess.CalledProcessError as e:
302
+ print(f"Failed to switch to Linux containers: {e}")
303
+ if e.stdout:
304
+ print(f"stdout: {e.stdout}")
305
+ if e.stderr:
306
+ print(f"stderr: {e.stderr}")
307
+ return False
308
+ except Exception as e:
309
+ print(f"Unexpected error switching to Linux containers: {e}")
310
+ return False
311
+
312
+ @staticmethod
313
+ def is_running() -> tuple[bool, Exception | None]:
314
+ """Check if Docker is running by pinging the Docker daemon."""
315
+
316
+ if not DockerManager.is_docker_installed():
317
+ print("Docker is not installed.")
318
+ return False, Exception("Docker is not installed.")
319
+ try:
320
+ # self.client.ping()
321
+ client = docker.from_env()
322
+ client.ping()
323
+ print("Docker is running.")
324
+ return True, None
325
+ except DockerException as e:
326
+ print(f"Docker is not running: {str(e)}")
327
+ return False, e
328
+ except Exception as e:
329
+ print(f"Error pinging Docker daemon: {str(e)}")
330
+ return False, e
331
+
332
+ def start(self) -> bool:
333
+ """Attempt to start Docker Desktop (or the Docker daemon) automatically."""
334
+ print("Attempting to start Docker...")
335
+
336
+ try:
337
+ if sys.platform == "win32":
338
+ docker_path = _win32_docker_location()
339
+ if not docker_path:
340
+ print("Docker Desktop not found.")
341
+ return False
342
+ subprocess.run(["start", "", docker_path], shell=True)
343
+ elif sys.platform == "darwin":
344
+ subprocess.run(["open", "-a", "Docker"])
345
+ elif sys.platform.startswith("linux"):
346
+ subprocess.run(["sudo", "systemctl", "start", "docker"])
347
+ else:
348
+ print("Unknown platform. Cannot auto-launch Docker.")
349
+ return False
350
+
351
+ # Wait for Docker to start up with increasing delays
352
+ print("Waiting for Docker Desktop to start...")
353
+ attempts = 0
354
+ max_attempts = 20 # Increased max wait time
355
+ while attempts < max_attempts:
356
+ attempts += 1
357
+ if self.is_running():
358
+ print("Docker started successfully.")
359
+ return True
360
+
361
+ # Gradually increase wait time between checks
362
+ wait_time = min(5, 1 + attempts * 0.5)
363
+ print(
364
+ f"Docker not ready yet, waiting {wait_time:.1f}s... (attempt {attempts}/{max_attempts})"
365
+ )
366
+ time.sleep(wait_time)
367
+
368
+ print("Failed to start Docker within the expected time.")
369
+ print(
370
+ "Please try starting Docker Desktop manually and run this command again."
371
+ )
372
+ except KeyboardInterrupt:
373
+ print("Aborted by user.")
374
+ raise
375
+ except Exception as e:
376
+ print(f"Error starting Docker: {str(e)}")
377
+ return False
378
+
379
+ def has_newer_version(
380
+ self, image_name: str, tag: str = "latest"
381
+ ) -> tuple[bool, str]:
382
+ """
383
+ Check if a newer version of the image is available in the registry.
384
+
385
+ Args:
386
+ image_name: The name of the image to check
387
+ tag: The tag of the image to check
388
+
389
+ Returns:
390
+ A tuple of (has_newer_version, message)
391
+ has_newer_version: True if a newer version is available, False otherwise
392
+ message: A message describing the result, including the date of the newer version if available
393
+ """
394
+ try:
395
+ # Get the local image
396
+ local_image = self.client.images.get(f"{image_name}:{tag}")
397
+ local_image_id = local_image.id
398
+ assert local_image_id is not None
399
+
400
+ # Get the remote image data
401
+ remote_image = self.client.images.get_registry_data(f"{image_name}:{tag}")
402
+ remote_image_hash = remote_image.id
403
+
404
+ # Check if we have a cached remote hash for this local image
405
+ try:
406
+ remote_image_hash_from_local_image = DISK_CACHE.get(local_image_id)
407
+ except Exception:
408
+ remote_image_hash_from_local_image = None
409
+
410
+ # Compare the hashes
411
+ if remote_image_hash_from_local_image == remote_image_hash:
412
+ return False, f"Local image {image_name}:{tag} is up to date."
413
+ else:
414
+ # Get the creation date of the remote image if possible
415
+ try:
416
+ # Try to get detailed image info including creation date
417
+ remote_image_details = self.client.api.inspect_image(
418
+ f"{image_name}:{tag}"
419
+ )
420
+ if "Created" in remote_image_details:
421
+ created_date = remote_image_details["Created"].split("T")[
422
+ 0
423
+ ] # Extract just the date part
424
+ return (
425
+ True,
426
+ f"Newer version of {image_name}:{tag} is available (published on {created_date}).",
427
+ )
428
+ except Exception:
429
+ pass
430
+
431
+ # Fallback if we couldn't get the date
432
+ return True, f"Newer version of {image_name}:{tag} is available."
433
+
434
+ except ImageNotFound:
435
+ return True, f"Image {image_name}:{tag} not found locally."
436
+ except DockerException as e:
437
+ return False, f"Error checking for newer version: {e}"
438
+
439
+ def validate_or_download_image(
440
+ self, image_name: str, tag: str = "latest", upgrade: bool = False
441
+ ) -> bool:
442
+ """
443
+ Validate if the image exists, and if not, download it.
444
+ If upgrade is True, will pull the latest version even if image exists locally.
445
+ """
446
+ ok = DockerManager.ensure_linux_containers_for_windows()
447
+ if not ok:
448
+ warnings.warn(
449
+ "Failed to ensure Linux containers on Windows. This build may fail."
450
+ )
451
+ print(f"Validating image {image_name}:{tag}...")
452
+ remote_image_hash_from_local_image: str | None = None
453
+ remote_image_hash: str | None = None
454
+
455
+ with get_lock(f"{image_name}-{tag}"):
456
+ try:
457
+ local_image = self.client.images.get(f"{image_name}:{tag}")
458
+ print(f"Image {image_name}:{tag} is already available.")
459
+
460
+ if upgrade:
461
+ remote_image = self.client.images.get_registry_data(
462
+ f"{image_name}:{tag}"
463
+ )
464
+ remote_image_hash = remote_image.id
465
+
466
+ try:
467
+ local_image_id = local_image.id
468
+ assert local_image_id is not None
469
+ remote_image_hash_from_local_image = DISK_CACHE.get(
470
+ local_image_id
471
+ )
472
+ except KeyboardInterrupt:
473
+ raise
474
+ except Exception:
475
+ remote_image_hash_from_local_image = None
476
+ stack = traceback.format_exc()
477
+ warnings.warn(
478
+ f"Error getting remote image hash from local image: {stack}"
479
+ )
480
+ if remote_image_hash_from_local_image == remote_image_hash:
481
+ print(f"Local image {image_name}:{tag} is up to date.")
482
+ return False
483
+
484
+ # Quick check for latest version
485
+ with Spinner(f"Pulling newer version of {image_name}:{tag}..."):
486
+ cmd_list = ["docker", "pull", f"{image_name}:{tag}"]
487
+ cmd_str = subprocess.list2cmdline(cmd_list)
488
+ print(f"Running command: {cmd_str}")
489
+ subprocess.run(cmd_list, check=True)
490
+ print(f"Updated to newer version of {image_name}:{tag}")
491
+ local_image_hash = self.client.images.get(f"{image_name}:{tag}").id
492
+ assert local_image_hash is not None
493
+ if remote_image_hash is not None:
494
+ DISK_CACHE.put(local_image_hash, remote_image_hash)
495
+ return True
496
+
497
+ except ImageNotFound:
498
+ print(f"Image {image_name}:{tag} not found.")
499
+ with Spinner("Loading "):
500
+ # We use docker cli here because it shows the download.
501
+ cmd_list = ["docker", "pull", f"{image_name}:{tag}"]
502
+ cmd_str = subprocess.list2cmdline(cmd_list)
503
+ print(f"Running command: {cmd_str}")
504
+ subprocess.run(cmd_list, check=True)
505
+ try:
506
+ local_image = self.client.images.get(f"{image_name}:{tag}")
507
+ local_image_hash = local_image.id
508
+ print(f"Image {image_name}:{tag} downloaded successfully.")
509
+ except ImageNotFound:
510
+ warnings.warn(f"Image {image_name}:{tag} not found after download.")
511
+ return True
512
+
513
+ def tag_image(self, image_name: str, old_tag: str, new_tag: str) -> None:
514
+ """
515
+ Tag an image with a new tag.
516
+ """
517
+ image: Image = self.client.images.get(f"{image_name}:{old_tag}")
518
+ image.tag(image_name, new_tag)
519
+ print(f"Image {image_name}:{old_tag} tagged as {new_tag}.")
520
+
521
+ def _container_configs_match(
522
+ self,
523
+ container: Container,
524
+ command: str | None,
525
+ volumes_dict: dict[str, dict[str, str]] | None,
526
+ ports: dict[int, int] | None,
527
+ ) -> bool:
528
+ """Compare if existing container has matching configuration"""
529
+ try:
530
+ # Check if container is using the same image
531
+ image = container.image
532
+ assert image is not None
533
+ container_image_id = image.id
534
+ container_image_tags = image.tags
535
+ assert container_image_id is not None
536
+
537
+ # Simplified image comparison - just compare the IDs directly
538
+ if not container_image_tags:
539
+ print(f"Container using untagged image with ID: {container_image_id}")
540
+ else:
541
+ current_image = self.client.images.get(container_image_tags[0])
542
+ if container_image_id != current_image.id:
543
+ print(
544
+ f"Container using different image version. Container: {container_image_id}, Current: {current_image.id}"
545
+ )
546
+ return False
547
+
548
+ # Check command if specified
549
+ if command and container.attrs["Config"]["Cmd"] != command.split():
550
+ print(
551
+ f"Command mismatch: {container.attrs['Config']['Cmd']} != {command}"
552
+ )
553
+ return False
554
+
555
+ # Check volumes if specified
556
+ if volumes_dict:
557
+ container_mounts = (
558
+ {
559
+ m["Source"]: {"bind": m["Destination"], "mode": m["Mode"]}
560
+ for m in container.attrs["Mounts"]
561
+ }
562
+ if container.attrs.get("Mounts")
563
+ else {}
564
+ )
565
+
566
+ for host_dir, mount in volumes_dict.items():
567
+ if host_dir not in container_mounts:
568
+ print(f"Volume {host_dir} not found in container mounts.")
569
+ return False
570
+ if container_mounts[host_dir] != mount:
571
+ print(
572
+ f"Volume {host_dir} has different mount options: {container_mounts[host_dir]} != {mount}"
573
+ )
574
+ return False
575
+
576
+ # Check ports if specified
577
+ if ports:
578
+ container_ports = (
579
+ container.attrs["Config"]["ExposedPorts"]
580
+ if container.attrs["Config"].get("ExposedPorts")
581
+ else {}
582
+ )
583
+ container_port_bindings = (
584
+ container.attrs["HostConfig"]["PortBindings"]
585
+ if container.attrs["HostConfig"].get("PortBindings")
586
+ else {}
587
+ )
588
+
589
+ for container_port, host_port in ports.items():
590
+ port_key = f"{container_port}/tcp"
591
+ if port_key not in container_ports:
592
+ print(f"Container port {port_key} not found.")
593
+ return False
594
+ if not container_port_bindings.get(port_key, [{"HostPort": None}])[
595
+ 0
596
+ ]["HostPort"] == str(host_port):
597
+ print(f"Port {host_port} is not bound to {port_key}.")
598
+ return False
599
+ except KeyboardInterrupt:
600
+ raise
601
+ except NotFound:
602
+ print("Container not found.")
603
+ return False
604
+ except Exception as e:
605
+ stack = traceback.format_exc()
606
+ warnings.warn(f"Error checking container config: {e}\n{stack}")
607
+ return False
608
+ return True
609
+
610
+ def run_container_detached(
611
+ self,
612
+ image_name: str,
613
+ tag: str,
614
+ container_name: str,
615
+ command: str | None = None,
616
+ volumes: list[Volume] | None = None,
617
+ ports: dict[int, int] | None = None,
618
+ remove_previous: bool = False,
619
+ environment: dict[str, str] | None = None,
620
+ tmpfs_size: str | None = None, # suffixed like 25mb.
621
+ ) -> Container:
622
+ """
623
+ Run a container from an image. If it already exists with matching config, start it.
624
+ If it exists with different config, remove and recreate it.
625
+
626
+ Args:
627
+ volumes: List of Volume objects for container volume mappings
628
+ ports: Dict mapping host ports to container ports
629
+ Example: {8080: 80} maps host port 8080 to container port 80
630
+ """
631
+ tmpfs_size = tmpfs_size or get_ramdisk_size()
632
+ sys_admin = tmpfs_size is not None and tmpfs_size != "0"
633
+ volumes = _hack_to_fix_mac(volumes)
634
+ # Convert volumes to the format expected by Docker API
635
+ volumes_dict = None
636
+ if volumes is not None:
637
+ volumes_dict = {}
638
+ for volume in volumes:
639
+ volumes_dict.update(volume.to_dict())
640
+
641
+ # Serialize the volumes to a json string
642
+ if volumes_dict:
643
+ volumes_str = json.dumps(volumes_dict)
644
+ print(f"Volumes: {volumes_str}")
645
+ print("Done")
646
+ image_name = f"{image_name}:{tag}"
647
+ try:
648
+ container: Container = self.client.containers.get(container_name)
649
+
650
+ if remove_previous:
651
+ print(f"Removing existing container {container_name}...")
652
+ container.remove(force=True)
653
+ raise NotFound("Container removed due to remove_previous")
654
+ # Check if configuration matches
655
+ elif not self._container_configs_match(
656
+ container, command, volumes_dict, ports
657
+ ):
658
+ print(
659
+ f"Container {container_name} exists but with different configuration. Removing and recreating..."
660
+ )
661
+ container.remove(force=True)
662
+ raise NotFound("Container removed due to config mismatch")
663
+ print(f"Container {container_name} found with matching configuration.")
664
+
665
+ # Existing container with matching config - handle various states
666
+ if container.status == "running":
667
+ print(f"Container {container_name} is already running.")
668
+ elif container.status == "exited":
669
+ print(f"Starting existing container {container_name}.")
670
+ container.start()
671
+ elif container.status == "restarting":
672
+ print(f"Waiting for container {container_name} to restart...")
673
+ timeout = 10
674
+ container.wait(timeout=10)
675
+ if container.status == "running":
676
+ print(f"Container {container_name} has restarted.")
677
+ else:
678
+ print(
679
+ f"Container {container_name} did not restart within {timeout} seconds."
680
+ )
681
+ container.stop(timeout=0)
682
+ print(f"Container {container_name} has been stopped.")
683
+ container.start()
684
+ elif container.status == "paused":
685
+ print(f"Resuming existing container {container_name}.")
686
+ container.unpause()
687
+ else:
688
+ print(f"Unknown container status: {container.status}")
689
+ print(f"Starting existing container {container_name}.")
690
+ self.first_run = True
691
+ container.start()
692
+ except NotFound:
693
+ print(f"Creating and starting {container_name}")
694
+ out_msg = f"# Running in container: {command}"
695
+ msg_len = len(out_msg)
696
+ print("\n" + "#" * msg_len)
697
+ print(out_msg)
698
+ print("#" * msg_len + "\n")
699
+
700
+ tmpfs: dict[str, str] | None = None
701
+ if tmpfs_size:
702
+ tmpfs = {_DEFAULT_BUILD_DIR: f"size={tmpfs_size}"}
703
+ container = self.client.containers.run(
704
+ image=image_name,
705
+ command=command,
706
+ name=container_name,
707
+ tmpfs=tmpfs,
708
+ cap_add=["SYS_ADMIN"] if sys_admin else None,
709
+ detach=True,
710
+ tty=True,
711
+ volumes=volumes_dict,
712
+ ports=ports, # type: ignore
713
+ environment=environment,
714
+ remove=True,
715
+ )
716
+ return container
717
+
718
+ def run_container_interactive(
719
+ self,
720
+ image_name: str,
721
+ tag: str,
722
+ container_name: str,
723
+ command: str | None = None,
724
+ volumes: list[Volume] | None = None,
725
+ ports: dict[int, int] | None = None,
726
+ environment: dict[str, str] | None = None,
727
+ ) -> None:
728
+ # Convert volumes to the format expected by Docker API
729
+ volumes = _hack_to_fix_mac(volumes)
730
+ volumes_dict = None
731
+ if volumes is not None:
732
+ volumes_dict = {}
733
+ for volume in volumes:
734
+ volumes_dict.update(volume.to_dict())
735
+ # Remove existing container
736
+ try:
737
+ container: Container = self.client.containers.get(container_name)
738
+ container.remove(force=True)
739
+ except NotFound:
740
+ pass
741
+ start_time = time.time()
742
+ try:
743
+ docker_command: list[str] = [
744
+ "docker",
745
+ "run",
746
+ "-it",
747
+ "--rm",
748
+ "--name",
749
+ container_name,
750
+ ]
751
+ if volumes_dict:
752
+ for host_dir, mount in volumes_dict.items():
753
+ docker_volume_arg = [
754
+ "-v",
755
+ f"{host_dir}:{mount['bind']}:{mount['mode']}",
756
+ ]
757
+ docker_command.extend(docker_volume_arg)
758
+ if ports:
759
+ for host_port, container_port in ports.items():
760
+ docker_command.extend(["-p", f"{host_port}:{container_port}"])
761
+ if environment:
762
+ for env_name, env_value in environment.items():
763
+ docker_command.extend(["-e", f"{env_name}={env_value}"])
764
+ docker_command.append(f"{image_name}:{tag}")
765
+ if command:
766
+ docker_command.append(command)
767
+ cmd_str: str = subprocess.list2cmdline(docker_command)
768
+ print(f"Running command: {cmd_str}")
769
+ subprocess.run(docker_command, check=False)
770
+ except subprocess.CalledProcessError as e:
771
+ print(f"Error running Docker command: {e}")
772
+ diff = time.time() - start_time
773
+ if diff < 5:
774
+ raise
775
+ sys.exit(1) # Probably a user exit.
776
+
777
+ def attach_and_run(self, container: Container | str) -> RunningContainer:
778
+ """
779
+ Attach to a running container and monitor its logs in a background thread.
780
+ Returns a RunningContainer object that can be used to stop monitoring.
781
+ """
782
+ if isinstance(container, str):
783
+ container_name = container
784
+ tmp = self.get_container(container)
785
+ assert tmp is not None, f"Container {container_name} not found."
786
+ container = tmp
787
+
788
+ assert container is not None, "Container not found."
789
+
790
+ print(f"Attaching to container {container.name}...")
791
+
792
+ first_run = self.first_run
793
+ self.first_run = False
794
+
795
+ return RunningContainer(container, first_run)
796
+
797
+ def suspend_container(self, container: Container | str) -> None:
798
+ """
799
+ Suspend (pause) the container.
800
+ """
801
+ if self.is_suspended:
802
+ return
803
+ if isinstance(container, str):
804
+ container_name = container
805
+ # container = self.get_container(container)
806
+ tmp = self.get_container(container_name)
807
+ if not tmp:
808
+ print(f"Could not put container {container_name} to sleep.")
809
+ return
810
+ container = tmp
811
+ assert isinstance(container, Container)
812
+ try:
813
+ if platform.system() == "Windows":
814
+ container.pause()
815
+ else:
816
+ container.stop()
817
+ container.remove()
818
+ print(f"Container {container.name} has been suspended.")
819
+ except KeyboardInterrupt:
820
+ print(f"Container {container.name} interrupted by keyboard interrupt.")
821
+ except Exception as e:
822
+ print(f"Failed to suspend container {container.name}: {e}")
823
+
824
+ def resume_container(self, container: Container | str) -> None:
825
+ """
826
+ Resume (unpause) the container.
827
+ """
828
+ container_name = "UNKNOWN"
829
+ if isinstance(container, str):
830
+ container_name = container
831
+ container_or_none = self.get_container(container)
832
+ if container_or_none is None:
833
+ print(f"Could not resume container {container}.")
834
+ return
835
+ container = container_or_none
836
+ container_name = container.name
837
+ elif isinstance(container, Container):
838
+ container_name = container.name
839
+ assert isinstance(container, Container)
840
+ if not container:
841
+ print(f"Could not resume container {container}.")
842
+ return
843
+ try:
844
+ assert isinstance(container, Container)
845
+ container.unpause()
846
+ print(f"Container {container.name} has been resumed.")
847
+ except Exception as e:
848
+ print(f"Failed to resume container {container_name}: {e}")
849
+
850
+ def get_container(self, container_name: str) -> Container | None:
851
+ """
852
+ Get a container by name.
853
+ """
854
+ try:
855
+ return self.client.containers.get(container_name)
856
+ except NotFound:
857
+ return None
858
+
859
+ def is_container_running(self, container_name: str) -> bool:
860
+ """
861
+ Check if a container is running.
862
+ """
863
+ try:
864
+ container = self.client.containers.get(container_name)
865
+ return container.status == "running"
866
+ except NotFound:
867
+ print(f"Container {container_name} not found.")
868
+ return False
869
+
870
+ def build_image(
871
+ self,
872
+ image_name: str,
873
+ tag: str,
874
+ dockerfile_path: Path,
875
+ build_context: Path,
876
+ build_args: dict[str, str] | None = None,
877
+ platform_tag: str = "",
878
+ ) -> None:
879
+ """
880
+ Build a Docker image from a Dockerfile.
881
+
882
+ Args:
883
+ image_name: Name for the image
884
+ tag: Tag for the image
885
+ dockerfile_path: Path to the Dockerfile
886
+ build_context: Path to the build context directory
887
+ build_args: Optional dictionary of build arguments
888
+ platform_tag: Optional platform tag (e.g. "-arm64")
889
+ """
890
+ if not dockerfile_path.exists():
891
+ raise FileNotFoundError(f"Dockerfile not found at {dockerfile_path}")
892
+
893
+ if not build_context.exists():
894
+ raise FileNotFoundError(
895
+ f"Build context directory not found at {build_context}"
896
+ )
897
+
898
+ print(f"Building Docker image {image_name}:{tag} from {dockerfile_path}")
899
+
900
+ # Prepare build arguments
901
+ buildargs = build_args or {}
902
+ if platform_tag:
903
+ buildargs["PLATFORM_TAG"] = platform_tag
904
+
905
+ try:
906
+ cmd_list = [
907
+ "docker",
908
+ "build",
909
+ "-t",
910
+ f"{image_name}:{tag}",
911
+ ]
912
+
913
+ # Add build args
914
+ for arg_name, arg_value in buildargs.items():
915
+ cmd_list.extend(["--build-arg", f"{arg_name}={arg_value}"])
916
+
917
+ # Add dockerfile and context paths
918
+ cmd_list.extend(["-f", str(dockerfile_path), str(build_context)])
919
+
920
+ cmd_str = subprocess.list2cmdline(cmd_list)
921
+ print(f"Running command: {cmd_str}")
922
+
923
+ # Run the build command
924
+ # cp = subprocess.run(cmd_list, check=True, capture_output=True)
925
+ proc: subprocess.Popen = subprocess.Popen(
926
+ cmd_list, stdout=subprocess.PIPE, stderr=subprocess.STDOUT
927
+ )
928
+ stdout = proc.stdout
929
+ assert stdout is not None, "stdout is None"
930
+ for line in iter(stdout.readline, b""):
931
+ try:
932
+ line_str = line.decode("utf-8")
933
+ print(line_str, end="")
934
+ except UnicodeDecodeError:
935
+ print("Error decoding line")
936
+ rtn = proc.wait()
937
+ if rtn != 0:
938
+ warnings.warn(
939
+ f"Error building Docker image, is docker running? {rtn}, stdout: {stdout}, stderr: {proc.stderr}"
940
+ )
941
+ raise subprocess.CalledProcessError(rtn, cmd_str)
942
+ print(f"Successfully built image {image_name}:{tag}")
943
+
944
+ except subprocess.CalledProcessError as e:
945
+ print(f"Error building Docker image: {e}")
946
+ raise
947
+
948
+ def purge(self, image_name: str) -> None:
949
+ """
950
+ Remove all containers and images associated with the given image name.
951
+
952
+ Args:
953
+ image_name: The name of the image to purge (without tag)
954
+ """
955
+ print(f"Purging all containers and images for {image_name}...")
956
+
957
+ # Remove all containers using this image
958
+ try:
959
+ containers = self.client.containers.list(all=True)
960
+ for container in containers:
961
+ if any(image_name in tag for tag in container.image.tags):
962
+ print(f"Removing container {container.name}")
963
+ container.remove(force=True)
964
+
965
+ except Exception as e:
966
+ print(f"Error removing containers: {e}")
967
+
968
+ # Remove all images with this name
969
+ try:
970
+ self.client.images.prune(filters={"dangling": False})
971
+ images = self.client.images.list()
972
+ for image in images:
973
+ if any(image_name in tag for tag in image.tags):
974
+ print(f"Removing image {image.tags}")
975
+ self.client.images.remove(image.id, force=True)
976
+ except Exception as e:
977
+ print(f"Error removing images: {e}")
978
+
979
+
980
+ def main() -> None:
981
+ # Register SIGINT handler
982
+ # signal.signal(signal.SIGINT, handle_sigint)
983
+
984
+ docker_manager = DockerManager()
985
+
986
+ # Parameters
987
+ image_name = "python"
988
+ tag = "3.10-slim"
989
+ # new_tag = "my-python"
990
+ container_name = "my-python-container"
991
+ command = "python -m http.server"
992
+ running_container: RunningContainer | None = None
993
+
994
+ try:
995
+ # Step 1: Validate or download the image
996
+ docker_manager.validate_or_download_image(image_name, tag, upgrade=True)
997
+
998
+ # Step 2: Tag the image
999
+ # docker_manager.tag_image(image_name, tag, new_tag)
1000
+
1001
+ # Step 3: Run the container
1002
+ container = docker_manager.run_container_detached(
1003
+ image_name, tag, container_name, command
1004
+ )
1005
+
1006
+ # Step 4: Attach and monitor the container logs
1007
+ running_container = docker_manager.attach_and_run(container)
1008
+
1009
+ # Wait for keyboard interrupt
1010
+ while True:
1011
+ time.sleep(0.1)
1012
+
1013
+ except KeyboardInterrupt:
1014
+ print("\nStopping container...")
1015
+ if isinstance(running_container, RunningContainer):
1016
+ running_container.stop()
1017
+ container_or_none = docker_manager.get_container(container_name)
1018
+ if container_or_none is not None:
1019
+ docker_manager.suspend_container(container_or_none)
1020
+ else:
1021
+ warnings.warn(f"Container {container_name} not found.")
1022
+
1023
+ try:
1024
+ # Suspend and resume the container
1025
+ container = docker_manager.get_container(container_name)
1026
+ assert container is not None, "Container not found."
1027
+ docker_manager.suspend_container(container)
1028
+
1029
+ input("Press Enter to resume the container...")
1030
+
1031
+ docker_manager.resume_container(container)
1032
+ except Exception as e:
1033
+ print(f"An error occurred: {e}")
1034
+
1035
+
1036
+ if __name__ == "__main__":
1037
+ main()