pyAPNG API reference¶

A Python module to deal with APNG file.

Usage/examples can be founded at pyAPNG’s readme.

Functions¶

parse_chunks(b)¶

Parse PNG bytes into multiple chunks.

Parameters: b (bytes) – The raw bytes of the PNG file.
Returns: A generator yielding Chunk.
Return type: Iterator[Chunk]

make_chunk(chunk_type, chunk_data)¶

Create a raw chunk by composing chunk type and data. It calculates chunk length and CRC for you.

Parameters

chunk_type (str) – PNG chunk type.
chunk_data (bytes) – PNG chunk data, excluding chunk length, type, and CRC.

Return type

bytes

make_text_chunk(type='tEXt', key='Comment', value='', compression_flag=0, compression_method=0, lang='', translated_key='')¶

Create a text chunk with a key value pair. See https://www.w3.org/TR/PNG/#11textinfo for text chunk information.

Usage:

from apng import APNG, make_text_chunk

im = APNG.open("file.png")
png, control = im.frames[0]
png.chunks.append(make_text_chunk("tEXt", "Comment", "some text"))
im.save("file.png")

Parameters

type (str) –
Text chunk type: “tEXt”, “zTXt”, or “iTXt”:

tEXt uses Latin-1 characters. zTXt uses Latin-1 characters, compressed with zlib. iTXt uses UTF-8 characters.
key (str) – The key string, 1-79 characters.
value (str) – The text value. It would be encoded into bytes and compressed if needed.
compression_flag (int) – The compression flag for iTXt.
compression_method (int) – The compression method for zTXt and iTXt.
lang (str) – The language tag for iTXt.
translated_key (str) – The translated keyword for iTXt.

Return type

Chunk

Classes¶

class Chunk¶

A namedtuple to represent the PNG chunk.

Parameters

type (str) – The chunk type.
data (bytes) – The raw bytes of the chunk, including chunk length, type, data, and CRC.

Create new instance of Chunk(type, data)

class PNG¶

Represent a PNG image.

chunks = []¶: A list of Chunk. After reading a PNG file, the bytes are parsed into multiple chunks. You can remove/add chunks into this array before calling to_bytes().

classmethod from_bytes(b)¶

Create PNG from raw bytes.

Parameters: b (bytes) – The raw bytes of the PNG file.
Return type: PNG

classmethod open(file)¶

Open a PNG file.

Parameters: file (path-like or file-like) – Input file.
Return type: PNG

classmethod open_any(file)¶

Open an image file. If the image is not PNG format, it would convert the image into PNG with Pillow module. If the module is not installed, ImportError would be raised.

Parameters: file (path-like or file-like) – Input file.
Return type: PNG

save(file)¶

Save the entire image to a file.

Parameters: file (path-like or file-like) – Output file.

to_bytes()¶

Convert the entire image to bytes.

Return type: bytes

class FrameControl(width=None, height=None, x_offset=0, y_offset=0, delay=100, delay_den=1000, depose_op=1, blend_op=0)¶

A data class holding fcTL info.

Parameters are assigned as object members. See https://wiki.mozilla.org/APNG_Specification for the detail of fcTL.

classmethod from_bytes(b)¶

Contruct fcTL info from bytes.

Parameters: b (bytes) – The length of b must be 28, excluding sequence number and CRC.

to_bytes()¶

Convert to bytes.

Return type: bytes

class APNG(num_plays=0)¶

Represent an APNG image.

An APNG is composed by multiple PNG s and FrameControl, which can be inserted with append().

Parameters

num_plays (int) – Number of times to loop. 0 = infinite.

Variables

frames (list[tuple(PNG, FrameControl)]) – The frames of APNG.
num_plays (int) – same as num_plays.

append(png, **options)¶

Append one frame.

Parameters

png (PNG) – Append a PNG as a frame.
options (dict) – The options for FrameControl.

append_file(file, **options)¶

Create a PNG from file and append the PNG as a frame.

Parameters

file (path-like or file-like.) – Input file.
options (dict) – The options for FrameControl.

classmethod from_bytes(b)¶

Create an APNG from raw bytes.

Parameters: b (bytes) – The raw bytes of the APNG file.
Return type: APNG

classmethod from_files(files, **options)¶

Create an APNG from multiple files.

This is a shortcut of:

im = APNG()
for file in files:
        im.append_file(file, **options)

Parameters

files (list) – A list of filename. See PNG.open().
options (dict) – Options for FrameControl.

Return type

APNG

classmethod open(file)¶

Open an APNG file.

Parameters: file (path-like or file-like.) – Input file.
Return type: APNG

save(file)¶

Save the entire image to a file.

Parameters: file (path-like or file-like) – Output file.

to_bytes()¶

Convert the entire image to bytes.

Return type: bytes