py-bulk-image-compressor 1.0.0__py3-none-any.whl

components/imageCompressor.py

@@ -0,0 +1,73 @@
+#!/usr/bin/python
+import sys
+from PIL import Image, ImageFile
+from pillow_heif import register_heif_opener
+
+# Mitigate issues with truncated images
+ImageFile.LOAD_TRUNCATED_IMAGES = True
+
+# Add HEIC/HEIF
+register_heif_opener()
+
+avif_supported = True
+try:
+    import avif  # noqa
+except ImportError:
+    avif_supported = False
+
+
+def compress_resize_image(**kwargs) -> None:
+    """
+    Compress/resize. Remove metadata if remove_meta=True.
+    If format == avif but 'pillow-avif-plugin' is not installed, skip & raise.
+    """
+    remove_meta = kwargs.get('remove_meta', False)
+    set_format = kwargs['set_format'].lower()
+
+    # If user wants AVIF but plugin is not installed, raise an exception
+    if set_format == 'avif' and not avif_supported:
+        raise ValueError("AVIF plugin (pillow-avif-plugin) not installed. Cannot save as AVIF.")
+
+    try:
+        with Image.open(kwargs['image_location']) as im:
+            # If removing meta, skip exif
+            if not remove_meta:
+                exif_data = im.info.get('exif')
+            else:
+                exif_data = None
+
+            # Convert mode
+            if im.mode in ("RGBA", "LA") or (im.mode == "P" and "transparency" in im.info):
+                im = im.convert("RGBA")
+            else:
+                im = im.convert("RGB")
+
+            # Calculate new dimensions
+            if kwargs['max_width'] is None or im.width <= kwargs['max_width']:
+                w, h = im.width, im.height
+            else:
+                ratio = im.width / im.height
+                w = kwargs['max_width']
+                h = round(w / ratio)
+
+            im_resized = im.resize((w, h), resample=Image.LANCZOS)
+
+            # If not removing meta and set_format supports EXIF
+            if exif_data and set_format in ['jpeg', 'jpg', 'tiff']:
+                im_resized.save(
+                    kwargs['image_destination'],
+                    set_format,
+                    optimize=True,
+                    quality=kwargs['quality'],
+                    exif=exif_data
+                )
+            else:
+                im_resized.save(
+                    kwargs['image_destination'],
+                    set_format,
+                    optimize=True,
+                    quality=kwargs['quality']
+                )
+
+    except Exception as err:
+        raise err

components/localColors.py

@@ -0,0 +1,13 @@
+#!/usr/bin/python
+
+# Simple color utility for terminal output
+class select:
+    HEADER = '\033[95m'
+    OKBLUE = '\033[94m'
+    OKCYAN = '\033[96m'
+    OKGREEN = '\033[92m'
+    WARNING = '\033[93m'
+    FAIL = '\033[91m'
+    ENDC = '\033[0m'
+    BOLD = '\033[1m'
+    UNDERLINE = '\033[4m'

components/mainClasses.py

@@ -0,0 +1,14 @@
+#!/usr/bin/python
+
+class set_default_values:
+    """
+    Assigns a default value if the provided argument is None.
+    Usage:
+        set_default_values(default, provided)
+    """
+    def __init__(self, *args):
+        # args[0] -> default, args[1] -> provided
+        if args[1] is None:
+            self.set = args[0]
+        else:
+            self.set = args[1]

components/mainFunctions.py

