Add ConfigOption for flexible configuration.

Introduce `ConfigOption` and related utilities in `bumpversion.click_config` to handle configuration file paths or URLs. Includes tests for processing options, resolving paths/URLs, and handling errors in `resolve_conf_location` and `download_url`.

Author: coordt

bumpversion/click_config.py

@@ -0,0 +1,164 @@
+"""A configuration option for click."""
+
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any, Callable, Optional, Sequence, Union
+from urllib.parse import urlparse
+
+import httpx
+from click import Context, Option
+from click.decorators import FC, _param_memo  # noqa: PLC2701
+
+from bumpversion.exceptions import BadInputError
+from bumpversion.ui import get_indented_logger
+
+logger = get_indented_logger(__name__)
+
+BoolOrStr = Union[bool, str]
+StrSequence = Sequence[str]
+
+
+class ConfigOption(Option):
+    """A configuration option for click."""
+
+    def __init__(
+        self,
+        param_decls: Optional[StrSequence] = None,
+        show_default: Optional[BoolOrStr] = None,
+        allow_from_autoenv: bool = True,
+        help: Optional[str] = None,
+        show_envvar: bool = False,
+        **attrs,
+    ):
+        param_decls = param_decls or ("--config", "-C")
+        multiple = False
+        count = False
+        hidden = False
+        show_choices = True
+        prompt = False
+        confirmation_prompt = False
+        is_flag = None
+        flag_value = None
+        prompt_required = True
+        hide_input = False
+        type_ = str
+        meta_var = "PATH_OR_URL"
+
+        super().__init__(
+            param_decls=param_decls,
+            show_default=show_default,
+            prompt=prompt,
+            confirmation_prompt=confirmation_prompt,
+            prompt_required=prompt_required,
+            hide_input=hide_input,
+            is_flag=is_flag,
+            flag_value=flag_value,
+            metavar=meta_var,
+            multiple=multiple,
+            count=count,
+            allow_from_autoenv=allow_from_autoenv,
+            type=type_,
+            help=help,
+            hidden=hidden,
+            show_choices=show_choices,
+            show_envvar=show_envvar,
+            **attrs,
+        )
+
+    def process_value(self, ctx: Context, value: Any) -> Path:
+        """Process the value of the option."""
+        value = super().process_value(ctx, value)
+        return resolve_conf_location(value)
+
+
+def config_option(*param_decls: str, cls: Optional[type[ConfigOption]] = None, **attrs: Any) -> Callable[[FC], FC]:
+    """
+    Attaches a ConfigOption to the command.
+
+    All positional arguments are passed as parameter declarations to `ConfigOption`.
+
+    All keyword arguments are forwarded unchanged (except ``cls``). This is equivalent to creating a
+    `ConfigOption` instance manually and attaching it to the `Command.params` list.
+
+    For the default option class, refer to `ConfigOption` and `Parameter` for descriptions of parameters.
+
+    Args:
+        *param_decls: Passed as positional arguments to the constructor of `cls`.
+        cls: the option class to instantiate.  This defaults to `ConfigOption`.
+        **attrs: Passed as keyword arguments to the constructor of `cls`.
+
+    Returns:
+        A decorated function.
+    """
+    if cls is None:  # pragma: no-coverage
+        cls = ConfigOption
+
+    def decorator(f: FC) -> FC:
+        _param_memo(f, cls(param_decls, **attrs))
+        return f
+
+    return decorator
+
+
+def resolve_conf_location(url_or_path: str) -> Path:
+    """Resolve a URL or path.
+
+    The path is considered a URL if it is parseable as such and starts with ``http://`` or ``https://``.
+
+    Args:
+        url_or_path: The URL or path to resolve.
+
+    Returns:
+        The contents of the location.
+    """
+    parsed_url = urlparse(url_or_path)
+
+    if parsed_url.scheme in ("http", "https"):
+        return download_url(url_or_path)
+
+    return Path(url_or_path)
+
+
+def download_url(url: str) -> Path:
+    """
+    Download the contents of a URL.
+
+    Args:
+        url: The URL to download
+
+    Returns:
+        The Path to the downloaded file.
+
+    Raises:
+        BadInputError: if there is a problem downloading the URL
+    """
+    logger.debug(f"Downloading configuration from URL: {url}")
+    filename = get_file_name_from_url(url)
+    suffix = Path(filename).suffix
+
+    try:
+        resp = httpx.get(url, follow_redirects=True, timeout=1)
+        resp.raise_for_status()
+        with NamedTemporaryFile(mode="w", delete=False, encoding="utf-8", suffix=suffix) as tmp:
+            tmp.write(resp.text)
+        return Path(tmp.name)
+    except httpx.RequestError as e:
+        raise BadInputError(f"Unable to download configuration from URL: {url}") from e
+    except httpx.HTTPStatusError as e:
+        msg = f"Error response {e.response.status_code} while requesting {url}."
+        raise BadInputError(msg) from e
+
+
+def get_file_name_from_url(url: str) -> str:
+    """
+    Extracts the file name from a URL.
+
+    Args:
+        url: The URL to extract the file name from.
+
+    Returns:
+        The file name from the URL, or an empty string if there is no file name.
+    """
+    parsed_url = urlparse(url)
+
+    return parsed_url.path.split("/")[-1]

