Easy Images

`py_simple.easy_images`

easy_images is meant to simplify common image processing tasks (resizing, converting, rotating, and inspecting images) using Pillow.

`ImageProcessingError`

Bases: Exception

Raised when a py_simple image function fails to complete.

This covers a missing input file, an unsupported/corrupt image format, or any other error that prevents a function from returning a real result.

Parameters:

Name	Type	Description	Default
`message`	`str`	Description of what went wrong.	required

`convert_image(input_path, output_path)`

Convert an image to a different format based on the output file's extension (e.g. PNG to JPG).

Parameters:

Name	Type	Description	Default
`input_path`	`str`	Path of the image to convert.	required
`output_path`	`str`	Path to save the converted image to. The new format is inferred from this path's extension.	required

Example

The Py_simple WayThe Traditional Way

from py_simple import convert_image

convert_image("photo.png", "photo.jpg")

from PIL import Image

with Image.open("photo.png") as img:
    img.convert("RGB").save("photo.jpg")

`create_thumbnail(input_path, output_path, max_width, max_height)`

Create a thumbnail that fits within the given dimensions.

The image keeps its original aspect ratio and is never enlarged.

Parameters:

Name	Type	Description	Default
`input_path`	`str`	Path of the source image.	required
`output_path`	`str`	Path to save the thumbnail to.	required
`max_width`	`int`	Maximum thumbnail width in pixels.	required
`max_height`	`int`	Maximum thumbnail height in pixels.	required

Raises:

Type	Description
`ValueError`	If either maximum dimension is not a positive integer.

Example

The Py_simple WayThe Traditional Way

from py_simple import create_thumbnail

create_thumbnail("photo.jpg", "thumbnail.jpg", 320, 320)

from PIL import Image

with Image.open("photo.jpg") as img:
    img.thumbnail((320, 320))
    img.save("thumbnail.jpg")

`flip_image(input_path, output_path, direction='horizontal')`

Flip an image horizontally or vertically and save the result.

Parameters:

Name	Type	Description	Default
`input_path`	`str`	Path of the image to flip.	required
`output_path`	`str`	Path to save the flipped image to.	required
`direction`	`str`	Either "horizontal" (left-right) or "vertical" (top-bottom). Defaults to "horizontal".	`'horizontal'`

Raises:

Type	Description
`ValueError`	If `direction` is not "horizontal" or "vertical".
`ImageProcessingError`	If the input file is missing or not a supported image.

Example

The Py_simple WayThe Traditional Way

from py_simple import flip_image

flip_image("photo.jpg", "photo_flipped.jpg", "horizontal")

from PIL import Image

with Image.open("photo.jpg") as img:
    img.transpose(Image.Transpose.FLIP_LEFT_RIGHT).save(
        "photo_flipped.jpg"
    )

`get_image_info(input_path)`

Get basic information about an image.

Parameters:

Name	Type	Description	Default
`input_path`	`str`	Path of the image to inspect.	required

Returns:

Name	Type	Description
`dict`	`dict`	With keys "width", "height", "format", and "mode".

Example

The Py_simple WayThe Traditional Way

from py_simple import get_image_info

info = get_image_info("photo.jpg")
# {"width": 1920, "height": 1080, "format": "JPEG", "mode": "RGB"}

from PIL import Image

with Image.open("photo.jpg") as img:
    info = {
        "width": img.width,
        "height": img.height,
        "format": img.format,
        "mode": img.mode,
    }

`resize_image(input_path, output_path, width, height)`

Resize an image to the given dimensions and save it.

Parameters:

Name	Type	Description	Default
`input_path`	`str`	Path of the image to resize.	required
`output_path`	`str`	Path to save the resized image to.	required
`width`	`int`	Target width in pixels.	required
`height`	`int`	Target height in pixels.	required

Example

The Py_simple WayThe Traditional Way

from py_simple import resize_image

resize_image("photo.jpg", "photo_small.jpg", 320, 240)

from PIL import Image

with Image.open("photo.jpg") as img:
    img.resize((320, 240)).save("photo_small.jpg")

`rotate_image(input_path, output_path, angle)`

Rotate an image by the given angle (counter-clockwise) and save it.

Parameters:

Name	Type	Description	Default
`input_path`	`str`	Path of the image to rotate.	required
`output_path`	`str`	Path to save the rotated image to.	required
`angle`	`float`	Degrees to rotate counter-clockwise, e.g. 90.	required

Example

The Py_simple WayThe Traditional Way

from py_simple import rotate_image

rotate_image("photo.jpg", "photo_rotated.jpg", 90)

from PIL import Image

with Image.open("photo.jpg") as img:
    img.rotate(90, expand=True).save("photo_rotated.jpg")