heatmap_cli 0.25.5__tar.gz → 0.27.0__tar.gz

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.
Files changed (54) hide show
  1. {heatmap_cli-0.25.5/src/heatmap_cli.egg-info → heatmap_cli-0.27.0}/PKG-INFO +4 -7
  2. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/README.md +3 -6
  3. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/pyproject.toml +1 -1
  4. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/src/heatmap_cli/__init__.py +28 -8
  5. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/src/heatmap_cli/cli.py +167 -30
  6. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/src/heatmap_cli/heatmap.py +78 -8
  7. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0/src/heatmap_cli.egg-info}/PKG-INFO +4 -7
  8. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/src/heatmap_cli.egg-info/SOURCES.txt +0 -1
  9. heatmap_cli-0.27.0/tests/test_end_date_option.py +87 -0
  10. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_heatmap_errors.py +36 -0
  11. heatmap_cli-0.27.0/tests/test_help_flag.py +75 -0
  12. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_purge_flag.py +25 -1
  13. heatmap_cli-0.27.0/tests/test_refresh_output_dir.py +126 -0
  14. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_start_date_option.py +10 -0
  15. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_version_flag.py +16 -1
  16. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_year_option.py +32 -0
  17. heatmap_cli-0.25.5/tests/test_end_date_option.py +0 -41
  18. heatmap_cli-0.25.5/tests/test_help_flag.py +0 -25
  19. heatmap_cli-0.25.5/tests/test_refresh_output_dir.py +0 -45
  20. heatmap_cli-0.25.5/tests/test_verbose_flag.py +0 -31
  21. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/LICENSE.md +0 -0
  22. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/setup.cfg +0 -0
  23. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/src/heatmap_cli/__main__.py +0 -0
  24. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/src/heatmap_cli/py.typed +0 -0
  25. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/src/heatmap_cli.egg-info/dependency_links.txt +0 -0
  26. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/src/heatmap_cli.egg-info/entry_points.txt +0 -0
  27. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/src/heatmap_cli.egg-info/requires.txt +0 -0
  28. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/src/heatmap_cli.egg-info/top_level.txt +0 -0
  29. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_animate_by_week.py +0 -0
  30. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_animate_no_frames.py +0 -0
  31. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_animate_open.py +0 -0
  32. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_annotate_flag.py +0 -0
  33. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_annotation_truncation.py +0 -0
  34. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_cbar_flag.py +0 -0
  35. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_cmap_option.py +0 -0
  36. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_cmax_option.py +0 -0
  37. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_cmin_option.py +0 -0
  38. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_configure_cbar.py +0 -0
  39. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_debug_flag.py +0 -0
  40. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_demo_option.py +0 -0
  41. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_env_flag.py +0 -0
  42. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_heatmap_direct.py +0 -0
  43. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_heatmap_open.py +0 -0
  44. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_heatmap_utils.py +0 -0
  45. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_heatmap_wrapper.py +0 -0
  46. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_iso_53_week_year.py +0 -0
  47. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_no_annotate.py +0 -0
  48. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_open_heatmap.py +0 -0
  49. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_output_dir_option.py +0 -0
  50. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_quiet_flag.py +0 -0
  51. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_setup_logging.py +0 -0
  52. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_title_option.py +0 -0
  53. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_week_option.py +0 -0
  54. {heatmap_cli-0.25.5 → heatmap_cli-0.27.0}/tests/test_yes_flag.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: heatmap_cli
3
- Version: 0.25.5
3
+ Version: 0.27.0
4
4
  Summary: A console program that generates a yearly calendar heatmap.
5
5
  Author-email: Kian-Meng Ang <kianmeng@cpan.org>
6
6
  License-Expression: AGPL-3.0-or-later
