There is a problem that arises from an interaction between PyCharm's auto-import logic and the described project structure. This seems like a bug to me as it isn't in line with the project structure of a lot of existing Python projects.
So usually a Python project is structured in the following manner (using scikit-learn as an example but this also applies to scipy, numpy, gensim etc.)
scikit-learn <– top-level directory created during git clone (project root)
./benchmarks <– benchmarks (obviously)
./sklearn <– all the sources for the project
./sklearn/cluster <– sklearn cluster package containing stuff related to clustering
To get PyCharm to recognise what is what, one tends to mark some directories as Source directories in Settings - Project Structure. Given that the `scikit-learn/sklearn` directory is the root of the entire source directory tree one would be inclined to mark that as `Source`, especially when all the other directories don't really contain any sources, just auxiliary things. Doing this however will cause all the auto-imports to fail because PyCharm won't take the Source directory itself into account when auto-importing. So the `sklearn.cluster` package will be imported as just `import cluster` which will of course fail when trying to run your code. The import should of course be `from sklearn import cluster`, but PyCharm discounts the top of the Source tree.
There are two solutions to this:
1) create a separate 'src' directory under the project root and then the top level package in in there - this doesn't actually rhyme well with a lot of existing projects (sklearn, scipy, numpy, gensim, ...)
2) Mark the entire project directory as a Source directory and then Exclude all the directories that don't actually contain any sources - this is just stupid
Is there are better way to get the auto-imports to work properly?