Metadata-Version: 2.4
Name: imgsqueeze
Version: 0.1.1
Summary: Compress the PNG, JPEG and WebP images of a blog once, and remember that they are done.
Author-email: Sanhe Hu <husanhe@gmail.com>
Maintainer-email: Sanhe Hu <husanhe@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MacHu-GWU/imgsqueeze-project
Project-URL: Documentation, https://imgsqueeze.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/MacHu-GWU/imgsqueeze-project
Project-URL: Issues, https://github.com/MacHu-GWU/imgsqueeze-project/issues
Project-URL: Changelog, https://github.com/MacHu-GWU/imgsqueeze-project/blob/main/release-history.rst
Project-URL: Download, https://pypi.org/pypi/imgsqueeze#files
Keywords: image,compression,png,jpeg,webp,pngquant,oxipng,blog,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
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
Requires-Python: <4.0,>=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
License-File: AUTHORS.rst
Requires-Dist: pillow<13.0.0,>=12.0.0
Provides-Extra: dev
Requires-Dist: rich<15.0.0,>=14.3.4; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest<10.0.0,>=9.1.1; extra == "test"
Requires-Dist: pytest-cov<8.0.0,>=7.1.0; extra == "test"
Provides-Extra: doc
Requires-Dist: Sphinx<9.0.0,>=8.2.3; extra == "doc"
Requires-Dist: sphinx-copybutton<1.0.0,>=0.5.2; extra == "doc"
Requires-Dist: sphinx-design<1.0.0,>=0.7.0; extra == "doc"
Requires-Dist: sphinx-jinja<3.0.0,>=2.0.2; extra == "doc"
Requires-Dist: furo==2025.12.19; extra == "doc"
Requires-Dist: pygments<3.0.0,>=2.18.0; extra == "doc"
Requires-Dist: ipython<8.19.0,>=8.18.1; extra == "doc"
Requires-Dist: ipykernel<8.0.0,>=7.3.0; extra == "doc"
Requires-Dist: nbsphinx<1.0.0,>=0.9.8; extra == "doc"
Requires-Dist: rstobj<3.0.0,>=2.0.0; extra == "doc"
Requires-Dist: docfly<4.0.0,>=3.0.3; extra == "doc"
Provides-Extra: mise
Requires-Dist: PyGithub<3.0.0,>=2.8.0; extra == "mise"
Requires-Dist: httpx2<3.0.0,>=2.13.1; extra == "mise"
Dynamic: license-file


.. image:: https://readthedocs.org/projects/imgsqueeze/badge/?version=latest
    :target: https://imgsqueeze.readthedocs.io/en/latest/
    :alt: Documentation Status

.. image:: https://github.com/MacHu-GWU/imgsqueeze-project/actions/workflows/main.yml/badge.svg
    :target: https://github.com/MacHu-GWU/imgsqueeze-project/actions?query=workflow:CI

.. image:: https://codecov.io/gh/MacHu-GWU/imgsqueeze-project/branch/main/graph/badge.svg
    :target: https://codecov.io/gh/MacHu-GWU/imgsqueeze-project

.. image:: https://img.shields.io/pypi/v/imgsqueeze.svg
    :target: https://pypi.python.org/pypi/imgsqueeze

.. image:: https://img.shields.io/pypi/l/imgsqueeze.svg
    :target: https://pypi.python.org/pypi/imgsqueeze

.. image:: https://img.shields.io/pypi/pyversions/imgsqueeze.svg
    :target: https://pypi.python.org/pypi/imgsqueeze

.. image:: https://img.shields.io/badge/✍️_Release_History!--None.svg?style=social&logo=github
    :target: https://github.com/MacHu-GWU/imgsqueeze-project/blob/main/release-history.rst

.. image:: https://img.shields.io/badge/⭐_Star_me_on_GitHub!--None.svg?style=social&logo=github
    :target: https://github.com/MacHu-GWU/imgsqueeze-project

------

.. image:: https://img.shields.io/badge/Link-API-blue.svg
    :target: https://imgsqueeze.readthedocs.io/en/latest/py-modindex.html

