[gentoo-dev] python-namespaces.eclass

[gentoo-dev] python-namespaces.eclass

[Arfrever Frehtes Taifersar Arahesis]

[-- Attachment #1.1: Type: Text/Plain, Size: 642 bytes --]

I would like to add python-namespaces.eclass. This eclass will be used by a small number of
special packages, which will provide Python namespaces. These packages will be used as
dependencies of other packages already present in the tree.

Ebuilds using this eclass must set PYTHON_NAMESPACES variable before inheriting this eclass.
Example (from net-zope/namespaces-zope):
  PYTHON_NAMESPACES="Products Shared Shared.DC five +zope zope.app"

This eclass provides 3 public functions:
  python-namespaces_src_install()
  python-namespaces_pkg_postinst()
  python-namespaces_pkg_postrm()

-- 
Arfrever Frehtes Taifersar Arahesis

[-- Attachment #1.2: python-namespaces.eclass --]
[-- Type: text/plain, Size: 5384 bytes --]

# Copyright 1999-2011 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

# @ECLASS: python-namespaces.eclass
# @MAINTAINER:
# Gentoo Python Project <python@gentoo.org>
# @BLURB: Eclass for packages installing Python namespaces
# @DESCRIPTION:
# The python-namespaces eclass defines phase functions for packages installing Python namespaces.

if ! has "${EAPI:-0}" 4; then
	die "EAPI=\"${EAPI}\" not supported by python-namespaces.eclass"
fi

if [[ -z "${SUPPORT_PYTHON_ABIS}" ]]; then
	die "python-namespaces.eclass cannot be used in ebuilds of packages not supporting installation for multiple Python ABIs"
fi

if [[ -z "${PYTHON_NAMESPACES}" ]]; then
	die "PYTHON_NAMESPACES variable not set"
fi

inherit python

# ================================================================================================
# ===================================== HANDLING OF METADATA =====================================
# ================================================================================================

# @ECLASS-VARIABLE: PYTHON_NAMESPACES
# @REQUIRED
# @DESCRIPTION:
# Python namespaces.
# If given namespace is prepended with "+" or "-", then "+" or "-" is prepended to corresponding
# USE flag in generated IUSE.

_python-namespaces_set_metadata() {
	local namespace parent_namespace

	_PYTHON_NAMESPACES=""
	_PYTHON_NAMESPACES_COUNT="0"
	for namespace in ${PYTHON_NAMESPACES}; do
		_PYTHON_NAMESPACES+="${_PYTHON_NAMESPACES:+ }${namespace#[+-]}"
		((_PYTHON_NAMESPACES_COUNT++))
	done

	DESCRIPTION="Python namespaces: ${_PYTHON_NAMESPACES// /, }"
	HOMEPAGE="http://www.gentoo.org/"
	SRC_URI=""

	LICENSE="public-domain"
	SLOT="0"

	if [[ "${_PYTHON_NAMESPACES_COUNT}" -ge 2 ]]; then
		IUSE="${PYTHON_NAMESPACES//./-}"
		REQUIRED_USE="|| ( ${_PYTHON_NAMESPACES//./-} )"

		for namespace in ${_PYTHON_NAMESPACES}; do
			if [[ "${namespace}" == *.* ]]; then
				parent_namespace="${namespace%.*}"
				REQUIRED_USE+=" ${namespace//./-}? ( ${parent_namespace//./-} )"
			fi
		done
	else
		IUSE=""
		REQUIRED_USE=""
	fi

	S="${WORKDIR}"
}
_python-namespaces_set_metadata
unset -f _python-namespaces_set_metadata

# ================================================================================================
# ======================================= PHASE FUNCTIONS ========================================
# ================================================================================================

EXPORT_FUNCTIONS src_install pkg_postinst pkg_postrm

_python-namespaces_get_enabled_namespaces() {
	local namespace

	if [[ "${_PYTHON_NAMESPACES_COUNT}" -ge 2 ]]; then
		for namespace in ${_PYTHON_NAMESPACES}; do
			if use ${namespace//./-}; then
				echo ${namespace}
			fi
		done
	else
		echo ${_PYTHON_NAMESPACES}
	fi
}

# @FUNCTION: python-namespaces_src_install
# @DESCRIPTION:
# Implementation of src_install() phase. This function is exported.
# This function installs __init__.py modules corresponding to Python namespaces.
python-namespaces_src_install() {
	if [[ "${EBUILD_PHASE}" != "install" ]]; then
		die "${FUNCNAME}() can be used only in src_install() phase"
	fi

	_python_check_python_pkg_setup_execution

	if [[ "$#" -ne 0 ]]; then
		die "${FUNCNAME}() does not accept arguments"
	fi

	python-namespaces_installation() {
		local namespace
		for namespace in $(_python-namespaces_get_enabled_namespaces); do
			dodir $(python_get_sitedir)/${namespace//.//} || return 1
			echo \
"try:
	import pkg_resources
	pkg_resources.declare_namespace(__name__)
	try:
		del pkg_resources
	except NameError:
		pass
except ImportError:
	import pkgutil
	__path__ = pkgutil.extend_path(__path__, __name__)
	del pkgutil" > "${ED}$(python_get_sitedir)/${namespace//.//}/__init__.py" || return 1
		done
	}
	python_execute_function \
		--action-message 'Installation of Python namespaces with $(python_get_implementation) $(python_get_version)' \
		--failure-message 'Installation of Python namespaces with $(python_get_implementation) $(python_get_version) failed' \
		python-namespaces_installation
	unset -f python-namespaces_installation
}

# @FUNCTION: python-namespaces_pkg_postinst
# @DESCRIPTION:
# Implementation of pkg_postinst() phase. This function is exported.
# This function calls python_mod_optimize() with __init__.py modules corresponding to Python namespaces.
python-namespaces_pkg_postinst() {
	if [[ "${EBUILD_PHASE}" != "postinst" ]]; then
		die "${FUNCNAME}() can be used only in pkg_postinst() phase"
	fi

	_python_check_python_pkg_setup_execution

	if [[ "$#" -ne 0 ]]; then
		die "${FUNCNAME}() does not accept arguments"
	fi

	python_mod_optimize $(for namespace in $(_python-namespaces_get_enabled_namespaces); do echo ${namespace//.//}/__init__.py; done)
}

# @FUNCTION: python-namespaces_pkg_postrm
# @DESCRIPTION:
# Implementation of pkg_postrm() phase. This function is exported.
# This function calls python_mod_cleanup() with __init__.py modules corresponding to Python namespaces.
python-namespaces_pkg_postrm() {
	if [[ "${EBUILD_PHASE}" != "postrm" ]]; then
		die "${FUNCNAME}() can be used only in pkg_postrm() phase"
	fi

	_python_check_python_pkg_setup_execution

	if [[ "$#" -ne 0 ]]; then
		die "${FUNCNAME}() does not accept arguments"
	fi

	python_mod_cleanup $(for namespace in $(_python-namespaces_get_enabled_namespaces); do echo ${namespace//.//}/__init__.py; done)
}

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

[gentoo-dev] Re: python-namespaces.eclass

[Tomáš Chvátal]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Dne 3.4.2011 19:38, Arfrever Frehtes Taifersar Arahesis napsal(a):
> I would like to add python-namespaces.eclass. This eclass will be used by a small number of
> special packages, which will provide Python namespaces. These packages will be used as
> dependencies of other packages already present in the tree.
> 
> Ebuilds using this eclass must set PYTHON_NAMESPACES variable before inheriting this eclass.
> Example (from net-zope/namespaces-zope):
>   PYTHON_NAMESPACES="Products Shared Shared.DC five +zope zope.app"
> 
> This eclass provides 3 public functions:
>   python-namespaces_src_install()
>   python-namespaces_pkg_postinst()
>   python-namespaces_pkg_postrm()
> 
Why you do so much overquoting in the conditions?

Why do you die on those arguments, just ignore them...

You could use some eclass-debug calls (see other eclasses) :)

Why do you call those set_metadata right after its creation and delete
it right away, does it save so much time it is better than doing it in
global scope?

Since it is new eclass why are not python namespaces bash array? You
could then stop counting them and so on :)
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.17 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk2YykIACgkQHB6c3gNBRYfcLACgnvv+0UVw/YeJyUxwblM72AWJ
Tl4AmgNqdcU7sto0xSqrXFEdCxufd4ik
=zy/K
-----END PGP SIGNATURE-----

[gentoo-dev] Re: python-namespaces.eclass

[Arfrever Frehtes Taifersar Arahesis]

[-- Attachment #1: Type: Text/Plain, Size: 1582 bytes --]

2011-04-03 21:28:02 Tomáš Chvátal napisał(a):
> Dne 3.4.2011 19:38, Arfrever Frehtes Taifersar Arahesis napsal(a):
> > I would like to add python-namespaces.eclass. This eclass will be used by a small number of
> > special packages, which will provide Python namespaces. These packages will be used as
> > dependencies of other packages already present in the tree.
> >
> > Ebuilds using this eclass must set PYTHON_NAMESPACES variable before inheriting this eclass.
> > Example (from net-zope/namespaces-zope):
> >   PYTHON_NAMESPACES="Products Shared Shared.DC five +zope zope.app"
> >
> > This eclass provides 3 public functions:
> >   python-namespaces_src_install()
> >   python-namespaces_pkg_postinst()
> >   python-namespaces_pkg_postrm()
> >
> Why you do so much overquoting in the conditions?

I like consistency with python.eclass and improved syntax highlighting :) .

> Why do you die on those arguments, just ignore them...

The policy for Python-related eclasses is to not ignore misusage of functions.

> You could use some eclass-debug calls (see other eclasses) :)

IMHO they are helpless in debugging. 'set -x' enabled by -d option of emerge is more helpful.

> Why do you call those set_metadata right after its creation and delete
> it right away, does it save so much time it is better than doing it in
> global scope?

It is used to have appropriate scope for local variables, so that they don't have to be unset
manually immediately after the code, in which they should exist.

-- 
Arfrever Frehtes Taifersar Arahesis

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-dev] python-namespaces.eclass

[Fabian Groffen]

On 03-04-2011 19:38:17 +0200, Arfrever Frehtes Taifersar Arahesis wrote:
> I would like to add python-namespaces.eclass. This eclass will be used by a small number of
> special packages, which will provide Python namespaces. These packages will be used as
> dependencies of other packages already present in the tree.

Could you please update it not to exceed 80 characters?
See http://devmanual.gentoo.org/ebuild-writing/file-format/index.html
caption "Indenting and Whitespace".

> inherit python
> 
> # ================================================================================================
> # ===================================== HANDLING OF METADATA =====================================
> # ================================================================================================



-- 
Fabian Groffen
Gentoo on a different level

Re: [gentoo-dev] Re: python-namespaces.eclass

[Tomáš Chvátal]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Dne 4.4.2011 01:13, Arfrever Frehtes Taifersar Arahesis napsal(a):
> 2011-04-03 21:28:02 Tomáš Chvátal napisał(a):
>> Dne 3.4.2011 19:38, Arfrever Frehtes Taifersar Arahesis napsal(a):
>>> I would like to add python-namespaces.eclass. This eclass will be used by a small number of
>>> special packages, which will provide Python namespaces. These packages will be used as
>>> dependencies of other packages already present in the tree.
>>>
>>> Ebuilds using this eclass must set PYTHON_NAMESPACES variable before inheriting this eclass.
>>> Example (from net-zope/namespaces-zope):
>>>   PYTHON_NAMESPACES="Products Shared Shared.DC five +zope zope.app"
>>>
>>> This eclass provides 3 public functions:
>>>   python-namespaces_src_install()
>>>   python-namespaces_pkg_postinst()
>>>   python-namespaces_pkg_postrm()
>>>
>> Why you do so much overquoting in the conditions?
> 
> I like consistency with python.eclass and improved syntax highlighting :) .
Improved syntax highlighting? Apart from making it a bit larger that
indeed is not a point if bash has to process and strip all the quotes
your code is to be slower than the one without them.
> 
>> Why do you die on those arguments, just ignore them...
> 
> The policy for Python-related eclasses is to not ignore misusage of functions.

It is policy defined by you that makes the code larger for no gain. You
do the same when you check if the ebuild scope is the same for the
function. These checks are not required for any aparent reason. If
developer wants to execute src_unpack in src_prepare and shoot himself
into his leg eclasses are not the one that should prevent him from doing
so. Basically you just add useless logic into the functions, so please
do not do that. (this apply for all your patches)
> 
>> You could use some eclass-debug calls (see other eclasses) :)
> 
> IMHO they are helpless in debugging. 'set -x' enabled by -d option of emerge is more helpful.
> 
Ok if you don't feel it helps the development then indeed it is not
required to set them :)

>> Why do you call those set_metadata right after its creation and delete
>> it right away, does it save so much time it is better than doing it in
>> global scope?
> 
> It is used to have appropriate scope for local variables, so that they don't have to be unset
> manually immediately after the code, in which they should exist.
> 
OOk works for me.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.17 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk2Zl7wACgkQHB6c3gNBRYeH9wCfcac24FDG2t8Z1JFZbZ8AQDSv
Oq0An3AIfm+JehVVhZksgxmwNfhWi0Sd
=0qyh
-----END PGP SIGNATURE-----

Re: [gentoo-dev] python-namespaces.eclass

[Brian Harring]

[-- Attachment #1: Type: text/plain, Size: 2458 bytes --]

On Sun, Apr 03, 2011 at 07:38:17PM +0200, Arfrever Frehtes Taifersar Arahesis wrote:
> I would like to add python-namespaces.eclass. This eclass will be used by a small number of
> special packages, which will provide Python namespaces. These packages will be used as
> dependencies of other packages already present in the tree.
> 
> Ebuilds using this eclass must set PYTHON_NAMESPACES variable before inheriting this eclass.
> Example (from net-zope/namespaces-zope):

namespaces-zope's invocation of the mod_optimize/cleanup crap isn't 
needed since it's EAPI>=3; EAPI3 preserves mtime.

What other consumers are expected for this beyond namespaces-zope?


>   PYTHON_NAMESPACES="Products Shared Shared.DC five +zope zope.app"
> 
> This eclass provides 3 public functions:
>   python-namespaces_src_install()
>   python-namespaces_pkg_postinst()
>   python-namespaces_pkg_postrm()
> 
> -- 
> Arfrever Frehtes Taifersar Arahesis
>
> # Copyright 1999-2011 Gentoo Foundation
> # Distributed under the terms of the GNU General Public License v2
> # $Header: $
> 
> # @ECLASS: python-namespaces.eclass
> # @MAINTAINER:
> # Gentoo Python Project <python@gentoo.org>
> # @BLURB: Eclass for packages installing Python namespaces
> # @DESCRIPTION:
> # The python-namespaces eclass defines phase functions for packages installing Python namespaces.

^^^ This isn't a useful description.  What is it doing to the phase 
functions?  What's the purpose for someone who isn't intimately 
familiar w/ python setuptools/namespaces?  Etc.

Seriously, I just spent a good 10 minutes digging through this crap 
trying to figure out what you were up to- that is *exactly* what the 
description should convey.

Same goes for the code; this needs to be peppered with 
clear/descriptive comments.  The description for PYTHON_NAMESPACES for 
example on it's own doesn't make clear that it screws with 
REQUIRED_USE (let alone exactly it's intent).

General commentary: If you want to do magic like this, it needs to be 
documented clearly so everyone else can figure out wtf it is exactly 
intending on doing (including what it actually is doing)- if it can't 
be documented to that level it doesn't belong in the tree, only in 
your personal overlay.

As mentioned by others, if you're going to use [[ ]] stop doing
unnecessarily quoting w/ that construct- fix your editor if it 
doesn't color it correctly.

~harring

[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] Re: python-namespaces.eclass

[Alec Warner]

2011/4/4 Tomáš Chvátal <scarabeus@gentoo.org>:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Dne 4.4.2011 01:13, Arfrever Frehtes Taifersar Arahesis napsal(a):
>> 2011-04-03 21:28:02 Tomáš Chvátal napisał(a):
>>> Dne 3.4.2011 19:38, Arfrever Frehtes Taifersar Arahesis napsal(a):
>>>> I would like to add python-namespaces.eclass. This eclass will be used by a small number of
>>>> special packages, which will provide Python namespaces. These packages will be used as
>>>> dependencies of other packages already present in the tree.
>>>>
>>>> Ebuilds using this eclass must set PYTHON_NAMESPACES variable before inheriting this eclass.
>>>> Example (from net-zope/namespaces-zope):
>>>>   PYTHON_NAMESPACES="Products Shared Shared.DC five +zope zope.app"
>>>>
>>>> This eclass provides 3 public functions:
>>>>   python-namespaces_src_install()
>>>>   python-namespaces_pkg_postinst()
>>>>   python-namespaces_pkg_postrm()
>>>>
>>> Why you do so much overquoting in the conditions?
>>
>> I like consistency with python.eclass and improved syntax highlighting :) .
> Improved syntax highlighting? Apart from making it a bit larger that
> indeed is not a point if bash has to process and strip all the quotes
> your code is to be slower than the one without them.

If you are going to complain about quotes, at least complain sanely.
The cost of 'parsing the quotes' is negligible.  It is not a question
of performance, it is a question of readability and style.

>>
>>> Why do you die on those arguments, just ignore them...
>>
>> The policy for Python-related eclasses is to not ignore misusage of functions.
>
> It is policy defined by you that makes the code larger for no gain. You
> do the same when you check if the ebuild scope is the same for the
> function. These checks are not required for any aparent reason. If
> developer wants to execute src_unpack in src_prepare and shoot himself
> into his leg eclasses are not the one that should prevent him from doing
> so. Basically you just add useless logic into the functions, so please
> do not do that. (this apply for all your patches)
>>
>>> You could use some eclass-debug calls (see other eclasses) :)
>>
>> IMHO they are helpless in debugging. 'set -x' enabled by -d option of emerge is more helpful.
>>
> Ok if you don't feel it helps the development then indeed it is not
> required to set them :)
>
>>> Why do you call those set_metadata right after its creation and delete
>>> it right away, does it save so much time it is better than doing it in
>>> global scope?
>>
>> It is used to have appropriate scope for local variables, so that they don't have to be unset
>> manually immediately after the code, in which they should exist.
>>
> OOk works for me.
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.17 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iEYEARECAAYFAk2Zl7wACgkQHB6c3gNBRYeH9wCfcac24FDG2t8Z1JFZbZ8AQDSv
> Oq0An3AIfm+JehVVhZksgxmwNfhWi0Sd
> =0qyh
> -----END PGP SIGNATURE-----
>
>

Re: [gentoo-dev] python-namespaces.eclass

[Arfrever Frehtes Taifersar Arahesis]

[-- Attachment #1: Type: Text/Plain, Size: 1383 bytes --]

2011-04-04 12:04:44 Tomáš Chvátal napisał(a):
> Dne 4.4.2011 01:13, Arfrever Frehtes Taifersar Arahesis napsal(a):
> > 2011-04-03 21:28:02 Tomáš Chvátal napisał(a):
> >> Dne 3.4.2011 19:38, Arfrever Frehtes Taifersar Arahesis napsal(a):
> >>> I would like to add python-namespaces.eclass. This eclass will be used by a small number of
> >>> special packages, which will provide Python namespaces. These packages will be used as
> >>> dependencies of other packages already present in the tree.
> >>>
> >>> Ebuilds using this eclass must set PYTHON_NAMESPACES variable before inheriting this eclass.
> >>> Example (from net-zope/namespaces-zope):
> >>>   PYTHON_NAMESPACES="Products Shared Shared.DC five +zope zope.app"
> >>>
> >>> This eclass provides 3 public functions:
> >>>   python-namespaces_src_install()
> >>>   python-namespaces_pkg_postinst()
> >>>   python-namespaces_pkg_postrm()
> >>>
> >> Why you do so much overquoting in the conditions?
> >
> > I like consistency with python.eclass and improved syntax highlighting :) .
> Improved syntax highlighting? Apart from making it a bit larger that
> indeed is not a point if bash has to process and strip all the quotes
> your code is to be slower than the one without them.

Please don't try to force other developers to use your coding style.

-- 
Arfrever Frehtes Taifersar Arahesis

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-dev] python-namespaces.eclass

