Ah damned. the package hierarchy is not pythonic. That renders all the functionality of this package completely unusable.

Come on people, don't be like this. It takes 5 seconds to rephrase a comment like this into something friendlier.

Yes, the scheduler, fetcher, processor is stand alone here, they are running in different process. But they are sharing some common libs. I haven't made a decision how to put them into a single package, and running together.

Any advice or project that I can refer to?

What is the recommended way? (Serious question, I have larger projects that I would someday like to refactor into proper packages)

There is also these guides that provide plenty of information on how packages work and best practices:

https://packaging.python.org/en/latest/distributing.html

https://github.com/pypa/sampleproject

I have "organize the code using a single top-level package".

Because the name "libs" is now installed into the global module namespace. It's better to use a less generic name.

Why isn't it a good idea? I have plenty of projects setup this way and it works well.

It looks pretty well organized to me.

The issue is that if you have two packages installed, and both use "libs" as their top-level package, they'll collide. Use "projectname.common" instead.

This is not true, you can specify package directories in setup.py.

See https://docs.python.org/2/distutils/setupscript.html#listing...

A package name != the actual name of the directory in the source tree. My point stands.