1

Sample Repository

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
README.rst
LICENSE
setup.py
requirements.txt
sample/__init__.py
sample/core.py
sample/helpers.py
docs/conf.py
docs/index.rst
tests/test_basic.py
tests/test_advanced.py

The Actual Module

Location ./sample/ or ./sample.py

Your module package is the core focus of the repository. It should not be tucked away:

1
./sample/

If your module consists of only a single file, you can place it directly in the root of your repository:

1
./sample.py

Your library does not belong in an ambiguous src or python subdirectory.

Test Suite

Location ./test_sample.py or ./tests

Starting out, a small test suite will often exist in a single file:

1
./test_sample.py

Once a test suite grows, you can move your tests to a directory, like so:

1
2
tests/test_basic.py
tests/test_advanced.py

Obviously, these test modules must import your packaged module to test it. You can do this a few ways:

  • Expect the package to be installed in site-packages.
  • Use a simple (but explicit) path modification to resolve the package properly.

I highly recommend the latter. Requiring a developer to run setup.py develop to test an actively changing codebase also requires them to have an isolated environment setup for each instance of the codebase.

To give the individual tests import context, create a tests/context.py file:

1
2
3
4
5
import os
import sys
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(**file**), '..')))

import sample

Then, within the individual test modules, import the module like so:

1
from .context import sample

This will always work as expected, regardless of installation method.

Some people will assert that you should distribute your tests within your module itself – I disagree. It often increases complexity for your users; many test suites often require additional dependencies and runtime contexts.

setup.py example

1
2
3
4
5
6
# Download the setup.py file:
#  download with wget
wget https://raw.githubusercontent.com/navdeep-G/setup.py/master/setup.py -O setup.py

#  download with curl
curl -O https://raw.githubusercontent.com/navdeep-G/setup.py/master/setup.py