[Arfrever Frehtes Taifersar Arahesis]

[-- Attachment #1: Type: Text/Plain, Size: 601 bytes --]

2011-04-04 13:48:43 Brian Harring napisał(a):
> What other consumers are expected for this beyond namespaces-zope?

dev-python/namespaces-enthought
dev-python/namespaces-peak
dev-python/namespaces-repoze
net-zope/namespaces-archetypes
net-zope/namespaces-grok
net-zope/namespaces-plone
net-zope/namespaces-silva
net-zope/namespaces-zc
net-zope/namespaces-z3c

The following packages will use both distutils.eclass and python-namespaces.eclass:
dev-python/dap
dev-python/flask
dev-python/logilab-common
dev-python/paste
net-zope/kss-core

-- 
Arfrever Frehtes Taifersar Arahesis

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-dev] Re: python-namespaces.eclass

[Jeroen Roovers]

On Mon, 4 Apr 2011 01:13:37 +0200
Arfrever Frehtes Taifersar Arahesis <Arfrever@gentoo.org> wrote:

> The policy for Python-related eclasses is to not ignore misusage of
> functions.

Funny how you keep saying that when it's obvious that the policy is just
you.


     jer

Re: [gentoo-dev] python-namespaces.eclass

[Arfrever Frehtes Taifersar Arahesis]

