heatmap_cli 0.25.1__tar.gz → 0.25.2__tar.gz

{heatmap_cli-0.25.1/src/heatmap_cli.egg-info → heatmap_cli-0.25.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: heatmap_cli
-Version: 0.25.1
+Version: 0.25.2
 Summary: A console program that generates a yearly calendar heatmap.
 Author-email: Kian-Meng Ang <kianmeng@cpan.org>
 License-Expression: AGPL-3.0-or-later

{heatmap_cli-0.25.1 → heatmap_cli-0.25.2}/pyproject.toml

@@ -25,7 +25,7 @@ classifiers = [
     "Programming Language :: Python",
     "Topic :: Scientific/Engineering :: Visualization",
 ]
-version = "0.25.1"
+version = "0.25.2"
 keywords = ["heatmap", "cli", "visualization", "calendar", "data-viz"]
 dependencies = [
     "matplotlib",

{heatmap_cli-0.25.1 → heatmap_cli-0.25.2}/src/heatmap_cli/__init__.py

@@ -43,6 +43,10 @@ DEMO_MAX_COUNT = 12000
 # Fixed default seed so --demo output is deterministic for docs and tests.
 DEFAULT_DEMO_SEED = 42
 
+# The demo sample CSV uses a dedicated, unlikely-to-collide name so --demo
+# does not silently overwrite a user's file in the output directory.
+DEMO_SAMPLE_FILENAME = "heatmap_demo_sample.csv"
+
 # Sort colormaps in a case-insensitive manner.
 CMAPS = sorted(plt.colormaps, key=str.casefold)
 
@@ -129,21 +133,24 @@ def generate_demo(config: argparse.Namespace) -> None:
     Returns:
         None
     """
-    config.input_filename = f"{config.output_dir}/sample.csv"
     random.seed(config.seed if config.seed is not None else DEFAULT_DEMO_SEED)
     config.cmap = random.sample(CMAPS, config.demo)
-    _generate_sample_csv(config)
+    config.input_filename = str(_generate_sample_csv(config))
     generate_heatmaps(config)
 
 
-def _generate_sample_csv(config: argparse.Namespace) -> None:
+def _generate_sample_csv(config: argparse.Namespace) -> Path:
     """Generate a sample CSV data file.
 
+    The file uses the dedicated demo name so a user's own ``sample.csv`` in
+    the output directory is never touched. Re-running ``--demo`` into the same
+    directory may overwrite this demo's own previous artifact.
+
     Args:
         config (argparse.Namespace): Config from command line arguments.
 
     Returns:
-        None
+        Path: The path the sample CSV was written to.
     """
     df_dates = pd.DataFrame(
         {
@@ -155,10 +162,11 @@ def _generate_sample_csv(config: argparse.Namespace) -> None:
     )
     df_dates["count"] = random.sample(range(DEMO_MAX_COUNT), len(df_dates))
 
-    csv_filename = Path(config.output_dir) / "sample.csv"
+    csv_filename = Path(config.output_dir) / DEMO_SAMPLE_FILENAME
     csv_filename.parent.mkdir(parents=True, exist_ok=True)
     df_dates.to_csv(csv_filename, sep=",", index=False, header=False)
     logger.debug("Generate sample CSV file: %s", csv_filename)
+    return csv_filename
 
 
 class EnvironmentAction(argparse.Action):

{heatmap_cli-0.25.1 → heatmap_cli-0.25.2}/src/heatmap_cli/cli.py

@@ -32,9 +32,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
-import matplotlib as mpl
-from matplotlib.backend_bases import FigureCanvasBase
-from matplotlib.backends import backend_registry
+from matplotlib.backends.backend_agg import FigureCanvasAgg
 
 from heatmap_cli import (
     CMAPS,
@@ -44,18 +42,31 @@ from heatmap_cli import (
     generate_demo,
     setup_logging,
 )
-from heatmap_cli.heatmap import run as generate_heatmaps
+from heatmap_cli.heatmap import (
+    _weeks_in_iso_year,
+)
+from heatmap_cli.heatmap import (
+    run as generate_heatmaps,
+)
 
 
 def _get_supported_formats() -> list[str]:
-    """Retrieve supported image formats dynamically from matplotlib."""
-    try:
-        backend_name = mpl.get_backend()
-        backend_mod = backend_registry.load_backend_module(backend_name)
-        canvas_cls = backend_mod.FigureCanvas
-        return sorted(canvas_cls.get_supported_filetypes().keys())
-    except (AttributeError, ImportError, KeyError, TypeError):
-        return sorted(FigureCanvasBase.get_supported_filetypes().keys())
+    """Retrieve image formats supported by the Agg rendering backend.
+
+    All heatmaps are rendered with the Agg backend (see
+    ``heatmap.run`` and ``_setup_plot_artists``), so the CLI choices are
+    derived from `FigureCanvasAgg` rather than the backend active at import
+    time, keeping ``--format`` choices in sync with what can actually be
+    saved.
+
+    ``gif`` is added explicitly: it is not produced by matplotlib's
+    ``savefig`` (Agg does not list it) but by the PIL encoder in the
+    ``--animate-by-week`` path, which implies that format.
+    """
+    formats = sorted(FigureCanvasAgg.get_supported_filetypes().keys())
+    if "gif" not in formats:
+        formats.append("gif")
+    return formats
 
 
 IMAGE_FORMATS = _get_supported_formats()
@@ -429,11 +440,19 @@ def _process_args(
     Raises:
         SystemExit: If validation fails, typically via parser.error().
     """
-    # Handle --end-date overriding --year and --week
+    # A --start-date/--end-date pair defines a self-contained calendar date
+    # range that overrides the -y/--year and -w/--week cutoff, avoiding a
+    # double filter between the ISO-week year column and the raw date column.
+    # When only one endpoint is given it derives a partial-year view; when
+    # both are given --end-date wins for the year/week since it caps the range.
     if parsed_args.end_date:
         (year, week, _day) = parsed_args.end_date.isocalendar()
         parsed_args.year = [year]
         parsed_args.week = week
+    elif parsed_args.start_date:
+        (year, _week, _day) = parsed_args.start_date.isocalendar()
+        parsed_args.year = [year]
+        parsed_args.week = _weeks_in_iso_year(year)
 
     if (
         parsed_args.start_date
@@ -460,6 +479,12 @@ def _process_args(
     if parsed_args.cmap is None:
         parsed_args.cmap = [DEFAULT_CMAP]
 
+    # A GIF output is only ever produced by the animation path, so asking for
+    # gif implies --animate-by-week; otherwise fig.savefig(format="gif") would
+    # emit a single-frame still instead of an animation.
+    if parsed_args.format == "gif":
+        parsed_args.animate_by_week = True
+
     return parsed_args
 
 

{heatmap_cli-0.25.1 → heatmap_cli-0.25.2}/src/heatmap_cli/heatmap.py

@@ -311,7 +311,8 @@ def _read_and_prepare_data(config: argparse.Namespace) -> pd.DataFrame:
 
     Raises:
         FileNotFoundError: If the input CSV file does not exist.
-        ValueError: If duplicate dates or negative counts are found.
+        ValueError: If the input is empty, or duplicate dates or negative
+            counts are found.
     """
     try:
         dataframe = pd.read_csv(
@@ -323,6 +324,10 @@ def _read_and_prepare_data(config: argparse.Namespace) -> pd.DataFrame:
         logger.error("Input file not found: %s", config.input_filename)
         raise
 
+    if dataframe.empty:
+        msg = f"Input CSV file is empty: {config.input_filename}"
+        raise ValueError(msg)
+
     dataframe["date"] = pd.to_datetime(dataframe["date"])
 
     negative_counts = dataframe[dataframe["count"] < 0]
@@ -814,13 +819,17 @@ def _refresh_output_dir(config: argparse.Namespace) -> None:
 def _get_output_dir(config: argparse.Namespace) -> Path:
     """Get the output directory path, resolved relative to CWD.
 
+    Expands a leading ``~``/``~user`` (user home) and environment variables
+    such as ``$HOME`` or ``${OUTPUT_DIR}`` before resolving relative paths
+    against the current working directory.
+
     Args:
         config (argparse.Namespace): Config from command line arguments.
 
     Returns:
         Path: The output directory path.
     """
-    output_dir = Path(config.output_dir)
+    output_dir = Path(os.path.expandvars(config.output_dir)).expanduser()
     if output_dir.is_absolute():
         return output_dir
 

{heatmap_cli-0.25.1 → heatmap_cli-0.25.2/src/heatmap_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: heatmap_cli
-Version: 0.25.1
+Version: 0.25.2
 Summary: A console program that generates a yearly calendar heatmap.
 Author-email: Kian-Meng Ang <kianmeng@cpan.org>
 License-Expression: AGPL-3.0-or-later

{heatmap_cli-0.25.1 → heatmap_cli-0.25.2}/tests/test_animate_by_week.py

@@ -52,3 +52,16 @@ def test_animate_by_week_with_start_date(cli_runner, csv_file):
         "2023-01-01",
     )
     assert ret.returncode == 0
+
+
+def test_gif_format_implies_animate_by_week(cli_runner, csv_file, tmpdir):
+    """-f gif should route into the animation path via --animate-by-week."""
+    csv = csv_file("sample.csv")
+    ret = cli_runner(csv, "-f", "gif", "-y", "2023", "-w", "1", "-d")
+    assert ret.returncode == 0
+    assert "animate_by_week=True" in ret.stderr
+
+    output_dir = Path(str(tmpdir.join("scripttest", "output")))
+    gif_files = list(output_dir.glob("*.gif"))
+    assert len(gif_files) == 1
+    assert "animated" in gif_files[0].name

{heatmap_cli-0.25.1 → heatmap_cli-0.25.2}/tests/test_demo_option.py

@@ -17,13 +17,13 @@ import argparse
 from pathlib import Path
 from unittest.mock import MagicMock
 
-from heatmap_cli import CMAPS, DemoAction
+from heatmap_cli import CMAPS, DEMO_SAMPLE_FILENAME, DemoAction
 
 
 def test_debug_logs(cli_runner):
     ret = cli_runner("-d", "--demo", 1)
     assert "demo=1" in ret.stderr
-    assert "input_filename='output/sample.csv'" in ret.stderr
+    assert f"input_filename='output/{DEMO_SAMPLE_FILENAME}'" in ret.stderr
 
 
 def test_no_debug_logs_without_debug_flag(cli_runner):
@@ -64,7 +64,7 @@ def test_demo_clamps_to_minimum_of_one():
 def _demo_output(tmpdir):
     output_dir = Path(tmpdir, "scripttest", "output")
     files = sorted(path.name for path in output_dir.iterdir())
-    csv_bytes = (output_dir / "sample.csv").read_bytes()
+    csv_bytes = (output_dir / DEMO_SAMPLE_FILENAME).read_bytes()
     return files, csv_bytes
 
 
@@ -87,3 +87,16 @@ def test_demo_changes_with_different_seed(cli_runner, tmpdir):
     _, csv2 = _demo_output(tmpdir)
 
     assert csv1 != csv2
+
+
+def test_demo_does_not_clobber_user_sample(tmpdir, cli_runner):
+    """A user's own sample.csv in the output dir must survive --demo."""
+    output_dir = Path(tmpdir, "scripttest", "output")
+    output_dir.mkdir(parents=True)
+    user_sample = output_dir / "sample.csv"
+    user_sample.write_text("user,data\n")
+
+    cli_runner("--demo", 1)
+
+    assert user_sample.read_text() == "user,data\n"
+    assert (output_dir / DEMO_SAMPLE_FILENAME).exists()

{heatmap_cli-0.25.1 → heatmap_cli-0.25.2}/tests/test_heatmap_errors.py

@@ -56,6 +56,24 @@ def test_negative_count_error_direct(tmpdir):
         _read_and_prepare_data(config)
 
 
+def test_empty_csv_error_direct(tmpdir):
+    csv_path = Path(tmpdir) / "empty.csv"
+    csv_path.write_text("")
+
+    config = argparse.Namespace(input_filename=str(csv_path), annotate=False)
+    with pytest.raises(ValueError, match="Input CSV file is empty"):
+        _read_and_prepare_data(config)
+
+
+def test_empty_csv_error_cli(cli_runner, tmpdir):
+    csv_path = Path(tmpdir) / "empty.csv"
+    csv_path.write_text("")
+
+    ret = cli_runner(str(csv_path))
+    assert "Input CSV file is empty" in ret.stderr
+    assert "No data extracted" not in ret.stderr
+
+
 def test_refresh_output_dir_purge_os_error(tmpdir):
     output_dir = Path(tmpdir) / "output"
     output_dir.mkdir()

{heatmap_cli-0.25.1 → heatmap_cli-0.25.2}/tests/test_heatmap_utils.py

@@ -15,10 +15,12 @@
 
 import argparse
 import datetime
+from pathlib import Path
 
 from heatmap_cli.heatmap import (
     _generate_filename,
     _generate_title,
+    _get_output_dir,
     _sanitize_string_for_filename,
     _week_start_date,
 )
@@ -82,3 +84,29 @@ def test_generate_title():
 
     config.title = "Custom Title"
     assert _generate_title(config) == "Custom Title"
+
+
+def test_get_output_dir_relative(tmpdir, monkeypatch):
+    monkeypatch.chdir(tmpdir)
+    config = argparse.Namespace(output_dir="out")
+    assert _get_output_dir(config) == Path.cwd() / "out"
+
+
+def test_get_output_dir_absolute(tmpdir):
+    absolute = Path(str(tmpdir)) / "abs"
+    config = argparse.Namespace(output_dir=str(absolute))
+    assert _get_output_dir(config) == absolute
+
+
+def test_get_output_dir_expands_tilde(tmpdir, monkeypatch):
+    home = Path(str(tmpdir))
+    monkeypatch.setenv("HOME", str(home))
+    config = argparse.Namespace(output_dir="~/out")
+    assert _get_output_dir(config) == home / "out"
+
+
+def test_get_output_dir_expands_env_var(tmpdir, monkeypatch):
+    fromenv = Path(str(tmpdir)) / "fromenv"
+    monkeypatch.setenv("OUTPUT_DIR", str(fromenv))
+    config = argparse.Namespace(output_dir="$OUTPUT_DIR/sub")
+    assert _get_output_dir(config) == fromenv / "sub"

{heatmap_cli-0.25.1 → heatmap_cli-0.25.2}/tests/test_start_date_option.py

@@ -56,3 +56,23 @@ def test_title_with_start_and_end_date(cli_runner, csv_file):
         "Year 2023: Total Daily Walking Steps From 2023-01-01 to 2023-01-31"
     )
     assert f"DEBUG: heatmap_cli.heatmap: {expected_title}" in ret.stderr
+
+
+def test_start_date_alone_derives_year(cli_runner, csv_file):
+    """--start-date alone should derive year/week instead of double-filtering.
+
+    Without this, -s 2023-06-01 on 2023 data would default year to the
+    current year and raise "No data extracted". The date now drives a
+    partial-year view.
+    """
+    csv = csv_file("sample.csv")
+    ret = cli_runner(csv, "-d", "-s", "2023-06-01")
+    assert "year=[2023], week=52" in ret.stderr
+    assert ret.returncode == 0
+
+
+def test_start_date_overrides_year_cutoff(cli_runner, csv_file):
+    """An explicit -y conflicting with --start-date is resolved by the date."""
+    csv = csv_file("sample.csv")
+    ret = cli_runner(csv, "-d", "-s", "2023-06-01", "--year", "2024")
+    assert "year=[2023]" in ret.stderr