transimage 1.0.0__tar.gz

transimage-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Daethyra Carino
+
+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.

transimage-1.0.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.1
+Name: transimage
+Version: 1.0.0
+Summary: Converts images from one format to another using Pillow. Supports JPG, PNG, BMP, and WebP.
+Author-Email: Daethyra <109057945+Daethyra@users.noreply.github.com>
+License: MIT
+Requires-Python: <4.0,>=3.13
+Requires-Dist: pillow<12.0.0,>=11.0.0
+Description-Content-Type: text/markdown
+
+# transimage - image format conversion
+
+## Description
+`transimage` is a Python package and CLI tool for converting images between different formats using the Pillow library. It supports conversions between JPG, PNG, BMP, and WebP formats.
+
+>> send your PR based god🙏🏻
+
+## Features
+- Convert images between JPG, PNG, BMP, and WebP formats
+- Batch conversion of multiple images
+- Simple command-line interface
+- Skips conversion if the input and output formats are the same
+
+## Usage
+
+#### Dependencies
+- Pillow >= 11.0.0
+
+#### Setup
+To set up the development environment:
+
+1. Clone the repository
+2. Install PDM if you haven't already: `pip install pdm`
+3. Install dependencies: `pdm install`
+4. Convert images: `python src/____main____.py ./input_image.jpg ./output_image.png png`
+
+### Using `____main____.py` directly as a CLI tool (Recommended)
+
+Once you've cloned the repository or downloaded the source code, you can use the `__main__.py` file directly by using the following: `python __main__.py <input_path> <output_path> <output_format>`
+
+**Input target may be a single file or directory.**
+
+- `<input_path>`: Path to the input image file or directory
+- `<output_path>`: Path to save the converted image(s)
+- `<output_format>`: Desired output format (jpg, png, bmp, or webp)
+
+### Using the transimage package in your own projects
+
+You may test the transimage package is properly installed by running it directly from the command line: `python -m transimage <input_path> <output_path> <output_format>`
+
+1. First, ensure you're working within a virtual environment with PDM:
+
+   `pdm install`
+
+2. In your Python script, import the necessary functions:
+
+```python
+from transimage import collect_images, ImageConverter
+```
+
+To convert a single image, use the ImageConverter class directly:
+
+```python
+converter = ImageConverter('path/to/input/image.jpg', 'path/to/output/image.png', 'png')
+converter.convert()
+```
+
+For batch conversion, you can pass in directories as arguments instead of individual image paths. Then, use the collect_images function and loop through the results:
+
+```python
+from transimage import collect_images, ImageConverter
+
+input_directory = 'path/to/input/directory'
+output_directory = 'path/to/output/directory'
+output_format = 'png'
+
+image_files = collect_images(input_directory)
+
+for input_path in image_files:
+    filename = os.path.basename(input_path)
+    name, _ = os.path.splitext(filename)
+    output_path = os.path.join(output_directory, f"{name}.{output_format}")
+    convert_image(input_path, output_path, output_format)
+```
+
+## License
+This project is licensed under the MIT License. See the LICENSE file for details.
+
+## Contributing 
+Like I said, send your PR. Based. God.
+
+### Set up
+1. Install the developer dependencies: `pdm install -G dev`
+2. Add your changes
+3. Test your code(`pdm run pytest tests/`)
+4. Iterate, repeat until finished.
+5. Run the `all` script to lint and format the code: `pdm run all`
+
+## Version
+1.0.0

transimage-1.0.0/README.md

