Merge pull request #1019 from wiredfool/load-docs

Docs for PyAccess, PixelAccess objects [ci skip]

PIL/Image.py

@@ -745,6 +745,7 @@ class Image:
         associated with the image.
 
         :returns: An image access object.
+        :rtype: :ref:`PixelAccess` or :py:class:`PIL.PyAccess` 
         """
         if self.im and self.palette and self.palette.dirty:
             # realize palette

PIL/PyAccess.py

@@ -78,6 +78,8 @@ class PyAccess(object):
         images
 
         :param xy: The pixel coordinate, given as (x, y).
+        :returns: a pixel value for single band images, a tuple of
+          pixel values for multiband images.
         """
 
         (x, y) = self.check_xy(xy)

docs/reference/PixelAccess.rst

@@ -0,0 +1,74 @@
+.. _PixelAccess:
+
+:py:class:`PixelAccess` Class
+=============================
+
+The PixelAccess class provides read and write access to
+:py:class:`PIL.Image` data at a pixel level.
+
+.. note::  Accessing individual pixels is fairly slow. If you are looping over all of the pixels in an image, there is likely a faster way using other parts of the Pillow API.  
+
+Example
+-------
+
+The following script loads an image, accesses one pixel from it, then
+changes it.
+
+.. code-block:: python
+    
+    from PIL import Image
+    im = Image.open('hopper.jpg')
+    px = im.load()
+    print (px[4,4])
+    px[4,4] = (0,0,0)
+    print (px[4,4])
+
+Results in the following::
+
+    (23, 24, 68)
+    (0, 0, 0)
+
+   
+
+:py:class:`PixelAccess` Class
+-----------------------------------
+
+.. class:: PixelAccess
+
+  .. method:: __setitem__(self, xy, color):
+
+        Modifies the pixel at x,y. The color is given as a single
+        numerical value for single band images, and a tuple for
+        multi-band images
+
+        :param xy: The pixel coordinate, given as (x, y).
+        :param value: The pixel value.
+   
+  .. method:: __getitem__(self, xy):
+ 
+       Returns the pixel at x,y. The pixel is returned as a single
+        value for single band images or a tuple for multiple band
+        images
+
+        :param xy: The pixel coordinate, given as (x, y).
+        :returns: a pixel value for single band images, a tuple of
+          pixel values for multiband images.
+
+  .. method:: putpixel(self, xy, color):
+
+        Modifies the pixel at x,y. The color is given as a single
+        numerical value for single band images, and a tuple for
+        multi-band images
+
+        :param xy: The pixel coordinate, given as (x, y).
+        :param value: The pixel value.
+   
+  .. method:: getpixel(self, xy):
+ 
+       Returns the pixel at x,y. The pixel is returned as a single
+        value for single band images or a tuple for multiple band
+        images
+
+        :param xy: The pixel coordinate, given as (x, y).
+        :returns: a pixel value for single band images, a tuple of
+          pixel values for multiband images.

docs/reference/PyAccess.rst

@@ -0,0 +1,38 @@
+.. py:module:: PIL.PyAccess
+.. py:currentmodule:: PIL.PyAccess
+
+:py:mod:`PyAccess` Module
+=========================
+
+The :py:mod:`PyAccess` module provides a CFFI/Python implementation of the :ref:`PixelAccess`. This implementation is far faster on PyPy than the PixelAccess version.
+
+.. note:: Accessing individual pixels is fairly slow. If you are
+           looping over all of the pixels in an image, there is likely
+           a faster way using other parts of the Pillow API.
+
+Example
+-------
+
+The following script loads an image, accesses one pixel from it, then changes it.
+
+.. code-block:: python
+    
+    from PIL import Image
+    im = Image.open('hopper.jpg')
+    px = im.load()
+    print (px[4,4])
+    px[4,4] = (0,0,0)
+    print (px[4,4])
+
+Results in the following::
+
+    (23, 24, 68)
+    (0, 0, 0)
+
+   
+
+:py:class:`PyAccess` Class
+--------------------------
+
+.. autoclass:: PIL.PyAccess.PyAccess()
+    :members:

docs/reference/index.rst

@@ -28,4 +28,6 @@ Reference
    ExifTags
    OleFileIO
    PSDraw
+   PixelAccess
+   PyAccess
    ../PIL