From ee6f150ef1dd73c2bf6d39dd8c64cae3d48fdc29 Mon Sep 17 00:00:00 2001
From: wiredfool <eric-github@soroos.net>
Date: Wed, 19 Nov 2014 14:04:39 -0800
Subject: [PATCH] Docs for PyAccess, PixelAccess objects [ci skip]

---
 PIL/Image.py                   |  1 +
 PIL/PyAccess.py                |  2 +
 docs/reference/PixelAccess.rst | 74 ++++++++++++++++++++++++++++++++++
 docs/reference/PyAccess.rst    | 38 +++++++++++++++++
 docs/reference/index.rst       |  2 +
 5 files changed, 117 insertions(+)
 create mode 100644 docs/reference/PixelAccess.rst
 create mode 100644 docs/reference/PyAccess.rst

diff --git a/PIL/Image.py b/PIL/Image.py
index d556df34c..b961ae2ce 100644
--- a/PIL/Image.py
+++ b/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
diff --git a/PIL/PyAccess.py b/PIL/PyAccess.py
index 93aeae59e..28829051d 100644
--- a/PIL/PyAccess.py
+++ b/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)
diff --git a/docs/reference/PixelAccess.rst b/docs/reference/PixelAccess.rst
new file mode 100644
index 000000000..55ab8c578
--- /dev/null
+++ b/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.
diff --git a/docs/reference/PyAccess.rst b/docs/reference/PyAccess.rst
new file mode 100644
index 000000000..cb853f89e
--- /dev/null
+++ b/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:
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 2f10b861d..73a3ecfed 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -28,4 +28,6 @@ Reference
    ExifTags
    OleFileIO
    PSDraw
+   PixelAccess
+   PyAccess
    ../PIL