Skip to content

Commit

Permalink
Merge pull request #1926 from hugovk/docstring
Browse files Browse the repository at this point in the history 
 Comments to docstrings (+flake8)
  • Loading branch information
@wiredfool
wiredfool committed May 24, 2016
2 parents 477841b + 9344852 commit 1c5bcec
Show file tree
Hide file tree
Showing 9 changed files with 184 additions and 213 deletions.
33 changes: 18 additions & 15 deletions PIL/ImageCms.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,16 @@
from __future__ import print_function
import sys

from PIL import Image
try:
from PIL import _imagingcms
except ImportError as ex:
# Allow error import for doc purposes, but error out when accessing
# anything in core.
from _util import deferred_error
_imagingcms = deferred_error(ex)
from PIL._util import isStringType

DESCRIPTION = """
pyCMS
Expand Down Expand Up @@ -85,16 +95,6 @@

# --------------------------------------------------------------------.

from PIL import Image
try:
from PIL import _imagingcms
except ImportError as ex:
# Allow error import for doc purposes, but error out when accessing
# anything in core.
from _util import deferred_error
_imagingcms = deferred_error(ex)
from PIL._util import isStringType

core = _imagingcms

#
Expand Down Expand Up @@ -188,10 +188,12 @@ def tobytes(self):

class ImageCmsTransform(Image.ImagePointHandler):

# Transform. This can be used with the procedural API, or with the
# standard Image.point() method.
#
# Will return the output profile in the output.info['icc_profile'].
"""
Transform. This can be used with the procedural API, or with the standard
Image.point() method.
Will return the output profile in the output.info['icc_profile'].
"""

def __init__(self, input, output, input_mode, output_mode,
intent=INTENT_PERCEPTUAL, proof=None,
Expand Down Expand Up @@ -590,7 +592,8 @@ def applyTransform(im, transform, inPlace=0):
with the transform applied is returned (and im is not changed). The
default is False.
:returns: Either None, or a new PIL Image object, depending on the value of
inPlace. The profile will be returned in the image's info['icc_profile'].
inPlace. The profile will be returned in the image's
info['icc_profile'].
:exception PyCMSError:
"""

Expand Down
151 changes: 64 additions & 87 deletions PIL/ImageDraw.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,26 +36,27 @@
from PIL import Image, ImageColor
from PIL._util import isStringType

##
# A simple 2D drawing interface for PIL images.
# <p>
# Application code should use the <b>Draw</b> factory, instead of
# directly.
"""
A simple 2D drawing interface for PIL images.
<p>
Application code should use the <b>Draw</b> factory, instead of
directly.
"""


class ImageDraw(object):

##
# Create a drawing instance.
#
# @param im The image to draw in.
# @param mode Optional mode to use for color values. For RGB
# images, this argument can be RGB or RGBA (to blend the
# drawing into the image). For all other modes, this argument
# must be the same as the image mode. If omitted, the mode
# defaults to the mode of the image.

def __init__(self, im, mode=None):
"""
Create a drawing instance.
@param im The image to draw in.
@param mode Optional mode to use for color values. For RGB
images, this argument can be RGB or RGBA (to blend the
drawing into the image). For all other modes, this argument
must be the same as the image mode. If omitted, the mode
defaults to the mode of the image.
"""
im.load()
if im.readonly:
im._copy() # make it writeable
Expand Down Expand Up @@ -100,10 +101,8 @@ def setfont(self, font):
# compatibility
self.font = font

##
# Get the current default font.

def getfont(self):
"""Get the current default font."""
if not self.font:
# FIXME: should add a font repository
from PIL import ImageFont
Expand Down Expand Up @@ -131,107 +130,84 @@ def _getink(self, ink, fill=None):
fill = self.draw.draw_ink(fill, self.mode)
return ink, fill

##
# Draw an arc.

def arc(self, xy, start, end, fill=None):
"""Draw an arc."""
ink, fill = self._getink(fill)
if ink is not None:
self.draw.draw_arc(xy, start, end, ink)

