[Distutils] local development scenarios

[Todd Greenwood-Geer]

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

Perhaps the docs could flesh out a bit more on the svn/ez_setup trick.

As an example of a full set of instructions:

- - mkdir testApp
- - touch testApp/foo.py
- - svn import testApp file:///....path to my repos
- - cd to some working area
- - svn co file:///path-to-repos/testApp testApp
- - cd testApp
- - svn propedit svn:externals .
- - enter this in to the editor, save and exit >>>
~    ez_setup svn://svn.eby-sarna.com/svnroot/ez_setup
- - modify setup.py like so:
"""
from ez_setup import use_setuptools
use_setuptools()
from setuptools import setup, find_packages

setup(name = "testApp",
~    version = "0.1",
~    description = "test",
~    packages = find_packages(exclude=['ez_setup'], ''),
~    package_dir = {'':''},
~    classifiers = [
~        "Development Status :: 1 - Alpha",
~        "Intended Audience :: Developers",
~        "License :: OSI Approved :: GNU Library or Lesser General Public
License (LGPL)",
~        "Programming Language :: Python",
~        "Topic :: Database :: Front-Ends",
~    ]
~    )
"""
- - check to see your mods to the externals : svn propget svn:externals
- - get the ez_setup files : svn update
- - do a dir listing, you should see:
~  ./ez_setup/
~  ./ez_setup/__init__.py
~  ./ez_setup/README.txt


- - Todd


