Code Management

[Ben Finney]

Jens <j3nsby at gmail.com> writes:

> 1) Should I put my unittests in a subdirectory?

I find that it is best to do so even for single-module packages,
because it makes writing the 'setup.py' easier ("don't install
anything in the unit test directory").

> Does the subdirectory have to be a package?

Doing so allows you to address individual test modules and cases by
imported name, which (IIRC) enables some features of the unittest
library module. If you intend to use 'setuptools', this allows you to
specify the test suite by name, which will be run before building the
distribution files.

> 2) Does the main folder /myproject have to be a package? Should I put
> my modules directly under /myproject, or should I create a subfolder,
> for example /myproject/modules

I find this structure to be best::

  fooproject/
    setup.py
    LICENSE
    Makefile
    foo/
      __init__.py
      spam.py
      eggs.py
      bar/
        __init__.py
        beans.py
      baz/
        __init__.py
        bacon.py
    test/
      suite.py
      test_foo.py
      test_spam.py
      test_eggs.py
      test_bar_beans.py
      test_baz_bacon.py
    doc/
      README
      blah.txt
      mumble.txt

Each of the unit test modules is executable (invoking
'unittest.main()' if run as a program), and corresponds to one
importable module from the code under test; this isn't strictly
necessary but makes it much easier to manage. There is no need to
mimic the hierarchical structure of the implementation modules, so
long as each unit test module clearly shows what it's testing.

The 'test/suite.py' module is executable (again, invoking
'unittest.main()') and defines a 'unittest.TestSuite' instance for all
the test cases, named 'suite'.

The (setuptools-enabled) 'setup.py' is configured to not install the
'test' package, and to use 'test.suite.suite' as the test suite
object. It will include the documentation and LICENSE in source and
"binary" distributions.

The Python package will be installed as an importable package named
'foo', with the hierarchy of sub-packages as shown; this is pretty
automatic via setuptools (as per the documentation, anyway) with the
structure defined above.

The 'Makefile' contains targets for 'build', 'install', 'clean', etc.
and a 'test' target that runs 'python ./test/suite.py'.

-- 
 \       "Never use a long word when there's a commensurate diminutive |
  `\                                 available."  -- Stan Kelly-Bootle |
_o__)                                                                  |
Ben Finney