@@ -0,0 +1,90 @@
+# transimage - image format conversion
+
+## Description
+`transimage` is a Python package and CLI tool for converting images between different formats using the Pillow library. It supports conversions between JPG, PNG, BMP, and WebP formats.
+
+>> send your PR based god🙏🏻
+
+## Features
+- Convert images between JPG, PNG, BMP, and WebP formats
+- Batch conversion of multiple images
+- Simple command-line interface
+- Skips conversion if the input and output formats are the same
+
+## Usage
+
+#### Dependencies
+- Pillow >= 11.0.0
+
+#### Setup
+To set up the development environment:
+
+1. Clone the repository
+2. Install PDM if you haven't already: `pip install pdm`
+3. Install dependencies: `pdm install`
+4. Convert images: `python src/____main____.py ./input_image.jpg ./output_image.png png`
+
+### Using `____main____.py` directly as a CLI tool (Recommended)
+
+Once you've cloned the repository or downloaded the source code, you can use the `__main__.py` file directly by using the following: `python __main__.py <input_path> <output_path> <output_format>`
+
+**Input target may be a single file or directory.**
+
+- `<input_path>`: Path to the input image file or directory
+- `<output_path>`: Path to save the converted image(s)
+- `<output_format>`: Desired output format (jpg, png, bmp, or webp)
+
+### Using the transimage package in your own projects
+
+You may test the transimage package is properly installed by running it directly from the command line: `python -m transimage <input_path> <output_path> <output_format>`
+
+1. First, ensure you're working within a virtual environment with PDM:
+
+   `pdm install`
+
+2. In your Python script, import the necessary functions:
+
+```python
+from transimage import collect_images, ImageConverter
+```
+
+To convert a single image, use the ImageConverter class directly:
+
+```python
+converter = ImageConverter('path/to/input/image.jpg', 'path/to/output/image.png', 'png')
+converter.convert()
+```
+
+For batch conversion, you can pass in directories as arguments instead of individual image paths. Then, use the collect_images function and loop through the results:
+
+```python
+from transimage import collect_images, ImageConverter
+
+input_directory = 'path/to/input/directory'
+output_directory = 'path/to/output/directory'
+output_format = 'png'
+
+image_files = collect_images(input_directory)
+
+for input_path in image_files:
+    filename = os.path.basename(input_path)
+    name, _ = os.path.splitext(filename)
+    output_path = os.path.join(output_directory, f"{name}.{output_format}")
+    convert_image(input_path, output_path, output_format)
+```
+
+## License
+This project is licensed under the MIT License. See the LICENSE file for details.
+
+## Contributing 
+Like I said, send your PR. Based. God.
+
+### Set up
+1. Install the developer dependencies: `pdm install -G dev`
+2. Add your changes
+3. Test your code(`pdm run pytest tests/`)
+4. Iterate, repeat until finished.
+5. Run the `all` script to lint and format the code: `pdm run all`
+
+## Version
+1.0.0

transimage-1.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "transimage"
+version = "1.0.0"
+description = "Converts images from one format to another using Pillow. Supports JPG, PNG, BMP, and WebP."
+authors = [
+    { name = "Daethyra", email = "109057945+Daethyra@users.noreply.github.com" },
+]
+dependencies = [
+    "pillow<12.0.0,>=11.0.0",
+]
+requires-python = "<4.0,>=3.13"
+readme = "README.md"
+
+[project.license]
+text = "MIT"
+
+[tool.pdm]
+distribution = true
+package-dir = "src"
+
+[tool.pdm.build]
+includes = []
+
+[tool.pdm.scripts]
+format = "black src/transimage tests"
+lint = "flake8 src/transimage tests"
+test = "pytest tests"
+
+[tool.pdm.scripts.all]
+composite = [
+    "format",
+    "lint",
+    "test",
+]
+
+[build-system]
+requires = [
+    "pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[dependency-groups]
+dev = [
+    "black>=24.10.0",
+    "flake8>=7.1.2",
+    "pdm>=2.25.4",
+    "pytest>=8.4.1",
+]

transimage-1.0.0/src/transimage/__init__.py

@@ -0,0 +1,2 @@
+from .image_collector import collect_images
+from .image_converter import ImageConverter, convert_image

transimage-1.0.0/src/transimage/__main__.py

@@ -0,0 +1,81 @@
+"""
+Main module for image conversion. Handles both single image and directory processing.
+"""
+
+import argparse
+import os
+from typing import List
+
+from transimage.image_collector import collect_images
+from transimage.image_converter import convert_image
+
+
+def process_images(input_path: str, output_path: str, output_format: str) -> List[str]:
+    """
+    Process images based on whether the input path is a single image or a directory.
+
+    Args:
+        input_path (str): Path to the input image file or directory.
+        output_path (str): Path to save the converted image file or directory.
+        output_format (str): Desired output format (e.g., 'jpg', 'png', 'bmp', 'webp').
+
+    Returns:
+        List[str]: A list of paths to the converted images.
+
+    Raises:
+        ValueError: If the input path does not exist.
+    """
+    if not os.path.exists(input_path):
+        raise ValueError(f"Input path does not exist: {input_path}")
+
+    converted_images = []
+
+    if os.path.isfile(input_path):
+        # Single image processing
+        output_filename = (
+            f"{os.path.splitext(os.path.basename(input_path))[0]}.{output_format}"
+        )
+        output_file_path = os.path.join(output_path, output_filename)
+        convert_image(input_path, output_file_path, output_format)
+        if os.path.exists(output_file_path):
+            converted_images.append(output_file_path)
+    elif os.path.isdir(input_path):
+        # Directory processing
+        os.makedirs(output_path, exist_ok=True)
+        image_files = collect_images(input_path)
+
+        for file_path in image_files:
+            output_filename = (
+                f"{os.path.splitext(os.path.basename(file_path))[0]}.{output_format}"
+            )
+            output_file_path = os.path.join(output_path, output_filename)
+            try:
+                convert_image(file_path, output_file_path, output_format)
+                if os.path.exists(output_file_path):
+                    converted_images.append(output_file_path)
+            except ValueError as e:
+                print(f"Error converting {file_path}: {str(e)}")
+
+    return converted_images
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Convert images to a specified format."
+    )
+    parser.add_argument("input_path", help="Path to input image or directory")
+    parser.add_argument(
+        "output_path", help="Path to output directory. Do not include file name."
+    )
+    parser.add_argument(
+        "output_format", help="Desired output format (jpg, png, bmp, webp)"
+    )
+    args = parser.parse_args()
+
+    try:
+        converted_files = process_images(
+            args.input_path, args.output_path, args.output_format
+        )
+        print(f"Successfully converted {len(converted_files)} images.")
+    except ValueError as e:
+        print(f"Error: {str(e)}")

