LDP/LDP/retired/PLD-Guide/python.xml

<section id='python'>
    <title>Python Packages</title>
    <abstract>
        <para>
            This section describes how to prepare packages which contain
            applications written in Python, Python modules and Python language
            itself.
        </para>
    </abstract>
    <section id='python.dist'>
        <title>What is distributed?</title>
        <para>
            There is no doubt when you create package with Python modules
            which sources are written in C language. Sources should be
            compiled for given architecture, that's all. The problem arises
            when modules are written in Python language. What should be
            distributed? Sources - *.py files? Byte compiled files - *.pyc?
            Optimized byte compiled files - *.pyo? All of them?
        </para>
        <para>
            We have decided that packages with Python modules
            should contain both, byte compiled and optimized byte compiled
            files. Yes, *.pyc and *.pyo files. PLD developers aim to 
            provide optimized software whenever it is possible.
        </para>
        <para>
            Why not to distribute only *.py files and byte compile them during
            package installation? We want to distribute prepared packages
            so user is not forced to compile the sources and such
            philosophy applies to Python, too.
        </para>
        <para>
            Why not only *.pyo files? Firstly, optimized byte compiled modules
            cannot be imported without *.pyc files.<!-- why cannot python
            do it? - explanation should be here -->
            Secondly, *.pyo do not contain docstrings - source code
            documentation.
        </para>
        <para>
            Why not only *.pyc files? As it is mentioned above, PLD
            developers do not want to deprive users of optimized software.
            We want to provide fully optimized Python modules
            as we provide packages
            optimized for many architectures. It would be not a good idea if
            users, which want to use optimized modules, have been forced
            to create them manually because it requires root privileges
            and creates files which are in <filename>/usr</filename> hierarchy
            and not in <application>RPM</application> database.
        </para>
    </section>
    <section id='python.lang'>
        <title>Python Language</title>
        <para>
        </para>
    </section>
    <section id='python.modules'>
        <title>Python Modules</title>
        <section id='python.modules.install'>
            <title><application>RPM</application> Install Section</title>
            <para>
                Python modules can be installed with
                <itemizedlist>
                    <listitem><simpara>autoconf/automake combo</simpara></listitem>
                    <listitem><simpara>distutils</simpara></listitem>
                    <listitem><simpara>other method (hand written Makefile files, manual
                    installation)</simpara></listitem>
                </itemizedlist>
            </para>
            <para>
                <application>Automake</application> 1.5 introduced Python
                support. Developers want to use the same tool for
                their projects written in Python or C and
                <application>automake</application> gives such possibility to them.
            </para>
            <para>
                Installing Python modules can be done the same way
                as installing other applications or libraries, which
                authors use <application>automake</application>.
                Just remember to pass <envar>$RPM_BUILD_ROOT</envar>
                to <envar>DESTDIR</envar>, so
                <application>make</application> will install source files
                (*.py), byte compiled (*.pyc) and optimized byte compiled
                (*.pyo) files under <envar>$RPM_BUILD_ROOT</envar>
                hierarchy.
                <example>
                    <title>
                        Installing Python modules with Makefile files
                        created with <application>automake</application>.
                    </title>
                    <screen>
%{__make} install DESTDIR=$RPM_BUILD_ROOT
                    </screen>
                </example>
            </para>
            <para>
                Python <literal role='lib'>distutils</literal>
                has ability to install optimized and
                normal byte compiled files. It can be done with
                <command>setup.py</command> script option
                <parameter>--optimize</parameter>.
                Option <parameter>--root</parameter> should
                be used too, because installed files
                should be put in <envar>$RPM_BUILD_ROOT</envar>
                directory.
                <example>
                    <title>
                        Installing Python modules in <application>RPM</application> install section
                        with <literal role='lib'>distutils</literal>
                    </title>
                    <screen>
python setup.py install --optimize=2 --root=$RPM_BUILD_ROOT
                    </screen>
                </example>
                Sometimes <literal role='lib'>distutils</literal>
                refuses to install files under
                <envar>$RPM_BUILD_ROOT</envar> hierarchy. Set
                <envar>$PYTHONPATH</envar> variable to
                <literal>$RPM_BUILD_ROOT%{py_sitedir}</literal> value
                before module installation.
            </para>
        </section>
        <section id='python.modules.groups'>
            <title><application>RPM</application> groups</title>
            <para>
                Every package is assigned to <application>RPM</application>
                group. Packages which contain developer files such as
                header files should be assigned to
                <literal role='rpm.group'>Development/Languages/Python</literal>
                group.
                Packages with just modules should be assigned to <literal
                        role='rpm.group'>Libraries/Python</literal> group.
            </para>
            <para>
                Rules used to assign
                <application>RPM</application> group to applications, apply
                to applications written in Python, too. Taking
                <application>sketch</application> for example, the
                graphics manipulation program, there is
                used <literal role='rpm.group'>X11/Application/Graphics</literal>
                group. Another example is
                <application>happydoc</application> with
                <literal role='rpm.group'>Development/Tools</literal> group or
                <application>ipython</application> with <literal
                    role='rpm.group'>Applications/Shells</literal> group.
            </para>
        </section>
    </section>
    <section id='python.macros'>
        <title>Standard <application>RPM</application> Macros</title>
	<para>Dummy...</para>
    </section>
</section>