clickqt-utils 0.0.1__tar.gz

clickqt_utils-0.0.1/LICENSE.md

@@ -0,0 +1,8 @@
+Copyright 2026, The copyright holders according to COPYING.md
+
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

clickqt_utils-0.0.1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: clickqt-utils
+Version: 0.0.1
+Summary: Some click utilities that are understood by clickqt
+Maintainer-email: Dominic Kempf <ssc@uni-heidelberg.de>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: click
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Dynamic: license-file
+
+# Welcome to clickqt-utils
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/ssciwr/clickqt-utils/ci.yml?branch=main)](https://github.com/ssciwr/clickqt-utils/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/ssciwr/clickqt-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/ssciwr/clickqt-utils)
+
+A collection of `click` utilities that is also understood by `clickqt`.
+
+## Features
+
+Currently, `clickqt-utils` contains the following utilities:
+
+* `PathWithExtensions`: a `click.Path` type that only accepts files with configured extensions.
+
+They are usable with any CLI written in `click`, but they have the advantage
+of being directly understood by `clickqt`. Notably, this package does not
+depend on `clickqt`, so depending on this will not make you depend on QT,
+but your users can opt into using `clickqt` for GUI support of your tools.
+
+## Installation
+
+The Python package `clickqt-utils` can be installed from PyPI:
+
+```
+python -m pip install clickqt-utils
+```
+
+## Acknowledgments
+
+This repository was set up using the [SSC Cookiecutter for Python Packages](https://github.com/ssciwr/cookiecutter-python-package).

clickqt_utils-0.0.1/README.md

@@ -0,0 +1,30 @@
+# Welcome to clickqt-utils
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/ssciwr/clickqt-utils/ci.yml?branch=main)](https://github.com/ssciwr/clickqt-utils/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/ssciwr/clickqt-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/ssciwr/clickqt-utils)
+
+A collection of `click` utilities that is also understood by `clickqt`.
+
+## Features
+
+Currently, `clickqt-utils` contains the following utilities:
+
+* `PathWithExtensions`: a `click.Path` type that only accepts files with configured extensions.
+
+They are usable with any CLI written in `click`, but they have the advantage
+of being directly understood by `clickqt`. Notably, this package does not
+depend on `clickqt`, so depending on this will not make you depend on QT,
+but your users can opt into using `clickqt` for GUI support of your tools.
+
+## Installation
+
+The Python package `clickqt-utils` can be installed from PyPI:
+
+```
+python -m pip install clickqt-utils
+```
+
+## Acknowledgments
+
+This repository was set up using the [SSC Cookiecutter for Python Packages](https://github.com/ssciwr/cookiecutter-python-package).

clickqt_utils-0.0.1/clickqt_utils/__init__.py

@@ -0,0 +1,13 @@
+from importlib import metadata
+
+__version__ = metadata.version(__package__)
+del metadata
+
+
+def add_one(x: int):
+    """An example function that increases a number
+
+    :param x: The input parameter to increase
+    :return: The successor of the given number
+    """
+    return x + 1

clickqt_utils-0.0.1/clickqt_utils/extensions.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Mapping
+from typing import Callable, Any
+
+import click
+
+
+class PathWithExtensions(click.Path):
+    """A ``click.Path`` variant that restricts accepted file extensions."""
+
+    def __init__(
+        self,
+        *args: Any,
+        file_extensions: Iterable[str] | Mapping[Iterable[str], str] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+
+        self.file_extension_groups = self._normalize_extension_groups(file_extensions)
+        self.file_extensions = tuple(
+            dict.fromkeys(
+                extension
+                for extension_group, _group_name in self.file_extension_groups
+                for extension in extension_group
+            )
+        )
+
+        self.validation_callbacks: tuple[
+            Callable[
+                [
+                    str | bytes | os.PathLike[str] | os.PathLike[bytes],
+                    click.Parameter | None,
+                    click.Context | None,
+                ],
+                None,
+            ],
+            ...,
+        ] = (
+            self._validate_not_directory,
+            self._validate_file_extension,
+        )
+
+    def convert(
+        self,
+        value: str | bytes | os.PathLike[str] | os.PathLike[bytes],
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> str | bytes | os.PathLike[str] | os.PathLike[bytes]:
+        converted = super().convert(value, param, ctx)
+
+        for validation_callback in self.validation_callbacks:
+            validation_callback(converted, param, ctx)
+
+        return converted
+
+    def _validate_not_directory(
+        self,
+        value: str | bytes | os.PathLike[str] | os.PathLike[bytes],
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> None:
+        path = os.fspath(value)
+        if os.path.isdir(path):
+            self.fail(f"{path!r} is a directory.", param, ctx)
+
+    def _validate_file_extension(
+        self,
+        value: str | bytes | os.PathLike[str] | os.PathLike[bytes],
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> None:
+        if not self.file_extensions:
+            return
+
+        path = os.fspath(value)
+        lower_path = os.fsdecode(path).lower()
+
+        if any(lower_path.endswith(extension) for extension in self.file_extensions):
+            return
+
+        allowed_extensions = ", ".join(self.file_extensions)
+        self.fail(
+            f"{path!r} does not have one of the required extensions: {allowed_extensions}",
+            param,
+            ctx,
+        )
+
+    def _normalize_extension_groups(
+        self,
+        file_extensions: Iterable[str] | Mapping[Iterable[str], str] | None,
+    ) -> tuple[tuple[tuple[str, ...], str], ...]:
+        if file_extensions is None:
+            return ()
+
+        if isinstance(file_extensions, Mapping):
+            return tuple(
+                (self._normalize_extensions(extensions), group_name)
+                for extensions, group_name in file_extensions.items()
+            )
+
+        normalized_extensions = self._normalize_extensions(file_extensions)
+        if not normalized_extensions:
+            return ()
+        return ((normalized_extensions, "Allowed Files"),)
+
+    @staticmethod
+    def _normalize_extensions(file_extensions: Iterable[str]) -> tuple[str, ...]:
+        return tuple(
+            extension.lower() if extension.startswith(".") else f".{extension.lower()}"
+            for extension in file_extensions
+        )

clickqt_utils-0.0.1/clickqt_utils.egg-info/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: clickqt-utils
+Version: 0.0.1
+Summary: Some click utilities that are understood by clickqt
+Maintainer-email: Dominic Kempf <ssc@uni-heidelberg.de>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: click
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Dynamic: license-file
+
+# Welcome to clickqt-utils
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/ssciwr/clickqt-utils/ci.yml?branch=main)](https://github.com/ssciwr/clickqt-utils/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/ssciwr/clickqt-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/ssciwr/clickqt-utils)
+
+A collection of `click` utilities that is also understood by `clickqt`.
+
+## Features
+
+Currently, `clickqt-utils` contains the following utilities:
+
+* `PathWithExtensions`: a `click.Path` type that only accepts files with configured extensions.
+
+They are usable with any CLI written in `click`, but they have the advantage
+of being directly understood by `clickqt`. Notably, this package does not
+depend on `clickqt`, so depending on this will not make you depend on QT,
+but your users can opt into using `clickqt` for GUI support of your tools.
+
+## Installation
+
+The Python package `clickqt-utils` can be installed from PyPI:
+
+```
+python -m pip install clickqt-utils
+```
+
+## Acknowledgments
+
+This repository was set up using the [SSC Cookiecutter for Python Packages](https://github.com/ssciwr/cookiecutter-python-package).

clickqt_utils-0.0.1/clickqt_utils.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE.md
+README.md
+pyproject.toml
+clickqt_utils/__init__.py
+clickqt_utils/extensions.py
+clickqt_utils.egg-info/PKG-INFO
+clickqt_utils.egg-info/SOURCES.txt
+clickqt_utils.egg-info/dependency_links.txt
+clickqt_utils.egg-info/requires.txt
+clickqt_utils.egg-info/top_level.txt
+tests/test_extensions.py

clickqt_utils-0.0.1/clickqt_utils.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clickqt_utils-0.0.1/clickqt_utils.egg-info/requires.txt

@@ -0,0 +1,5 @@
+click
+
+[tests]
+pytest
+pytest-cov

clickqt_utils-0.0.1/clickqt_utils.egg-info/top_level.txt

@@ -0,0 +1 @@
+clickqt_utils

clickqt_utils-0.0.1/pyproject.toml

@@ -0,0 +1,50 @@
+# This section describes the requirements of the build/installation
+# process itself. Being able to do this was the original reason to
+# introduce pyproject.toml
+[build-system]
+requires = [
+    "setuptools >=61",
+]
+build-backend = "setuptools.build_meta"
+
+# This section provides general project metadata that is used across
+# a variety of build tools. Notably, the version specified here is the
+# single source of truth for clickqt_utils's version
+[project]
+name = "clickqt-utils"
+description = "Some click utilities that are understood by clickqt"
+readme = "README.md"
+maintainers = [
+    { name = "Dominic Kempf", email = "ssc@uni-heidelberg.de" },
+]
+version = "0.0.1"
+requires-python = ">=3.10"
+license-files = ["LICENSE.md"]
+license = "MIT"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "click",
+]
+
+[project.optional-dependencies]
+tests = [
+    "pytest",
+    "pytest-cov",
+]
+
+
+# The following section contains setuptools-specific configuration
+# options. For a full reference of available options, check the overview
+# at https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["clickqt_utils*"]
+
+# The following is the configuration for the pytest test suite
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]

clickqt_utils-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

clickqt_utils-0.0.1/tests/test_extensions.py

@@ -0,0 +1,135 @@
+import click
+import pytest
+
+from click.testing import CliRunner
+from clickqt_utils.extensions import PathWithExtensions
+
+
+def test_path_with_extensions_stores_file_extensions():
+    path_type = PathWithExtensions(file_extensions=["txt", ".csv"])
+
+    assert path_type.file_extensions == (".txt", ".csv")
+    assert path_type.file_extension_groups == (((".txt", ".csv"), "Allowed Files"),)
+    assert path_type.validation_callbacks[1] == path_type._validate_file_extension
+
+
+def test_path_with_extensions_stores_extension_groups_for_dialog():
+    path_type = PathWithExtensions(
+        file_extensions={
+            ("png", ".JPEG"): "Images",
+            ("txt",): "Text Files",
+        }
+    )
+
+    assert path_type.file_extensions == (".png", ".jpeg", ".txt")
+    assert path_type.file_extension_groups == (
+        ((".png", ".jpeg"), "Images"),
+        ((".txt",), "Text Files"),
+    )
+
+
+def test_path_with_extensions_accepts_matching_extension(tmp_path):
+    input_file = tmp_path / "input.TXT"
+    input_file.write_text("data", encoding="utf-8")
+
+    path_type = PathWithExtensions(file_extensions=[".txt"], exists=True)
+
+    assert path_type.convert(str(input_file), None, None) == str(input_file)
+
+
+def test_path_with_extensions_rejects_wrong_extension(tmp_path):
+    input_file = tmp_path / "input.csv"
+    input_file.write_text("data", encoding="utf-8")
+
+    path_type = PathWithExtensions(file_extensions=["txt"], exists=True)
+
+    with pytest.raises(click.BadParameter, match="required extensions"):
+        path_type.convert(str(input_file), None, None)
+
+
+def test_path_with_extensions_accepts_grouped_extensions(tmp_path):
+    image_file = tmp_path / "photo.JPEG"
+    image_file.write_text("img", encoding="utf-8")
+    text_file = tmp_path / "readme.txt"
+    text_file.write_text("txt", encoding="utf-8")
+
+    path_type = PathWithExtensions(
+        file_extensions={
+            ("png", ".jpeg"): "Images",
+            ("txt",): "Text Files",
+        },
+        exists=True,
+    )
+
+    assert path_type.convert(str(image_file), None, None) == str(image_file)
+    assert path_type.convert(str(text_file), None, None) == str(text_file)
+
+
+def test_path_with_extensions_rejects_directories(tmp_path):
+    input_dir = tmp_path / "folder.txt"
+    input_dir.mkdir()
+
+    path_type = PathWithExtensions(file_extensions=[".txt"], exists=True)
+
+    with pytest.raises(click.BadParameter, match="directory"):
+        path_type.convert(str(input_dir), None, None)
+
+
+@click.command()
+@click.argument(
+    "path",
+    type=PathWithExtensions(file_extensions=[".txt"], exists=True),
+)
+def cli(path):
+    click.echo(path)
+
+
+def test_path_with_extensions_click_cli_system(tmp_path):
+    runner = CliRunner()
+
+    valid_file = tmp_path / "valid.txt"
+    valid_file.write_text("ok", encoding="utf-8")
+    valid_result = runner.invoke(cli, [str(valid_file)])
+    assert valid_result.exit_code == 0
+    assert str(valid_file) in valid_result.output
+
+    invalid_file = tmp_path / "invalid.csv"
+    invalid_file.write_text("no", encoding="utf-8")
+    invalid_result = runner.invoke(cli, [str(invalid_file)])
+    assert invalid_result.exit_code != 0
+    assert "required extensions" in invalid_result.output
+
+    invalid_dir = tmp_path / "folder.txt"
+    invalid_dir.mkdir()
+    dir_result = runner.invoke(cli, [str(invalid_dir)])
+    assert dir_result.exit_code != 0
+    assert "is a directory" in dir_result.output
+
+
+def test_path_with_extensions_grouped_extensions_click_cli_system(tmp_path):
+    @click.command()
+    @click.argument(
+        "path",
+        type=PathWithExtensions(
+            file_extensions={
+                ("png", ".jpeg"): "Images",
+                ("txt",): "Text Files",
+            },
+            exists=True,
+        ),
+    )
+    def grouped_cli(path):
+        click.echo(path)
+
+    runner = CliRunner()
+
+    image_file = tmp_path / "photo.png"
+    image_file.write_text("image", encoding="utf-8")
+    image_result = runner.invoke(grouped_cli, [str(image_file)])
+    assert image_result.exit_code == 0
+
+    invalid_file = tmp_path / "archive.zip"
+    invalid_file.write_text("zip", encoding="utf-8")
+    invalid_result = runner.invoke(grouped_cli, [str(invalid_file)])
+    assert invalid_result.exit_code != 0
+    assert "required extensions" in invalid_result.output