transimage-1.0.0/src/transimage/image_collector.py

@@ -0,0 +1,40 @@
+"""
+This module provides functionality to collect images from a directory.
+"""
+
+import os
+from typing import List
+
+from .image_converter import ImageConverter
+
+
+def collect_images(input_dir: str) -> List[str]:
+    """
+    Collects all supported image files from the input directory.
+
+    Args:
+        input_dir (str): Path to the input directory containing images.
+
+    Returns:
+        List[str]: A list of paths to the supported image files.
+
+    Raises:
+        ValueError: If the input directory does not exist.
+    """
+    if not os.path.isdir(input_dir):
+        raise ValueError(f"Input directory does not exist: {input_dir}")
+
+    supported_extensions = set(
+        ImageConverter.SUPPORTED_CONVERSIONS.keys()
+    )  # {'.jpg', '.jpeg', '.png', '.bmp', '.webp'}
+    image_files = []
+
+    for filename in os.listdir(input_dir):
+        file_path = os.path.join(input_dir, filename)
+        if (
+            os.path.isfile(file_path)
+            and os.path.splitext(filename)[1].lower() in supported_extensions
+        ):
+            image_files.append(file_path)
+
+    return image_files

transimage-1.0.0/src/transimage/image_converter.py

@@ -0,0 +1,130 @@
+"""
+This module provides a class for converting images to different formats using Pillow. It also has a function to simplify implementing the conversion logic.
+"""
+
+import os
+
+from PIL import Image
+
+
+class ImageConverter:
+    SUPPORTED_CONVERSIONS = {
+        ".jpg": {".jpg", ".png", ".bmp", ".webp"},
+        ".png": {".jpg", ".png", ".bmp", ".webp"},
+        ".bmp": {".jpg", ".png", ".bmp", ".webp"},
+        ".webp": {".jpg", ".png", ".bmp", ".webp"},
+    }
+
+    def __init__(self, input_path: str, output_path: str, output_format: str):
+        """
+        Initializes a new instance of the ImageConverter class.
+
+        Args:
+            input_path (str): Path to the input image file.
+            output_path (str): Path to save the converted image file.
+            output_format (str): Desired output format (e.g., 'png', 'jpg', 'bmp', 'webp').
+        """
+        self.input_path = input_path
+        self.output_path = output_path
+        self.output_format = output_format.lower()
+
+    def convert(self) -> None:
+        """
+        Converts an image to the desired format.
+
+        Raises:
+            ValueError: If the input file format is not supported or the conversion is not possible.
+        """
+        input_ext = os.path.splitext(self.input_path)[1].lower()
+        output_ext = os.path.splitext(self.output_path)[1].lower()
+
+        if input_ext not in self.SUPPORTED_CONVERSIONS:
+            raise ValueError(
+                f"Unsupported input file format: {input_ext}. {self.supported_conversions()}"
+            )
+
+        if output_ext not in self.SUPPORTED_CONVERSIONS[input_ext]:
+            raise ValueError(
+                f"Unsupported conversion: {input_ext} to {output_ext}. {self.supported_conversions()}"
+            )
+
+        if input_ext == output_ext:
+            # If the input and output formats are the same, move the file instead of re-saving it
+            # self._move_or_error()
+            print(
+                f"Skipping conversion for {self.input_path} (already in {self.output_format} format)"
+            )
+            return
+        else:
+            # Handle JPG conversion separately
+            if self.output_format.lower() == "jpg":
+                self._convert_to_jpg(input_ext, output_ext)
+            else:
+                self._convert_image(input_ext, output_ext)
+
+    def _convert_to_jpg(self, input_ext: str, output_ext: str) -> None:
+        img = Image.open(self.input_path)
+
+        # Ensure the output format is actually JPG
+        if output_ext.lower() != "jpg":
+            output_ext = "jpg"
+
+        # Save transparency metadata for palette images w/ transparency
+        if img.mode == "P" and img.info.get("transparency"):
+            img = img.convert("RGBA")
+
+        # Convert to RGB
+        rgb_img = img.convert("RGB")
+
+        # Save as JPG with quality 95 (adjust as needed)
+        rgb_img.save(self.output_path, "JPEG", quality=95)
+
+    def _convert_image(self, input_ext: str, output_ext: str) -> None:
+        """
+        Converts the input image to the specified output format using Pillow.
+        """
+        img = Image.open(self.input_path)
+        img.save(self.output_path)
+
+    def _move_or_error(self) -> None:
+        """
+        If the input and output paths are the same, move the file instead of re-saving it.
+        """
+        if self.input_path != self.output_path:
+            os.replace(self.input_path, self.output_path)
+        else:
+            raise ValueError(
+                f"Input and output paths are the same: {self.input_path}. Please provide a different output path."
+            )
+
+    @staticmethod
+    def supported_conversions() -> str:
+        """
+        Returns a string with the supported file formats and conversions.
+
+        Returns:
+            str: A string with the supported file formats and conversions.
+        """
+        return (
+            "Supported file formats and conversions:\n"
+            "JPEG: can be converted to JPEG, PNG, BMP, WebP\n"
+            "PNG: can be converted to JPEG, PNG, BMP, WebP\n"
+            "BMP: can be converted to JPEG, PNG, BMP, WebP\n"
+            "WebP: can be converted to JPEG, PNG, BMP, WebP"
+        )
+
+
+def convert_image(input_path: str, output_path: str, output_format: str) -> None:
+    """
+    Converts an image to the desired format.
+
+    Args:
+        input_path (str): Path to the input image file.
+        output_path (str): Path to save the converted image file.
+        output_format (str): Desired output format (e.g., 'png', 'jpg', 'bmp', 'webp').
+
+    Raises:
+        ValueError: If the input file format is not supported or the conversion is not possible.
+    """
+    converter = ImageConverter(input_path, output_path, output_format)
+    converter.convert()

