General overview

The Python packaging system is known as "distutils", and the hallmark of a Python package using distutils is the presence of a setup.py file. (One can think of the setup.py file as the Python equivalent of a Makefile.) Although distutils is straightforward to use by directly running the setup.py with the appropriate arguments, the distutils eclass makes the process much simpler (and dramatically lowers the chance of sandbox violations). For example, for the dev-python/id3-py package the body of the ebuild (other than the header and URIs) could have been written as just:

inherit distutils

DOCS="CHANGES"

Any files listed in ${DOCS} will be put in the docs directory when installed. Note that older versions of the distutils eclass used ${mydoc} instead, but the preferred variable is DOCS.

In practice, some tweaking is often required in the src_compile() or, more commonly, in the src_install() steps, and the distutils eclass provides the distutils_src_compile() and the distutils_src_install() convenience functions:

src_compile() {
    distutils_src_compile
    # ...
}

src_install() {
    # From the docutils ebuild
    distutils_src_install
    cd "${S}/tools"
    for tool in *.py; do
        newbin ${tool} docutils-${tool}
    done

    # ...
}

Tkinter (Tk) support

Until Portage gains the long-requested ability to depend on USE flags, ebuild authors who package graphical Python programs will probably need to check at emerge-time whether or not Python was compiled with support for Tkinter. Since Tkinter requires Tk, which requires X, default Python builds do not include Tkinter. It's easy enough to check:

pkg_setup() {
    distutils_python_tkinter
}