@@ -0,0 +1,136 @@
+#!/usr/bin/python
+import os
+import shutil
+from pathlib import Path
+from datetime import datetime
+
+from components import imageCompressor as iC, setConfigurations
+
+config = setConfigurations.get_resources()
+
+LOG_FILE = "logs.txt"
+
+
+def build_file_list(your_folder) -> dir:
+    """
+    Builds a generator of files from 'your_folder' that match any of the
+    supported formats in 'configurations.ini'.
+    """
+    for root, dirs, files in os.walk(your_folder):
+        for file_bfl in files:
+            if os.path.splitext(file_bfl)[1].lower() in config['supported_formats'].values():
+                yield os.path.join(root, file_bfl)
+
+
+def create_folder(your_path) -> None:
+    """Creates a folder if it does not exist."""
+    if not os.path.exists(your_path):
+        os.makedirs(your_path)
+
+
+def folder_size(your_folder) -> str:
+    """Returns a string representing total folder size in KB."""
+    if not os.path.exists(your_folder):
+        return "Total folder size: 0 KB"
+
+    total_size_kb = sum(
+        file.stat().st_size for file in Path(your_folder).rglob('*') if file.is_file()
+    ) / 1024
+    return f"Total folder size: {round(total_size_kb, 2)} KB"
+
+
+def get_percentage_difference(num_a, num_b) -> float:
+    """
+    Positive if compressed is smaller, negative if compressed is larger.
+    """
+    if num_b == 0:
+        return 0.0
+    if num_b >= num_a:
+        return -round((abs(num_b - num_a) / num_b) * 100, 2)
+    else:
+        return round((abs(num_a - num_b) / num_b) * 100, 2)
+
+
+def start_command(**kwargs) -> None:
+    """
+    1) Creates destination folder.
+    2) Compresses/resizes.
+    3) Copies timestamps (unless remove_meta == True).
+    """
+    src_image = kwargs['source_image']
+    before, sep, after = src_image.partition(kwargs['img_path'])
+
+    try:
+        create_folder(kwargs['img_destination'] + os.path.dirname(after))
+    except Exception: # noqa
+        pass
+
+    new_file_path = (
+        kwargs['img_destination']
+        + after.replace(os.path.splitext(after)[1], '')
+        + f".{kwargs['set_format']}"
+    )
+
+    # Compress
+    iC.compress_resize_image(
+        image_location=kwargs['source_image'],
+        image_destination=new_file_path,
+        set_format=kwargs['set_format'],
+        max_width=kwargs['max_width'],
+        quality=kwargs['quality'],
+        remove_meta=kwargs.get('remove_meta', False)
+    )
+
+    # If removing metadata, skip copying timestamps
+    if not kwargs.get('remove_meta', False):
+        if os.path.exists(new_file_path):
+            try:
+                shutil.copystat(src_image, new_file_path)
+            except Exception as e:
+                log_message(
+                    config,
+                    "error",
+                    f"[{datetime.now()}] ERROR copying timestamps {new_file_path}: {e}\n"
+                )
+
+
+def log_message(config, log_type: str, message: str): # noqa
+    """
+    Logs a message if the corresponding log_<type> is True in config.
+    The log types are "success", "warning", "error".
+    """
+    # read booleans from config
+    max_rows = int(config['logs']['max_rows'])
+
+    # For safety, using getboolean
+    log_success = config['logs'].getboolean('log_success')
+    log_errors = config['logs'].getboolean('log_errors')
+    log_warnings = config['logs'].getboolean('log_warnings')
+
+    if log_type == "success" and not log_success:
+        return
+    if log_type == "warning" and not log_warnings:
+        return
+    if log_type == "error" and not log_errors:
+        return
+
+    log_path = os.path.join(os.getcwd(), LOG_FILE)
+
+    # Append log
+    try:
+        with open(log_path, 'a', encoding='utf-8') as file:
+            file.write(message)
+    except Exception as e:
+        print(f"Cannot write to log file: {e}")
+        return
+
+    # Now enforce max_rows limit
+    try:
+        with open(log_path, 'r+', encoding='utf-8') as file:
+            lines = file.readlines()
+        if len(lines) > max_rows:
+            new_lines = lines[-max_rows:]
+            with open(log_path, 'w', encoding='utf-8') as file:
+                file.writelines(new_lines)
+    except Exception as e:
+        print(f"Error trimming log file: {e}")

components/setConfigurations.py

@@ -0,0 +1,9 @@
+import configparser
+
+def get_resources() -> configparser:
+    """
+    Loads and returns the settings from 'resources/configurations.ini'.
+    """
+    my_config = configparser.ConfigParser()
+    my_config.read('resources/configurations.ini')
+    return my_config

py_bulk_image_compressor-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 George Khananaev
+
+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.

