PyPNG 0.20231004.0

Dnyarri · Dnyarri · commit c62e68e6823d · 2025-11-23T08:47:11.000+03:00
diff --git a/pypng/__init__.py b/pypng/__init__.py
@@ -1 +1,12 @@
-"""Type `from pypng import pnglpng` to get access to functions."""
+"""
+Type::
+
+    from pypng import pnglpng
+
+or::
+
+    from pypng.pnglpng import list2png, png2list
+
+to get access to functions.
+
+"""
diff --git a/pypng/pnglpng.py b/pypng/pnglpng.py
@@ -8,55 +8,48 @@
 Joint between PyPNG and other programs
 --------------------------------------
 
-Created by: `Ilya Razmanov<mailto:ilyarazmanov@gmail.com>`_
-aka `Ilyich the Toad<mailto:amphisoft@gmail.com>`_.
-
 Overview
----------
+--------
 
 **pnglpng** (png-list-png) is a suitable joint between `PyPNG`_
 and other Python programs, providing data conversion from/to used by PyPNG
 to/from understandable by ordinary average human.
 
 Functions included are:
 
-:png2list: reading PNG file and returning all data;
-:list2png: getting data and writing PNG file;
-:create_image: creating empty nested 3D list for image representation.
+- ``png2list``: reading PNG file and returning all data;
+- ``list2png``: getting data and writing PNG file;
+- ``create_image``: creating empty nested 3D list for image representation.
 
 Installation
--------------
+------------
 
 Should be kept together with ``png.py`` module. See ``import`` for detail.
 
 Usage
-------
-
-After ``import pnglpng``, use something like
+-----
 
-::
+After ``import pnglpng``, use something like::
 
     X, Y, Z, maxcolors, list_3d, info = pnglpng.png2list(in_filename)
 
-for reading data from ``in_filename`` PNG, where:
-
-:X, Y, Z: image dimensions (int);
-:maxcolors: number of colors per channel for current image (int);
-:list_3d: image pixel data as list(list(list(int)));
-:info: PNG chunks like resolution etc (dictionary);
+for reading data from PNG file, where:
 
-and
+- ``X``, ``Y``, ``Z``: PNG image dimensions (int);
+- ``maxcolors``: number of colors per channel for current image (int), either 1, or 255, or 65535, for 1 bpc, 8 bpc and 16 bpc PNG respectively;
+- ``list_3d``: Y * X * Z list (image) of lists (rows) of lists (pixels) of ints (channels), from PNG iDAT;
+- ``info``: dictionary of PNG chunks like resolution etc., as they are accessible by PyPNG.
 
-::
+and ::
 
     pnglpng.list2png(out_filename, list_3d, info)
 
-for writing data to ``out_filename`` PNG.
+for writing data as listed above to ``out_filename`` PNG.
 
-Prerequisites and References
-----------------------------
+References
+----------
 
-1. `PyPNG`_
+1. `PyPNG`_ download
 2. `PyPNG docs`_
 
 .. _PyPNG: https://gitlab.com/drj11/pypng
@@ -84,19 +77,13 @@
 def png2list(in_filename):
     """Take PNG filename and return PNG data in a human-friendly form.
 
-    Usage
-
-    ::
-
-        X, Y, Z, maxcolors, list_3d, info = pnglpng.png2list(in_filename)
+    :param str in_filename: input file name;
+    :return X, Y, Z, maxcolors, list_3d, info: tuple, consisting of:
 
-    Takes PNG filename ``in_filename`` and return the following tuple
-
-    :X, Y, Z: PNG image dimensions (int);
-    :maxcolors: number of colors per channel for current image (int),
-        either 1, or 255, or 65535, for 1 bpc, 8 bpc and 16 bpc PNG respectively;
-    :list_3d: Y * X * Z list (image) of lists (rows) of lists (pixels) of ints (channels), from PNG iDAT;
-    :info: dictionary from PNG chunks like resolution etc. as they are accessible by PyPNG.
+    - ``X``, ``Y``, ``Z``: PNG image dimensions (int);
+    - ``maxcolors``: number of colors per channel for current image (int), either 1, or 255, or 65535, for 1 bpc, 8 bpc and 16 bpc PNG respectively;
+    - ``list_3d``: Y * X * Z list (image) of lists (rows) of lists (pixels) of ints (channels), from PNG iDAT;
+    - ``info``: dictionary of PNG chunks like resolution etc., as they are accessible by PyPNG.
 
     """
 
@@ -128,18 +115,12 @@ def png2list(in_filename):
 def list2png(out_filename, list_3d, info):
     """Take filename and image data, and create PNG file.
 
-    Usage
-
-    ::
-
-        pnglpng.list2png(out_filename, list_3d, info)
-
-    Take data described below and write PNG file `out_filename` out of it.
-
-    :list_3d: Y * X * Z list (image) of lists (rows) of lists (pixels) of ints (channels);
-    :info: dictionary, chunks like resolution etc. as you want them to be present in PNG.
+    :param list_3d: Y * X * Z list (image) of lists (rows) of lists (pixels) of ints (channels);
+    :param info: dictionary, chunks like resolution etc. as you want them to be present in PNG;
+    :param str out_filename: output PNG file name (str).
 
-    Note that ``X``, ``Y`` and ``Z`` detected from the list structure override those set in ``info``.
+    .. note:: ``X``, ``Y`` and ``Z`` detected from the list structure override those set in ``info``.
+    .. warning:: Correct ``info['bitdepth']`` is **critical** because it cannot be detected from the list structure.
 
     """
 
@@ -177,7 +158,7 @@ def flatten_2d(list_3d):
 
         yield from ([list_3d[y][x][z] for x in range(X) for z in range(Z)] for y in range(Y))
 
-    # ↓ Writing PNG with `.write` method (row by row), 
+    # ↓ Writing PNG with `.write` method (row by row),
     #   using `flatten_2d` generator to save memory
     writer = png.Writer(X, Y, **info)
     with open(out_filename, 'wb') as result_png:
