svgconverter 1.2.0__tar.gz

svgconverter-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Chien-Hsun, Chang
+
+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.

svgconverter-1.2.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: svgconverter
+Version: 1.2.0
+Summary: Embed PNG and JPEG raster images in SVG containers.
+Author: Chien-Hsun Chang
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KageRyo/SVGConverter
+Project-URL: Documentation, https://github.com/KageRyo/SVGConverter#readme
+Project-URL: Issues, https://github.com/KageRyo/SVGConverter/issues
+Project-URL: Changelog, https://github.com/KageRyo/SVGConverter/blob/main/CHANGELOG.md
+Keywords: image,svg,converter,raster,embed
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Dynamic: license-file
+
+# SVGConverter
+
+[正體中文](README_TW.md)
+
+SVGConverter wraps a PNG or JPEG image in an SVG container. It provides a
+small Python API, command-line interface, and desktop GUI.
+
+> **Important:** current `embed` mode Base64-encodes the original raster image
+> into an SVG `<image>` element. It does **not** trace pixels into vector paths,
+> and it does not inherently reduce file size. A future `vectorize` mode is
+> tracked separately.
+
+## Installation
+
+SVGConverter requires Python 3.10 or newer. After v1.2.0 has been published to
+PyPI:
+
+```bash
+python -m pip install --upgrade svgconverter
+```
+
+To run the current development version instead:
+
+```bash
+git clone https://github.com/KageRyo/SVGConverter.git
+cd SVGConverter
+python -m pip install .
+```
+
+## Command line
+
+Convert one image, retaining its dimensions in the generated SVG:
+
+```bash
+svgconverter image.png
+svgconverter photo.jpg --output output.svg
+```
+
+Convert all supported images immediately inside a directory:
+
+```bash
+svgconverter ./images --output-dir ./svg-output
+```
+
+Outputs are never overwritten unless `--overwrite` is supplied. Run
+`svgconverter --help` for all options. Supported inputs are PNG, JPG, and JPEG
+(including upper-case extensions); recursive conversion and image optimization
+are not part of the current release.
+
+## Python API
+
+```python
+from svgconverter import SVGConverter, convert_file
+
+convert_file("image.png", "image.svg")
+
+converter = SVGConverter(overwrite=True)
+result = converter.convert_directory("./images", "./svg-output")
+print(result.success_count, result.failure_count)
+```
+
+`convert_file()` returns the output `pathlib.Path`. Directory conversion returns
+a `BatchResult` containing successful output paths and per-file failures, so a
+bad image does not abort the entire batch.
+
+## GUI
+
+Install the package and run:
+
+```bash
+svgconverter-gui
+```
+
+The legacy development command `python main.py` starts the same GUI. The GUI
+currently selects a directory and offers Traditional Chinese, English, and
+Japanese. It uses the same public conversion API as the CLI.
+
+## Release process
+
+The tag workflow uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+instead of a long-lived API token. Before the first release, configure a
+pending or normal PyPI Trusted Publisher for:
+
+- owner: `KageRyo`
+- repository: `SVGConverter`
+- workflow: `release.yml`
+- environment: `pypi`
+
+After the pull request is merged, create an annotated `v1.2.0` tag whose
+version matches `pyproject.toml`. The workflow builds, checks, publishes to
+PyPI, and then creates a GitHub Release with the distributions attached.
+
+## Contributing and license
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local checks and commit conventions.
+This project is licensed under the [MIT License](LICENSE).

svgconverter-1.2.0/README.md

