===============
 Python in PHP
===============

-------------
 Users Guide
-------------

:Author:    Jon Parise
:Contact:   jon@php.net
:Date:      $Date: 2008/10/04 22:20:50 $
:Revision:  $Revision: 1.3 $

.. contents:: Contents
   :depth: 2

.. section-numbering::

Overview
========

Requirements
------------
The Python extension has the following system requirements:

- `PHP`_ version 5.2.0 or later
- `PEAR`_ installer version 1.4.3 or later

.. _PHP: http://www.php.net/
.. _PEAR: http://pear.php.net/

Installation
------------
The easiest way to install the Perforce extension is by using the PECL
installer::

    pecl install python

If you're building from source code, should use the ``--with-python``
configuration option.  If your copy of the Python hasn't been installed in one
of the default locations, you can specify it as a parameter::

    --with-python=/opt/python

More detailed information on installing PECL packages in general can be found
in the `Installation of PECL Extensions`_ section of the `PHP Manual`_.

.. _Installation of PECL Extensions: http://www.php.net/manual/install.pecl.php
.. _PHP Manual: http://www.php.net/manual/

Source Code
-----------
This package's source code is hosted the `PHP CVS repository`_.  To check out
a read-only (anonymous) copy of the source code, start by logging in to the
PHP CVS server.  The password for the ``cvsread`` account is ``phpfi``.

::

    cvs -d :pserver:cvsread@cvs.php.net:/repository login

Then you'll be able to check out the Python's extension's source code::

    cvs -d :pserver:cvsread@cvs.php.net:/repository co -d python pecl/python

A number of unit tests are included to help maintain correct and expected
behavior.  The tests can be run using PECL tool's ``run-tests`` command::

    pecl run-tests -p python

Additional unit test contributions are welcome, especially when they increase
code coverage or exercise specific use cases.

.. _PHP CVS repository: http://www.php.net/anoncvs.php

Usage
=====

INI Settings
------------

python.optimize
~~~~~~~~~~~~~~~
The ``python.optimize`` INI setting controls the Python interpreter's runtime
optimization level.  This is a global, system-wide setting and therefore can
only be set in the PHP.ini file.

When set to **0** (the default), no additional optimizations are enabled, and
the built-in ``__debug__`` flag is True.

When set to **1** (equivalent to Python's ``-O`` command line option), the
Python interpreter will generate optimized bytecode, and the built-in
``__debug__`` flag is set to False.

When set to **2** (equivalent to Python's ``-OO`` command line option), the
Python doc-strings will be removed in addition to the above optimizations.

Development and Support
=======================

Reporting Problems and Suggestions
----------------------------------
If you run into a problem or would like to make a suggestion, please use the
`PECL Bug Tracker`_.  Feel free to contact me directly for other issues, but
please try to use the bug tracker whenever possible so that others in the
community will benefit from your feedback and my responses.

- `Open Bugs`_
- `Report a New Bug`_

.. _PECL Bug Tracker: http://pecl.php.net/bugs/
.. _Open Bugs: http://pecl.php.net/bugs/search.php?cmd=display&status=Open&package_name[]=python
.. _Report a New Bug: http://pecl.php.net/bugs/report.php?package=python

Coming Soon
-----------
This section contains a list of "todo" items that will hopefully be addressed
in future releases.

- *No items at this time.*

If you have feature suggestions, please submit them using the `PECL Bug
Tracker`_.

.. vim: tabstop=4 shiftwidth=4 softtabstop=4 expandtab textwidth=78 ft=rst: