heatmap_cli 0.25.4__tar.gz → 0.26.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.4/src/heatmap_cli.egg-info → heatmap_cli-0.26.0}/PKG-INFO +31 -33
  2. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/README.md +30 -32
  3. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/pyproject.toml +4 -1
  4. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/src/heatmap_cli/__init__.py +22 -3
  5. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/src/heatmap_cli/cli.py +103 -19
  6. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/src/heatmap_cli/heatmap.py +75 -8
  7. heatmap_cli-0.26.0/src/heatmap_cli/py.typed +0 -0
  8. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0/src/heatmap_cli.egg-info}/PKG-INFO +31 -33
  9. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/src/heatmap_cli.egg-info/SOURCES.txt +1 -0
  10. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_animate_by_week.py +18 -0
  11. heatmap_cli-0.26.0/tests/test_end_date_option.py +87 -0
  12. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_heatmap_errors.py +47 -0
  13. heatmap_cli-0.26.0/tests/test_help_flag.py +71 -0
  14. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_no_annotate.py +1 -1
  15. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_purge_flag.py +25 -0
  16. heatmap_cli-0.26.0/tests/test_refresh_output_dir.py +126 -0
  17. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_start_date_option.py +10 -0
  18. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_version_flag.py +16 -1
  19. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_year_option.py +32 -0
  20. heatmap_cli-0.25.4/tests/test_end_date_option.py +0 -41
  21. heatmap_cli-0.25.4/tests/test_help_flag.py +0 -25
  22. heatmap_cli-0.25.4/tests/test_refresh_output_dir.py +0 -45
  23. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/LICENSE.md +0 -0
  24. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/setup.cfg +0 -0
  25. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/src/heatmap_cli/__main__.py +0 -0
  26. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/src/heatmap_cli.egg-info/dependency_links.txt +0 -0
  27. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/src/heatmap_cli.egg-info/entry_points.txt +0 -0
  28. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/src/heatmap_cli.egg-info/requires.txt +0 -0
  29. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/src/heatmap_cli.egg-info/top_level.txt +0 -0
  30. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_animate_no_frames.py +0 -0
  31. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_animate_open.py +0 -0
  32. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_annotate_flag.py +0 -0
  33. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_annotation_truncation.py +0 -0
  34. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_cbar_flag.py +0 -0
  35. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_cmap_option.py +0 -0
  36. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_cmax_option.py +0 -0
  37. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_cmin_option.py +0 -0
  38. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_configure_cbar.py +0 -0
  39. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_debug_flag.py +0 -0
  40. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_demo_option.py +0 -0
  41. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_env_flag.py +0 -0
  42. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_heatmap_direct.py +0 -0
  43. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_heatmap_open.py +0 -0
  44. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_heatmap_utils.py +0 -0
  45. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_heatmap_wrapper.py +0 -0
  46. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_iso_53_week_year.py +0 -0
  47. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_open_heatmap.py +0 -0
  48. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_output_dir_option.py +0 -0
  49. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_quiet_flag.py +0 -0
  50. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_setup_logging.py +0 -0
  51. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_title_option.py +0 -0
  52. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_verbose_flag.py +0 -0
  53. {heatmap_cli-0.25.4 → heatmap_cli-0.26.0}/tests/test_week_option.py +0 -0
  54. {heatmap_cli-0.25.4 → heatmap_cli-0.26.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.4
3
+ Version: 0.26.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
@@ -75,18 +75,18 @@ 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: '192')
79
79
  --seed SEED
80
80
  set random seed for reproducible --demo output (default: None)
81
- -y, --year YEAR
81
+ -y YEAR, --year YEAR
82
82
  filter by year from the CSV file (default: 'None')
83
- -w, --week WEEK
83
+ -w WEEK, --week WEEK
84
84
  filter until week of the year from the CSV file (default: current week)