@@ -56,7 +56,7 @@ heatmap -h -v
56
56
  ```console
57
57
  usage: heatmap_cli [--demo [NUMBER_OF_COLORMAP]] [--seed SEED] [-y YEAR]
58
58
  [-w WEEK] [-e END_DATE] [-s START_DATE] [-O OUTPUT_DIR]
59
- [-o] [-p] [-v] [-t TITLE] [-u AUTHOR] [-f IMAGE_FORMAT]
59
+ [-o] [-p] [-t TITLE] [-u AUTHOR] [-f IMAGE_FORMAT]
60
60
  [-c COLORMAP] [-i COLORMAP_MIN_VALUE]
61
61
  [-x COLORMAP_MAX_VALUE] [-b]
62
62
  [-a | --annotate | --no-annotate] [--animate-by-week] [-q]
@@ -75,7 +75,7 @@ positional arguments:
75
75
 
76
76
  options:
77
77
  --demo [NUMBER_OF_COLORMAP]
78
- generate number of heatmaps by colormaps (default: '194')
78
+ generate number of heatmaps by colormaps (default: '194'). Implied: covers the current ISO year; -y/-w/-s/-e/-c are ignored.
79
79
  --seed SEED
80
80
  set random seed for reproducible --demo output (default: None)
81
81
  -y, --year YEAR
@@ -85,15 +85,13 @@ options:
85
85
  -e, --end-date END_DATE
86
86
  filter until the date of the year from the CSV file and this will overwrite -y and -w option (default: None)
87
87
  -s, --start-date START_DATE
88
- filter from the date of the year from the CSV file (default: None)
88
+ filter from the date of the year from the CSV file and this will overwrite -y and -w option (default: None)
89
89
  -O, --output-dir OUTPUT_DIR
90
90
  set default output folder (default: 'output')
91
91
  -o, --open
92
92
  open the generated heatmap using the default program (default: False)
93
93
  -p, --purge
94
94
  remove all leftover artifacts set by --output-dir folder (default: False)
95
- -v, --verbose
96
- show verbosity of debugging log. Use -vv, -vvv for more details
97
95
  -t, --title TITLE
98
96
  set title for the heatmap (default: None)
99
97
  -u, --author AUTHOR
@@ -102,7 +100,6 @@ options:
102
100
  set the default image format (default: 'png')
103
101
  -c, --cmap COLORMAP
104
102
  Set default colormap. (default: 'RdYlGn_r')
105
-
106
103
  Available colormaps:
107
104
  Accent, Accent_r, afmhot, afmhot_r, autumn, autumn_r
108
105
  berlin, berlin_r, binary, binary_r, Blues, Blues_r
@@ -27,7 +27,7 @@ heatmap -h -v
27
27
  ```console
28
28
  usage: heatmap_cli [--demo [NUMBER_OF_COLORMAP]] [--seed SEED] [-y YEAR]
29
29
  [-w WEEK] [-e END_DATE] [-s START_DATE] [-O OUTPUT_DIR]
30
- [-o] [-p] [-v] [-t TITLE] [-u AUTHOR] [-f IMAGE_FORMAT]
30
+ [-o] [-p] [-t TITLE] [-u AUTHOR] [-f IMAGE_FORMAT]
31
31
  [-c COLORMAP] [-i COLORMAP_MIN_VALUE]
32
32
  [-x COLORMAP_MAX_VALUE] [-b]
33
33
  [-a | --annotate | --no-annotate] [--animate-by-week] [-q]
@@ -46,7 +46,7 @@ positional arguments:
46
46
 
47
47
  options:
48
48
  --demo [NUMBER_OF_COLORMAP]
49
- generate number of heatmaps by colormaps (default: '194')
49
+ generate number of heatmaps by colormaps (default: '194'). Implied: covers the current ISO year; -y/-w/-s/-e/-c are ignored.
50
50
  --seed SEED
51
51
  set random seed for reproducible --demo output (default: None)
52
52
  -y, --year YEAR
@@ -56,15 +56,13 @@ options:
56
56
  -e, --end-date END_DATE
57
57
  filter until the date of the year from the CSV file and this will overwrite -y and -w option (default: None)
58
58
  -s, --start-date START_DATE