transimage-1.0.0/tests/test_image_collector.py

@@ -0,0 +1,63 @@
+import unittest
+import sys
+import os
+import tempfile
+import shutil
+
+sys.path.insert(
+    0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "src"))
+)
+
+from transimage.image_collector import collect_images
+from transimage.image_converter import ImageConverter
+
+
+class TestImageCollector(unittest.TestCase):
+
+    def setUp(self):
+        # Create a temporary directory
+        self.test_dir = tempfile.mkdtemp()
+
+        # Create some test files
+        self.valid_images = ["test1.jpg", "test2.png", "test3.bmp", "test4.webp"]
+        self.invalid_files = ["test5.txt", "test6.pdf", "test7"]
+
+        for filename in self.valid_images + self.invalid_files:
+            open(os.path.join(self.test_dir, filename), "a").close()
+
+    def tearDown(self):
+        # Remove the directory after the test
+        shutil.rmtree(self.test_dir)
+
+    def test_collect_images(self):
+        # Test if the function collects only valid image files
+        collected_images = collect_images(self.test_dir)
+
+        self.assertEqual(len(collected_images), len(self.valid_images))
+
+        for image in collected_images:
+            self.assertTrue(os.path.basename(image) in self.valid_images)
+
+    def test_non_existent_directory(self):
+        # Test if the function raises a ValueError for a non-existent directory
+        with self.assertRaises(ValueError):
+            collect_images("/path/to/non/existent/directory")
+
+    def test_empty_directory(self):
+        # Test if the function returns an empty list for an empty directory
+        empty_dir = tempfile.mkdtemp()
+        self.assertEqual(collect_images(empty_dir), [])
+        shutil.rmtree(empty_dir)
+
+    def test_supported_extensions(self):
+        # Test if the function only collects files with supported extensions
+        collected_images = collect_images(self.test_dir)
+        supported_extensions = set(ImageConverter.SUPPORTED_CONVERSIONS.keys())
+
+        for image in collected_images:
+            _, ext = os.path.splitext(image)
+            self.assertIn(ext.lower(), supported_extensions)
+
+
+if __name__ == "__main__":
+    unittest.main()