@@ -0,0 +1,96 @@
+# SVGConverter
+
+[正體中文](README_TW.md)
+
+SVGConverter wraps a PNG or JPEG image in an SVG container. It provides a
+small Python API, command-line interface, and desktop GUI.
+
+> **Important:** current `embed` mode Base64-encodes the original raster image
+> into an SVG `<image>` element. It does **not** trace pixels into vector paths,
+> and it does not inherently reduce file size. A future `vectorize` mode is
+> tracked separately.
+
+## Installation
+
+SVGConverter requires Python 3.10 or newer. After v1.2.0 has been published to
+PyPI:
+
+```bash
+python -m pip install --upgrade svgconverter
+```
+
+To run the current development version instead:
+
+```bash
+git clone https://github.com/KageRyo/SVGConverter.git
+cd SVGConverter
+python -m pip install .
+```
+
+## Command line
+
+Convert one image, retaining its dimensions in the generated SVG:
+
+```bash
+svgconverter image.png
+svgconverter photo.jpg --output output.svg
+```
+
+Convert all supported images immediately inside a directory:
+
+```bash
+svgconverter ./images --output-dir ./svg-output
+```
+
+Outputs are never overwritten unless `--overwrite` is supplied. Run
+`svgconverter --help` for all options. Supported inputs are PNG, JPG, and JPEG
+(including upper-case extensions); recursive conversion and image optimization
+are not part of the current release.
+
+## Python API
+
+```python
+from svgconverter import SVGConverter, convert_file
+
+convert_file("image.png", "image.svg")
+
+converter = SVGConverter(overwrite=True)
+result = converter.convert_directory("./images", "./svg-output")
+print(result.success_count, result.failure_count)
+```
+
+`convert_file()` returns the output `pathlib.Path`. Directory conversion returns
+a `BatchResult` containing successful output paths and per-file failures, so a
+bad image does not abort the entire batch.
+
+## GUI
+
+Install the package and run:
+
+```bash
+svgconverter-gui
+```
+
+The legacy development command `python main.py` starts the same GUI. The GUI
+currently selects a directory and offers Traditional Chinese, English, and
+Japanese. It uses the same public conversion API as the CLI.
+
+## Release process
+
+The tag workflow uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+instead of a long-lived API token. Before the first release, configure a
+pending or normal PyPI Trusted Publisher for:
+
+- owner: `KageRyo`
+- repository: `SVGConverter`
+- workflow: `release.yml`
+- environment: `pypi`
+
+After the pull request is merged, create an annotated `v1.2.0` tag whose
+version matches `pyproject.toml`. The workflow builds, checks, publishes to
+PyPI, and then creates a GitHub Release with the distributions attached.
+
+## Contributing and license
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local checks and commit conventions.
+This project is licensed under the [MIT License](LICENSE).

svgconverter-1.2.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "svgconverter"
+version = "1.2.0"
+description = "Embed PNG and JPEG raster images in SVG containers."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Chien-Hsun Chang" }]
+keywords = ["image", "svg", "converter", "raster", "embed"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Environment :: Win32 (MS Windows)",
+  "Intended Audience :: End Users/Desktop",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Multimedia :: Graphics :: Graphics Conversion",
+]
+dependencies = ["Pillow>=10.0"]
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "pytest>=8.0", "ruff>=0.8", "twine>=6.0"]
+
+[project.urls]
+Homepage = "https://github.com/KageRyo/SVGConverter"
+Documentation = "https://github.com/KageRyo/SVGConverter#readme"
+Issues = "https://github.com/KageRyo/SVGConverter/issues"
+Changelog = "https://github.com/KageRyo/SVGConverter/blob/main/CHANGELOG.md"
+
+[project.scripts]
+svgconverter = "svgconverter.cli:main"
+svgconverter-gui = "svgconverter.gui:run_gui"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"svgconverter.resources" = ["*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

svgconverter-1.2.0/setup.cfg

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

svgconverter-1.2.0/src/svgconverter/__init__.py

@@ -0,0 +1,33 @@
+"""Public library interface for SVGConverter.
+
+SVGConverter's current ``embed`` mode wraps raster image bytes in an SVG
+``<image>`` element. It does not trace images into vector paths.
+"""
+
+from .converter import (
+    BatchResult,
+    ConversionError,
+    ConversionFailure,
+    InputPathError,
+    OutputExistsError,
+    SVGConverter,
+    SVGConverterError,
+    UnsupportedImageError,
+    convert_directory,
+    convert_file,
+)
+
+__all__ = [
+    "BatchResult",
+    "ConversionError",
+    "ConversionFailure",
+    "InputPathError",
+    "OutputExistsError",
+    "SVGConverter",
+    "SVGConverterError",
+    "UnsupportedImageError",
+    "convert_directory",
+    "convert_file",
+]
+
+__version__ = "1.2.0"

svgconverter-1.2.0/src/svgconverter/cli.py

@@ -0,0 +1,94 @@
+"""Command-line interface for SVGConverter."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from .converter import BatchResult, SVGConverterError, convert_directory, convert_file
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the ``svgconverter`` command parser."""
+
+    parser = argparse.ArgumentParser(
+        prog="svgconverter",
+        description=(
+            "Embed a PNG or JPEG raster image in an SVG container. "
+            "This does not vectorize the image."
+        ),
+    )
+    parser.add_argument(
+        "input", type=Path, help="PNG/JPG/JPEG file or a directory of images"
+    )
+    output_group = parser.add_mutually_exclusive_group()
+    output_group.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        help="Output SVG path for a single input file",
+    )
+    output_group.add_argument(
+        "--output-dir",
+        type=Path,
+        help="Output directory for a directory input",
+    )
+    parser.add_argument(
+        "--overwrite", action="store_true", help="Replace existing output SVG files"
+    )
+    parser.add_argument(
+        "--mode",
+        choices=("embed",),
+        default="embed",
+        help="Conversion mode (only embed is currently available)",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    return parser
+
+
+def _print_batch_result(result: BatchResult) -> None:
+    for output_path in result.converted:
+        print(f"Converted: {output_path}")
+    for failure in result.failed:
+        print(f"Failed: {failure.input_path}: {failure.error}")
+    print(f"Summary: {result.success_count} converted, {result.failure_count} failed")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI and return a process exit code."""
+
+    parser = build_parser()
+    arguments = parser.parse_args(argv)
+    try:
+        if arguments.input.is_file():
+            if arguments.output_dir is not None:
+                parser.error("--output-dir can only be used with a directory input")
+            output_path = convert_file(
+                arguments.input,
+                arguments.output,
+                overwrite=arguments.overwrite,
+                mode=arguments.mode,
+            )
+            print(f"Converted: {output_path}")
+            return 0
+
+        if arguments.output is not None:
+            parser.error("--output can only be used with a single input file")
+        result = convert_directory(
+            arguments.input,
+            arguments.output_dir,
+            overwrite=arguments.overwrite,
+            mode=arguments.mode,
+        )
+        _print_batch_result(result)
+        return 1 if result.failed else 0
+    except SVGConverterError as error:
+        parser.exit(1, f"error: {error}\n")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

svgconverter-1.2.0/src/svgconverter/converter.py

@@ -0,0 +1,236 @@
+"""Core raster-image embedding functionality.
+
+The conversion mode implemented here is deliberately named ``embed``: the
+source raster bytes are Base64 encoded into an SVG ``<image>`` element. No
+attempt is made to convert pixels into vector paths.
+"""
+
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from PIL import Image, UnidentifiedImageError
+
+ConversionMode = Literal["embed"]
+
+_SUPPORTED_EXTENSIONS = frozenset({".png", ".jpg", ".jpeg"})
+_MIME_TYPES = {"PNG": "image/png", "JPEG": "image/jpeg"}
+
+
+class SVGConverterError(Exception):
+    """Base exception for expected SVGConverter failures."""
+
+
+class InputPathError(SVGConverterError):
+    """Raised when an input path is missing or is the wrong kind of path."""
+
+
+class UnsupportedImageError(SVGConverterError):
+    """Raised when an input is not a supported PNG or JPEG image."""
+
+
+class OutputExistsError(SVGConverterError):
+    """Raised when conversion would overwrite an existing SVG."""
+
+
+class ConversionError(SVGConverterError):
+    """Raised when an image cannot be read or an SVG cannot be written."""
+
+
+@dataclass(frozen=True)
+class ConversionFailure:
+    """One failed item from a batch conversion."""
+
+    input_path: Path
+    error: SVGConverterError
+
+
+@dataclass(frozen=True)
+class BatchResult:
+    """Successful and failed items from a directory conversion."""
+
+    converted: tuple[Path, ...]
+    failed: tuple[ConversionFailure, ...]
+
+    @property
+    def success_count(self) -> int:
+        """Return the number of converted images."""
+
+        return len(self.converted)
+
+    @property
+    def failure_count(self) -> int:
+        """Return the number of files that could not be converted."""
+
+        return len(self.failed)
+
+
+def _validate_mode(mode: ConversionMode) -> None:
+    if mode != "embed":
+        raise ValueError(
+            "Only mode='embed' is available; vectorization is not implemented."
+        )
+
+
+def _validate_input(input_path: Path) -> None:
+    if not input_path.exists():
+        raise InputPathError(f"Input file does not exist: {input_path}")
+    if not input_path.is_file():
+        raise InputPathError(f"Input path is not a file: {input_path}")
+    if input_path.suffix.lower() not in _SUPPORTED_EXTENSIONS:
+        supported = ", ".join(sorted(_SUPPORTED_EXTENSIONS))
+        raise UnsupportedImageError(
+            f"Unsupported image extension {input_path.suffix!r}; "
+            f"supported extensions: {supported}"
+        )
+
+
+def _read_image_metadata(input_path: Path) -> tuple[int, int, str]:
+    try:
+        with Image.open(input_path) as image:
+            image.verify()
+        with Image.open(input_path) as image:
+            mime_type = _MIME_TYPES.get(image.format or "")
+            if mime_type is None:
+                raise UnsupportedImageError(
+                    f"Unsupported image format in {input_path}: "
+                    f"{image.format or 'unknown'}"
+                )
+            return image.width, image.height, mime_type
+    except UnsupportedImageError:
+        raise
+    except (OSError, UnidentifiedImageError) as error:
+        raise ConversionError(f"Cannot read image {input_path}: {error}") from error
+
+
+def _svg_document(*, data_uri: str, width: int, height: int) -> str:
+    return (
+        '<?xml version="1.0" encoding="UTF-8"?>\n'
+        '<svg xmlns="http://www.w3.org/2000/svg" '
+        f'width="{width}" height="{height}" viewBox="0 0 {width} {height}">\n'
+        f'  <image href="{data_uri}" width="{width}" height="{height}"/>\n'
+        "</svg>\n"
+    )
+
+
+def convert_file(
+    input_path: str | Path,
+    output_path: str | Path | None = None,
+    *,
+    overwrite: bool = False,
+    mode: ConversionMode = "embed",
+) -> Path:
+    """Embed one PNG or JPEG image in an SVG file and return its output path.
+
+    ``output_path`` defaults to the input filename with an ``.svg`` suffix.
+    Parent directories for an explicit output path are created automatically.
+    Existing outputs are preserved unless ``overwrite=True`` is provided.
+    """
+
+    _validate_mode(mode)
+    source = Path(input_path)
+    _validate_input(source)
+    destination = (
+        Path(output_path) if output_path is not None else source.with_suffix(".svg")
+    )
+
+    if destination.exists() and not overwrite:
+        raise OutputExistsError(
+            f"Output already exists: {destination}. Pass overwrite=True to replace it."
+        )
+    if destination.exists() and destination.is_dir():
+        raise InputPathError(f"Output path is a directory: {destination}")
+
+    width, height, mime_type = _read_image_metadata(source)
+    try:
+        image_data = source.read_bytes()
+        data_uri = (
+            f"data:{mime_type};base64,{base64.b64encode(image_data).decode('ascii')}"
+        )
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(
+            _svg_document(data_uri=data_uri, width=width, height=height),
+            encoding="utf-8",
+        )
+    except OSError as error:
+        raise ConversionError(f"Cannot write SVG {destination}: {error}") from error
+
+    return destination
+
+
+def convert_directory(
+    directory: str | Path,
+    output_dir: str | Path | None = None,
+    *,
+    overwrite: bool = False,
+    mode: ConversionMode = "embed",
+) -> BatchResult:
+    """Convert supported images directly in a directory without recursing.
+
+    Files with non-image extensions are ignored. Each supported image is
+    attempted independently, so a corrupt image does not stop the batch.
+    """
+
+    _validate_mode(mode)
+    source_directory = Path(directory)
+    if not source_directory.exists():
+        raise InputPathError(f"Input directory does not exist: {source_directory}")
+    if not source_directory.is_dir():
+        raise InputPathError(f"Input path is not a directory: {source_directory}")
+
+    destination_directory = (
+        Path(output_dir) if output_dir is not None else source_directory
+    )
+    converted: list[Path] = []
+    failed: list[ConversionFailure] = []
+    candidates = sorted(
+        (
+            path
+            for path in source_directory.iterdir()
+            if path.is_file() and path.suffix.lower() in _SUPPORTED_EXTENSIONS
+        ),
+        key=lambda path: path.name.casefold(),
+    )
+
+    for source in candidates:
+        destination = destination_directory / f"{source.stem}.svg"
+        try:
+            converted.append(
+                convert_file(source, destination, overwrite=overwrite, mode=mode)
+            )
+        except SVGConverterError as error:
+            failed.append(ConversionFailure(input_path=source, error=error))
+
+    return BatchResult(converted=tuple(converted), failed=tuple(failed))
+
+
+class SVGConverter:
+    """Configurable facade for repeated SVG embedding operations."""
+
+    def __init__(
+        self, *, overwrite: bool = False, mode: ConversionMode = "embed"
+    ) -> None:
+        _validate_mode(mode)
+        self.overwrite = overwrite
+        self.mode = mode
+
+    def convert_file(
+        self, input_path: str | Path, output_path: str | Path | None = None
+    ) -> Path:
+        """Convert one image using this instance's configuration."""
+
+        return convert_file(
+            input_path, output_path, overwrite=self.overwrite, mode=self.mode
+        )
+
+    def convert_directory(
+        self, directory: str | Path, output_dir: str | Path | None = None
+    ) -> BatchResult:
+        """Convert one directory using this instance's configuration."""
+
+        return convert_directory(
+            directory, output_dir, overwrite=self.overwrite, mode=self.mode
+        )

svgconverter-1.2.0/src/svgconverter/gui.py

@@ -0,0 +1,82 @@
+"""Tkinter desktop interface built on the public conversion API."""
+
+from __future__ import annotations
+
+import tkinter as tk
+from tkinter import filedialog, messagebox
+
+from .converter import SVGConverter, SVGConverterError
+from .i18n import (
+    DEFAULT_LOCALE,
+    load_translations,
+    locale_for_display_name,
+    translation_for,
+)
+
+
+class SVGConverterApp:
+    """The standalone GUI application."""
+
+    def __init__(self) -> None:
+        self.root = tk.Tk()
+        self.root.title("SVGConverter")
+        self.converter = SVGConverter()
+        self.translations = load_translations()
+        self.locale = DEFAULT_LOCALE
+        self.button = tk.Button(self.root, command=self.select_folder)
+        self.button.pack(pady=20)
+        initial_name = translation_for(self.locale, self.translations)["name"]
+        self.language_var = tk.StringVar(value=initial_name)
+        self.language_menu = tk.OptionMenu(
+            self.root,
+            self.language_var,
+            *(text["name"] for text in self.translations.values()),
+            command=self.change_language,
+        )
+        self.language_menu.pack()
+        self._refresh_text()
+
+    def _refresh_text(self) -> None:
+        self.button.config(
+            text=translation_for(self.locale, self.translations)["select"]
+        )
+
+    def select_folder(self) -> None:
+        folder = filedialog.askdirectory(parent=self.root)
+        if not folder:
+            return
+        text = translation_for(self.locale, self.translations)
+        try:
+            result = self.converter.convert_directory(folder)
+        except SVGConverterError as error:
+            messagebox.showerror("SVGConverter", str(error), parent=self.root)
+            return
+
+        message = text["done"].format(
+            converted=result.success_count, failed=result.failure_count
+        )
+        if result.failed:
+            details = "\n".join(
+                f"{failure.input_path.name}: {failure.error}"
+                for failure in result.failed
+            )
+            messagebox.showwarning(
+                "SVGConverter", f"{message}\n\n{details}", parent=self.root
+            )
+        else:
+            messagebox.showinfo("SVGConverter", message, parent=self.root)
+
+    def change_language(self, display_name: str) -> None:
+        self.locale = locale_for_display_name(display_name, self.translations)
+        self._refresh_text()
+
+    def run(self) -> None:
+        """Start the Tkinter event loop."""
+
+        self.root.mainloop()
+
+
+def run_gui() -> None:
+    """Launch the SVGConverter desktop interface."""
+
+    SVGConverterApp().run()

svgconverter-1.2.0/src/svgconverter/i18n.py

@@ -0,0 +1,43 @@
+"""Package-safe localization helpers for the Tkinter interface."""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+
+DEFAULT_LOCALE = "zh_TW"
+
+
+def load_translations() -> dict[str, dict[str, str]]:
+    """Load bundled translations without relying on the current directory."""
+
+    resource = resources.files("svgconverter.resources").joinpath("languages.json")
+    with resource.open("r", encoding="utf-8") as translation_file:
+        translations: dict[str, dict[str, str]] = json.load(translation_file)
+    return translations
+
+
+def locale_for_display_name(
+    display_name: str, translations: dict[str, dict[str, str]]
+) -> str:
+    """Return the locale key represented by a language menu label.
+
+    Unknown labels use Traditional Chinese, the package's default locale.
+    """
+
+    for locale, text in translations.items():
+        if text.get("name") == display_name:
+            return locale
+    return (
+        DEFAULT_LOCALE if DEFAULT_LOCALE in translations else next(iter(translations))
+    )
+
+
+def translation_for(
+    locale: str, translations: dict[str, dict[str, str]]
+) -> dict[str, str]:
+    """Return translations for ``locale`` with a safe fallback."""
+
+    return translations.get(
+        locale, translations.get(DEFAULT_LOCALE, next(iter(translations.values())))
+    )

svgconverter-1.2.0/src/svgconverter/resources/__init__.py

@@ -0,0 +1 @@
+"""Bundled localization resources for SVGConverter."""

svgconverter-1.2.0/src/svgconverter/resources/languages.json

@@ -0,0 +1,17 @@
+{
+  "zh_TW": {
+    "name": "正體中文",
+    "select": "選擇資料夾",
+    "done": "轉換完成：已轉換 {converted} 個檔案；失敗 {failed} 個。"
+  },
+  "en_US": {
+    "name": "English",
+    "select": "Select Folder",
+    "done": "Conversion complete: {converted} converted; {failed} failed."
+  },
+  "ja_JP": {
+    "name": "日本語",
+    "select": "フォルダを選択",
+    "done": "変換完了：{converted} 件変換、{failed} 件失敗。"
+  }
+}

svgconverter-1.2.0/src/svgconverter.egg-info/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: svgconverter
+Version: 1.2.0
+Summary: Embed PNG and JPEG raster images in SVG containers.
+Author: Chien-Hsun Chang
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KageRyo/SVGConverter
+Project-URL: Documentation, https://github.com/KageRyo/SVGConverter#readme
+Project-URL: Issues, https://github.com/KageRyo/SVGConverter/issues
+Project-URL: Changelog, https://github.com/KageRyo/SVGConverter/blob/main/CHANGELOG.md
+Keywords: image,svg,converter,raster,embed
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Dynamic: license-file
+
+# SVGConverter
+
+[正體中文](README_TW.md)
+
+SVGConverter wraps a PNG or JPEG image in an SVG container. It provides a
+small Python API, command-line interface, and desktop GUI.
+
+> **Important:** current `embed` mode Base64-encodes the original raster image
+> into an SVG `<image>` element. It does **not** trace pixels into vector paths,
+> and it does not inherently reduce file size. A future `vectorize` mode is
+> tracked separately.
+
+## Installation
+
+SVGConverter requires Python 3.10 or newer. After v1.2.0 has been published to
+PyPI:
+
+```bash
+python -m pip install --upgrade svgconverter
+```
+
+To run the current development version instead:
+
+```bash
+git clone https://github.com/KageRyo/SVGConverter.git
+cd SVGConverter
+python -m pip install .
+```
+
+## Command line
+
+Convert one image, retaining its dimensions in the generated SVG:
+
+```bash
+svgconverter image.png
+svgconverter photo.jpg --output output.svg
+```
+
+Convert all supported images immediately inside a directory:
+
+```bash
+svgconverter ./images --output-dir ./svg-output
+```
+
+Outputs are never overwritten unless `--overwrite` is supplied. Run
+`svgconverter --help` for all options. Supported inputs are PNG, JPG, and JPEG
+(including upper-case extensions); recursive conversion and image optimization
+are not part of the current release.
+
+## Python API
+
+```python
+from svgconverter import SVGConverter, convert_file
+
+convert_file("image.png", "image.svg")
+
+converter = SVGConverter(overwrite=True)
+result = converter.convert_directory("./images", "./svg-output")
+print(result.success_count, result.failure_count)
+```
+
+`convert_file()` returns the output `pathlib.Path`. Directory conversion returns
+a `BatchResult` containing successful output paths and per-file failures, so a
+bad image does not abort the entire batch.
+
+## GUI
+
+Install the package and run:
+
+```bash
+svgconverter-gui
+```
+
+The legacy development command `python main.py` starts the same GUI. The GUI
+currently selects a directory and offers Traditional Chinese, English, and
+Japanese. It uses the same public conversion API as the CLI.
+
+## Release process
+
+The tag workflow uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+instead of a long-lived API token. Before the first release, configure a
+pending or normal PyPI Trusted Publisher for:
+
+- owner: `KageRyo`
+- repository: `SVGConverter`
+- workflow: `release.yml`
+- environment: `pypi`
+
+After the pull request is merged, create an annotated `v1.2.0` tag whose
+version matches `pyproject.toml`. The workflow builds, checks, publishes to
+PyPI, and then creates a GitHub Release with the distributions attached.
+
+## Contributing and license
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local checks and commit conventions.
+This project is licensed under the [MIT License](LICENSE).

svgconverter-1.2.0/src/svgconverter.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+src/svgconverter/__init__.py
+src/svgconverter/cli.py
+src/svgconverter/converter.py
+src/svgconverter/gui.py
+src/svgconverter/i18n.py
+src/svgconverter.egg-info/PKG-INFO
+src/svgconverter.egg-info/SOURCES.txt
+src/svgconverter.egg-info/dependency_links.txt
+src/svgconverter.egg-info/entry_points.txt
+src/svgconverter.egg-info/requires.txt
+src/svgconverter.egg-info/top_level.txt
+src/svgconverter/resources/__init__.py
+src/svgconverter/resources/languages.json
+tests/test_cli.py
+tests/test_converter.py
+tests/test_i18n.py

svgconverter-1.2.0/src/svgconverter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

svgconverter-1.2.0/src/svgconverter.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+svgconverter = svgconverter.cli:main
+svgconverter-gui = svgconverter.gui:run_gui

svgconverter-1.2.0/src/svgconverter.egg-info/requires.txt

@@ -0,0 +1,7 @@
+Pillow>=10.0
+
+[dev]
+build>=1.2
+pytest>=8.0
+ruff>=0.8
+twine>=6.0

svgconverter-1.2.0/src/svgconverter.egg-info/top_level.txt

@@ -0,0 +1 @@
+svgconverter

svgconverter-1.2.0/tests/test_cli.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from PIL import Image
+
+from svgconverter.cli import main
+
+
+def create_image(path: Path, image_format: str) -> Path:
+    image = Image.new("RGB", (2, 2), color=(25, 50, 75))
+    image.save(path, format=image_format)
+    return path
+
+
+def test_cli_converts_single_file_to_explicit_output(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    source = create_image(tmp_path / "sample.png", "PNG")
+    destination = tmp_path / "output.svg"
+
+    exit_code = main([str(source), "--output", str(destination)])
+
+    assert exit_code == 0
+    assert destination.is_file()
+    assert "Converted:" in capsys.readouterr().out
+
+
+def test_cli_converts_directory_and_reports_a_failure(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    source_directory = tmp_path / "images"
+    source_directory.mkdir()
+    create_image(source_directory / "good.png", "PNG")
+    (source_directory / "bad.jpg").write_bytes(b"not an image")
+    output_directory = tmp_path / "out"
+
+    exit_code = main([str(source_directory), "--output-dir", str(output_directory)])
+
+    captured = capsys.readouterr()
+    assert exit_code == 1
+    assert (output_directory / "good.svg").is_file()
+    assert "Summary: 1 converted, 1 failed" in captured.out
+
+
+def test_cli_uses_nonzero_exit_code_for_invalid_input(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    with pytest.raises(SystemExit) as exit_status:
+        main([str(tmp_path / "missing.png")])
+
+    assert exit_status.value.code == 1
+    assert "does not exist" in capsys.readouterr().err

svgconverter-1.2.0/tests/test_converter.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from PIL import Image
+
+from svgconverter import (
+    ConversionError,
+    InputPathError,
+    OutputExistsError,
+    SVGConverter,
+    UnsupportedImageError,
+    convert_directory,
+    convert_file,
+)
+
+
+def create_image(path: Path, image_format: str, size: tuple[int, int] = (3, 2)) -> Path:
+    image = Image.new("RGB", size, color=(25, 50, 75))
+    image.save(path, format=image_format)
+    return path
+
+
+def test_convert_png_embeds_correct_mime_and_dimensions(tmp_path: Path) -> None:
+    source = create_image(tmp_path / "sample.png", "PNG", (3, 2))
+
+    output = convert_file(source)
+
+    document = output.read_text(encoding="utf-8")
+    assert output == tmp_path / "sample.svg"
+    assert 'width="3" height="2"' in document
+    assert "data:image/png;base64," in document
+
+
+@pytest.mark.parametrize("suffix", [".jpg", ".jpeg", ".JPG"])
+def test_convert_jpeg_uses_jpeg_mime_type(tmp_path: Path, suffix: str) -> None:
+    source = create_image(tmp_path / f"photo{suffix}", "JPEG")
+
+    output = convert_file(source)
+
+    assert "data:image/jpeg;base64," in output.read_text(encoding="utf-8")
+
+
+def test_mime_type_is_detected_from_image_content(tmp_path: Path) -> None:
+    source = create_image(tmp_path / "misnamed.jpg", "PNG")
+
+    output = convert_file(source)
+
+    assert "data:image/png;base64," in output.read_text(encoding="utf-8")
+
+
+def test_explicit_output_creates_parent_directories(tmp_path: Path) -> None:
+    source = create_image(tmp_path / "sample.png", "PNG")
+    destination = tmp_path / "nested" / "result.svg"
+
+    output = convert_file(source, destination)
+
+    assert output == destination
+    assert output.is_file()
+
+
+def test_existing_output_requires_overwrite(tmp_path: Path) -> None:
+    source = create_image(tmp_path / "sample.png", "PNG")
+    destination = tmp_path / "result.svg"
+    destination.write_text("original", encoding="utf-8")
+
+    with pytest.raises(OutputExistsError):
+        convert_file(source, destination)
+
+    convert_file(source, destination, overwrite=True)
+    assert "data:image/png;base64," in destination.read_text(encoding="utf-8")
+
+
+def test_invalid_inputs_raise_useful_errors(tmp_path: Path) -> None:
+    with pytest.raises(InputPathError):
+        convert_file(tmp_path / "missing.png")
+
+    text_file = tmp_path / "not-an-image.gif"
+    text_file.write_text("not an image", encoding="utf-8")
+    with pytest.raises(UnsupportedImageError):
+        convert_file(text_file)
+
+    corrupt_image = tmp_path / "corrupt.png"
+    corrupt_image.write_bytes(b"not a PNG")
+    with pytest.raises(ConversionError, match="Cannot read image"):
+        convert_file(corrupt_image)
+
+
+def test_directory_conversion_reports_successes_and_failures(tmp_path: Path) -> None:
+    source_directory = tmp_path / "images"
+    source_directory.mkdir()
+    create_image(source_directory / "one.png", "PNG")
+    create_image(source_directory / "two.JPEG", "JPEG")
+    (source_directory / "bad.jpg").write_bytes(b"not an image")
+    (source_directory / "ignored.txt").write_text("ignored", encoding="utf-8")
+    output_directory = tmp_path / "converted"
+
+    result = convert_directory(source_directory, output_directory)
+
+    assert result.success_count == 2
+    assert result.failure_count == 1
+    assert {path.name for path in result.converted} == {"one.svg", "two.svg"}
+    assert result.failed[0].input_path.name == "bad.jpg"
+    assert (output_directory / "one.svg").is_file()
+
+
+def test_converter_class_uses_its_configuration(tmp_path: Path) -> None:
+    source = create_image(tmp_path / "sample.png", "PNG")
+    destination = tmp_path / "result.svg"
+    destination.write_text("old", encoding="utf-8")
+
+    output = SVGConverter(overwrite=True).convert_file(source, destination)
+
+    assert output == destination
+    assert "data:image/png;base64," in destination.read_text(encoding="utf-8")
+
+
+def test_only_embed_mode_is_available(tmp_path: Path) -> None:
+    source = create_image(tmp_path / "sample.png", "PNG")
+
+    with pytest.raises(ValueError, match="Only mode='embed'"):
+        convert_file(source, mode="vectorize")  # type: ignore[arg-type]

svgconverter-1.2.0/tests/test_i18n.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from svgconverter.i18n import (
+    DEFAULT_LOCALE,
+    load_translations,
+    locale_for_display_name,
+    translation_for,
+)
+
+
+def test_bundled_translations_have_all_supported_locales() -> None:
+    translations = load_translations()
+
+    assert set(translations) == {"zh_TW", "en_US", "ja_JP"}
+    assert locale_for_display_name("English", translations) == "en_US"
+    assert locale_for_display_name("日本語", translations) == "ja_JP"
+
+
+def test_unknown_locale_and_display_name_fall_back_to_default() -> None:
+    translations = load_translations()
+
+    assert locale_for_display_name("unknown", translations) == DEFAULT_LOCALE
+    assert translation_for("unknown", translations) == translations[DEFAULT_LOCALE]