85
- -e, --end-date END_DATE
85
+ -e END_DATE, --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
- -s, --start-date START_DATE
88
- filter from the date of the year from the CSV file (default: None)
89
- -O, --output-dir OUTPUT_DIR
87
+ -s START_DATE, --start-date START_DATE
88
+ filter from the date of the year from the CSV file and this will overwrite -y and -w option (default: None)
89
+ -O OUTPUT_DIR, --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)
@@ -94,15 +94,14 @@ options:
94
94
  remove all leftover artifacts set by --output-dir folder (default: False)
95
95
  -v, --verbose
96
96
  show verbosity of debugging log. Use -vv, -vvv for more details
97
- -t, --title TITLE
97
+ -t TITLE, --title TITLE
98
98
  set title for the heatmap (default: None)
99
- -u, --author AUTHOR
99
+ -u AUTHOR, --author AUTHOR
100
100
  set author for the heatmap (default: kianmeng.org)
101
- -f, --format IMAGE_FORMAT
101
+ -f IMAGE_FORMAT, --format IMAGE_FORMAT
102
102
  set the default image format (default: 'png')
103
- -c, --cmap COLORMAP
103
+ -c COLORMAP, --cmap COLORMAP
104
104
  Set default colormap. (default: 'RdYlGn_r')
105
-
106
105
  Available colormaps:
107
106
  Accent, Accent_r, afmhot, afmhot_r, autumn, autumn_r
108
107
  berlin, berlin_r, binary, binary_r, Blues, Blues_r
@@ -120,31 +119,30 @@ options:
120
119
  hot, hot_r, hsv, hsv_r, icefire, icefire_r
121
120
  inferno, inferno_r, jet, jet_r, magma, magma_r
122
121
  mako, mako_r, managua, managua_r, nipy_spectral, nipy_spectral_r
123
- ocean, ocean_r, okabe_ito, okabe_ito_r, Oranges, Oranges_r
124
- OrRd, OrRd_r, Paired, Paired_r, Pastel1, Pastel1_r
125
- Pastel2, Pastel2_r, pink, pink_r, PiYG, PiYG_r
126
- plasma, plasma_r, PRGn, PRGn_r, prism, prism_r
127
- PuBu, PuBu_r, PuBuGn, PuBuGn_r, PuOr, PuOr_r
128
- PuRd, PuRd_r, Purples, Purples_r, rainbow, rainbow_r
129
- RdBu, RdBu_r, RdGy, RdGy_r, RdPu, RdPu_r
130
- RdYlBu, RdYlBu_r, RdYlGn, RdYlGn_r, Reds, Reds_r
131
- rocket, rocket_r, seismic, seismic_r, Set1, Set1_r
132
- Set2, Set2_r, Set3, Set3_r, Spectral, Spectral_r
133
- spring, spring_r, summer, summer_r, tab10, tab10_r
134
- tab20, tab20_r, tab20b, tab20b_r, tab20c, tab20c_r
135
- terrain, terrain_r, turbo, turbo_r, twilight, twilight_r
136
- twilight_shifted, twilight_shifted_r, vanimo, vanimo_r, viridis, viridis_r
137
- vlag, vlag_r, winter, winter_r, Wistia, Wistia_r
138
- YlGn, YlGn_r, YlGnBu, YlGnBu_r, YlOrBr, YlOrBr_r
139
- YlOrRd, YlOrRd_r
140
- -i, --cmap-min COLORMAP_MIN_VALUE
122
+ ocean, ocean_r, Oranges, Oranges_r, OrRd, OrRd_r
123
+ Paired, Paired_r, Pastel1, Pastel1_r, Pastel2, Pastel2_r
124
+ pink, pink_r, PiYG, PiYG_r, plasma, plasma_r
125
+ PRGn, PRGn_r, prism, prism_r, PuBu, PuBu_r
126
+ PuBuGn, PuBuGn_r, PuOr, PuOr_r, PuRd, PuRd_r
127
+ Purples, Purples_r, rainbow, rainbow_r, RdBu, RdBu_r
128
+ RdGy, RdGy_r, RdPu, RdPu_r, RdYlBu, RdYlBu_r
129
+ RdYlGn, RdYlGn_r, Reds, Reds_r, rocket, rocket_r
130
+ seismic, seismic_r, Set1, Set1_r, Set2, Set2_r
131
+ Set3, Set3_r, Spectral, Spectral_r, spring, spring_r
132
+ summer, summer_r, tab10, tab10_r, tab20, tab20_r
133
+ tab20b, tab20b_r, tab20c, tab20c_r, terrain, terrain_r
134
+ turbo, turbo_r, twilight, twilight_r, twilight_shifted, twilight_shifted_r
135
+ vanimo, vanimo_r, viridis, viridis_r, vlag, vlag_r
136
+ winter, winter_r, Wistia, Wistia_r, YlGn, YlGn_r
137
+ YlGnBu, YlGnBu_r, YlOrBr, YlOrBr_r, YlOrRd, YlOrRd_r
138
+ -i COLORMAP_MIN_VALUE, --cmap-min COLORMAP_MIN_VALUE
141
139
  Set the minimum value of the colormap range (default: None)
142
- -x, --cmap-max COLORMAP_MAX_VALUE
140
+ -x COLORMAP_MAX_VALUE, --cmap-max COLORMAP_MAX_VALUE
143
141
  Set the maximum value of the colormap range (default: None)
144
142
  -b, --cbar
145
143
  show colorbar (default: False)
146
144
  -a, --annotate, --no-annotate
147
- add count to each heatmap region (use --no-annotate to disable)
145
+ add count to each heatmap region (use --no-annotate to disable) (default: True)
148
146
  --animate-by-week
149
147
  create an animation for each day of the current week
150
148
  -q, --quiet
@@ -46,18 +46,18 @@ 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: '192')
50
50
  --seed SEED
51
51
  set random seed for reproducible --demo output (default: None)
52
- -y, --year YEAR
52
+ -y YEAR, --year YEAR
53
53
  filter by year from the CSV file (default: 'None')
54
- -w, --week WEEK
54
+ -w WEEK, --week WEEK
55
55
  filter until week of the year from the CSV file (default: current week)
56
- -e, --end-date END_DATE
56
+ -e END_DATE, --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
- -s, --start-date START_DATE
59
- filter from the date of the year from the CSV file (default: None)
60
- -O, --output-dir OUTPUT_DIR
58
+ -s START_DATE, --start-date START_DATE
59
+ filter from the date of the year from the CSV file and this will overwrite -y and -w option (default: None)
60
+ -O OUTPUT_DIR, --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)
@@ -65,15 +65,14 @@ options:
65
65
  remove all leftover artifacts set by --output-dir folder (default: False)
66
66
  -v, --verbose
67
67
  show verbosity of debugging log. Use -vv, -vvv for more details
68
- -t, --title TITLE
68
+ -t TITLE, --title TITLE
69
69
  set title for the heatmap (default: None)
70
- -u, --author AUTHOR
70
+ -u AUTHOR, --author AUTHOR
71
71
  set author for the heatmap (default: kianmeng.org)
72
- -f, --format IMAGE_FORMAT
72
+ -f IMAGE_FORMAT, --format IMAGE_FORMAT
73
73
  set the default image format (default: 'png')
74
- -c, --cmap COLORMAP
74
+ -c COLORMAP, --cmap COLORMAP
75
75
  Set default colormap. (default: 'RdYlGn_r')
76
-
77
76
  Available colormaps:
78
77
  Accent, Accent_r, afmhot, afmhot_r, autumn, autumn_r
79
78
  berlin, berlin_r, binary, binary_r, Blues, Blues_r
@@ -91,31 +90,30 @@ options:
91
90
  hot, hot_r, hsv, hsv_r, icefire, icefire_r