59
- filter from the date of the year from the CSV file (default: None)
59
+ filter from the date of the year from the CSV file and this will overwrite -y and -w option (default: None)
60
60
  -O, --output-dir OUTPUT_DIR
61
61
  set default output folder (default: 'output')
62
62
  -o, --open
63
63
  open the generated heatmap using the default program (default: False)
64
64
  -p, --purge
65
65
  remove all leftover artifacts set by --output-dir folder (default: False)
66
- -v, --verbose
67
- show verbosity of debugging log. Use -vv, -vvv for more details
68
66
  -t, --title TITLE
69
67
  set title for the heatmap (default: None)
70
68
  -u, --author AUTHOR
@@ -73,7 +71,6 @@ options:
73
71
  set the default image format (default: 'png')
74
72
  -c, --cmap COLORMAP
75
73
  Set default colormap. (default: 'RdYlGn_r')
76
-
77
74
  Available colormaps:
78
75
  Accent, Accent_r, afmhot, afmhot_r, autumn, autumn_r
79
76
  berlin, berlin_r, binary, binary_r, Blues, Blues_r
@@ -28,7 +28,7 @@ classifiers = [
28
28
  "Programming Language :: Python",
29
29
  "Topic :: Scientific/Engineering :: Visualization",
30
30
  ]
31
- version = "0.25.5"
31
+ version = "0.27.0"
32
32
  keywords = ["heatmap", "cli", "visualization", "calendar", "data-viz"]
33
33
  dependencies = [
34
34
  "matplotlib",
@@ -18,7 +18,6 @@
18
18
  from __future__ import annotations
19
19
 
20
20
  import argparse
21
- import datetime
22
21
  import logging
23
22
  import platform
24
23
  import random
@@ -34,7 +33,25 @@ import seaborn as sns
34
33
  from heatmap_cli.heatmap import _get_output_dir
35
34
  from heatmap_cli.heatmap import run as generate_heatmaps
36
35
 
37
- __version__ = metadata.version("heatmap_cli")
36
+ # Reported when the distribution metadata is unavailable, so that a source
37
+ # checkout which was never installed still runs instead of failing to import.
38
+ FALLBACK_VERSION = "0.0.0+unknown"
39
+
40
+
41
+ def _resolve_version() -> str:
42
+ """Return the version from the installed distribution metadata.
43
+
44
+ Returns:
45
+ str: The installed version, or ``FALLBACK_VERSION`` when the
46
+ package is not installed.
47
+ """
48
+ try:
49
+ return metadata.version("heatmap_cli")
50
+ except metadata.PackageNotFoundError:
51
+ return FALLBACK_VERSION
52
+
53
+
54
+ __version__ = _resolve_version()
38
55
 
39
56
  # Max value for demo heatmap count
40
57
  DEMO_MAX_COUNT = 12000
@@ -116,13 +133,16 @@ class DemoAction(argparse.Action):
116
133
  values: object,
117
134
  _option_string: str | None = None,
118
135
  ) -> None:
119
- """Set the namespace values required by the demo flow."""
136
+ """Record how many demo heatmaps to generate.
137
+
138
+ Only ``namespace.demo`` is set here. The demo flow's year, week,
139
+ colourbar and colormap defaults are applied once parsing has
140
+ finished (see `heatmap_cli.cli._apply_demo_overrides`), so that the
141
+ position of ``--demo`` on the command line cannot change the
142
+ outcome.
143
+ """
120
144
  demo_count = min(cast("int", values), len(CMAPS))
121
- demo_count = max(demo_count, 1)
122
- namespace.year = [datetime.datetime.now(tz=datetime.timezone.utc).year]
123
- namespace.week = 52
124
- namespace.cbar = True
125
- namespace.demo = demo_count
145
+ namespace.demo = max(demo_count, 1)
126
146
 
127
147
 
128
148
  def generate_demo(config: argparse.Namespace) -> None:
@@ -79,6 +79,19 @@ DEFAULT_CMAP = "RdYlGn_r"
79
79
  CMAP_ITEMS_PER_ROW = 6
80
80
  MAX_ISO_WEEK = 53
81
81
 
82
+ # Options that --demo overrides. --demo synthesises its own sample data for
83
+ # the current ISO year, so the options that select or restyle *that* data have
84
+ # nothing left to act on. -b/--cbar is absent on purpose: it is a store_true
85
+ # already defaulted to False, and --demo forces it to True, which is exactly
86
+ # what -b asks for, so there is nothing to report.
87
+ DEMO_IGNORED_OPTIONS = (
88
+ ("-y/--year", "year"),
89
+ ("-w/--week", "week"),
90
+ ("-s/--start-date", "start_date"),
91
+ ("-e/--end-date", "end_date"),
92
+ ("-c/--cmap", "cmap"),
93
+ )
94
+
82
95
 
83
96
  def _valid_date(s: str) -> datetime.date:
84
97
  """Validate date format.
@@ -148,7 +161,8 @@ def build_parser() -> argparse.ArgumentParser:
148
161
  dest="demo",
149
162
  help=(
150
163
  "generate number of heatmaps by colormaps "
151
- f"(default: '{len(CMAPS)}')"
164
+ f"(default: '{len(CMAPS)}'). "
165
+ "Implied: covers the current ISO year; -y/-w/-s/-e/-c are ignored."
152
166
  ),
153
167
  metavar="NUMBER_OF_COLORMAP",
154
168
  )
@@ -247,15 +261,6 @@ def build_parser() -> argparse.ArgumentParser:
247
261
  ),
248
262
  )
249
263
 
250
- parser.add_argument(
251
- "-v",
252
- "--verbose",
253
- default=0,
254
- action="count",
255
- dest="verbose",
256
- help="show verbosity of debugging log. Use -vv, -vvv for more details",
257
- )
258
-
259
264
  parser.add_argument(
260
265
  "input_filename",
261
266
  help="CSV filename (required unless --demo is used)",
@@ -410,6 +415,11 @@ def build_parser() -> argparse.ArgumentParser:
410
415
  def _generate_cmap_help() -> str:
411
416
  """Generate the help text for colormap options.
412
417
 
418
+ The colormap list follows the summary on the next line rather than after
419
+ a blank line: argparse's RawTextHelpFormatter indents every line of the
420
+ help text, so an empty line would come out as trailing whitespace, which
421
+ the trailing-whitespace hook then strips from the generated README.
422
+
413
423
  Returns:
414
424
  str: Formatted help text.
