diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml index 384b7aecc4..e8e55a39a5 100644 --- a/doc/src/sgml/plpython.sgml +++ b/doc/src/sgml/plpython.sgml @@ -1,4 +1,4 @@ - + PL/Python - Python Procedural Language @@ -153,9 +153,8 @@ PL/Python Functions - Functions in PL/Python are declared via the standard - syntax: + Functions in PL/Python are declared via the + standard syntax: CREATE FUNCTION funcname (argument-list) @@ -168,11 +167,15 @@ $$ LANGUAGE plpythonu; The body of a function is simply a Python script. When the function - is called, its arguments are passed as elements of the array - args[]; named arguments are also passed as ordinary - variables to the Python script. The result is returned from the Python code + is called, its arguments are passed as elements of the list + args; named arguments are also passed as + ordinary variables to the Python script. Use of named arguments is + usually more readable. The result is returned from the Python code in the usual way, with return or - yield (in case of a result-set statement). + yield (in case of a result-set statement). If + you do not provide a return value, Python returns the default + None. PL/Python translates + Python's None into the SQL null value. @@ -203,16 +206,6 @@ def __plpython_procedure_pymax_23456(): PostgreSQL. - - The PostgreSQL function parameters are available in - the global args list. In the - pymax example, args[0] contains - whatever was passed in as the first argument and - args[1] contains the second argument's - value. Alternatively, one can use named parameters as shown in the example - above. Use of named parameters is usually more readable. - - The arguments are set as global variables. Because of the scoping rules of Python, this has the subtle consequence that an argument @@ -248,7 +241,122 @@ $$ LANGUAGE plpythonu; PL/Python. It is better to treat the function parameters as read-only. + + + Data Values + + Generally speaking, the aim of PL/Python is to provide + a natural mapping between the PostgreSQL and the + Python worlds. This informs the data mapping rules described + below. + + + + Data Type Mapping + + Function arguments are converted from their PostgreSQL type to a + corresponding Python type: + + + + PostgreSQL boolean is converted to Python bool. + + + + + + PostgreSQL smallint and int are + converted to Python int. + PostgreSQL bigint is converted + to long in Python 2 and to int in + Python 3. + + + + + + PostgreSQL real, double, + and numeric are converted to + Python float. Note that for + the numeric this loses information and can lead to + incorrect results. This might be fixed in a future + release. + + + + + + PostgreSQL bytea is converted to + Python str in Python 2 and to bytes + in Python 3. In Python 2, the string should be treated as a + byte sequence without any character encoding. + + + + + + All other data types, including the PostgreSQL character string + types, are converted to a Python str. In Python + 2, this string will be in the PostgreSQL server encoding; in + Python 3, it will be a Unicode string like all strings. + + + + + + For nonscalar data types, see below. + + + + + + + Function return values are converted to the declared PostgreSQL + return data type as follows: + + + + When the PostgreSQL return type is boolean, the + return value will be evaluated for truth according to the + Python rules. That is, 0 and empty string + are false, but notably 'f' is true. + + + + + + When the PostgreSQL return type is bytea, the + return value will be converted to a string (Python 2) or bytes + (Python 3) using the respective Python builtins, with the + result being converted bytea. + + + + + + For all other PostgreSQL return types, the returned Python + value is converted to a string using the Python + builtin str, and the result is passed to the + input function of the PostgreSQL data type. + + + + + + For nonscalar data types, see below. + + + + + Note that logical mismatches between the declared PostgreSQL + return type and the Python data type of the actual return object + are not flagged; the value will be converted in any case. + + + + + Null, None If an SQL null valuenull valuePL/Python is passed to a @@ -276,7 +384,10 @@ $$ LANGUAGE plpythonu; function, return the value None. This can be done whether the function is strict or not. + + + Arrays, Lists SQL array values are passed into PL/Python as a Python list. To return an SQL array value out of a PL/Python function, return a @@ -313,7 +424,10 @@ SELECT return_str_arr(); (1 row) + + + Composite Types Composite-type arguments are passed to the function as Python mappings. The element names of the mapping are the attribute names of the composite type. @@ -430,13 +544,10 @@ $$ LANGUAGE plpythonu; + - - If you do not provide a return value, Python returns the default - None. PL/Python translates - Python's None into the SQL null value. - - + + Set-Returning Functions A PL/Python function can also return sets of scalar or composite types. There are several ways to achieve this because @@ -516,7 +627,7 @@ $$ LANGUAGE plpythonu; - Currently, due to Python + Due to Python bug #1483133, some debug versions of Python 2.4 (configured and compiled with option --with-pydebug) @@ -532,7 +643,11 @@ $$ LANGUAGE plpythonu; + + + + Sharing Data The global dictionary SD is available to store data between function calls. This variable is private static data. @@ -579,24 +694,98 @@ $$ LANGUAGE plpythonu; When a function is used as a trigger, the dictionary - TD contains trigger-related values. - TD["event"] contains - the event as a string (INSERT, UPDATE, - DELETE, TRUNCATE, or UNKNOWN). - TD["when"] contains one of BEFORE, - AFTER, or UNKNOWN. - TD["level"] contains one of ROW, - STATEMENT, or UNKNOWN. - For a row-level trigger, the trigger - rows are in TD["new"] and/or TD["old"] - depending on the trigger event. - TD["name"] contains the trigger name, - TD["table_name"] contains the name of the table on which the trigger occurred, - TD["table_schema"] contains the schema of the table on which the trigger occurred, - and TD["relid"] contains the OID of the table on - which the trigger occurred. If the CREATE TRIGGER command - included arguments, they are available in TD["args"][0] to - TD["args"][n-1]. + TD contains trigger-related values: + + + TD["event"] + + + contains the event as a string: + INSERT, UPDATE, + DELETE, TRUNCATE, + or UNKNOWN. + + + + + + TD["when"] + + + contains one of BEFORE, AFTER, + or UNKNOWN. + + + + + + TD["level"] + + + contains one of ROW, + STATEMENT, or UNKNOWN. + + + + + + TD["new"] + TD["old"] + + + For a row-level trigger, one or both of these fields contain + the respective trigger rows, depending on the trigger event. + + + + + + TD["name"] + + + contains the trigger name. + + + + + + TD["table_name"] + + + contains the name of the table on which the trigger occurred. + + + + + + TD["table_schema"] + + + contains the schema of the table on which the trigger occurred. + + + + + + TD["relid"] + + + contains the OID of the table on which the trigger occurred. + + + + + + TD["args"] + + + If the CREATE TRIGGER command + included arguments, they are available in TD["args"][0] to + TD["args"][n-1]. + + + + @@ -617,35 +806,11 @@ $$ LANGUAGE plpythonu; The PL/Python language module automatically imports a Python module called plpy. The functions and constants in this module are available to you in the Python code as - plpy.foo. At present - plpy implements the functions - plpy.debug(msg), - plpy.log(msg), - plpy.info(msg), - plpy.notice(msg), - plpy.warning(msg), - plpy.error(msg), and - plpy.fatal(msg).elogin PL/Python - plpy.error and - plpy.fatal actually raise a Python exception - which, if uncaught, propagates out to the calling query, causing - the current transaction or subtransaction to be aborted. - raise plpy.ERROR(msg) and - raise plpy.FATAL(msg) are - equivalent to calling - plpy.error and - plpy.fatal, respectively. - The other functions only generate messages of different - priority levels. - Whether messages of a particular priority are reported to the client, - written to the server log, or both is controlled by the - and - configuration - variables. See for more information. + plpy.foo. - Additionally, the plpy module provides two + The plpy module provides two functions called execute and prepare. Calling plpy.execute with a query string and an @@ -697,7 +862,7 @@ rv = plpy.execute(plan, [ "name" ], 5) In order to make effective use of this across function calls one needs to use one of the persistent storage dictionaries SD or GD (see - ). For example: + ). For example: CREATE FUNCTION usesavedplan() RETURNS trigger AS $$ if SD.has_key("plan"): @@ -711,31 +876,34 @@ $$ LANGUAGE plpythonu; - - - - Restricted Environment - + + Utility Functions - The current version of PL/Python - functions as a trusted language only; access to the file system and - other local resources is disabled. Specifically, - PL/Python uses the Python restricted - execution environment, further restricts it to prevent the use of - the file open call, and allows only modules from a - specific list to be imported. Presently, that list includes: - array, bisect, binascii, - calendar, cmath, codecs, - errno, marshal, math, md5, - mpz, operator, pcre, - pickle, random, re, regex, - sre, sha, string, StringIO, - struct, time, whrandom, and - zlib. + The plpy module also provides the functions + plpy.debug(msg), + plpy.log(msg), + plpy.info(msg), + plpy.notice(msg), + plpy.warning(msg), + plpy.error(msg), and + plpy.fatal(msg).elogin PL/Python + plpy.error and + plpy.fatal actually raise a Python exception + which, if uncaught, propagates out to the calling query, causing + the current transaction or subtransaction to be aborted. + raise plpy.ERROR(msg) and + raise plpy.FATAL(msg) are + equivalent to calling + plpy.error and + plpy.fatal, respectively. + The other functions only generate messages of different + priority levels. + Whether messages of a particular priority are reported to the client, + written to the server log, or both is controlled by the + and + configuration + variables. See for more information. -]]> -