[-- Attachment #1: Type: Text/Plain, Size: 512 bytes --]

2011-04-04 13:48:43 Brian Harring napisał(a):
> > # @ECLASS: python-namespaces.eclass
> > # @MAINTAINER:
> > # Gentoo Python Project <python@gentoo.org>
> > # @BLURB: Eclass for packages installing Python namespaces
> > # @DESCRIPTION:
> > # The python-namespaces eclass defines phase functions for packages installing Python namespaces.
> 
> ^^^ This isn't a useful description.

IMHO it's sufficient, but could you suggest some sentences of description?

-- 
Arfrever Frehtes Taifersar Arahesis

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [gentoo-dev] python-namespaces.eclass

[Brian Harring]

[-- Attachment #1: Type: text/plain, Size: 2104 bytes --]

On Sat, Apr 30, 2011 at 11:27:47PM +0200, Arfrever Frehtes Taifersar Arahesis wrote:
> 2011-04-04 13:48:43 Brian Harring napisał(a):
> > > # @ECLASS: python-namespaces.eclass
> > > # @MAINTAINER:
> > > # Gentoo Python Project <python@gentoo.org>
> > > # @BLURB: Eclass for packages installing Python namespaces
> > > # @DESCRIPTION:
> > > # The python-namespaces eclass defines phase functions for packages installing Python namespaces.
> > 
> > ^^^ This isn't a useful description.
> 
> IMHO it's sufficient, but could you suggest some sentences of description?

It probably is sufficient for *you*- you're knee deep in the guts of 
python, and know it's purpose.  Plus you wrote the eclass ;)

The purpose of the description, and general code comments is for 
*other* folk who may be looking at that code/problem for the first 
time.  It needs to be written aimed at them.

I'd suggest doing a grep of DESCRIPTION w/in eclasses and working from 
the clearer examples- just looking at the first few examples returned, 
alternatives for example has enough in the opening description to 
understand exactly what it's for, same for apache-2.

One thing to keep in mind is that even for folk who know python, this 
is actually an area that doesn't match the normal verbage, and is a 
bit niche in it's usage- try googling 'python namespaces' sometime, 
note that it's scope discussions rather than pkgutil/distribute 
importation across multiple directories. 

To be clear, 'python namespaces' is a whole other thing from what this 
is doing- this is manipulation of importation pathways (the 
module/import hierarchy/namespace, rather than the common scope 
terminology).

Either way, rough suggestion:
"""
This eclass handles installation/creation of python 2.7 and higher 
pkgutil namespaces, and the equivalent distibute functionality.  See 
zope's (example ebuild) for examples of usage.
"""

Rewording it might be wise, but that lays out exactly what this is 
for, it's intended usage, and gives folks a pointer were to look for 
usage examples.
~brian

[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-dev] python-namespaces.eclass

[Arfrever Frehtes Taifersar Arahesis]

[-- Attachment #1: Type: Text/Plain, Size: 2228 bytes --]

2011-05-01 00:32:13 Brian Harring napisał(a):
> On Sat, Apr 30, 2011 at 11:27:47PM +0200, Arfrever Frehtes Taifersar Arahesis wrote:
> > 2011-04-04 13:48:43 Brian Harring napisał(a):
> > > > # @ECLASS: python-namespaces.eclass
> > > > # @MAINTAINER:
> > > > # Gentoo Python Project <python@gentoo.org>
> > > > # @BLURB: Eclass for packages installing Python namespaces
> > > > # @DESCRIPTION:
> > > > # The python-namespaces eclass defines phase functions for packages installing Python namespaces.
> > > 
> > > ^^^ This isn't a useful description.
> > 
> > IMHO it's sufficient, but could you suggest some sentences of description?
> 
> It probably is sufficient for *you*- you're knee deep in the guts of 
> python, and know it's purpose.  Plus you wrote the eclass ;)
> 
> The purpose of the description, and general code comments is for 
> *other* folk who may be looking at that code/problem for the first 
> time.  It needs to be written aimed at them.
> 
> I'd suggest doing a grep of DESCRIPTION w/in eclasses and working from 
> the clearer examples- just looking at the first few examples returned, 
> alternatives for example has enough in the opening description to 
> understand exactly what it's for, same for apache-2.
> 
> One thing to keep in mind is that even for folk who know python, this 
> is actually an area that doesn't match the normal verbage, and is a 
> bit niche in it's usage- try googling 'python namespaces' sometime, 
> note that it's scope discussions rather than pkgutil/distribute 
> importation across multiple directories. 
> 
> To be clear, 'python namespaces' is a whole other thing from what this 
> is doing- this is manipulation of importation pathways (the 
> module/import hierarchy/namespace, rather than the common scope 
> terminology).
> 
> Either way, rough suggestion:
> """
> This eclass handles installation/creation of python 2.7 and higher

__init__.py files generated by this eclass work with Python 2.4.
(I haven't tested them with older versions.)

> pkgutil namespaces, and the equivalent distibute functionality.  See 
> zope's (example ebuild) for examples of usage.
> """

-- 
Arfrever Frehtes Taifersar Arahesis

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 836 bytes --]