.. image:: https://img.shields.io/badge/Link-Install-blue.svg
    :target: `install`_

.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg
    :target: https://github.com/MacHu-GWU/imgsqueeze-project

.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg
    :target: https://github.com/MacHu-GWU/imgsqueeze-project/issues

.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg
    :target: https://github.com/MacHu-GWU/imgsqueeze-project/issues

.. image:: https://img.shields.io/badge/Link-Download-blue.svg
    :target: https://pypi.org/pypi/imgsqueeze#files


Welcome to ``imgsqueeze`` Documentation
==============================================================================
.. image:: https://imgsqueeze.readthedocs.io/en/latest/_static/imgsqueeze-logo.png
    :target: https://imgsqueeze.readthedocs.io/en/latest/

``imgsqueeze`` compresses the PNG, JPEG and WebP images of a blog **once**, and
remembers that they are done.

- **Visually lossless presets.** PNG goes through `pngquant <https://pngquant.org/>`_
  and `oxipng <https://github.com/shssoichiro/oxipng>`_; JPEG and WebP are
  re-encoded with `Pillow <https://python-pillow.org/>`_. A result is kept
  only when it saves enough bytes; otherwise the original stays untouched.
- **Done is done.** Each image gets a small ``<image>.json`` sidecar that
  records the hash of its final content. Running again skips it, whatever
  the preset, so no image is ever compressed twice.
- **Safe to run anywhere, any time.** Files are replaced atomically, and an
  image changed by another process while it was compressed is left alone.
- **Made for agents.** ``--json`` output, stable exit codes, and a ``check``
  command for pre-commit hooks.

.. code-block:: console

    $ imgsqueeze optimize ~/blog/images
    optimized     /Users/me/blog/images/cover.jpg 419423 -> 76176 bytes (81.8% saved)
    optimized     /Users/me/blog/images/diagram.png 55537 -> 7793 bytes (86.0% saved)
    no_gain       /Users/me/blog/images/hero.webp 373482 -> 373482 bytes (0.0% saved)
    3 images: 2 optimized, 1 no_gain; saved 390991 bytes

Commit the images together with their ``.json`` sidecars. Read the full
documentation at https://imgsqueeze.readthedocs.io/.


.. _install:

Install
------------------------------------------------------------------------------
``imgsqueeze`` needs Python 3.11+ and `mise <https://mise.jdx.dev/getting-started.html>`_.
mise installs the pinned pngquant and oxipng the first time a PNG is
compressed; JPEG and WebP need nothing else. Run it without installing:

.. code-block:: console

    $ uvx imgsqueeze optimize ~/blog/images

Or install it from PyPI:

.. code-block:: console

    $ pip install imgsqueeze

To install pngquant and oxipng ahead of time:

.. code-block:: console

    $ imgsqueeze setup


.. _use-with-ai-coding-agents:

Use with AI Coding Agents
------------------------------------------------------------------------------

This repo ships an `Agent Skill <https://code.claude.com/docs/en/skills>`_ that documents the public API of ``imgsqueeze``, so an AI coding agent such as Claude Code can use the library without reading its source. It lives in `.claude/skills/pypi-imgsqueeze <https://github.com/MacHu-GWU/imgsqueeze-project/tree/main/.claude/skills/pypi-imgsqueeze>`_. To use it in your project, copy it into your project's ``.claude/skills/`` folder. Run this from your project's root:

.. code-block:: console

    $ git clone --depth 1 https://github.com/MacHu-GWU/imgsqueeze-project.git /tmp/imgsqueeze-project
    $ mkdir -p .claude/skills
    $ cp -R /tmp/imgsqueeze-project/.claude/skills/pypi-imgsqueeze .claude/skills/


License
------------------------------------------------------------------------------
``imgsqueeze`` is MIT licensed. It runs pngquant, by Kornel Lesiński and
contributors, as a separate program and never bundles it; pngquant is
dual-licensed under `GPL-3.0 or a commercial license <https://pngquant.org/>`_,
and the images it produces are not covered by its license.
