pythonic way of folder structure in python project

I like the project structre suggested in this blog. I've reproduced it in my own github repo with stub files here. Here is what it looks like:

cmdline_bootstrap/
├── docs
├── test
├── bootstrap
│   ├── __init__.py
│   ├── __main__.py
│   ├── bootstrap.py
│   └── stuff.py
├── bootstrap-runner.py
├── LICENSE
├── MANIFEST.in
├── README.rst
└── setup.py

A structure like this allows the folder bootstrap to be packaged up and distributed as a library or command line application. Having the test folders outside of the main module permits easy testing using python setup.py test. Putting the doc folder outside the main module makes it easy for github to automatically deploy documentation on github pages.

For your specific project I might do something like this inside the bootstrap folder:

cmdline_bootstrap/
├── bootstrap
│   ├── __init__.py
│   ├── __main__.py
│   ├── file_handlers: read_automation_rules.py, output_automation_results.py, __init__.py
│   ├── optimization_functions: cost_funciton_reduce_foo.py, __init__.py
│   └── bootstrap.py

...

I recommend structuring your folders by intent. For example, one folder contains all the files that handle read/writing to the file_system. Another folder might have all the different optimization functions your are trying with your automation app. You, of course, will need more folders.

Contrary to your example, I believe every folder should contain about 5 files. 1 file means you really didn't need a folder. 10 files means the intent of your folder might be to broad for the current application.

Edit:

Also of note, PEP 8 recommends the following for folder naming:

Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

Using this guidance class_a.py is preferred over classA.py. For folders file_readers is preferred over fileReaders.