tests/test_click_config.py

@@ -0,0 +1,102 @@
+"""Tests for the bumpversion.click_config module."""
+
+from pathlib import Path
+
+import click
+import httpx
+import pytest
+
+from bumpversion.click_config import config_option, resolve_conf_location, download_url
+from bumpversion.exceptions import BadInputError
+
+
+@click.command()
+@config_option()
+def hello(config: Path):
+    """Say hello."""
+    click.echo(f"Hello {config}!")
+    click.echo(f"path exists: {config.exists()}")
+
+
+class TestConfigOption:
+    """Tests to for config_option."""
+
+    def test_config_option(self, runner):
+        """Passing an invalid option should raise an error."""
+        result = runner.invoke(hello, ["--config", "idont/exist.txt"])
+
+        assert result.exit_code == 0
+        assert "path exists: False" in result.output
+
+
+class TestResolveConfLocation:
+    """Tests for resolve_conf_location."""
+
+    def test_resolves_file_path(self, fixtures_path: Path):
+        """Should return a Path object for a valid local file path."""
+        dummy_path = fixtures_path / "basic_cfg.toml"
+        result = resolve_conf_location(str(dummy_path))
+        assert isinstance(result, Path)
+        assert result == dummy_path
+
+    def test_resolves_valid_url(self, mocker):
+        """Should download the file if given a valid URL."""
+        # Arrange
+        mocked_download = mocker.patch(
+            "bumpversion.click_config.download_url", return_value=Path("/tmp/downloaded_config.txt")
+        )
+        url = "http://example.com/config.txt"
+
+        # Act
+        result = resolve_conf_location(url)
+
+        # Assert
+        mocked_download.assert_called_once_with(url)
+        assert isinstance(result, Path)
+        assert str(result) == "/tmp/downloaded_config.txt"
+
+
+class TestDownloadUrl:
+    """Tests for download_url."""
+
+    def test_download_url_success(self, mocker, tmp_path: Path):
+        """Should return a Path for a valid request."""
+        # Arrange
+        mock_response = mocker.Mock(spec=httpx.Response)
+        mock_response.status_code = 200
+        mock_response.text = "content"
+        mocker.patch("httpx.get", return_value=mock_response)
+        tmp_file = tmp_path / "tempfile.txt"
+        mock_tempfile = mocker.patch("bumpversion.click_config.NamedTemporaryFile", autospec=True)
+        temp_file_instance = mock_tempfile.return_value.__enter__.return_value
+        temp_file_instance.name = str(tmp_file)
+
+        # Act
+        result = download_url("http://example.com/config.txt")
+
+        # Assert
+        assert isinstance(result, Path)
+        assert result == tmp_file
+        mock_tempfile.assert_called_once()
+
+    def test_download_url_request_error(self, mocker):
+        """Should raise BadInputError for a RequestError."""
+        # Arrange
+        mocker.patch("httpx.get", side_effect=httpx.RequestError("Request failed"))
+
+        # Act & Assert
+        with pytest.raises(BadInputError, match="Unable to download configuration from URL"):
+            download_url("http://example.com/config.txt")
+
+    def test_download_url_http_status_error(self, mocker):
+        """Should raise BadInputError for an HTTPStatusError."""
+        mock_response = mocker.Mock(spec=httpx.Response)
+        mock_response.status_code = 404
+        mock_response.raise_for_status.side_effect = httpx.HTTPStatusError(
+            "Error", request=mocker.Mock(), response=mock_response
+        )
+        mocker.patch("httpx.get", return_value=mock_response)
+
+        # Act & Assert
+        with pytest.raises(BadInputError, match="Error response 404 while requesting"):
+            download_url("http://example.com/config.txt")