transimage-1.0.0/tests/test_image_converter.py

@@ -0,0 +1,80 @@
+import sys
+import os
+
+sys.path.insert(
+    0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "src"))
+)
+
+import unittest
+import tempfile
+import shutil
+from PIL import Image
+from transimage.image_converter import ImageConverter, convert_image
+
+
+class TestImageConverter(unittest.TestCase):
+
+    def setUp(self):
+        self.test_dir = tempfile.mkdtemp()
+        self.input_jpg = os.path.join(self.test_dir, "test.jpg")
+        self.output_png = os.path.join(self.test_dir, "test.png")
+        self.output_jpg = os.path.join(self.test_dir, "test_output.jpg")
+
+        # Create a test JPEG image
+        with Image.new("RGB", (100, 100), color="red") as img:
+            img.save(self.input_jpg)
+
+    def tearDown(self):
+        shutil.rmtree(self.test_dir)
+
+    def test_convert_jpg_to_png(self):
+        converter = ImageConverter(self.input_jpg, self.output_png, "png")
+        converter.convert()
+        self.assertTrue(os.path.exists(self.output_png))
+        with Image.open(self.output_png) as img:
+            self.assertEqual(img.format, "PNG")
+
+    def test_convert_jpg_to_jpg(self):
+        converter = ImageConverter(self.input_jpg, self.output_jpg, "jpg")
+        converter.convert()
+        self.assertFalse(
+            os.path.exists(self.output_jpg)
+        )  # Should not create a new file
+
+    def test_unsupported_input_format(self):
+        invalid_input = os.path.join(self.test_dir, "test.txt")
+        with open(invalid_input, "w") as f:
+            f.write("This is not an image file")
+        with self.assertRaises(ValueError):
+            converter = ImageConverter(invalid_input, self.output_png, "png")
+            converter.convert()
+
+    def test_unsupported_conversion(self):
+        invalid_output = os.path.join(self.test_dir, "test.gif")
+        with self.assertRaises(ValueError):
+            converter = ImageConverter(self.input_jpg, invalid_output, "gif")
+            converter.convert()
+
+    def test_same_input_output_format(self):
+        output_jpg = os.path.join(self.test_dir, "test_same.jpg")
+        converter = ImageConverter(self.input_jpg, output_jpg, "jpg")
+        converter.convert()
+        self.assertFalse(os.path.exists(output_jpg))  # Should not create a new file
+
+    def test_convert_image_function(self):
+        convert_image(self.input_jpg, self.output_png, "png")
+        self.assertTrue(os.path.exists(self.output_png))
+        with Image.open(self.output_png) as img:
+            self.assertEqual(img.format, "PNG")
+
+    def test_supported_conversions_string(self):
+        supported_str = ImageConverter.supported_conversions()
+        self.assertIsInstance(supported_str, str)
+        self.assertIn("JPEG", supported_str)
+        self.assertIn("PNG", supported_str)
+        self.assertIn("BMP", supported_str)
+        self.assertIn("WebP", supported_str)
+
+
+if __name__ == "__main__":
+    unittest.main()