415
425
  """
@@ -417,7 +427,7 @@ def _generate_cmap_help() -> str:
417
427
  cmap_default = f" (default: '{DEFAULT_CMAP}')"
418
428
 
419
429
  # Always show all colormaps in help text
420
- cmap_choices = "\nAvailable colormaps:\n"
430
+ cmap_choices = "Available colormaps:\n"
421
431
  cmap_bygroups = zip_longest(*(iter(CMAPS),) * CMAP_ITEMS_PER_ROW)
422
432
  for cmap_bygroup in cmap_bygroups:
423
433
  cmap_choices += " " + ", ".join(filter(None, cmap_bygroup)) + "\n"
@@ -425,6 +435,67 @@ def _generate_cmap_help() -> str:
425
435
  return cmap_help + cmap_default + "\n" + cmap_choices.rstrip()
426
436
 
427
437
 
438
+ def _warn_ignored_filters(
439
+ option: str,
440
+ explicit_year: list[int] | None,
441
+ explicit_week: int | None,
442
+ ) -> None:
443
+ """Warn that -y/--year and -w/--week are ignored by a date filter.
444
+
445
+ Args:
446
+ option (str): The date option that takes precedence, for example
447
+ "--start-date".
448
+ explicit_year (list[int] | None): The years asked for on the command
449
+ line, or None when -y/--year was not given.
450
+ explicit_week (int | None): The week asked for on the command line,
451
+ or None when -w/--week was not given.
452
+
453
+ Returns:
454
+ None
455
+ """
456
+ if explicit_year is not None:
457
+ logger.warning(
458
+ "argument %s: --year is ignored when %s is used.",
459
+ option,
460
+ option,
461
+ )
462
+ if explicit_week is not None:
463
+ logger.warning(
464
+ "argument %s: --week is ignored when %s is used.",
465
+ option,
466
+ option,
467
+ )
468
+
469
+
470
+ def _warn_dropped_years(
471
+ option: str,
472
+ explicit_year: list[int] | None,
473
+ kept_year: int,
474
+ ) -> None:
475
+ """Warn that a date filter narrows a multi-year request to one year.
476
+
477
+ Args:
478
+ option (str): The date option that takes precedence.
479
+ explicit_year (list[int] | None): The years asked for on the command
480
+ line, or None when -y/--year was not given.
481
+ kept_year (int): The single year the date filter resolves to.
482
+
483
+ Returns:
484
+ None
485
+ """
486
+ if explicit_year is None:
487
+ return
488
+
489
+ dropped = [year for year in explicit_year if year != kept_year]
490
+ if dropped:
491
+ logger.warning(
492
+ "argument %s: only year %d is kept, dropping %s.",
493
+ option,
494
+ kept_year,
495
+ ", ".join(str(year) for year in dropped),
496
+ )
497
+
498
+
428
499
  def _resolve_date_filter_overrides(
429
500
  parsed_args: argparse.Namespace,
430
501
  ) -> None:
@@ -449,23 +520,81 @@ def _resolve_date_filter_overrides(
449
520
  explicit_week = parsed_args.week
450
521
 
451
522
  if parsed_args.end_date:
523
+ override_option = "--end-date"
452
524
  (year, week, _day) = parsed_args.end_date.isocalendar()
453
- parsed_args.year = [year]
454
- parsed_args.week = week
455
525
  elif parsed_args.start_date:
456
- if explicit_year is not None:
457
- logger.warning(
458
- "argument --start-date: --year is ignored when "
459
- "--start-date is used.",
460
- )
461
- if explicit_week is not None:
462
- logger.warning(
463
- "argument --start-date: --week is ignored when "
464
- "--start-date is used.",
465
- )
526
+ override_option = "--start-date"
466
527
  (year, _week, _day) = parsed_args.start_date.isocalendar()
467
- parsed_args.year = [year]
468
- parsed_args.week = _weeks_in_iso_year(year)
528
+ # --start-date alone views the rest of its ISO year.
529
+ week = _weeks_in_iso_year(year)
530
+ else:
531
+ return
532
+
533
+ _warn_ignored_filters(override_option, explicit_year, explicit_week)
534
+ _warn_dropped_years(override_option, explicit_year, year)
535
+ parsed_args.year = [year]
536
+ parsed_args.week = week
537
+
538
+
539
+ def _apply_demo_overrides(parsed_args: argparse.Namespace) -> None:
540
+ """Apply the --demo defaults, discarding options that cannot apply.
541
+
542
+ --demo generates its own sample data covering the current ISO year, so
543
+ the options that filter that data (-y, -w, -s, -e) and the option that
544
+ picks the colormaps (-c) are reported as ignored rather than silently
545
+ dropped. The defaults are applied here, after parsing has finished, so
546
+ that the position of --demo on the command line cannot change the
547
+ outcome.
548
+
549
+ Args:
550
+ parsed_args (argparse.Namespace): The parsed arguments, mutated in
551
+ place.
552
+
553
+ Returns:
554
+ None
555
+ """
556
+ ignored = [
557
+ option
558
+ for option, dest in DEMO_IGNORED_OPTIONS
559
+ if getattr(parsed_args, dest) is not None
560
+ ]
561
+ if ignored:
562
+ logger.warning(
563
+ "argument --demo: %s ignored, the demo data covers the "
564
+ "current year only.",
565
+ ", ".join(ignored),
566
+ )
567
+
568
+ iso_year = (
569
+ datetime.datetime.now(
570
+ tz=datetime.timezone.utc,
571
+ )
572
+ .isocalendar()
573
+ .year
574
+ )
575
+ parsed_args.year = [iso_year]
576
+ parsed_args.week = _weeks_in_iso_year(iso_year)
577
+ parsed_args.cbar = True
578
+
579
+
580
+ def _default_year_and_week(
581
+ now: datetime.datetime,
582
+ ) -> tuple[list[int], int]:
583
+ """Return the default year and week filters for the current time.
584
+
585
+ Both come from the ISO calendar so that they always describe the same
586
+ week. The calendar year and the ISO year disagree for the last few days
587
+ of December, when the current week already belongs to the next ISO year,
588
+ e.g. 2024-12-30 is in 2025-W01.
589
+
590
+ Args:
591
+ now (datetime.datetime): The current time.
592
+
593
+ Returns:
594
+ tuple[list[int], int]: The default year list and week number.
595
+ """
596
+ (iso_year, iso_week, _day) = now.isocalendar()
597
+ return [iso_year], iso_week
469
598
 
470
599
 
471
600
  def _process_args(
@@ -489,7 +618,14 @@ def _process_args(
489
618
  # double filter between the ISO-week year column and the raw date column.
490
619
  # When only one endpoint is given it derives a partial-year view; when
491
620
  # both are given --end-date wins for the year/week since it caps the range.
492
- _resolve_date_filter_overrides(parsed_args)
621
+ #
622
+ # --demo is exempt: it brings its own data for the current ISO year, so
623
+ # resolving a date range against it would only produce a misleading
624
+ # warning about the demo's own year.
625
+ if parsed_args.demo:
626
+ _apply_demo_overrides(parsed_args)
627
+ else:
628
+ _resolve_date_filter_overrides(parsed_args)
493
629
 
494
630
  if (
495
631
  parsed_args.start_date
@@ -505,12 +641,13 @@ def _process_args(
505
641
  parser.error("the following arguments are required: CSV_FILENAME")
506
642
 
507
643
  # Handle defaults for year and week
508
- if parsed_args.year is None or parsed_args.week is None:
509
- now = datetime.datetime.now(tz=datetime.timezone.utc)
644
+ (default_year, default_week) = _default_year_and_week(
645
+ datetime.datetime.now(tz=datetime.timezone.utc)
646
+ )
510
647
  if parsed_args.year is None:
511
- parsed_args.year = [now.year]
648
+ parsed_args.year = default_year
512
649
  if parsed_args.week is None:
513
- parsed_args.week = now.isocalendar().week
650
+ parsed_args.week = default_week
514
651
 
515
652
  # Handle default for cmap
516
653
  if parsed_args.cmap is None:
@@ -288,11 +288,28 @@ def _generate_static_heatmaps(
288
288
  ]
289
289
  logger.debug(args)
290
290
 
291
- with multiprocessing.Pool(
292
- initializer=_init_worker_logging,
293
- initargs=(config,),
294
- ) as pool:
295
- generated_files = pool.starmap(_generate_heatmap_wrapper, args)
291
+ generated_files: list[Path | None] = []
292
+ if len(config.cmap) == 1:
293
+ # For a single colormap, avoid spawning a multiprocessing Pool (and
294
+ # the associated per-worker imports on spawn-based platforms). This
295
+ # removes unnecessary overhead for the common default case while
296
+ # still returning the generated file so opening works as before.
297
+ seq, cmap = args[0][:2] # (seq, cmap, ...)
298
+ generated_files = [
299
+ _generate_heatmap(
300
+ seq,
301
+ cmap,
302
+ config,
303
+ pivoted_dataframe,
304
+ return_image=False,
305
+ )
306
+ ]
307
+ else:
308
+ with multiprocessing.Pool(
309
+ initializer=_init_worker_logging,
310
+ initargs=(config,),
311
+ ) as pool:
312
+ generated_files = pool.starmap(_generate_heatmap_wrapper, args)
296
313
 
297
314
  # Workers never open browsers; open the finished heatmaps from the main
298
315
  # process instead, so -o does not spawn a tab per background worker.
@@ -339,18 +356,27 @@ def _read_and_prepare_data(config: argparse.Namespace) -> pd.DataFrame:
339
356
 
340
357
  Raises:
341
358
  FileNotFoundError: If the input CSV file does not exist.
342
- ValueError: If the input is empty, or duplicate dates or negative
343
- counts are found.
359
+ ValueError: If the input is empty, or the dates or counts are
360
+ invalid, or duplicate dates or negative counts are found.
344
361
  """
