heatmap_cli 0.25.0__tar.gz → 0.25.2__tar.gz

{heatmap_cli-0.25.0/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.0
+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.0 → heatmap_cli-0.25.2}/pyproject.toml

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

{heatmap_cli-0.25.0 → 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.0 → 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()
@@ -65,6 +76,7 @@ logger = logging.getLogger(__name__)
 
 DEFAULT_CMAP = "RdYlGn_r"
 CMAP_ITEMS_PER_ROW = 6
+MAX_ISO_WEEK = 53
 
 
 def _valid_date(s: str) -> datetime.date:
@@ -86,6 +98,31 @@ def _valid_date(s: str) -> datetime.date:
         raise argparse.ArgumentTypeError(msg) from error
 
 
+def _valid_week(s: str) -> int:
+    """Validate the ISO week number.
+
+    Args:
+        s (str): Week number string to validate.
+
+    Returns:
+        int: The validated week number.
+
+    Raises:
+        argparse.ArgumentTypeError: If the week number is invalid.
+    """
+    try:
+        week = int(s)
+    except ValueError as error:
+        msg = f"invalid week number: '{s}', expected an integer."
+        raise argparse.ArgumentTypeError(msg) from error
+
+    if not 1 <= week <= MAX_ISO_WEEK:
+        msg = f"invalid week number: '{s}', expected between 1 and 53."
+        raise argparse.ArgumentTypeError(msg)
+
+    return week
+
+
 def build_parser() -> argparse.ArgumentParser:
     """Build the argument parser for the CLI.
 
@@ -142,7 +179,7 @@ def build_parser() -> argparse.ArgumentParser:
         "-w",
         "--week",
         dest="week",
-        type=int,
+        type=_valid_week,
         default=None,
         help=(
             "filter until week of the year from the CSV file "
@@ -403,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
@@ -434,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.0 → heatmap_cli-0.25.2}/src/heatmap_cli/heatmap.py

@@ -21,6 +21,7 @@ import copy
 import io
 import logging
 import multiprocessing
+import os
 import re
 import shutil
 import webbrowser
@@ -40,10 +41,6 @@ from matplotlib.backends.backend_agg import FigureCanvasAgg
 from matplotlib.figure import Figure
 from PIL import Image
 
-# Generate matplotlib graphs without an X server.
-# See http://stackoverflow.com/a/4935945
-mpl.use("agg")
-
 # Define constants for figure and image settings
 DEFAULT_FIGURE_SIZE = (8, 5)
 DEFAULT_DPI = 76
@@ -99,7 +96,13 @@ def run(config: argparse.Namespace) -> None:
         None
     """
     logger.debug(config)
-    logger.debug("number of cpu: %d", multiprocessing.cpu_count())
+    logger.debug("number of cpu: %d", os.cpu_count())
+
+    # Generate matplotlib graphs without an X server. Applied at run time so
+    # merely importing this module does not switch the global backend.
+    # See http://stackoverflow.com/a/4935945
+    if mpl.get_backend().lower() != "agg":
+        mpl.use("agg")
 
     _refresh_output_dir(config)
 
@@ -120,6 +123,22 @@ def run(config: argparse.Namespace) -> None:
             _generate_static_heatmaps(pivoted_dataframe, config_for_year)
 
 
+def _weeks_in_iso_year(year: int) -> int:
+    """Return the number of ISO weeks (52 or 53) in the given year.
+
+    December 28 is always in the last ISO week of its year, so its week
+    number gives the total count of weeks for that year. For example,
+    2026 is a 53-week ISO year while 2025 has 52 weeks.
+
+    Args:
+        year (int): The ISO year.
+
+    Returns:
+        int: Number of ISO weeks in the year.
+    """
+    return date(year, 12, 28).isocalendar().week
+
+
 def _week_start_date(year: int, week: int) -> date:
     """Return the Monday of the given ISO week.
 
@@ -222,6 +241,22 @@ def _generate_animated_heatmap(
         _open_heatmap(img_filename)
 
 
+def _init_worker_logging(config: argparse.Namespace) -> None:
+    """Configure logging in a pool worker process.
+
+    Non-fork platforms spawn fresh worker processes that do not inherit
+    the parent logger handlers and level, so reapply the logging
+    configuration in every worker.
+
+    Args:
+        config (argparse.Namespace): Config from command line arguments.
+    """
+    # Imported here to avoid a circular import with the package __init__.
+    from heatmap_cli import setup_logging  # noqa: PLC0415
+
+    setup_logging(config)
+
+
 def _generate_static_heatmaps(
     pivoted_dataframe: pd.DataFrame,
     config: argparse.Namespace,
@@ -239,9 +274,10 @@ def _generate_static_heatmaps(
     ]
     logger.debug(args)
 
-    # Fork, instead of spawn process (child) inherit parent logger config.
-    # See https://stackoverflow.com/q/14643568
-    with multiprocessing.get_context("fork").Pool() as pool:
+    with multiprocessing.Pool(
+        initializer=_init_worker_logging,
+        initargs=(config,),
+    ) as pool:
         pool.starmap(_generate_heatmap_wrapper, args)
 
 
@@ -275,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(
@@ -287,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]
@@ -337,7 +378,13 @@ def _filter_and_pivot_data(
         ValueError: If no data is extracted for the specified period.
     """
     date_filter = dataframe["year"] == config.year
-    date_filter &= dataframe["week"] <= str(config.week).zfill(2)
+
+    # A week of 52 or above means the whole year is requested, so include
+    # week 53 for ISO 53-week years instead of silently dropping its data.
+    max_week = config.week
+    if max_week >= WEEKS_IN_YEAR:
+        max_week = _weeks_in_iso_year(config.year)
+    date_filter &= dataframe["week"] <= str(max_week).zfill(2)
 
     if config.start_date:
         date_filter &= dataframe["date"] >= pd.Timestamp(config.start_date)
@@ -772,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.0 → 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.0
+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.0 → heatmap_cli-0.25.2}/src/heatmap_cli.egg-info/SOURCES.txt

@@ -31,6 +31,7 @@ tests/test_heatmap_open.py
 tests/test_heatmap_utils.py
 tests/test_heatmap_wrapper.py
 tests/test_help_flag.py
+tests/test_iso_53_week_year.py
 tests/test_no_annotate.py
 tests/test_open_heatmap.py
 tests/test_output_dir_option.py

{heatmap_cli-0.25.0 → 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.0 → 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.0 → 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.0 → 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.2/tests/test_iso_53_week_year.py

@@ -0,0 +1,83 @@
+# Copyright (C) 2026 Kian-Meng Ang
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Tests for ISO 53-week year handling."""
+
+import argparse
+
+import pandas as pd
+
+from heatmap_cli.heatmap import (
+    WEEKS_IN_YEAR,
+    _filter_and_pivot_data,
+    _weeks_in_iso_year,
+)
+
+
+def test_weeks_in_iso_year():
+    assert _weeks_in_iso_year(2026) == 53
+    assert _weeks_in_iso_year(2020) == 53
+    assert _weeks_in_iso_year(2025) == 52
+    assert _weeks_in_iso_year(2024) == 52
+
+
+def _base_dataframe(rows: list[tuple[str, int]]) -> pd.DataFrame:
+    """Build a prepared DataFrame as done by _read_and_prepare_data."""
+    df = pd.DataFrame(rows, columns=["date", "count"])
+    df["date"] = pd.to_datetime(df["date"])
+    df["weekday"] = df["date"].dt.weekday + 1
+    df["year"] = df["date"].dt.isocalendar().year
+    df["week"] = df["date"].dt.isocalendar().week.astype(str).str.zfill(2)
+    return df
+
+
+def test_week_53_kept_when_full_year_requested():
+    # Week 53 of the 53-week ISO year 2026 starts on 2026-12-28.
+    df = _base_dataframe(
+        [
+            ("2026-01-05", 100),
+            ("2026-06-15", 200),
+            ("2026-12-28", 300),
+        ],
+    )
+    config = argparse.Namespace(
+        year=2026,
+        week=WEEKS_IN_YEAR,
+        start_date=None,
+        end_date=None,
+    )
+
+    pivoted = _filter_and_pivot_data(df, config)
+
+    assert pivoted.loc[1, "53"] == 300
+
+
+def test_week_53_dropped_when_partial_year_requested():
+    df = _base_dataframe(
+        [
+            ("2026-01-05", 100),
+            ("2026-12-28", 300),
+        ],
+    )
+    config = argparse.Namespace(
+        year=2026,
+        week=10,
+        start_date=None,
+        end_date=None,
+    )
+
+    pivoted = _filter_and_pivot_data(df, config)
+
+    assert pivoted["53"].sum() == 0

{heatmap_cli-0.25.0 → 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

{heatmap_cli-0.25.0 → heatmap_cli-0.25.2}/tests/test_week_option.py

@@ -63,3 +63,35 @@ def test_end_date_option_invalid_format(cli_runner, csv_file):
     assert (
         "invalid date format: '2025-13-01', expected YYYY-MM-DD." in ret.stderr
     )
+
+
+def test_last_valid_week(cli_runner, csv_file):
+    """Test that --week 53 is accepted."""
+    csv = csv_file("sample.csv")
+    ret = cli_runner(csv, "-y", "2024", "-d", "-w", "53")
+
+    assert "week=53" in ret.stderr
+
+
+@pytest.mark.parametrize("option", ["-w", "--week"])
+@pytest.mark.parametrize("value", ["0", "-3", "54", "99"])
+def test_week_out_of_range(cli_runner, csv_file, option, value):
+    """Test that --week rejects values outside the ISO week range."""
+    csv = csv_file("sample.csv")
+    ret = cli_runner(csv, "-y", "2024", option, value, expect_error=True)
+
+    assert ret.returncode == 2
+    assert (
+        f"invalid week number: '{value}', expected between 1 and 53."
+        in ret.stderr
+    )
+
+
+@pytest.mark.parametrize("option", ["-w", "--week"])
+def test_week_not_a_number(cli_runner, csv_file, option):
+    """Test that --week rejects non-integer values."""
+    csv = csv_file("sample.csv")
+    ret = cli_runner(csv, "-y", "2024", option, "abc", expect_error=True)
+
+    assert ret.returncode == 2
+    assert "invalid week number: 'abc', expected an integer." in ret.stderr