granicus.if.org Git - postgresql/blob - doc/src/sgml/plpython.sgml

   1 <!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.2 2001/09/10 21:58:47 petere Exp $ -->
   2
   3 <chapter id="plpython">
   4  <title>PL/Python - Python Procedural Language</title>
   5
   6  <note>
   7   <para>
   8    This chapter is not fully developed yet.
   9   </para>
  10  </note>
  11
  12  <sect1 id="plpython-install">
  13   <title>Installation</title>
  14
  15   <para>
  16    ... needs to be worked out.
  17   </para>
  18  </sect1>
  19
  20  <sect1 id="plpython-using">
  21   <title>Using</title>
  22
  23   <para>
  24    There are sample functions in
  25    <filename>plpython_function.sql</filename>.  The Python code you
  26    write gets transformed into a function.  E.g.,
  27 <programlisting>
  28 CREATE FUNCTION myfunc(text) RETURNS text AS
  29 'return args[0]'
  30 LANGUAGE 'plpython';
  31 </programlisting>
  32
  33    gets transformed into
  34
  35 <programlisting>
  36 def __plpython_procedure_myfunc_23456():
  37         return args[0]
  38 </programlisting>
  39
  40    where 23456 is the Oid of the function.
  41   </para>
  42
  43   <para>
  44    If you do not provide a return value, Python returns the default
  45    <symbol>None</symbol> which may or may not be what you want.  The
  46    language module translates Python's None into SQL NULL.
  47   </para>
  48
  49   <para>
  50    PostgreSQL function variables are available in the global
  51    <varname>args</varname> list.  In the <function>myfunc</function>
  52    example, <varname>args[0]</> contains whatever was passed in as the text
  53    argument.  For <literal>myfunc2(text, integer)</literal>, <varname>args[0]</>
  54    would contain the <type>text</type> variable and <varname>args[1]</varname> the <type>integer</type> variable.
  55   </para>
  56
  57   <para>
  58    The global dictionary SD is available to store data between
  59    function calls.  This variable is private static data.  The global
  60    dictionary GD is public data, available to all python functions
  61    within a backend.  Use with care.  When the function is used in a
  62    trigger, the triggers tuples are in <literal>TD["new"]</literal> and/or <literal>TD["old"]</literal>
  63    depending on the trigger event.  Return 'None' or "OK" from the
  64    python function to indicate the tuple is unmodified, "SKIP" to
  65    abort the event, or "MODIFIED" to indicate you've modified the
  66    tuple.  If the trigger was called with arguments they are available
  67    in <literal>TD["args"][0] to TD["args"][(n -1)]</literal>.
  68   </para>
  69
  70   <para>
  71    Each function gets its own restricted execution object in the
  72    Python interpreter, so that global data and function arguments from
  73    <function>myfunc</function> are not available to
  74    <function>myfunc2</function>.  The exception is the data in the GD
  75    dictionary, as mentioned above.
  76   </para>
  77
  78   <para>
  79    The PL/Python language module automatically imports a Python module
  80    called <literal>plpy</literal>.  The functions and constants in
  81    this module are available to you in the Python code as
  82    <literal>plpy.<replaceable>foo</replaceable></literal>.  At present
  83    <literal>plpy</literal> implements the functions
  84    <literal>plpy.error("msg")</literal>,
  85    <literal>plpy.fatal("msg")</literal>,
  86    <literal>plpy.debug("msg")</literal>, and
  87    <literal>plpy.notice("msg")</literal>.  They are mostly equivalent
  88    to calling <literal>elog(<replaceable>LEVEL</>, "msg")</literal>,
  89    where <replaceable>LEVEL</> is DEBUG, ERROR, FATAL or NOTICE.
  90    <function>plpy.error</function> and <function>plpy.fatal</function>
  91    actually raise a Python exception which, if uncaught, causes the
  92    PL/Python module to call <literal>elog(ERROR, msg)</literal> when
  93    the function handler returns from the Python interpreter.  Long
  94    jumping out of the Python interpreter is probably not good.
  95    <literal>raise plpy.ERROR("msg")</literal> and <literal>raise
  96    plpy.FATAL("msg")</literal> are equivalent to calling
  97    <function>plpy.error</function> or <function>plpy.fatal</function>.
  98   </para>
  99
 100   <para>
 101    Additionally, the <literal>plpy</literal> module provides two functions called
 102    <function>execute</function> and <function>prepare</function>.
 103    Calling <function>plpy.execute</function> with a query string, and
 104    an optional limit argument, causes that query to be run, and the
 105    result returned in a result object.  The result object emulates a
 106    list or dictionary object.  The result object can be accessed by
 107    row number, and field name.  It has these additional methods:
 108    <function>nrows()</function> which returns the number of rows
 109    returned by the query, and <function>status</function> which is the
 110    <function>SPI_exec</function> return variable.  The result object
 111    can be modified.
 112
 113 <programlisting>
 114 rv = plpy.execute("SELECT * FROM my_table", 5)
 115 </programlisting>
 116    returns up to 5 rows from my_table.  Ff my_table has a column
 117    my_field it would be accessed as
 118 <programlisting>
 119 foo = rv[i]["my_field"]
 120 </programlisting>
 121    The second function <function>plpy.prepare</function> is called
 122    with a query string, and a list of argument types if you have bind
 123    variables in the query.
 124 <programlisting>
 125 plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", [ "text" ])
 126 </programlisting>
 127    text is the type of the variable you will be passing as $1.  After
 128    preparing you use the function <function>plpy.execute</function> to
 129    run it.
 130 <programlisting>
 131 rv = plpy.execute(plan, [ "name" ], 5)
 132 </programlisting>
 133    The limit argument is optional in the call to
 134    <function>plpy.execute</function>.
 135   </para>
 136
 137   <para>
 138    When you prepare a plan using the PL/Python module it is
 139    automatically saved.  Read the SPI documentation (<xref
 140    linkend="spi">) for a description of what this means.  The take
 141    home message is if you do
 142 <programlisting>
 143 plan = plpy.prepare("SOME QUERY")
 144 plan = plpy.prepare("SOME OTHER QUERY")
 145 </programlisting>
 146    you are leaking memory, as I know of no way to free a saved plan.
 147    The alternative of using unsaved plans it even more painful (for
 148    me).
 149   </para>
 150  </sect1>
 151
 152 </chapter>