345
362
  try:
363
+ # The dtype makes pandas reject anything that is not a whole number,
364
+ # including blank cells, text, and infinity.
346
365
  dataframe = pd.read_csv(
347
366
  config.input_filename,
348
367
  header=None,
349
368
  names=["date", "count"],
369
+ dtype={"count": "int64"},
350
370
  )
351
371
  except FileNotFoundError:
352
372
  logger.error("Input file not found: %s", config.input_filename)
353
373
  raise
374
+ except ValueError as error:
375
+ msg = (
376
+ "Invalid count values in input CSV: "
377
+ f"{config.input_filename}, expected an integer."
378
+ )
379
+ raise ValueError(msg) from error
354
380
 
355
381
  if dataframe.empty:
356
382
  msg = f"Input CSV file is empty: {config.input_filename}"
@@ -822,6 +848,33 @@ def _generate_title(config: argparse.Namespace) -> str:
822
848
  return title
823
849
 
824
850
 
851
+ def _purge_blocker(output_dir: Path) -> str | None:
852
+ """Return why the output folder is unsafe to purge, or None if it is safe.
853
+
854
+ Purging recursively deletes the output folder, so refuse targets that
855
+ would take unrelated files with it: the filesystem root, the user's home
856
+ directory, the current working directory, or any ancestor of it (for
857
+ example ``-O .``, ``-O ..``, or ``-O /``).
858
+
859
+ Args:
860
+ output_dir (Path): The resolved output directory.
861
+
862
+ Returns:
863
+ str | None: The reason the purge is refused, or None when it is safe.
864
+ """
865
+ resolved = output_dir.resolve()
866
+ if resolved == Path(resolved.anchor):
867
+ return "it is the filesystem root"
868
+ if resolved == Path.home().resolve():
869
+ return "it is your home directory"
870
+ cwd = Path.cwd().resolve()
871
+ if resolved == cwd:
872
+ return "it is the current working directory"
873
+ if cwd.is_relative_to(resolved):
874
+ return "it contains the current working directory"
875
+ return None
876
+
877
+
825
878
  def _refresh_output_dir(config: argparse.Namespace) -> None:
826
879
  """Delete and recreate the output folder.
827
880
 
@@ -830,10 +883,25 @@ def _refresh_output_dir(config: argparse.Namespace) -> None:
830
883
 
831
884
  Returns:
832
885
  None
886
+
887
+ Raises:
888
+ ValueError: If purging is requested for an output folder that is
889
+ unsafe to delete.
833
890
  """
834
891
  output_dir = _get_output_dir(config)
835
892
 
836
893
  if config.purge:
894
+ # Checked before the prompt and before --yes is honoured, so a
895
+ # mistyped or expanded --output-dir value can never delete
896
+ # unrelated files, confirmed or not.
897
+ reason = _purge_blocker(output_dir)
898
+ if reason is not None:
899
+ msg = (
900
+ f"Refusing to purge output folder: {output_dir} because "
901
+ f"{reason}. Point --output-dir at a dedicated folder instead."
902
+ )
903
+ raise ValueError(msg)
904
+
837
905
  should_purge = config.yes or input(
838
906
  f"Are you sure to purge output folder: {output_dir}? [y/N] "
839
907
  ).lower() in {"y", "yes"}
@@ -842,12 +910,14 @@ def _refresh_output_dir(config: argparse.Namespace) -> None:
842
910
  try:
843
911
  shutil.rmtree(output_dir)