92
91
  inferno, inferno_r, jet, jet_r, magma, magma_r
93
92
  mako, mako_r, managua, managua_r, nipy_spectral, nipy_spectral_r
94
- ocean, ocean_r, okabe_ito, okabe_ito_r, Oranges, Oranges_r
95
- OrRd, OrRd_r, Paired, Paired_r, Pastel1, Pastel1_r
96
- Pastel2, Pastel2_r, pink, pink_r, PiYG, PiYG_r
97
- plasma, plasma_r, PRGn, PRGn_r, prism, prism_r
98
- PuBu, PuBu_r, PuBuGn, PuBuGn_r, PuOr, PuOr_r
99
- PuRd, PuRd_r, Purples, Purples_r, rainbow, rainbow_r
100
- RdBu, RdBu_r, RdGy, RdGy_r, RdPu, RdPu_r
101
- RdYlBu, RdYlBu_r, RdYlGn, RdYlGn_r, Reds, Reds_r
102
- rocket, rocket_r, seismic, seismic_r, Set1, Set1_r
103
- Set2, Set2_r, Set3, Set3_r, Spectral, Spectral_r
104
- spring, spring_r, summer, summer_r, tab10, tab10_r
105
- tab20, tab20_r, tab20b, tab20b_r, tab20c, tab20c_r
106
- terrain, terrain_r, turbo, turbo_r, twilight, twilight_r
107
- twilight_shifted, twilight_shifted_r, vanimo, vanimo_r, viridis, viridis_r
108
- vlag, vlag_r, winter, winter_r, Wistia, Wistia_r
109
- YlGn, YlGn_r, YlGnBu, YlGnBu_r, YlOrBr, YlOrBr_r
110
- YlOrRd, YlOrRd_r
111
- -i, --cmap-min COLORMAP_MIN_VALUE
93
+ ocean, ocean_r, Oranges, Oranges_r, OrRd, OrRd_r
94
+ Paired, Paired_r, Pastel1, Pastel1_r, Pastel2, Pastel2_r
95
+ pink, pink_r, PiYG, PiYG_r, plasma, plasma_r
96
+ PRGn, PRGn_r, prism, prism_r, PuBu, PuBu_r
97
+ PuBuGn, PuBuGn_r, PuOr, PuOr_r, PuRd, PuRd_r
98
+ Purples, Purples_r, rainbow, rainbow_r, RdBu, RdBu_r
99
+ RdGy, RdGy_r, RdPu, RdPu_r, RdYlBu, RdYlBu_r
100
+ RdYlGn, RdYlGn_r, Reds, Reds_r, rocket, rocket_r
101
+ seismic, seismic_r, Set1, Set1_r, Set2, Set2_r
102
+ Set3, Set3_r, Spectral, Spectral_r, spring, spring_r
103
+ summer, summer_r, tab10, tab10_r, tab20, tab20_r
104
+ tab20b, tab20b_r, tab20c, tab20c_r, terrain, terrain_r
105
+ turbo, turbo_r, twilight, twilight_r, twilight_shifted, twilight_shifted_r
106
+ vanimo, vanimo_r, viridis, viridis_r, vlag, vlag_r
107
+ winter, winter_r, Wistia, Wistia_r, YlGn, YlGn_r
108
+ YlGnBu, YlGnBu_r, YlOrBr, YlOrBr_r, YlOrRd, YlOrRd_r
109
+ -i COLORMAP_MIN_VALUE, --cmap-min COLORMAP_MIN_VALUE
112
110
  Set the minimum value of the colormap range (default: None)
113
- -x, --cmap-max COLORMAP_MAX_VALUE
111
+ -x COLORMAP_MAX_VALUE, --cmap-max COLORMAP_MAX_VALUE
114
112
  Set the maximum value of the colormap range (default: None)
115
113
  -b, --cbar
116
114
  show colorbar (default: False)
117
115
  -a, --annotate, --no-annotate
