Ticket #970: doc.patch

File doc.patch, 13.2 KB (added by Stefan Seefeld, 15 years ago)

  • tutorial/doc/tutorial.qbk 

    ? doc.patch
? tutorial/doc/html/HTML.manifest
RCS file: /cvsroot/boost/boost/libs/python/doc/tutorial/doc/tutorial.qbk,v
retrieving revision 1.16
diff -u -r1.16 tutorial.qbk
     
    13651365
    13661366[def Py_Initialize          [@http://www.python.org/doc/current/api/initialization.html#l2h-652  Py_Initialize]]
    13671367[def Py_Finalize            [@http://www.python.org/doc/current/api/initialization.html#l2h-656  Py_Finalize]]
    1368 [def PyRun_String           [@http://www.python.org/doc/current/api/veryhigh.html#l2h-55         PyRun_String]]
    1369 [def PyRun_File             [@http://www.python.org/doc/current/api/veryhigh.html#l2h-56         PyRun_File]]
    1370 [def Py_eval_input          [@http://www.python.org/doc/current/api/veryhigh.html#l2h-58         Py_eval_input]]
    1371 [def Py_file_input          [@http://www.python.org/doc/current/api/veryhigh.html#l2h-59         Py_file_input]]
    1372 [def Py_single_input        [@http://www.python.org/doc/current/api/veryhigh.html#l2h-60         Py_single_input]]
    13731368[def Py_XINCREF             [@http://www.python.org/doc/current/api/countingRefs.html#l2h-65     Py_XINCREF]]
    13741369[def Py_XDECREF             [@http://www.python.org/doc/current/api/countingRefs.html#l2h-67     Py_XDECREF]]
    13751370[def PyImport_AppendInittab [@http://www.python.org/doc/current/api/importing.html#l2h-137       PyImport_AppendInittab]]
    … …  
    13961391
    13971392[h2 Building embedded programs]
    13981393
    1399 To be able to use embedding in your programs, they have to be linked to
    1400 both Boost.Python's and Python's static link library.
     1394To be able to embed python into your programs, you have to link to
     1395both Boost.Python's as well as Python's own runtime library.
    14011396
    1402 Boost.Python's static link library comes in two variants. Both are located
     1397Boost.Python's library comes in two variants. Both are located
    14031398in Boost's [^/libs/python/build/bin-stage] subdirectory. On Windows, the
    14041399variants are called [^boost_python.lib] (for release builds) and
    14051400[^boost_python_debug.lib] (for debugging). If you can't find the libraries,
    14061401you probably haven't built Boost.Python yet. See
    14071402[@../../../building.html Building and Testing] on how to do this.
    14081403
    1409 Python's static link library can be found in the [^/libs] subdirectory of
     1404Python's library can be found in the [^/libs] subdirectory of
    14101405your Python directory. On Windows it is called pythonXY.lib where X.Y is
    14111406your major Python version number.
    14121407
    … …  
    14441439
    14451440# Call other Python C API routines to use the interpreter.\n\n
    14461441
    1447 # Call Py_Finalize() to stop the interpreter and release its resources.
     1442[/ # Call Py_Finalize() to stop the interpreter and release its resources.]
     1443
     1444[blurb __note__ [*Note that at this time you must not call Py_Finalize() to stop the
     1445interpreter. This may be fixed in a future version of boost.python.]
     1446]
    14481447
    14491448(Of course, there can be other C++ code between all of these steps.)
    14501449
    … …  
    14611460Fortunately Boost.Python provides the [@../../../v2/handle.html handle] and
    14621461[@../../../v2/object.html object] class templates to automate the process.
    14631462
    1464 [h2 Reference-counting handles and objects]
    1465 
    1466 There are two ways in which a function in the Python/C API can return a
    1467 [^PyObject*]: as a ['borrowed reference] or as a ['new reference]. Which of
    1468 these a function uses, is listed in that function's documentation. The two
    1469 require slightely different approaches to reference-counting but both can
    1470 be 'handled' by Boost.Python.
    1471 
    1472 For a function returning a ['borrowed reference] we'll have to tell the
    1473 [^handle] that the [^PyObject*] is borrowed with the aptly named
    1474 [@../../../v2/handle.html#borrowed-spec borrowed] function. Two functions
    1475 returning borrowed references are PyImport_AddModule and PyModule_GetDict.
    1476 The former returns a reference to an already imported module, the latter
    1477 retrieves a module's namespace dictionary. Let's use them to retrieve the
    1478 namespace of the [^__main__] module:
    1479 
    1480     object main_module((
    1481         handle<>(borrowed(PyImport_AddModule("__main__")))));
    1482 
    1483     object main_namespace = main_module.attr("__dict__");
    1484 
    1485 For a function returning a ['new reference] we can just create a [^handle]
    1486 out of the raw [^PyObject*] without wrapping it in a call to borrowed. One
    1487 such function that returns a new reference is PyRun_String which we'll
    1488 discuss in the next section.
    1489 
    1490 [blurb __note__ [*Handle is a class ['template], so why haven't we been using any template parameters?]\n
    1491 \n
    1492 [^handle] has a single template parameter specifying the type of the managed object. This type is [^PyObject] 99% of the time, so the parameter was defaulted to [^PyObject] for convenience. Therefore we can use the shorthand [^handle<>] instead of the longer, but equivalent, [^handle<PyObject>].
    1493 ]
    1494 
    14951463[h2 Running Python code]
    14961464
    1497 To run Python code from C++ there is a family of functions in the API
    1498 starting with the PyRun prefix. You can find the full list of these
    1499 functions [@http://www.python.org/doc/current/api/veryhigh.html here]. They
    1500 all work similarly so we will look at only one of them, namely:
    1501 
    1502     PyObject* PyRun_String(char *str, int start, PyObject *globals, PyObject *locals)
    1503 
    1504 PyRun_String takes the code to execute as a null-terminated (C-style)
    1505 string in its [^str] parameter. The function returns a new reference to a
    1506 Python object. Which object is returned depends on the [^start] paramater.
     1465Boost.python provides three related functions to run Python code from C++.
    15071466
    1508 The [^start] parameter is the start symbol from the Python grammar to use
    1509 for interpreting the code. The possible values are:
    1510 
    1511 [table Start symbols
    1512 
    1513     [[Py_eval_input]   [for interpreting isolated expressions]]
    1514     [[Py_file_input]   [for interpreting sequences of statements]]
    1515     [[Py_single_input] [for interpreting a single statement]]
    1516 ]
     1467    object eval(str expression, object globals = object(), object locals = object())
     1468    object exec(str code, object globals = object(), object locals = object())
     1469    object exec_file(str filename, object globals = object(), object locals = object())
    15171470
    1518 When using Py_eval_input, the input string must contain a single expression
    1519 and its result is returned. When using Py_file_input, the string can
    1520 contain an abitrary number of statements and None is returned.
    1521 Py_single_input works in the same way as Py_file_input but only accepts a
    1522 single statement.
     1471eval evaluates the given expression and returns the resulting value.
     1472exec executes the given code (typically a set of statements) returning the result,
     1473and exec_file executes the code contained in the given file.
    15231474
    1524 Lastly, the [^globals] and [^locals] parameters are Python dictionaries
     1475The [^globals] and [^locals] parameters are Python dictionaries
    15251476containing the globals and locals of the context in which to run the code.
    15261477For most intents and purposes you can use the namespace dictionary of the
    15271478[^__main__] module for both parameters.
    15281479
    1529 We have already seen how to get the [^__main__] module's namespace so let's
    1530 run some Python code in it:
     1480Boost.python provides a function to import a module:
    15311481
    1532     object main_module((
    1533         handle<>(borrowed(PyImport_AddModule("__main__")))));
     1482    object import(str name)
    15341483
    1535     object main_namespace = main_module.attr("__dict__");
     1484import imports a python module (potentially loading it into the running process
     1485first), and returns it.
    15361486
    1537     handle<> ignored((PyRun_String(
     1487Let's import the [^__main__] module and run some Python code in its namespace:
    15381488
    1539         "hello = file('hello.txt', 'w')\n"
    1540         "hello.write('Hello world!')\n"
    1541         "hello.close()"
    1542 
    1543       , Py_file_input
    1544       , main_namespace.ptr()
    1545       , main_namespace.ptr())
    1546     ));
     1489    object main_module = import("__main__");
     1490    object main_namespace = main_module.attr("__dict__");
    15471491
    1548 Because the Python/C API doesn't know anything about [^object]s, we used
    1549 the object's [^ptr] member function to retrieve the [^PyObject*].
     1492    object ignored = exec("hello = file('hello.txt', 'w')\n"
     1493                          "hello.write('Hello world!')\n"
     1494                          "hello.close()",
     1495                          main_namespace);
    15501496
    15511497This should create a file called 'hello.txt' in the current directory
    15521498containing a phrase that is well-known in programming circles.
    15531499
    1554 [blurb
    1555     __note__ [*Note] that we wrap the return value of PyRun_String in a
    1556     (nameless) [^handle] even though we are not interested in it. If we didn't
    1557     do this, the the returned object would be kept alive unnecessarily. Unless
    1558     you want to be a Dr. Frankenstein, always wrap [^PyObject*]s in [^handle]s.
    1559 ]
    1560 
    1561 [h2 Beyond handles]
     1500[h2 Manipulating Python objects]
    15621501
    1563 It's nice that [^handle] manages the reference counting details for us, but
    1564 other than that it doesn't do much. Often we'd like to have a more useful
    1565 class to manipulate Python objects. But we have already seen such a class
    1566 above, and in the [@python/object.html previous section]: the aptly
    1567 named [^object] class and it's derivatives. We've already seen that they
    1568 can be constructed from a [^handle]. The following examples should further
    1569 illustrate this fact:
    1570 
    1571     object main_module((
    1572          handle<>(borrowed(PyImport_AddModule("__main__")))));
     1502Often we'd like to have a class to manipulate Python objects.
     1503But we have already seen such a class above, and in the
     1504[@python/object.html previous section]: the aptly named [^object] class
     1505and its derivatives. We've already seen that they can be constructed from
     1506a [^handle]. The following examples should further illustrate this fact:
    15731507
     1508    object main_module = import("__main__");
    15741509    object main_namespace = main_module.attr("__dict__");
    1575 
    1576     handle<> ignored((PyRun_String(
    1577 
    1578         "result = 5 ** 2"
    1579 
    1580         , Py_file_input
    1581         , main_namespace.ptr()
    1582         , main_namespace.ptr())
    1583     ));
    1584 
     1510    object ignored = exec("result = 5 ** 2", main_namespace);
    15851511    int five_squared = extract<int>(main_namespace["result"]);
    15861512
    15871513Here we create a dictionary object for the [^__main__] module's namespace.
    15881514Then we assign 5 squared to the result variable and read this variable from
    1589 the dictionary. Another way to achieve the same result is to let
    1590 PyRun_String return the result directly with Py_eval_input:
    1591 
    1592     object result((handle<>(
    1593         PyRun_String("5 ** 2"
    1594             , Py_eval_input
    1595             , main_namespace.ptr()
    1596             , main_namespace.ptr()))
    1597     ));
     1515the dictionary. Another way to achieve the same result is to use eval instead,
     1516which returns the result directly:
    15981517
     1518    object result = eval("5 ** 2");
    15991519    int five_squared = extract<int>(result);
    16001520
    1601 [blurb
    1602     __note__ [*Note] that [^object]'s member function to return the wrapped
    1603     [^PyObject*] is called [^ptr] instead of [^get]. This makes sense if you
    1604     take into account the different functions that [^object] and [^handle]
    1605     perform.
    1606 ]
    1607 
    16081521[h2 Exception handling]
    16091522
    16101523If an exception occurs in the execution of some Python code, the PyRun_String
    … …  
    16151528
    16161529    try
    16171530    {
    1618         object result((handle<>(PyRun_String(
    1619             "5/0"
    1620           , Py_eval_input
    1621           , main_namespace.ptr()
    1622           , main_namespace.ptr()))
    1623         ));
    1624 
     1531        object result = eval("5/0");
    16251532        // execution will never get here:
    16261533        int five_divided_by_zero = extract<int>(result);
    16271534    }

  • v2/exec.html 

    RCS file: /cvsroot/boost/boost/libs/python/doc/v2/exec.html,v
retrieving revision 1.3
diff -u -r1.3 exec.html
     
    3838
    3939      <dd>
    4040        <dl class="page-index">
     41          <dt><a href="#eval-spec"><code>eval</code></a></dt>
    4142          <dt><a href="#exec-spec"><code>exec</code></a></dt>
    4243          <dt><a href="#exec_file-spec"><code>exec_file</code></a></dt>
    4344        </dl>
    … …  
    5253
    5354    <h2><a name="functions"></a>Functions</h2>
    5455
     56    <h3><a name="eval-spec"></a><code>eval</code></h3>
     57    <pre>
     58object eval(str expression,
     59            object globals = object(),
     60            object locals = object());
     61    </pre>
     62    <dl class="function-semantics">
     63      <dt><b>Effects:</b>
     64        Evaluate Python expression from <code>expression</code> in the context
     65        specified by the dictionaries <code>globals</code> and <code>locals</code>.
     66      </dt>
     67      <dt><b>Returns:</b>
     68        An instance of <a href="object.html#object-spec">object</a>
     69        which holds the value of the expression.
     70      </dt>
     71    </dl>
     72
    5573    <h3><a name="exec-spec"></a><code>exec</code></h3>
    5674    <pre>
    5775object exec(str code,

  • v2/reference.html 

    RCS file: /cvsroot/boost/boost/libs/python/doc/v2/reference.html,v
retrieving revision 1.40
diff -u -r1.40 reference.html
     
    977977
    978978          <dd>
    979979            <dl class="index">
     980              <dt><a href="exec.html#eval-spec">eval</a></dt>
    980981              <dt><a href="exec.html#exec-spec">exec</a></dt>
    981982              <dt><a href="exec.html#exec_file-spec">exec_file</a></dt>
    982983            </dl>