844
912
  except OSError as e:
913
+ # Logged and skipped rather than returned from: bailing out
914
+ # here would skip the mkdir below and leave the caller with
915
+ # no output directory at all.
845
916
  logger.error(
846
917
  "Error removing directory: %s - %s.",
847
918
  output_dir,
848
919
  e,
849
920
  )
850
- return
851
921
 
852
922
  # Ensure the output directory exists for writing files.
853
923
  # This will create it if it doesn't exist or was just purged.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: heatmap_cli
3
- Version: 0.25.5
3
+ Version: 0.27.0
4
4
  Summary: A console program that generates a yearly calendar heatmap.
5
5
  Author-email: Kian-Meng Ang <kianmeng@cpan.org>
6
6
  License-Expression: AGPL-3.0-or-later
@@ -56,7 +56,7 @@ heatmap -h -v
56
56
  ```console
57
57
  usage: heatmap_cli [--demo [NUMBER_OF_COLORMAP]] [--seed SEED] [-y YEAR]
58
58
  [-w WEEK] [-e END_DATE] [-s START_DATE] [-O OUTPUT_DIR]
59
- [-o] [-p] [-v] [-t TITLE] [-u AUTHOR] [-f IMAGE_FORMAT]
59
+ [-o] [-p] [-t TITLE] [-u AUTHOR] [-f IMAGE_FORMAT]
60
60
  [-c COLORMAP] [-i COLORMAP_MIN_VALUE]
61
61
  [-x COLORMAP_MAX_VALUE] [-b]
62
62
  [-a | --annotate | --no-annotate] [--animate-by-week] [-q]
@@ -75,7 +75,7 @@ positional arguments:
75
75
 
76
76
  options:
77
77
  --demo [NUMBER_OF_COLORMAP]
78
- generate number of heatmaps by colormaps (default: '194')
78
+ generate number of heatmaps by colormaps (default: '194'). Implied: covers the current ISO year; -y/-w/-s/-e/-c are ignored.
79
79
  --seed SEED
80
80
  set random seed for reproducible --demo output (default: None)
81
81
  -y, --year YEAR
@@ -85,15 +85,13 @@ options:
85
85
  -e, --end-date END_DATE
86
86
  filter until the date of the year from the CSV file and this will overwrite -y and -w option (default: None)
87
87
  -s, --start-date START_DATE
88
- filter from the date of the year from the CSV file (default: None)
88
+ filter from the date of the year from the CSV file and this will overwrite -y and -w option (default: None)
89
89
  -O, --output-dir OUTPUT_DIR
90
90
  set default output folder (default: 'output')
91
91
  -o, --open
92
92
  open the generated heatmap using the default program (default: False)
93
93
  -p, --purge
94
94
  remove all leftover artifacts set by --output-dir folder (default: False)
95
- -v, --verbose
96
- show verbosity of debugging log. Use -vv, -vvv for more details
97
95
  -t, --title TITLE
98
96
  set title for the heatmap (default: None)
99
97
  -u, --author AUTHOR
@@ -102,7 +100,6 @@ options:
102
100
  set the default image format (default: 'png')
103
101
  -c, --cmap COLORMAP
104
102
  Set default colormap. (default: 'RdYlGn_r')
105
-
106
103
  Available colormaps:
107
104
  Accent, Accent_r, afmhot, afmhot_r, autumn, autumn_r
108
105
  berlin, berlin_r, binary, binary_r, Blues, Blues_r
@@ -42,7 +42,6 @@ tests/test_refresh_output_dir.py
42
42
  tests/test_setup_logging.py
43
43
  tests/test_start_date_option.py
44
44
  tests/test_title_option.py
45
- tests/test_verbose_flag.py
46
45
  tests/test_version_flag.py
47
46
  tests/test_week_option.py
48
47
  tests/test_year_option.py