118
- add count to each heatmap region (use --no-annotate to disable)
116
+ add count to each heatmap region (use --no-annotate to disable) (default: True)
119
117
  --animate-by-week
120
118
  create an animation for each day of the current week
121
119
  -q, --quiet
@@ -5,6 +5,9 @@ build-backend = "setuptools.build_meta"
5
5
  [tool.setuptools.packages.find]
6
6
  where = ["src"]
7
7
 
8
+ [tool.setuptools.package-data]
9
+ heatmap_cli = ["py.typed"]
10
+
8
11
  [project]
9
12
  name = "heatmap_cli"
10
13
  description = "A console program that generates a yearly calendar heatmap."
@@ -25,7 +28,7 @@ classifiers = [
25
28
  "Programming Language :: Python",
26
29
  "Topic :: Scientific/Engineering :: Visualization",
27
30
  ]
28
- version = "0.25.4"
31
+ version = "0.26.0"
29
32
  keywords = ["heatmap", "cli", "visualization", "calendar", "data-viz"]
30
33
  dependencies = [
31
34
  "matplotlib",
@@ -28,14 +28,31 @@ from pathlib import Path
28
28
  from typing import Any, cast
29
29
 
30
30
  import matplotlib as mpl
31
- import matplotlib.pyplot as plt
32
31
  import pandas as pd
33
32
  import seaborn as sns
34
33
 
35
34
  from heatmap_cli.heatmap import _get_output_dir
36
35
  from heatmap_cli.heatmap import run as generate_heatmaps
37
36
 
38
- __version__ = metadata.version("heatmap_cli")
37
+ # Reported when the distribution metadata is unavailable, so that a source
38
+ # checkout which was never installed still runs instead of failing to import.
39
+ FALLBACK_VERSION = "0.0.0+unknown"
40
+
41
+
42
+ def _resolve_version() -> str:
43
+ """Return the version from the installed distribution metadata.
44
+
45
+ Returns:
46
+ str: The installed version, or ``FALLBACK_VERSION`` when the
47
+ package is not installed.
48
+ """
49
+ try:
50
+ return metadata.version("heatmap_cli")
51
+ except metadata.PackageNotFoundError:
52
+ return FALLBACK_VERSION
53
+
54
+
55
+ __version__ = _resolve_version()
39
56
 
40
57
  # Max value for demo heatmap count
41
58
  DEMO_MAX_COUNT = 12000
@@ -48,7 +65,9 @@ DEFAULT_DEMO_SEED = 42
48
65
  DEMO_SAMPLE_FILENAME = "heatmap_demo_sample.csv"
49
66
 
50
67
  # Sort colormaps in a case-insensitive manner.
51
- CMAPS = sorted(plt.colormaps, key=str.casefold)
68
+ # The colormap registry is read from matplotlib directly, not pyplot, so that
69
+ # importing the package never pulls in the pyplot backend machinery.
70
+ CMAPS = sorted(mpl.colormaps, key=str.casefold)
52
71
 
53
72
  logger = logging.getLogger(__name__)
54
73
 
@@ -410,6 +410,11 @@ def build_parser() -> argparse.ArgumentParser:
410
410
  def _generate_cmap_help() -> str:
411
411
  """Generate the help text for colormap options.
412
412
 
413
+ The colormap list follows the summary on the next line rather than after
414
+ a blank line: argparse's RawTextHelpFormatter indents every line of the
415
+ help text, so an empty line would come out as trailing whitespace, which
416
+ the trailing-whitespace hook then strips from the generated README.
417
+
413
418
  Returns:
414
419
  str: Formatted help text.
415
420
  """
@@ -417,7 +422,7 @@ def _generate_cmap_help() -> str:
417
422
  cmap_default = f" (default: '{DEFAULT_CMAP}')"
418
423
 
419
424
  # Always show all colormaps in help text
420
- cmap_choices = "\nAvailable colormaps:\n"
425
+ cmap_choices = "Available colormaps:\n"
421
426
  cmap_bygroups = zip_longest(*(iter(CMAPS),) * CMAP_ITEMS_PER_ROW)
422
427
  for cmap_bygroup in cmap_bygroups:
423
428
  cmap_choices += " " + ", ".join(filter(None, cmap_bygroup)) + "\n"
@@ -425,6 +430,67 @@ def _generate_cmap_help() -> str:
425
430
  return cmap_help + cmap_default + "\n" + cmap_choices.rstrip()
426
431
 
427
432
 
433
+ def _warn_ignored_filters(
434
+ option: str,
435
+ explicit_year: list[int] | None,
436
+ explicit_week: int | None,
437
+ ) -> None:
438
+ """Warn that -y/--year and -w/--week are ignored by a date filter.
439
+
440
+ Args:
441
+ option (str): The date option that takes precedence, for example
442
+ "--start-date".
443
+ explicit_year (list[int] | None): The years asked for on the command
444
+ line, or None when -y/--year was not given.
445
+ explicit_week (int | None): The week asked for on the command line,
446
+ or None when -w/--week was not given.
447
+
448
+ Returns:
449
+ None
450
+ """
451
+ if explicit_year is not None:
452
+ logger.warning(
453
+ "argument %s: --year is ignored when %s is used.",
454
+ option,
455
+ option,
456
+ )
457
+ if explicit_week is not None:
458
+ logger.warning(
459
+ "argument %s: --week is ignored when %s is used.",
460
+ option,
461
+ option,
462
+ )
463
+
464
+
465
+ def _warn_dropped_years(
466
+ option: str,
467
+ explicit_year: list[int] | None,
468
+ kept_year: int,
469
+ ) -> None:
470
+ """Warn that a date filter narrows a multi-year request to one year.
471
+
472
+ Args:
473
+ option (str): The date option that takes precedence.
474
+ explicit_year (list[int] | None): The years asked for on the command
475
+ line, or None when -y/--year was not given.
476
+ kept_year (int): The single year the date filter resolves to.
477
+
478
+ Returns:
479
+ None
480
+ """
481
+ if explicit_year is None:
482
+ return
483
+
484
+ dropped = [year for year in explicit_year if year != kept_year]
485
+ if dropped:
486
+ logger.warning(
487
+ "argument %s: only year %d is kept, dropping %s.",
488
+ option,
489
+ kept_year,
490
+ ", ".join(str(year) for year in dropped),
491
+ )
492
+
493
+
428
494
  def _resolve_date_filter_overrides(
429
495
  parsed_args: argparse.Namespace,
430
496
  ) -> None:
@@ -449,23 +515,40 @@ def _resolve_date_filter_overrides(
449
515
  explicit_week = parsed_args.week
450
516
 
451
517
  if parsed_args.end_date:
518
+ override_option = "--end-date"
452
519
  (year, week, _day) = parsed_args.end_date.isocalendar()
453
- parsed_args.year = [year]
454
- parsed_args.week = week
455
520
  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
- )
521
+ override_option = "--start-date"
466
522
  (year, _week, _day) = parsed_args.start_date.isocalendar()
467
- parsed_args.year = [year]
468
- parsed_args.week = _weeks_in_iso_year(year)
523
+ # --start-date alone views the rest of its ISO year.
524
+ week = _weeks_in_iso_year(year)
525
+ else:
526
+ return
527
+
528
+ _warn_ignored_filters(override_option, explicit_year, explicit_week)
529
+ _warn_dropped_years(override_option, explicit_year, year)
530
+ parsed_args.year = [year]
531
+ parsed_args.week = week
532
+
533
+
534
+ def _default_year_and_week(
535
+ now: datetime.datetime,
536
+ ) -> tuple[list[int], int]:
537
+ """Return the default year and week filters for the current time.
538
+
539
+ Both come from the ISO calendar so that they always describe the same
540
+ week. The calendar year and the ISO year disagree for the last few days
541
+ of December, when the current week already belongs to the next ISO year,
542
+ e.g. 2024-12-30 is in 2025-W01.
543
+
544
+ Args:
545
+ now (datetime.datetime): The current time.
546
+
547
+ Returns:
548
+ tuple[list[int], int]: The default year list and week number.
549
+ """
550
+ (iso_year, iso_week, _day) = now.isocalendar()
551
+ return [iso_year], iso_week
469
552
 
470
553
 
471
554
  def _process_args(
@@ -505,12 +588,13 @@ def _process_args(
505
588
  parser.error("the following arguments are required: CSV_FILENAME")
506
589
 
507
590
  # 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)
591
+ (default_year, default_week) = _default_year_and_week(
592
+ datetime.datetime.now(tz=datetime.timezone.utc)
593
+ )
510
594
  if parsed_args.year is None:
511
- parsed_args.year = [now.year]
595
+ parsed_args.year = default_year
512
596
  if parsed_args.week is None:
513
- parsed_args.week = now.isocalendar().week
597
+ parsed_args.week = default_week
514
598
 
515
599
  # Handle default for cmap
516
600
  if parsed_args.cmap is None:
@@ -180,6 +180,13 @@ def _generate_animated_heatmap(
180
180
  base_dataframe (pd.DataFrame): The base dataframe with all data.
181
181
  config (argparse.Namespace): Config from command line arguments.
182
182
  """
183
+ if len(config.cmap) > 1:
184
+ logger.warning(
185
+ "--animate-by-week uses only the first colormap; "
186
+ "%d colormap(s) ignored.",
187
+ len(config.cmap) - 1,
188
+ )
189
+
183
190
  # pivot the data once for the entire week to get the final state
184
191
  final_pivoted_df = _filter_and_pivot_data(base_dataframe, config)
185
192
  logger.debug(final_pivoted_df)
@@ -332,24 +339,43 @@ def _read_and_prepare_data(config: argparse.Namespace) -> pd.DataFrame:
332
339
 
333
340
  Raises:
334
341
  FileNotFoundError: If the input CSV file does not exist.
335
- ValueError: If the input is empty, or duplicate dates or negative
336
- counts are found.
342
+ ValueError: If the input is empty, or the dates or counts are
343
+ invalid, or duplicate dates or negative counts are found.
337
344
  """
338
345
  try:
346
+ # The dtype makes pandas reject anything that is not a whole number,
347
+ # including blank cells, text, and infinity.
339
348
  dataframe = pd.read_csv(
340
349
  config.input_filename,
341
350
  header=None,
342
351
  names=["date", "count"],
352
+ dtype={"count": "int64"},
343
353
  )
344
354
  except FileNotFoundError:
345
355
  logger.error("Input file not found: %s", config.input_filename)
346
356
  raise
357
+ except ValueError as error:
358
+ msg = (
359
+ "Invalid count values in input CSV: "
360
+ f"{config.input_filename}, expected an integer."
361
+ )
362
+ raise ValueError(msg) from error
347
363
 
348
364
  if dataframe.empty:
349
365
  msg = f"Input CSV file is empty: {config.input_filename}"
350
366
  raise ValueError(msg)
351
367
 
352
- dataframe["date"] = pd.to_datetime(dataframe["date"])
368
+ try:
369
+ dataframe["date"] = pd.to_datetime(
370
+ dataframe["date"],
371
+ format="%Y-%m-%d",
372
+ )
373
+ except ValueError as error:
374
+ msg = (
375
+ "Invalid date format in input CSV: "
376
+ f"{config.input_filename}, expected YYYY-MM-DD."
377
+ )
378
+ raise ValueError(msg) from error
353
379
 
354
380
  negative_counts = dataframe[dataframe["count"] < 0]
355
381
  if not negative_counts.empty:
@@ -514,7 +540,7 @@ def _setup_plot_artists(
514
540
  labelsize=DEFAULT_TICK_LABEL_FONTSIZE,
515
541
  )
516
542
 
517
- options, _ = _configure_heatmap_options(config, cmap, axis)
543
+ options = _configure_heatmap_options(config, cmap, axis)
518
544
  res = sns.heatmap(dataframe, **options)
519
545
 
520
546
  if config.annotate:
@@ -567,7 +593,7 @@ def _configure_heatmap_options(
567
593
  config: argparse.Namespace,
568
594
  cmap: str,
569
595
  axis: Axes,
570
- ) -> tuple[dict[str, Any], dict[str, Any]]:
596
+ ) -> dict[str, Any]:
571
597
  """Configure options for the heatmap plot.
572
598
 
573
599
  Args:
@@ -576,8 +602,7 @@ def _configure_heatmap_options(
576
602
  axis (Axes): Matplotlib axes object.
577
603
 
578
604
  Returns:
579
- tuple[dict, dict]: A tuple containing heatmap options and colorbar
580
- options.
605
+ dict: The options to pass to seaborn's heatmap.
581
606
  """
582
607
  cbar_options = {
583
608
  "orientation": "horizontal",
@@ -611,7 +636,7 @@ def _configure_heatmap_options(
611
636
  "linewidth": 0,
612
637
  },
613
638
  )
614
- return options, cbar_options
639
+ return options
615
640
 
616
641
 
617
642
  def _apply_annotations(res: Axes) -> None:
@@ -806,6 +831,33 @@ def _generate_title(config: argparse.Namespace) -> str:
806
831
  return title
807
832
 
808
833
 
834
+ def _purge_blocker(output_dir: Path) -> str | None:
835
+ """Return why the output folder is unsafe to purge, or None if it is safe.
836
+
837
+ Purging recursively deletes the output folder, so refuse targets that
838
+ would take unrelated files with it: the filesystem root, the user's home
839
+ directory, the current working directory, or any ancestor of it (for
840
+ example ``-O .``, ``-O ..``, or ``-O /``).
841
+
842
+ Args:
843
+ output_dir (Path): The resolved output directory.
844
+
845
+ Returns:
846
+ str | None: The reason the purge is refused, or None when it is safe.
847
+ """
848
+ resolved = output_dir.resolve()
849
+ if resolved == Path(resolved.anchor):
850
+ return "it is the filesystem root"
851
+ if resolved == Path.home().resolve():
852
+ return "it is your home directory"
853
+ cwd = Path.cwd().resolve()
854
+ if resolved == cwd:
855
+ return "it is the current working directory"
856
+ if cwd.is_relative_to(resolved):
857
+ return "it contains the current working directory"
858
+ return None
859
+
860
+
809
861
  def _refresh_output_dir(config: argparse.Namespace) -> None:
810
862
  """Delete and recreate the output folder.
811
863
 
@@ -814,10 +866,25 @@ def _refresh_output_dir(config: argparse.Namespace) -> None:
814
866
 
815
867
  Returns:
816
868
  None
869
+
870
+ Raises:
871
+ ValueError: If purging is requested for an output folder that is
872
+ unsafe to delete.
817
873
  """
818
874
  output_dir = _get_output_dir(config)
819
875
 
820
876
  if config.purge:
877
+ # Checked before the prompt and before --yes is honoured, so a
878
+ # mistyped or expanded --output-dir value can never delete
879
+ # unrelated files, confirmed or not.
880
+ reason = _purge_blocker(output_dir)
881
+ if reason is not None:
882
+ msg = (
883
+ f"Refusing to purge output folder: {output_dir} because "
884
+ f"{reason}. Point --output-dir at a dedicated folder instead."
885
+ )
886
+ raise ValueError(msg)
887
+
821
888
  should_purge = config.yes or input(
822
889
  f"Are you sure to purge output folder: {output_dir}? [y/N] "
823
890
  ).lower() in {"y", "yes"}
File without changes