guidance needed: best practice for script packaging

[Alan Isaac]

This is a simple question about actual practice.
I just want to know how you (yes you) are
approaching this problem.

The problem:
What is the recommended packaging of
demo scripts or test scripts for a package
to be distributed to others to "play with".
(I.e., without "installing".)

Example:
Suppose I have the package structure:

package/
__init__.py
subpackage1/
__init__.py
moduleXX.py
subpackage2/
__init__.py
moduleYY.py

Important detail:
moduleXX uses a relative import to access moduleYY.

The goal:
I have a script test.py that I want to
distribute with the package. This script will import
moduleXX to illustrate or test the module's use.

Is it the case that this script cannot reasonably be
bundled with `package`? (I.e., within its directory
structure.)

Note:
If I put it in the `subpackage1` directory and
just import moduleXX, I will get
ValueError: Attempted relative import in non-package

Note:
If I put it in the `package` directory and
import subpackage1.moduleXX, I will get
ValueError: Attempted relative import beyond toplevel package

Here is one hack, based on a suggestion of Alex Martelli
http://mail.python.org/pipermail/pyt...ay/438250.html
and others.
- add a `scripts` subdirectory to `package`
- use path manipulation to find the directory holding `package`
- insert this directory in sys.path

This hack "works".
However it has also been claimed that this approach is an
insane for any shared code. Is it? If so, what is best practice?

Note:
I do not want to assume the package will be installed:
a user should be able to play with it without installing it.

This is a repeat question. The usual rule is, if you do not get an answer, you
are asking the question in an unhelpful way. If my question is still unclear, I
would appreciate any leads on how to clarify it.

Thank you,
Alan Isaac

[Gabriel Genellina]

En Tue, 26 Jun 2007 23:35:37 -0300, Alan Isaac <ai****@american.edu>
escribió:

This is a simple question about actual practice.
I just want to know how you (yes you) are
approaching this problem.

The problem:
What is the recommended packaging of
demo scripts or test scripts for a package
to be distributed to others to "play with".
(I.e., without "installing".)

Example:
Suppose I have the package structure:

package/
__init__.py
subpackage1/
__init__.py
moduleXX.py
subpackage2/
__init__.py
moduleYY.py

Important detail:
moduleXX uses a relative import to access moduleYY.

I put test/demo/main scripts *outside* the package - that would be the
directory containing "package" here.
This way, "import package" works, and intra-package relative references
work too.

The goal:
I have a script test.py that I want to
distribute with the package. This script will import
moduleXX to illustrate or test the module's use.

Is it the case that this script cannot reasonably be
bundled with `package`? (I.e., within its directory
structure.)

Yes, perhaps there is no reasonably/good/non-hackish way to bundle it
inside "package". At least I don't know how to do that and also keep
relative imports working at the same time, without playing with sys.path
and such things.

Here is one hack, based on a suggestion of Alex Martelli
http://mail.python.org/pipermail/pyt...ay/438250.html
and others.
- add a `scripts` subdirectory to `package`
- use path manipulation to find the directory holding `package`
- insert this directory in sys.path

I use directly the parent directory (not a "scripts" subdirectory) because
it is already in sys.path (being the current directory where the script
resides). And I have only one or two such scripts, so it's not a big
problem for me if they are not grouped in its own directory.

I do not want to assume the package will be installed:
a user should be able to play with it without installing it.

What I suggest works in this case too.

This is a repeat question. The usual rule is, if you do not get an
answer, you
are asking the question in an unhelpful way. If my question is still
unclear, I
would appreciate any leads on how to clarify it.

I read your previous post, but since I didn't feel that I had a "good"
answer I didn't reply the first time. I were waiting for someone to
enlighten me too on this topic...

(Certainly rephrasing the question is a smart move - but most people
aren't as smart as you and just keep posting the same thing over and
over...)

--
Gabriel Genellina

[Josiah Carlson]

Alan Isaac wrote:

This is a simple question about actual practice.
I just want to know how you (yes you) are
approaching this problem.
The problem:
What is the recommended packaging of
demo scripts or test scripts for a package
to be distributed to others to "play with".
(I.e., without "installing".)

Example:
Suppose I have the package structure:

package/
__init__.py
subpackage1/
__init__.py
moduleXX.py
subpackage2/
__init__.py
moduleYY.py

Important detail:
moduleXX uses a relative import to access moduleYY.

The goal:
I have a script test.py that I want to
distribute with the package. This script will import
moduleXX to illustrate or test the module's use.

Is it the case that this script cannot reasonably be
bundled with `package`? (I.e., within its directory
structure.)

Note:
If I put it in the `subpackage1` directory and
just import moduleXX, I will get
ValueError: Attempted relative import in non-package

Note:
If I put it in the `package` directory and
import subpackage1.moduleXX, I will get
ValueError: Attempted relative import beyond toplevel package

Here is one hack, based on a suggestion of Alex Martelli
http://mail.python.org/pipermail/pyt...ay/438250.html
and others.
- add a `scripts` subdirectory to `package`
- use path manipulation to find the directory holding `package`
- insert this directory in sys.path

This hack "works".
However it has also been claimed that this approach is an
insane for any shared code. Is it? If so, what is best practice?

I have used this method more than once to get around the fact that
relative imports don't work the way I want them to in this situation.
Alternatively, you could use...

package/
__init__.py #for 'import package'
test.py
shared/
__init__.py
subpackage1/
__init__.py
moduleXX.py
subpackage2/
__init__.py
moduleYY.py

And always run scripts from the package/... path or from something that
is able to 'import package'. It does force a layer of useless
namespace, but it works.
- Josiah

[Alan Isaac]

My thanks to Gabriel and Josiah.
Alan