Committed patches from bugs #210362 and #209671 to make the distutils and python eclasses ready for eclass-manpage.

1 files changed, 62 insertions, 65 deletions

diff --git a/eclass/python.eclass b/eclass/python.eclass
index ba4b48115bb5..7bcbb1fc9afc 100644
--- a/eclass/python.eclass
+++ b/eclass/python.eclass
@@ -1,22 +1,15 @@
-# Copyright 1999-2004 Gentoo Foundation
+# Copyright 1999-2008 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo-x86/eclass/python.eclass,v 1.32 2007/05/06 22:11:12 kloeri Exp $
-#
-# Author: Alastair Tse <liquidx@gentoo.org>
-#
-# A Utility Eclass that should be inherited by anything that deals with
-# Python or Python modules.
-#
-# - Features:
-# python_version()        - sets PYVER/PYVER_MAJOR/PYVER_MINOR
-# python_tkinter_exists() - Checks for tkinter support in python
-# python_mod_exists()     - Checks if a python module exists
-# python_mod_compile()    - Compiles a .py file to a .pyc/.pyo
-# python_mod_optimize()   - Generates .pyc/.pyo precompiled scripts
-# python_mod_cleanup()    - Goes through /usr/lib*/python* to remove
-#                           orphaned *.pyc *.pyo
-# python_makesym()        - Makes /usr/bin/python symlinks
+# $Header: /var/cvsroot/gentoo-x86/eclass/python.eclass,v 1.33 2008/02/28 20:20:32 dev-zero Exp $
 
+# @ECLASS: python.eclass
+# @MAINTAINER:
+# python@gentoo.org
+#
+# original author: Alastair Tse <liquidx@gentoo.org>
+# @BLURB: A Utility Eclass that should be inherited by anything that deals with Python or Python modules.
+# @DESCRIPTION:
+# Some useful functions for dealing with python.
 inherit alternatives multilib
 
 
@@ -43,11 +36,11 @@ __python_eclass_test() {
 	echo " PYVER_MINOR: $PYVER_MINOR PYVER_MICRO: $PYVER_MICRO"
 }
 
-#
-# name:   python_disable/enable_pyc
-# desc:   tells python not to automatically recompile modules to .pyc/.pyo
-#         even if the timestamps/version stamps don't match. this is
-#         done to protect sandbox.
+# @FUNCTION: python_disable_pyc
+# @DESCRIPTION:
+# Tells python not to automatically recompile modules to .pyc/.pyo
+# even if the timestamps/version stamps don't match. This is done
+# to protect sandbox.
 #
 # note:   supported by >=dev-lang/python-2.2.3-r3 only.
 #
@@ -55,18 +48,20 @@ python_disable_pyc() {
 	export PYTHON_DONTCOMPILE=1
 }
 
+# @FUNCTION: python_enable_pyc
+# @DESCRIPTION:
+# Tells python to automatically recompile modules to .pyc/.pyo if the
+# timestamps/version stamps change
 python_enable_pyc() {
 	unset PYTHON_DONTCOMPILE
 }
 
 python_disable_pyc
 