##
# Draw a bitmap.

def bitmap(self, xy, bitmap, fill=None):
"""Draw a bitmap."""
bitmap.load()
ink, fill = self._getink(fill)
if ink is None:
ink = fill
if ink is not None:
self.draw.draw_bitmap(xy, bitmap.im, ink)

##
# Draw a chord.

def chord(self, xy, start, end, fill=None, outline=None):
"""Draw a chord."""
ink, fill = self._getink(outline, fill)
if fill is not None:
self.draw.draw_chord(xy, start, end, fill, 1)
if ink is not None:
self.draw.draw_chord(xy, start, end, ink, 0)

##
# Draw an ellipse.

def ellipse(self, xy, fill=None, outline=None):
"""Draw an ellipse."""
ink, fill = self._getink(outline, fill)
if fill is not None:
self.draw.draw_ellipse(xy, fill, 1)
if ink is not None:
self.draw.draw_ellipse(xy, ink, 0)

##
# Draw a line, or a connected sequence of line segments.

def line(self, xy, fill=None, width=0):
"""Draw a line, or a connected sequence of line segments."""
ink, fill = self._getink(fill)
if ink is not None:
self.draw.draw_lines(xy, ink, width)

##
# (Experimental) Draw a shape.

def shape(self, shape, fill=None, outline=None):
# experimental
"""(Experimental) Draw a shape."""
shape.close()
ink, fill = self._getink(outline, fill)
if fill is not None:
self.draw.draw_outline(shape, fill, 1)
if ink is not None:
self.draw.draw_outline(shape, ink, 0)

##
# Draw a pieslice.

def pieslice(self, xy, start, end, fill=None, outline=None):
"""Draw a pieslice."""
ink, fill = self._getink(outline, fill)
if fill is not None:
self.draw.draw_pieslice(xy, start, end, fill, 1)
if ink is not None:
self.draw.draw_pieslice(xy, start, end, ink, 0)

##
# Draw one or more individual pixels.

def point(self, xy, fill=None):
"""Draw one or more individual pixels."""
ink, fill = self._getink(fill)
if ink is not None:
self.draw.draw_points(xy, ink)

##
# Draw a polygon.

def polygon(self, xy, fill=None, outline=None):
"""Draw a polygon."""
ink, fill = self._getink(outline, fill)
if fill is not None:
self.draw.draw_polygon(xy, fill, 1)
if ink is not None:
self.draw.draw_polygon(xy, ink, 0)

##
# Draw a rectangle.

def rectangle(self, xy, fill=None, outline=None):
"""Draw a rectangle."""
ink, fill = self._getink(outline, fill)
if fill is not None:
self.draw.draw_rectangle(xy, fill, 1)
if ink is not None:
self.draw.draw_rectangle(xy, ink, 0)

##
# Draw text.

def _multiline_check(self, text):
"""Draw text."""
split_character = "\n" if isinstance(text, type("")) else b"\n"

return split_character in text
Expand All @@ -241,9 +217,11 @@ def _multiline_split(self, text):

return text.split(split_character)

def text(self, xy, text, fill=None, font=None, anchor=None, *args, **kwargs):
def text(self, xy, text, fill=None, font=None, anchor=None,
*args, **kwargs):
if self._multiline_check(text):
return self.multiline_text(xy, text, fill, font, anchor, *args, **kwargs)
return self.multiline_text(xy, text, fill, font, anchor,
*args, **kwargs)

