Linux/Unix > Python Essential Reference, Second Edition > B. Extending and Embedding Python > Converting Data from C to Python | See All Titles

< BACK | Make Note | Bookmark | CONTINUE >

155117184014003188065099048180054212144238241179195140058238111161105095080113234039226186

### Converting Data from C to Python

The following function is used to convert the values contained in C variables to a Python object:

    PyObject *Py_BuildValue(char *format, ...)

This constructs a Python object from a series of C variables. `format` is a string describing the desired conversion. The remaining arguments are the values of C variables to be converted.

The `format` specifier (see Table B.3) is similar to that used with the `PyArg_Parse*` functions.

##### Table B.3. Format Specifiers for `Py_BuildValue()`

Format | PyType | C Type | Description
--- | --- | --- | ---
`"s"` | String | `char *` | Null-terminated string. If the C string pointer is `NULL`, `None` is returned.
`"s#"` | String | `char *, int` | String and length. May contain null bytes. If the C string pointer is `NULL`, `None` is returned.
`"z"` | String or None | `char *` | Same as `"s"`.
`"z#"` | String or None | `char *, int` | Same as `"s#"`.
`"u"` | Unicode | `Py_UNICODE *` | Null-terminated Unicode string. If the C string pointer is `NULL`, `None` is returned.
`"u#"` | Unicode | `Py_UNICODE *, int` | Unicode string and length.
`"b"` | Integer | `char` | 8-bit integer.
`"h"` | Integer | `short` | Short 16-bit integer.
`"i"` | Integer | `int` | Integer.
`"l"` | Integer | `long` | Long integer.
`"c"` | String | `char` | Single character. Creates a Python string of length 1.
`"f"` | Float | `float` | Single-precision floating point.
`"d"` | Float | `double` | Double-precision floating point.
`"O"` | Any | `PyObject *` | Any Python object. The object is unchanged except for its reference count, which is incremented by `1`. If a `NULL` pointer is given, a `NULL` pointer is returned.
`"O&"` | Any | `converter` `,` `any` | C data processed through a converter function.
`"S"` | String | `PyObject *` | Same as `"O"`.
`"U"` | Unicode | `PyObject *` | Same as `"O"`.
`"N"` | Any | `PyObject *` | Same as `"O"` except that the reference count is not incremented.
`"(``items` `)"` | Tuple | `vars` | Creates a tuple of items. `items` is a string of format specifiers from this table. `vars` is a list of C variables corresponding to the items in `items` .
`"[``items` `]"` | List | `vars` | Creates a list of items. `items` is a string of format specifiers. `vars` is a list of C variables corresponding to the items in `items` .
`"{``items` `}"` | Dictionary | `vars` | Creates a dictionary of items.

Examples:

    Py_BuildValue("")                          None
    Py_BuildValue("i",37)                      37
    Py_BuildValue("ids",37,3.4,"hello")        (37, 3.5, "hello")
    Py_BuildValue("s#","hello",4)              "hell"
    Py_BuildValue("()")                        ()
    Py_BuildValue("(i)",37)                    (37,)
    Py_BuildValue("[ii]",1,2)                  [1,2]
    Py_BuildValue("[i,i]",1,2)                 [1,2]
    Py_BuildValue("{s:i,s:i}","x",1,"y",2)     {'x':1, 'y':2}

| Last updated on 3/28/2002 Python Essential Reference, Second Edition, © 2002 New Riders Publishing

< BACK | Make Note | Bookmark | CONTINUE >

© 2002, O'Reilly & Associates, Inc.