Project layout

[rlizzo]

Use this cookiecutter template to set up project structure (same one used as hangar)

https://cookiecutter-pypackage.readthedocs.io/en/latest/readme.html

Also please use the src/stockroom layout. Explanation of why from this article

The src directory is a better approach because:

• You get import parity. The current directory is implicitly included in sys.path; but not so when installing & importing from site-packages. Users will never have the same current working directory as you do.

This constraint has beneficial implications in both testing and packaging:

• You will be forced to test the installed code (e.g.: by installing in a virtualenv). This will ensure that the deployed code works (it's packaged correctly) - otherwise your tests will fail. Early. Before you can publish a broken distribution.

• You will be forced to install the distribution. If you ever uploaded a distribution on PyPI with missing modules or broken dependencies it's because you didn't test the installation. Just beeing able to successfuly build the sdist doesn't guarantee it will actually install!

• It prevents you from readily importing your code in the setup.py script. This is a bad practice because it will always blow up if importing the main package or module triggers additional imports for dependencies (which may not be available [5]). Best to not make it possible in the first place.

• Simpler packaging code and manifest. It makes manifests very simple to write (e.g.: you package a Django app that has templates or static files). Also, zero fuss for large libraries that have multiple packages. Clear separation of code being packaged and code doing the packaging.

• Without src writting a MANIFEST.in is tricky [6]. If your manifest is broken your tests will fail. It's much easier with a src directory: just add graft src in MANIFEST.in.

• Publishing a broken package to PyPI is not fun.

• Without src you get messy editable installs ("setup.py develop" or "pip install -e"). Having no separation (no src dir) will force setuptools to put your project's root on sys.path - with all the junk in it (e.g.: setup.py and other test or configuration scripts will unwittingly become importable).

• There are better tools. You don't need to deal with installing packages just to run the tests anymore. Just use tox - it will install the package for you [2] automatically, zero fuss, zero friction.

• Less chance for user mistakes - they will happen - assume nothing!

• Less chance for tools to mixup code with non-code.

Another way to put it, flat is better than nested [*] - but not for data. A file-system is just data after all - and cohesive, well normalized data structures are desirable.

[hhsecond]

@rlizzo I have updated the PR with cookiecutter template. About the layout, I have read this article earlier but did not give much attention since I liked what majority of the community followed at that time. I could see the reasons behind that extremely compelling but I am still not convinced by the saying "the benefits of using src outweigh the complexity". I am keeping this issue open to take a call on that later (before we make an alpha release, perhaps)