Changeset 3641

Timestamp:

18/10/08 19:15:39 (3 months ago)

Author:

dmeyer

Message:

create imlib2 sphinx doc

Location:

trunk

Files:

• doc/index.rst (modified) (1 diff)
• imlib2/doc/Makefile (added)
• imlib2/doc/conf.py (added)
• imlib2/doc/epydoc (deleted)
• imlib2/doc/font.rst (added)
• imlib2/doc/image.rst (added)
• imlib2/doc/index.rst (added)
• imlib2/setup.py (modified) (1 diff)
• imlib2/src/font.py (modified) (3 diffs)
• imlib2/src/image.py (modified) (29 diffs)

trunk/doc/index.rst

@@ -135 +135 @@
 ^^^^^^^^^^
 
-This module has no description yet
-
-* Detailed documentation is unavailable.
+kaa.imlib2 is a simple Python wrapper around imlib2 for fast image
+processing.
+
+* See `kaa.imlib2 documentation <imlib2/index.html>`_ for details.
 * Download the latest `release of kaa.imlib2
   <http://sourceforge.net/project/showfiles.php?group_id=46652&package_id=216046>`_

trunk/imlib2/setup.py

@@ -61 +61 @@
 
 setup(module      = 'imlib2',
-      version     = '0.2.3',
+      version     = '0.2.4',
       license     = 'LGPL',
       summary     = 'Python bindings for Imlib2',
-      epydoc      = [ 'doc/epydoc' ],
       rpminfo     = {
           'requires':       'python-kaa-base >= 0.1.2, imlib2 >= 1.2.1',

trunk/imlib2/src/font.py

@@ -83 +83 @@
         """
         Get the font metrics for the specified text as rendered by the
-        current font.
-
-        Arguments:
-          text: the text for which to retrieve the metric.
-
-        Returns: a 4-tuple containing the width, height, horizontal advance,
-                 and vertical advance of the text when rendered.
+        current font. The given text is used to retrieve the
+        metric. The functions returns a 4-tuple containing the width,
+        height, horizontal advance, and vertical advance of the text
+        when rendered.
         """
         return self._font.get_text_size(utf8(text))
@@ -96 +93 @@
     def set_color(self, color):
         """
-        Sets the default color for text rendered with this font.
-
-        Arguments:
-            color: a 3- or 4-tuple holding the red, green, blue, and alpha
-                   values of the color in which to render text with this
-                   font context.  If color is a 3-tuple, the implied alpha
-                   is 255.
+        Sets the default color for text rendered with this font. Color
+        is a 3- or 4-tuple holding the red, green, blue, and alpha
+        values of the color in which to render text with this font
+        context.  If color is a 3-tuple, the implied alpha is 255.
         """
         if len(color) == 3:
@@ -123 +117 @@
         """
         Set a text style. Based on the style different color parameter
-        need to be set.
+        need to be set. Depending on the style additional parameter
+        must be set:
 
-        Arguments:
-            style:   the style to use (disable with TEXT_STYLE_PLAIN)
-            shadow:  shadow color for TEXT_STYLE_SHADOW, TEXT_STYLE_OUTLINE_SHADOW,
-                     TEXT_STYLE_FAR_SHADOW, TEXT_STYLE_OUTLINE_SOFT_SHADOW,
-                     TEXT_STYLE_SOFT_SHADOW and TEXT_STYLE_FAR_SOFT_SHADOW
-            outline: outline color for TEXT_STYLE_OUTLINE, TEXT_STYLE_SOFT_OUTLINE,
-                     TEXT_STYLE_OUTLINE_SHADOW and TEXT_STYLE_OUTLINE_SOFT_SHADOW
-            glow:    glow color 1 for TEXT_STYLE_GLOW
-            glow2:   glow color 2 for TEXT_STYLE_GLOW
+        * TEXT_STYLE_PLAIN
+        * TEXT_STYLE_SHADOW, requires shadow
+        * TEXT_STYLE_OUTLINE, requires outline
+        * TEXT_STYLE_SOFT_OUTLINE, requires outline
+        * TEXT_STYLE_GLOW, requires glow, glow2
+        * TEXT_STYLE_OUTLINE_SHADOW, requires shadow, outline
+        * TEXT_STYLE_FAR_SHADOW, requires shadow
+        * TEXT_STYLE_OUTLINE_SOFT_SHADOW, requires shadow, outline
+        * TEXT_STYLE_SOFT_SHADOW, requires shadow
+        * TEXT_STYLE_FAR_SOFT_SHADOW, requires shadow
         """
         self.style = style

trunk/imlib2/src/image.py

@@ -55 +55 @@
 class Image(object):
     """
-    Imlib2 Image class.  The constructor can be called directly, or a new
-    Image object may be created via the new() and open() module functions.
+    Imlib2 Image class. The constructor can be called directly, or a
+    new Image object may be created via the new() and open() module
+    functions.  Instantiate the image from another Image instance, an
+    instance of the backend's image class or type, or a file name from
+    which to load the image.
     """
 
@@ -62 +65 @@
         """
         Create a new Image object.
-
-        @param image_or_filename: Instantiate the image from another Image
-               instance, an instance of the backend's image
-               class or type, or a file name from which to load
-               the image.
         """
         if type(image_or_filename) in types.StringTypes:
@@ -86 +84 @@
         """
         Supports these attributes:
-
-         - B{size}: tuple containing the width and height of the image
-         - B{width}: width of the image
-         - B{height}: height of the image
-         - B{format}: format of the image if loaded from file (e.g. PNG, JPEG)
-         - B{rowstride}: number of bytes per row of pixels
-         - B{has_alpha}: True if the image has an alpha channel, False otherwise
-         - B{filename}: filename if loaded from file
+         - size: tuple containing the width and height of the image
+         - width: width of the image
+         - height: height of the image
+         - format: format of the image if loaded from file (e.g. PNG, JPEG)
+         - rowstride: number of bytes per row of pixels
+         - has_alpha: True if the image has an alpha channel, False otherwise
+         - filename: filename if loaded from file
         """
         if attr in ('width', 'height', 'format', 'mode', 'filename', 'rowstride'):
@@ -121 +118 @@
     def get_raw_data(self, format = 'BGRA', write = False):
         """
-        Returns raw image data for read only access.
-
-        @param format: pixel format of the raw data to be returned.  If 'format' is
-            not a supported format, ValueError is raised.  Format
-            can be any combination of RGB or RGBA.
-
-        @return: A buffer object representing the raw pixel data.  The buffer
-            will be a writable buffer if 'write' was True or if the
-            'format' was non-native (i.e. something other than BGRA).  If
-            'format' was BGRA and 'write' was True, you'll need to call
-            put_back_raw_data() when you're done writing to the buffer.
+        Returns raw image data for read only access. *format* is pixel
+        format of the raw data to be returned. If it is not a
+        supported format, ValueError is raised. Format can be any
+        combination of RGB or RGBA. The function returns a buffer
+        object representing the raw pixel data.  The buffer will be a
+        writable buffer if 'write' was True or if the 'format' was
+        non-native (i.e. something other than BGRA).  If 'format' was
+        BGRA and 'write' was True, you'll need to call
+        put_back_raw_data() when you're done writing to the buffer.
         """
         if False in map(lambda x: x in 'RGBA', list(format)):
@@ -148 +143 @@
     def scale(self, (w, h), src_pos = (0, 0), src_size = (-1, -1)):
         """
-        Scale the image and return a new image.
-
-        @param w,h: the width and height of the new image.  If either argument
-                is -1, that dimension is calculated from the other dimension
-                while retaining the original aspect ratio.
-
-        @return: a new Image instance representing the scaled image.
+        Scale the image and return a new image. If either width or
+        height is -1, that dimension is calculated from the other
+        dimension while retaining the original aspect ratio.
         """
         src_w, src_h = src_size
@@ -176 +167 @@
     def crop(self, (x, y), (w, h)):
         """
-        Crop the image and return a new image.
-
-        Arguments:
-          x, y, w, h: represents the left, top, width, height region in
-                      the image.
-
-        Returns: a new Image instance representing the cropped image.
+        return a new Image which is croped at x,y with the given size.
         """
         return self.scale((w, h), (x, y), (w, h) )
@@ -189 +174 @@
     def rotate(self, angle):
         """
-        Rotate the image and return a new image.
-
-        @param angle: the angle in degrees by which to rotate the image.
-        @return: a new Image instance representing the rotated image.
-
-        @bug: imlib2's rotate works all wonky.  Doesn't act how I expect.
+        Rotate the image by the angle in degrees and return a new
+        image. Note: imlib2's rotate works all wonky.  Doesn't act how
+        expected for angles different than 90, 180 and 270.
         """
         return Image(self._image.rotate(angle * math.pi / 180))
@@ -201 +183 @@
     def orientate(self, orientation):
         """
-        Performs 90 degree rotations on the image.
-
-        @param orientation:
-          - 0: no rotation;
-          - 1: rotate clockwise 90 degrees,
-          - 2: rotate clockwise 180 degrees;
-          - 3: rotates clockwise 270 degrees.
-        @return: None
+        Performs 90 degree rotations on the image. Possible values are
+        0 (no rotation), 1 (rotate clockwise 90 degrees), 2 (rotate
+        clockwise 180 degrees) and 3 (rotates clockwise 270 degrees).
         """
         self._image.orientate(orientation)
@@ -217 +194 @@
         """
         Flips the image on its horizontal axis.
-
-        @return: None.
         """
         self._image.flip(True, False, False)
@@ -227 +202 @@
         """
         Flips the image on its vertical axis.
-
-        @return: None.
         """
         self._image.flip(False, True, False)
@@ -237 +210 @@
         """
         Flips the image on along its diagonal.
-
-        @return: None.
         """
         self._image.flip(False, False, True)
@@ -247 +218 @@
         """
         Blur the image
-
-        @return: None.
         """
         self._image.blur(radius)
@@ -257 +226 @@
         """
         Sharpen the image
-
-        @return: None.
         """
         self._image.sharpen(radius)
@@ -266 +233 @@
     def scale_preserve_aspect(self, (w, h)):
         """
-        Scales the image while retaining the original aspect ratio and return
-        a new image.
-
-        Arguments:
-          w, h: the maximum size of the new image.  The new image will be as
-                large as possible, using w, h as the upper limits, while
-                retaining the original aspect ratio.
-
-        Returns: a new Image instance represented the scaled image.
+        Scales the image while retaining the original aspect ratio and
+        return a new image. The given size is the maximum size of the
+        new image.  The new image will be as large as possible, using
+        w, h as the upper limits, while retaining the original aspect
+        ratio.
         """
         if 0 in (w, h):
@@ -304 +267 @@
         Copies a region within the image.
 
-        Arguments:
-          src_pos: a tuple holding the x, y coordinates marking the top left
-                   of the region to be moved.
-             size: a tuple holding the width and height of the region to move.
-                   If either dimension is -1, then that dimension extends to
-                   the far edge of the image.
-          dst_pos: a tuple holding the x, y coordinates within the image
-                   where the region will be moved to.
-        @return: None
+        :param src_pos: a tuple holding the x, y coordinates marking the top left
+            of the region to be moved.
+        :param size: a tuple holding the width and height of the region to move.
+            If either dimension is -1, then that dimension extends to the far edge
+            of the image.
+        :param dst_pos: a tuple holding the x, y coordinates within the image
+            where the region will be moved to.
         """
         self._image.copy_rect(src_pos, size, dst_pos)
@@ -324 +285 @@
         Blends one image onto another.
 
-        @param src: the image being blended onto 'self'
-        @param dst_pos: a tuple holding the x, y coordinates where the source
+        :param src: the image being blended onto 'self'
+        :param dst_pos: a tuple holding the x, y coordinates where the source
             image will be blended onto the destination image.
-        @param src_pos: a tuple holding the x, y coordinates within the source
+        :param src_pos: a tuple holding the x, y coordinates within the source
             image where blending will start.
-        @param src_size: a tuple holding the width and height of the source
+        :param src_size: a tuple holding the width and height of the source
             image to be blended.  A value of -1 for either one
             indicates the full dimension of the source image.
-        @param alpha: the "layer" alpha that is applied to all pixels of the
+        :param alpha: the "layer" alpha that is applied to all pixels of the
             image.  If an individual pixel has an alpha of 128 and
             this value is 128, the resulting pixel will have an
@@ -339 +300 @@
             and 256 is a special value that means alpha blending is
             disabled.
-        @param merge_alpha: if True, the alpha channel is also blended.  If False,
+        :param merge_alpha: if True, the alpha channel is also blended.  If False,
             the destination image's alpha channel is untouched and
             the RGB values are compensated
-
-        @return: None.
         """
 
@@ -360 +319 @@
     def clear(self, (x, y) = (0, 0), (w, h) = (-1, -1)):
         """
-        Clears the image at the specified rectangle, resetting all pixels in
-        that rectangle to fully transparent.
-
-        Arguments:
-          x, y: left and top coordinates of the rectangle to be cleared.
-                Default is the top left corner.
-          w, h: width and height of the rectangle to be cleared.  If either
-                value is -1 then the image is cleared to the far edge.
-
-        @return: None
+        Clears the image at the specified rectangle, resetting all
+        pixels in that rectangle to fully transparent. if either width
+        or height of the rectangle to be cleared is -1 then the image
+        is cleared to the far edge. Default values clear the whole image.
         """
         x = max(0, min(self.width, x))
@@ -393 +346 @@
                    alpha channel will be modified.  The mask is drawn to the
                    full width/height of maskimg.
-
-        @return: None
         """
 
@@ -404 +355 @@
         """
         Creates a copy of the current image.
-
-        @return: a new Image instance with a copy of the current image.
         """
         return Image(self._image.clone())
@@ -412 +361 @@
     def set_font(self, font_or_font_name):
         """
-        Sets the font context to font_or_font_name.  Subsequent calls to
-        draw_text() will be rendered using this font.
-
-        Arguments:
-          font_or_fontname: either a Font object, or a string containing the
-                            font's name and size.  This string is in the
-                            form "Fontname/Size" such as "Arial/16"
-
-
-        Returns: a Font instance represent the specified font.  If
-                 'font_or_fontname' is already a Font instance, it is simply
-                 returned back to the caller.
+        Sets the font context to font_or_font_name.  Subsequent calls
+        to draw_text() will be rendered using this font.
+        font_or_fontname is either a Font object, or a string
+        containing the font's name and size.  This string is in the
+        form 'Fontname/Size' such as 'Arial/16'
+
+        The function returns a Font instance represent the specified
+        font.  If 'font_or_fontname' is already a Font instance, it is
+        simply returned back to the caller.
         """
         if type(font_or_font_name) in types.StringTypes:
@@ -434 +380 @@
     def get_font(self):
         """
-        Gets the current Font context.
-
-        @return: A Font instance as created by set_font() or None if no font
-                 context is defined.
+        Gets the current Font context. Either the Font instance as
+        created by set_font() or None if no font context is defined.
         """
         return self.font
@@ -448 +392 @@
         Draws text on the image.
 
-        @param x, y: the left/top coordinates within the current image
+        :param x, y: the left/top coordinates within the current image
             where the text will be rendered.
-        @param text: a string holding the text to be rendered.
-        @param color: a 3- or 4-tuple holding the red, green, blue, and
+        :param text: a string holding the text to be rendered.
+        :param color: a 3- or 4-tuple holding the red, green, blue, and
             alpha values of the color in which to render the
             font.  If color is a 3-tuple, the implied alpha
             is 255.  If color is None, the color of the font
             context, as specified by set_font(), is used.
-        @param font_or_fontname: either a Font object, or a string containing the
+        :param font_or_fontname: either a Font object, or a string containing the
             font's name and size.  This string is in the
             form "Fontname/Size" such as "Arial/16".  If this
             parameter is none, the font context is used, as
             specified by set_font().
-        @param style: The style to use. Id style is None, the style from
+        :param style: The style to use. Id style is None, the style from
             the font object will be used.
 
-        @return: a 4-tuple representing the width, height, horizontal advance,
+        :return: a 4-tuple representing the width, height, horizontal advance,
             and vertical advance of the rendered text.
         """
@@ -513 +457 @@
         Draws a rectangle on the image.
 
-        @param x, y: the top left corner of the rectangle.
-        @param w, h: the width and height of the rectangle.
-        @param color: a 3- or 4-tuple holding the red, green, blue, and alpha
+        :param x, y: the top left corner of the rectangle.
+        :param w, h: the width and height of the rectangle.
+        :param color: a 3- or 4-tuple holding the red, green, blue, and alpha
             values of the color in which to draw the rectangle.  If
             color is a 3-tuple, the implied alpha is 255.
-        @param fill: whether the rectangle should be filled or not.  The default
+        :param fill: whether the rectangle should be filled or not.  The default
             is true.
-
-        @return: None
         """
         if len(color) == 3:
@@ -532 +474 @@
         Draws an ellipse on the image.
 
-        @param xc, yc: the x, y coordinates of the center of the ellipse.
-        @param a, b: the horizontal and veritcal amplitude of the ellipse.
-        @param color: a 3- or 4-tuple holding the red, green, blue, and alpha
+        :param xc, yc: the x, y coordinates of the center of the ellipse.
+        :param a, b: the horizontal and veritcal amplitude of the ellipse.
+        :param color: a 3- or 4-tuple holding the red, green, blue, and alpha
             values of the color in which to draw the ellipse.  If
             color is a 3-tuple, the implied alpha is 255.
-        @param fill: whether the ellipse should be filled or not.  The default
+        :param fill: whether the ellipse should be filled or not.  The default
             is true.
-
-        @return: None
         """
         if len(color) == 3:
@@ -550 +490 @@
     def get_pixel(self, (x, y)):
         """
-        Get the color for the specified pixel.
-
-        @param x, y: Coordinates of the pixel for which to return the color.
-        @return: a 4-tuple representing the color of the pixel.  The tuple is
-            in RGBA format, or (red, green, blue, alpha).
+        Get the color for the specified pixel as a 4-tuple
+        representing the color of the pixel.  The tuple is in RGBA
+        format, or (red, green, blue, alpha).
         """
         return self._image.get_pixel((x,y))
@@ -561 +499 @@
     def set_alpha(self, has_alpha):
         """
-        Enable / disable the alpha layer.
-
-        @param has_alpha: if True, the alpha layer will be enabled, if
-            False disabled
-        @return: None
+        Enable / disable the alpha layer. If has_alpha is True, the
+        alpha layer will be enabled, if False disabled
         """
         if has_alpha:
@@ -576 +511 @@
     def save(self, filename, format = None):
         """
-        Saves the image to a file.
-
-        @param format: the format of the written file (jpg, png, etc.).  If format
-            is None, the format is gotten from the filename extension.
-
-        @return: None.
+        Saves the image to a file. The format for the written file
+        (jpg, png, etc.) is gotten from the filename extension if not
+        format is provided.
         """
         if not format:
@@ -590 +522 @@
     def as_gdk_pixbuf(self):
         """
-        Convert the image into a gdk.Pixbuf object
-
-        @return: the current image as a gdk.Pixbuf
-        @raise ImportError: if pygtk is unavailable.
+        Convert the image into a gdk.Pixbuf object. This function will
+        either return a gdk.Pixbuf object or raises an ImportError if
+        pygtk is unavailable.
         """
         import gtk