ink, fill = self._getink(fill)
if font is None:
Expand Down Expand Up @@ -285,10 +263,8 @@ def multiline_text(self, xy, text, fill=None, font=None, anchor=None,
top += line_spacing
left = xy[0]

##
# Get the size of a given string, in pixels.

def textsize(self, text, font=None, *args, **kwargs):
"""Get the size of a given string, in pixels."""
if self._multiline_check(text):
return self.multiline_textsize(text, font, *args, **kwargs)

Expand All @@ -306,17 +282,17 @@ def multiline_textsize(self, text, font=None, spacing=4):
return max_width, len(lines)*line_spacing


##
# A simple 2D drawing interface for PIL images.
#
# @param im The image to draw in.
# @param mode Optional mode to use for color values. For RGB
# images, this argument can be RGB or RGBA (to blend the
# drawing into the image). For all other modes, this argument
# must be the same as the image mode. If omitted, the mode
# defaults to the mode of the image.

def Draw(im, mode=None):
"""
A simple 2D drawing interface for PIL images.
@param im The image to draw in.
@param mode Optional mode to use for color values. For RGB
images, this argument can be RGB or RGBA (to blend the
drawing into the image). For all other modes, this argument
must be the same as the image mode. If omitted, the mode
defaults to the mode of the image.
"""
try:
return im.getdraw(mode)
except AttributeError:
Expand All @@ -329,15 +305,15 @@ def Draw(im, mode=None):
Outline = None


##
# (Experimental) A more advanced 2D drawing interface for PIL images,
# based on the WCK interface.
#
# @param im The image to draw in.
# @param hints An optional list of hints.
# @return A (drawing context, drawing resource factory) tuple.

def getdraw(im=None, hints=None):
"""
(Experimental) A more advanced 2D drawing interface for PIL images,
based on the WCK interface.
@param im The image to draw in.
@param hints An optional list of hints.
@return A (drawing context, drawing resource factory) tuple.
"""
# FIXME: this needs more work!
# FIXME: come up with a better 'hints' scheme.
handler = None
Expand All @@ -353,19 +329,18 @@ def getdraw(im=None, hints=None):
return im, handler


##
# (experimental) Fills a bounded region with a given color.
#
# @param image Target image.
# @param xy Seed position (a 2-item coordinate tuple).
# @param value Fill color.
# @param border Optional border value. If given, the region consists of
# pixels with a color different from the border color. If not given,
# the region consists of pixels having the same color as the seed
# pixel.

def floodfill(image, xy, value, border=None):
"Fill bounded region."
"""
(experimental) Fills a bounded region with a given color.
@param image Target image.
@param xy Seed position (a 2-item coordinate tuple).
@param value Fill color.
@param border Optional border value. If given, the region consists of
pixels with a color different from the border color. If not given,
the region consists of pixels having the same color as the seed
pixel.
"""
# based on an implementation by Eric S. Raymond
pixel = image.load()
x, y = xy
Expand Down Expand Up @@ -405,3 +380,5 @@ def floodfill(image, xy, value, border=None):
pixel[s, t] = value
newedge.append((s, t))
edge = newedge

# End of file
4 changes: 3 additions & 1 deletion PIL/ImageMath.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ def _isconstant(v):


class _Operand(object):
# wraps an image operand, providing standard operators
"""Wraps an image operand, providing standard operators"""

def __init__(self, im):
self.im = im
Expand Down Expand Up @@ -268,3 +268,5 @@ def eval(expression, _dict={}, **kw):
return out.im
except AttributeError:
return out

# End of file
10 changes: 4 additions & 6 deletions PIL/ImageMode.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,8 @@
_modes = {}


##
# Wrapper for mode strings.

class ModeDescriptor(object):
"""Wrapper for mode strings."""

def __init__(self, mode, bands, basemode, basetype):
self.mode = mode
Expand All @@ -32,10 +30,8 @@ def __str__(self):
return self.mode


##
# Gets a mode descriptor for the given mode.

def getmode(mode):
"""Gets a mode descriptor for the given mode."""
if not _modes:
# initialize mode cache
from PIL import Image
Expand All @@ -50,3 +46,5 @@ def getmode(mode):
_modes["I;16L"] = ModeDescriptor("I;16L", "I", "L", "L")
_modes["I;16B"] = ModeDescriptor("I;16B", "I", "L", "L")
return _modes[mode]

# End of file

0 comments on commit 1c5bcec

Please sign in to comment.