Todd Greenwood-Geer wrote:
| Phillip -
|
| This is great feedback. I wrote this tutorial for myself because, in the
| course of writing a more involved application, I realized that I did not
| really understand how to use the egg/setuptools functionality. So, the
| example is definitely contrived.
|
| So, if I may summarize your guidelines:
|
| 1. Add complexity as needed
| ~ a) keep source in the root dir unless there is a need to differentiate
| ~ disparate types of files, such as source/docs/tests/etc
| ~ b) use the svn copy of ez_setup.py rather than checking this in to the
| repository
|
| 2. Clear use of names
| ~ a) use different names for packages and modules
| ~ b) again, nest only as necessary
|
| And, above all else, never admit to having a java background ;o).
|
| Thanks again. I'll re-factor as suggested and throw this at you one more
| time.
|
| -Todd
|
| Phillip J. Eby wrote:
| | At 08:27 PM 12/8/2005 -0800, Todd Greenwood-Geer wrote:
| | small_unittest.py::
| |
| |>         import small
| |>         import unittest
| |>         import doctest
| |>
| |>         def getTestSuite():
| |>                 suite = unittest.TestSuite()
| |>                 for mod in small,:
| |>                         suite.addTest(doctest.DocTestSuite(mod))
| |>                 return suite
| |>
| |>         runner = unittest.TextTestRunner()
| |>         runner.run(getTestSuite())
| |
| | If 'small.small_unittest' is the actual name of the module, then doing
| this:
| |
| |    python -c "from unittest import main; main(None)"
| | small.small_unittest.getTestSuite
| |
| | will run the test, even if it's inside an egg.  No unzipping is
| | necessary.  If the egg wasn't installed with a .pth file (i.e.
| | --multi-version or to a non-standard location), you'll need to make sure
| | it's on PYTHONPATH, along with its dependencies.
| |
| |> Here is what the src tree for the simple example looks like:
| |>
| |> dir listing::
| |>
| |>         small/src/small/test/test.txt
| |>         small/src/small/small2.py
| |>         small/src/small/small.py
| |>         small/src/small/small_unittest.pyc
| |>         small/src/small/__init__.py
| |>         small/src/small/small_unittest.py
| |>         small/src/small_unittest.py
| |
| | This looks like a duplicate.  I'm also not sure why you have a
small2, or
| | why you bother having a separate test subdirectory.  Indeed, for this
| | "small" of an example, a src/ directory is probably overkill.  For
| clarity,
| | I'd also suggest calling the topmost directory something like
| SmallExample
| | to help distinguish your project name (SmallExample) from your package
| name
| | (small).
| |
| |>         small/setup_mult.py
| |
|
| | What's this file for?
| |
| |
| |>         small/ez_setup.py
| |
| | If you're using Subversion, btw, you can use the svn:externals trick so
| | that you don't have to manually maintain this file; see the setuptools
| | manual under:
| |
| |
|
http://peak.telecommunity.com/DevCenter/setuptools#using-setuptools-without-bundling-it
| |
| |
| |
| |> The thing to note here is how small.small and small.small2 are
| referenced::
| |>
| |>         from small import small as s1
| |>         from small import small2 as s2
| |>
| |> For some reason, this gave me plenty of problems.
| |
| | It's generally not a good idea to name a module the same as a package,
| and
| | definitely not the same as a class within the module, or else it gets
| | unclear in code which one you're talking about.  In a language like
Java,
| | there's no such ambiguity because syntactically you can't refer to a
| class
| | where a package should be or vice versa, but in Python there are only
| | objects, so you should not name them all the same thing or you (and/or
| the
| | interpreter) will be confused.  :)
| |
| | Similarly, I suspect that your example has way too many files perhaps
| | because you have a Java background?  It really isn't necessary to split
| | Python projects up into so many small pieces; it just makes more
work for
| | you and doesn't get you any benefit until the files get too large to
| | conveniently work with.
| |
| |
| |> Complex Case
| |> ------------
| |>
| |> The complex case splits out the test modules into a nested package
| |> hierarchy like this:
| | ...
| |> Package Hierarchy
| |> +++++++++++++++++
| |>
| |> package hierarchy::
| |>
| |>         small/src/
| |>         small/src/size/
| |>         small/src/size/small
| |>         small/src/size/large
| |
| | Ouch.  I thought the previous example was the complex one.  ;)
| Seriously,
| | your simple example is way more complex than it needs to be.  This
bigger
| | one makes my head hurt, so I'm not going to try to comment on it
further,
| | except to suggest that its top-level directory should be named
| | "small-mult-test" since that's your project name.  Also, I'm
guessing you
| | mean your package hiearchy is size, size.small, and size.large.  The
| | small/src stuff isn't part of the package hierarchy, just the directory
| | hierarchy.
| |
| | By the way, the only reason to have a 'src' directory under your main
| | project directory is if you have a bunch of stuff that's *not* source
| code
| | there.  Such as documentation, documentation directories, test
| directories,
| | examples, etc.  Your projects here have none of those things, only a
| setup
| | script, so there's no reason to have a 'src' subdirectory; you could
just
| | put the 'small' or 'size' package directly under the project
| directory, and
| | in fact this is the most common layout for published Python packages.
|   The
| | 'src' or 'lib' subdirectory approach is mainly used by large projects
| with
| | a lot of other things in their project directory, and by people who got
| | used to that format by working on large projects.  :)
| |
| |
| |>         from size.small import small
| |>         from size.large import large
| |
| | I said I wasn't going to comment further, but this is technically a
| | repetition of my earlier comment: please don't name packages and modules
| | the same thing, you will confuse yourself and everyone else who will
| never
| | be sure if 'small' means 'size.small' or 'size.small.small' or worse,
| | 'size.small.small.small'.  Eeek!
| |
| |
| |>  * url : need to see if that works for downloading dependencies (next
| |> tutorial, not this one)
| |
| | Yes, it does, *if* you register your package with PyPI.  The URL given
| will
| | be scanned for download links when and if easy_install looks for your
| | package on PyPI.
| |
| |
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQFDmSc4z6uXX4lQc/URAoVlAKCzwzH1wr3G9x7nzPOFeWdn97oU/QCgjrqO
q9gT1aNL+ZagzWeoxqnVQIk=
=L/oc
-----END PGP SIGNATURE-----