.. _python:

*****************************************************************************
 Python MapScript Appendix
*****************************************************************************

:Author: Sean Gillies

.. contents::
    :depth: 2
    :backlinks: top

.. index::
    pair: MapScript; Python

=============================================================================
 Introduction
=============================================================================

The Python MapScript module contains some class extension methods that have
not yet been implemented for other languages.

.. index::
    triple: MapScript; Python; Classes

=============================================================================
 Classes
=============================================================================

References to sections below will be added here as the documentation grows.

.. index::
    triple: MapScript; Python; imageObj

-----------------------------------------------------------------------------
 imageObj
-----------------------------------------------------------------------------

The Python Imaging Library, http://www.pythonware.com/products/pil/, is an
indispensable tool for image manipulation.  The extensions to imageObj are
all geared towards better integration of PIL in MapScript applications.

imageObj Methods
----------------

imageObj( PyObject arg1, PyObject arg2 [, PyObject arg3 ] ) : imageObj_
    Create a new instance which is either empty or read from a Python
    file-like object that refers to a GD format image.
    
    The constructor has 2 different modes.  In the blank image mode, arg1
    and arg2 should be the desired width and height in pixels, and the 
    optional arg3 should be either an instance of outputFormatObj or
    a GD driver name as a shortcut to a format.  In the image file mode,
    arg1 should be a filename or a Python file or file-like object.  If
    the file-like object does not have a "seek" attribute (such as a
    urllib resource handle), then a GD driver name *must* be provided as
    arg2.
    
    Here's an example of creating a 320 pixel wide by 240 pixel high JPEG
    using the constructor's blank image mode::

        image = mapscript.imageObj(320, 240, 'GD/JPEG')
        
    In image file mode, interesting values of *arg1* to try are instances
    of *StringIO*::

        s = StringIO()
        pil_image.save(s)    # Save an image manipulated with PIL
        ms_image = imageObj(s)

    Or the file-like object returned from *urlopen*

    ::
        
        url = urllib.urlopen('http://mapserver.gis.umn.edu/bugs/ant.jpg')
        ms_image = imageObj(url, 'GD/JPEG')


write( [ PyObject file ] ) : void
    Write image data to a Python file-like object.  Default is stdout.

.. index::
    triple: MapScript; Python; pointObj

------------------------------------------------------------------------------
 pointObj
------------------------------------------------------------------------------

pointObj Methods
----------------

__str__() : string
    Return a string formatted like

    ::

        { 'x': %f , 'y': %f }

    
    with the coordinate values substituted appropriately.  Usage example:

    ::

        >>> p = mapscript.pointObj(1, 1)
        >>> str(p)
        { 'x': 1.000000 , 'y': 1.000000 }


    Note that the return value can be conveniently eval'd into a Python
    dictionary:

    ::

        >>> p_dict = eval(str(p))
        >>> p_dict['x']
        1.000000


.. index::
    triple: MapScript; Python; rectObj

------------------------------------------------------------------------------
 rectObj
------------------------------------------------------------------------------

rectObj Methods
---------------

__contains__( pointObj point ) : boolean
    Returns True if *point* is inside the rectangle, otherwise returns False.

    ::

        >>> r = mapscript.rectObj(0, 0, 1, 1)
        >>> p = mapscript.pointObj(2, 0)       # outside
        >>> p in r
        False
        >>> p not in r
        True

    
__str__() : string
    Return a string formatted like

    ::

        { 'minx': %f , 'miny': %f , 'maxx': %f , 'maxy': %f }

    
    with the bounding values substituted appropriately.  Usage example:

    ::

        >>> r = mapscript.rectObj(0, 0, 1, 1)
        >>> str(r)
        { 'minx': 0.000000 , 'miny': 0.000000 , 'maxx': 1.000000 , 'maxy': 1.000000 }


    Note that the return value can be conveniently eval'd into a Python
    dictionary:

    ::

        >>> r_dict = eval(str(r))
        >>> r_dict['minx']
        0.000000


.. index::
    triple: MapScript; Python; Exception handling

=============================================================================
 Exception Handling
=============================================================================

The Python MapScript module maps a few MapServer errors into Python exceptions.  
Attempting to load a non-existent mapfile raises an 'IOError', for example

::

    >>> import mapscript
    >>> mapfile = '/no/such/file.map'
    >>> m = mapscript.mapObj(mapfile)
    Traceback (most recent call last):
      File "<stdin>", line 1, in ?
      File "/usr/lib/python2.3/site-packages/mapscript.py", line 799, in __init__
        newobj = _mapscript.new_mapObj(*args)
    IOError: msLoadMap(): Unable to access file. (/no/such/file.map)
    >>>

The message of the error is written by 'msSetError' and so is the same message that 
CGI mapserv users see in error logs.