-#
-# name:   python_version
-# desc:   run without arguments and it will export the version of python
-#         currently in use as $PYVER
-#
-
+# @FUNCTION: python_version
+# @DESCRIPTION:
+# Run without arguments and it will export the version of python
+# currently in use as $PYVER; sets PYVER/PYVER_MAJOR/PYVER_MINOR
 __python_version_extract() {
 	verstr=$1
 	export PYVER_MAJOR=${verstr:0:1}
@@ -85,21 +80,19 @@ python_version() {
 	__python_version_extract $PYVER_ALL
 }
 
-#
-# name:   python_makesym
-# desc:   run without arguments, it will create the /usr/bin/python symlinks
-#         to the latest installed version
-#
+# @FUNCTION: python_makesym
+# @DESCRIPTION:
+# Run without arguments, it will create the /usr/bin/python symlinks
+# to the latest installed version
 python_makesym() {
 	alternatives_auto_makesym "/usr/bin/python" "python[0-9].[0-9]"
 	alternatives_auto_makesym "/usr/bin/python2" "python2.[0-9]"
 }
 
-#
-# name:   python_tkinter_exists
-# desc:   run without arguments, checks if python was compiled with Tkinter
-#         support.  If not, prints an error message and dies.
-#
+# @FUNCTION: python_tkinter_exists
+# @DESCRIPTION:
+# Run without arguments, checks if python was compiled with Tkinter
+# support.  If not, prints an error message and dies.
 python_tkinter_exists() {
 	if ! python -c "import Tkinter" >/dev/null 2>&1; then
 		eerror "You need to recompile python with Tkinter support."
@@ -110,17 +103,18 @@ python_tkinter_exists() {
 	fi
 }
 
+# @FUNCTION: python_mod_exists
+# @USAGE: < module >
+# @DESCRIPTION:
+# Run with the module name as an argument. it will check if a
+# python module is installed and loadable. it will return
+# TRUE(0) if the module exists, and FALSE(1) if the module does
+# not exist.
 #
-# name:   python_mod_exists
-# desc:   run with the module name as an argument. it will check if a
-#         python module is installed and loadable. it will return
-#         TRUE(0) if the module exists, and FALSE(1) if the module does
-#         not exist.
-# exam:
+# Example:
 #         if python_mod_exists gtk; then
 #             echo "gtk support enabled"
 #         fi
-#
 python_mod_exists() {
 	[ -z "$1" ] && die "${FUNCTION} requires an argument!"
 	if ! python -c "import $1" >/dev/null 2>&1; then
@@ -129,11 +123,13 @@ python_mod_exists() {
 	return 0
 }
 
+# @FUNCTION: python_mod_compile
+# @USAGE: < file >
+# @DESCRIPTION:
+# Given a filename, it will pre-compile the module's .pyc and .pyo.
+# should only be run in pkg_postinst()
 #
-# name:   python_mod_compile
-# desc:   given a filename, it will pre-compile the module's .pyc and .pyo.
-#         should only be run in pkg_postinst()
-# exam:
+# Example:
 #         python_mod_compile ${ROOT}usr/lib/python2.3/site-packages/pygoogle.py
 #
 python_mod_compile() {
@@ -154,17 +150,18 @@ python_mod_compile() {
 	fi
 }
 
+# @FUNCTION: python_mod_optimize
+# @USAGE: [ path ]
+# @DESCRIPTION:
+# If no arguments supplied, it will recompile all modules under
+# sys.path (eg. /usr/lib/python2.3, /usr/lib/python2.3/site-packages/ ..)
+# no recursively
 #
-# name:   python_mod_optimize
-# desc:   if no arguments supplied, it will recompile all modules under
-#         sys.path (eg. /usr/lib/python2.3, /usr/lib/python2.3/site-packages/ ..)
-#         no recursively
+# If supplied with arguments, it will recompile all modules recursively
+# in the supplied directory
 #
-#         if supplied with arguments, it will recompile all modules recursively
-#         in the supplied directory
-# exam:
+# Example:
 #         python_mod_optimize ${ROOT}usr/share/codegen
-#
 python_mod_optimize() {
 	local myroot
 	# strip trailing slash
@@ -190,15 +187,15 @@ python_mod_optimize() {
 	eend $?
 }
 
+# @FUNCTION: python_mod_cleanup
+# @USAGE: [ dir ]
+# @DESCRIPTION:
+# Run with optional arguments, where arguments are directories of
+# python modules. if none given, it will look in /usr/lib/python[0-9].[0-9]
 #
-# name:   python_mod_cleanup
-# desc:   run with optional arguments, where arguments are directories of
-#         python modules. if none given, it will look in /usr/lib/python[0-9].[0-9]
-#
-#         it will recursively scan all compiled python modules in the directories
-#         and determine if they are orphaned (eg. their corresponding .py is missing.)
-#         if they are, then it will remove their corresponding .pyc and .pyo
-#
+# It will recursively scan all compiled python modules in the directories
+# and determine if they are orphaned (eg. their corresponding .py is missing.)
+# if they are, then it will remove their corresponding .pyc and .pyo
 python_mod_cleanup() {
 	local SEARCH_PATH myroot