From a560022341ab021236ec4a99781e30f19ed163fc Mon Sep 17 00:00:00 2001 From: Felipe Reyes Date: Fri, 19 Jul 2013 15:11:26 +0000 Subject: [PATCH] Transformed docstrings of ImageFile and ImageFileIO modules --- PIL/ImageFile.py | 101 +++++++++++++++++++++------------------------ PIL/ImageFileIO.py | 37 +++++++++-------- 2 files changed, 66 insertions(+), 72 deletions(-) diff --git a/PIL/ImageFile.py b/PIL/ImageFile.py index f23823fc3..f5e2a839f 100644 --- a/PIL/ImageFile.py +++ b/PIL/ImageFile.py @@ -67,9 +67,6 @@ def _tilesort(t): # -------------------------------------------------------------------- # ImageFile base class -## -# Base class for image file handlers. - class ImageFile(Image.Image): "Base class for image file format handlers." @@ -266,14 +263,14 @@ class ImageFile(Image.Image): # def load_read(self, bytes): # pass -## -# Base class for stub image loaders. -#

-# A stub loader is an image loader that can identify files of a -# certain format, but relies on external code to load the file. class StubImageFile(ImageFile): - "Base class for stub image loaders." + """ + Base class for stub image loaders. + + A stub loader is an image loader that can identify files of a + certain format, but relies on external code to load the file. + """ def _open(self): raise NotImplementedError( @@ -290,41 +287,39 @@ class StubImageFile(ImageFile): self.__class__ = image.__class__ self.__dict__ = image.__dict__ - ## - # (Hook) Find actual image loader. - def _load(self): + "(Hook) Find actual image loader." raise NotImplementedError( "StubImageFile subclass must implement _load" ) -## -# Incremental image parser. This class implements the standard -# feed/close consumer interface. class Parser: - + """ + Incremental image parser. This class implements the standard + feed/close consumer interface. + """ incremental = None image = None data = None decoder = None finished = 0 - ## - # (Consumer) Reset the parser. Note that you can only call this - # method immediately after you've created a parser; parser - # instances cannot be reused. - def reset(self): + """ + (Consumer) Reset the parser. Note that you can only call this + method immediately after you've created a parser; parser + instances cannot be reused. + """ assert self.data is None, "cannot reuse parsers" - ## - # (Consumer) Feed data to the parser. - # - # @param data A string buffer. - # @exception IOError If the parser failed to parse the image file. - def feed(self, data): + """ + (Consumer) Feed data to the parser. + + :param data" A string buffer. + :exception IOError: If the parser failed to parse the image file. + """ # collect data if self.finished: @@ -403,13 +398,13 @@ class Parser: self.image = im - ## - # (Consumer) Close the stream. - # - # @return An image object. - # @exception IOError If the parser failed to parse the image file. - def close(self): + """ + (Consumer) Close the stream. + + :returns: An image object. + :exception IOError: If the parser failed to parse the image file. + """ # finish decoding if self.decoder: # get rid of what's left in the buffers @@ -432,25 +427,23 @@ class Parser: # -------------------------------------------------------------------- -## -# (Helper) Save image body to file. -# -# @param im Image object. -# @param fp File object. -# @param tile Tile list. -# @param bufsize Optional buffer size - def _save(im, fp, tile, bufsize=0): - "Helper to save image based on tile list" + """Helper to save image based on tile list + + :param im: Image object. + :param fp: File object. + :param tile: Tile list. + :param bufsize: Optional buffer size + """ im.load() if not hasattr(im, "encoderconfig"): im.encoderconfig = () tile.sort(key=_tilesort) # FIXME: make MAXBLOCK a configuration parameter - # It would be great if we could have the encoder specifiy what it needs - # But, it would need at least the image size in most cases. RawEncode is - # a tricky case. + # It would be great if we could have the encoder specifiy what it needs + # But, it would need at least the image size in most cases. RawEncode is + # a tricky case. bufsize = max(MAXBLOCK, bufsize, im.size[0] * 4) # see RawEncode.c try: fh = fp.fileno() @@ -484,16 +477,16 @@ def _save(im, fp, tile, bufsize=0): except: pass -## -# Reads large blocks in a safe way. Unlike fp.read(n), this function -# doesn't trust the user. If the requested size is larger than -# SAFEBLOCK, the file is read block by block. -# -# @param fp File handle. Must implement a read method. -# @param size Number of bytes to read. -# @return A string containing up to size bytes of data. - def _safe_read(fp, size): + """ + Reads large blocks in a safe way. Unlike fp.read(n), this function + doesn't trust the user. If the requested size is larger than + SAFEBLOCK, the file is read block by block. + + :param fp: File handle. Must implement a read method. + :param size: Number of bytes to read. + :returns: A string containing up to size bytes of data. + """ if size <= 0: return b"" if size <= SAFEBLOCK: diff --git a/PIL/ImageFileIO.py b/PIL/ImageFileIO.py index e2f53e38a..e57d3f43e 100644 --- a/PIL/ImageFileIO.py +++ b/PIL/ImageFileIO.py @@ -11,29 +11,30 @@ # # See the README file for information on usage and redistribution. # +""" +The **ImageFileIO** module can be used to read an image from a +socket, or any other stream device. + +Deprecated. New code should use the :class:`PIL.ImageFile.Parser` +class in the :mod:`PIL.ImageFile` module instead. + +.. seealso:: modules :class:`PIL.ImageFile.Parser` +""" from io import BytesIO -## -# The ImageFileIO module can be used to read an image from a -# socket, or any other stream device. -#

-# This module is deprecated. New code should use the Parser -# class in the ImageFile module instead. -# -# @see ImageFile#Parser class ImageFileIO(BytesIO): - - ## - # Adds buffering to a stream file object, in order to - # provide seek and tell methods required - # by the Image.open method. The stream object must - # implement read and close methods. - # - # @param fp Stream file handle. - # @see Image#open - def __init__(self, fp): + """ + Adds buffering to a stream file object, in order to + provide **seek** and **tell** methods required + by the :func:`PIL.Image.Image.open` method. The stream object must + implement **read** and **close** methods. + + :param fp: Stream file handle. + + .. seealso:: modules :func:`PIL.Image.open` + """ data = fp.read() BytesIO.__init__(self, data)