return_import_paths parameter

[seddonym]

We want the graph to make it easy to inspect dependencies between modules as packages rather than just as individual modules.

This needs more thought.

[seddonym]

The key is probably to allow any of the methods that return sets of modules to also allow client code to see the import paths for these modules. With the import paths, client code can then go on to use get_import_details for each direct import.

One way to do this would be to have an optional argument return_import_paths, like so:

graph.find_upstream_modules('mypackage.foo') == {
    'mypackage.bar', 'mypackage.baz',
}

graph.find_upstream_modules('mypackage.foo', return_import_paths=True) == (
    {
        'mypackage.bar', 'mypackage.baz',
    },
    (
        ('mypackage.foo', 'mypackage.elsewhere', 'mypackage.bar'),
        ('mypackage.foo', 'mypackage.baz'),
    )
)

This would be the same for find_downstream_modules, find_modules_that_directly_import and find_modules_directly_imported_by. The latter two would be not that useful unless as_packages=True is also passed (otherwise there's no way of knowing which descendants are involved in the direct import).