py_bulk_image_compressor-1.0.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.2
+Name: py-bulk--image-compressor
+Version: 1.0.0
+Summary: A Python bulk image compressor and resizer
+Home-page: https://github.com/georgekhananaev/py-image-compressor
+Author: George Khananaev
+Author-email: george.khananaev@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=11.1.0
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: pillow-heif>=0.21.0
+Requires-Dist: pillow-avif-plugin>=1.4.6
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: summary
+
+# Python Bulk Image Compressor + Resizer
+
+This Python script allows you to compress and resize images in bulk. It can optionally preserve EXIF metadata and file timestamps or remove them entirely if the `-rm y` flag is used.
+
+### Features
+- **Supports Multiple Formats:**
+  - **Full Metadata Preservation:** JPEG, JPG, TIFF.
+  - **Partial/No Metadata:** PNG, WEBP, BMP, etc., do not reliably store EXIF data.
+- **Metadata Removal:** If `-rm y` is specified, all metadata (e.g., GPS, date/time, camera info) is stripped, and timestamps are reset instead of being copied from the source.
+- **Logging:** Logs each compression operation in a `logs.txt` file. You can configure the maximum row limit for the log file in the `[logs]` section of `configurations.ini`. When the log file exceeds this limit, older rows are removed.
+
+![Animation](https://github.com/georgekhananaev/py-image-compressor/blob/main/screenshots/animation.gif?raw=true)
+
+---
+
+### Installation
+![Python Version](https://img.shields.io/badge/Python_3.11-Supported-green.svg)
+
+1. Install [Python 3+](https://www.python.org/downloads/).
+2. Install [Git](https://git-scm.com/).
+3. Clone this repository:
+   ```bash
+   git clone https://github.com/georgekhananaev/py-image-compressor.git
+   ```
+4. Install dependencies:
+   ```bash
+   cd py-image-compressor
+   pip install -r requirements.txt
+   ```
+
+---
+
+### Usage
+
+| Command | Required | Default Value   | Description           | Details                                                                                                                                   | Example                      |
+|---------|----------|-----------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------|------------------------------|
+| **-l**  | Yes      | N/A             | Input location        | Path to the folder containing original images.                                                                                            | `-l "C:/Original Images/"` |
+| **-d**  | No       | `/data/output/` | Output location       | Path where compressed images will be saved.                                                                                              | `-d "C:/Compressed Images/"` |
+| **-w**  | No       | `1920`          | Max width             | Resize images to this maximum width while maintaining aspect ratio.                                                                       | `-w 1920`                   |
+| **-q**  | No       | `80`            | Quality               | Image quality (percentage). Lower values save more space.                                                                                 | `-q 80`                     |
+| **-f**  | No       | `jpeg`          | Output format         | Supported formats: PNG, JPEG, JPG, PPM, GIF, TIFF, BMP, WEBP, HEIC, HEIF, AVIF. Refer to [Pillow Documentation](https://pillow.readthedocs.io/). | `-f jpeg`                   |
+| **-r**  | No       | `no`            | Remove larger files   | If set to `y`, deletes compressed images if they are larger than the original.                                                            | `-r y`                      |
+| **-rm** | No       | `no`            | Remove metadata       | If set to `y`, removes all metadata (EXIF, GPS, etc.) and resets timestamps.                                                              | `-rm y`                     |
+| **-h**  | No       | -               | Help                  | Displays help information about commands.                                                                                                | `-h` or `--help`            |
+
+> **Note:** Use quotation marks for paths with spaces (e.g., `"C:/My Folder/"`).
+
+---
+
+### Logging
+
+- A `logs.txt` file is created/appended in the script's directory.
+- Maximum rows are configured in `[logs] max_rows`. Older entries are pruned when the limit is exceeded.
+- Log levels:
+  - `log_success`
+  - `log_errors`
+  - `log_warnings`
+- Enable or disable logging levels in `configurations.ini`.
+
+---
+
+### Examples
+
+```bash
+python main.py -l "D:/Images/Originals/" -d "D:/Images/Compressed/" -f webp -w 500 -q 80 -rm y
+```
+
+Example output:
+
+![Terminal Screenshot](https://github.com/georgekhananaev/py-image-compressor/blob/main/screenshots/screenshot.jpg?raw=true)
+
+---
+
+## Updates
+
+#### **26/01/2025**
+1. EXIF metadata is preserved if supported by the output format (e.g., JPEG).
+2. Added support for `.avif` format (requires `pillow-avif-plugin`).
+3. Minor speed optimizations for faster compression.
+4. Updated `requirements.txt` with the latest package versions.
+5. Added logs, which is exported to logs.txt
+6. Added tests, use 
+    ```shell
+      pytest --maxfail=1 --disable-warnings -v
+    ```
+
+#### **02/12/2023**
+1. Automatic detection and handling of RGB/RGBA channels.
+2. Thanks to "ZenithVal" for the suggestion.
+
+#### **06/04/2023**
+1. Updated `README.md`.
+2. Updated `requirements.txt` with the latest package versions.
+
+#### **12/12/2022**
+1. Introduced a `resources` folder containing `configurations.ini` for storing program settings.
+2. Set up future GUI plans using `customtkinter`.
+3. Removed PySimpleGUI from dependencies.
+
+#### **06/12/2022**
+1. Default values added for `-d`, `-f`, and `-q` options. You can run:
+   ```bash
+   python main.py -l "C:/Your Folder/"
+   ```
+   Defaults: JPEG format, 80% quality, 1920px max width, `/data/output/` as the destination folder.
+2. Simplified the code using `*args` and `**kwargs`.
+
+#### **05/12/2022**
+1. Added support for `.heif` and `.heic` formats (e.g., iPhone photos).
+2. Updated `requirements.txt` to include `pillow-heif`.
+
+#### **04/12/2022**
+1. Improved the output to display the actual size saved for each image, with full multithreading conversion support.
+    > ![terminal](https://github.com/georgekhananaev/py-image-compressor/blob/main/screenshots/multicore.gif?raw=true)
+2. Enhanced terminal output for better visualization of size savings.
+3. Began GUI development for Windows and Ubuntu.
+4. Added `-r y` to skip retaining larger compressed images.
+
+---
+
+### Future Plans
+- A GUI interface will be added if this project receives 50+ stars on GitHub.
+- Integration with cloud storage services like AWS S3 and Google Drive for automatic uploads.
+- Support for more advanced image editing options, such as cropping and watermarking.
+
+> **Personal Note:** I use this script for compressing images for React-based websites and converting entire folders to WebP format with a single command.
+
+---
+
+## Contributing 🤝
+
+We’d love your help to make py-image-compressor even better! To contribute:
+
+1. Fork the repository.
+2. Create a new branch for your feature: `git checkout -b feature-name`.
+3. Commit your changes: `git commit -m "Add awesome feature"`.
+4. Push your branch: `git push origin feature-name`.
+5. Open a pull request and tell us about your changes.
+
+---
+
+## License
+
+py-image-compressor is licensed under the MIT License. See the `LICENSE` file for details.
+
+---
+
+## Need Help?
+
+If you run into any issues or have questions, feel free to [open an issue](https://github.com/georgekhananaev/py-image-compressor/issues).
+
+
+## Support Me
+
+If you find my work helpful, consider supporting me by buying me a coffee at [Buy Me A Coffee](https://www.buymeacoffee.com/georgekhananaev).
+Your support helps me continue to create and maintain useful projects.
+
+[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/georgekhananaev)
+
+Thank you!

py_bulk_image_compressor-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+components/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+components/imageCompressor.py,sha256=qMWARZrupo_Tj7EkekGxqrqW6TtxDTSVYoMaIdZvbaQ,2333
+components/localColors.py,sha256=RVS7gvSPPR0DJuFfcgeNSEg-9nLUhOv_tfyAHaOu3SI,288
+components/mainClasses.py,sha256=ngL5temf3hC_acL0gUP7cuFPxtZQ8KdA5EpX-vvzTCI,365
+components/mainFunctions.py,sha256=1LlLy12ZVUeOBAj8Kubey8FQdGcwoE4Yq7XxuqNAvOQ,4159
+components/setConfigurations.py,sha256=mZdoBrpfYhM2HXqirkS7weaKWt0qvl8lBBfH38Zk5wY,261
+data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_imageCompressor.py,sha256=B6S7-VMy-T13fgHFlKu0_viFyA390ljEuJ8Jhckwfu0,1028
+tests/test_main.py,sha256=6OI9OMyQkGCnHcVT249meVqU2RFk87kJ7HtYQtmB6Ns,897
+tests/test_mainFunctions.py,sha256=dm8Nzr51gD8x0VsB-ZwV0is9DvofaBfq0xcpHpLltz8,1209
+tests/test_setConfigurations.py,sha256=IEbdkyEPf03VZ4WhF96z1fQZbTYUUrBlfmJNEf7otjQ,416
+py_bulk_image_compressor-1.0.0.dist-info/LICENSE,sha256=gUujiUx8F-4IJKvnKzPGhhHnrRoMBOcwN_EEDZt6TKE,1073
+py_bulk_image_compressor-1.0.0.dist-info/METADATA,sha256=SrjDkSPUgXFWUcIVpqVimN934M7Khp5u9NfK-daKEQA,8356
+py_bulk_image_compressor-1.0.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+py_bulk_image_compressor-1.0.0.dist-info/top_level.txt,sha256=THioVdUbPSf1b-w7rr4aH13xcJH5BrQIxnH_EXsYDUc,22
+py_bulk_image_compressor-1.0.0.dist-info/RECORD,,

py_bulk_image_compressor-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_bulk_image_compressor-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+components
+data
+tests

tests/test_imageCompressor.py

@@ -0,0 +1,34 @@
+import os
+import pytest
+from PIL import Image
+from components import imageCompressor as ic
+
+@pytest.mark.parametrize("img_format", ["jpeg", "png", "webp"])
+def test_compress_resize_image(tmp_path, img_format):
+    """
+    Using a small sample image in tests/sample_images,
+    compress/resize it and ensure output file is created.
+    """
+    # Prepare sample image path
+    sample_dir = os.path.join(os.path.dirname(__file__), "sample_images")
+    sample_image = os.path.join(sample_dir, "sample.jpeg")
+
+    # Output path
+    output_image = tmp_path / f"compressed.{img_format}"
+
+    # Call compressor
+    ic.compress_resize_image(
+        image_location=sample_image,
+        image_destination=str(output_image),
+        set_format=img_format,
+        max_width=500,
+        quality=80,
+        remove_meta=False
+    )
+
+    # Check if file is created
+    assert output_image.exists()
+
+    # Check if it can be opened by Pillow
+    with Image.open(output_image) as img:
+        assert img.width <= 500  # we used max_width=500

tests/test_main.py

@@ -0,0 +1,26 @@
+import pytest
+import subprocess
+import sys
+import os
+
+def test_help_flag():
+    """
+    Ensure the script runs with -h and does not crash.
+    We'll capture stdout to verify it contains 'usage' or 'help'.
+    """
+    cmd = [sys.executable, "main.py", "-h"]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    assert result.returncode == 0
+    assert "usage" in result.stdout.lower() or "help" in result.stdout.lower()
+
+@pytest.mark.parametrize("flag", ["-l", "-d"])
+def test_missing_required_args(flag):
+    """
+    Test that missing required argument -l triggers an error.
+    We'll check for returncode != 0.
+    """
+    # When we run the script without -l or incomplete arguments, it should fail
+    cmd = [sys.executable, "main.py"]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    assert result.returncode != 0
+    assert "error" in result.stderr.lower()

tests/test_mainFunctions.py

@@ -0,0 +1,35 @@
+import os
+import pytest
+from pathlib import Path
+from components import mainFunctions as mf
+
+def test_create_folder(tmp_path):
+    """Test that create_folder() actually creates the given folder."""
+    test_dir = tmp_path / "test_folder"
+    assert not test_dir.exists()
+    mf.create_folder(str(test_dir))
+    assert test_dir.exists()
+
+def test_folder_size(tmp_path):
+    """Test folder_size() returns correct size in KB."""
+    test_dir = tmp_path / "test_folder2"
+    mf.create_folder(str(test_dir))
+
+    # Create a small file (1KB of data)
+    file_path = test_dir / "dummy.txt"
+    with open(file_path, "wb") as f:
+        f.write(b'X' * 1024)
+
+    result = mf.folder_size(str(test_dir))
+    # Should be around 1KB. We'll just check if the substring is in the output
+    assert "1.0 KB" in result or "1.0" in result
+
+def test_get_percentage_difference():
+    """Check the logic for get_percentage_difference."""
+    # original_size=100, new_size=50 => saves 100%
+    diff = mf.get_percentage_difference(num_a=100, num_b=50)
+    assert diff == 100.0
+
+    # original=50, new=100 => -50% (i.e., the new is bigger by 50%)
+    diff = mf.get_percentage_difference(num_a=50, num_b=100)
+    assert diff == -50.0

tests/test_setConfigurations.py

@@ -0,0 +1,13 @@
+import os
+from components import setConfigurations
+
+def test_get_resources():
+    """Check if configurations.ini is loaded properly."""
+    config = setConfigurations.get_resources()
+    # We expect certain sections to exist
+    assert 'default_parameters' in config
+    assert 'supported_formats' in config
+    assert 'logs' in config
+
+    # Check a known key
+    assert 'max_width' in config['default_parameters']