glass

glass copied to clipboard

Make all public GLASS functionality under the glass module name.

This needs a new structure for the documentation, and is therefore a bigger task than just importing the modules into glass/__init__.py.

Hi @ntessore , as you mention, it is straightforward to import into init.py - I don't understand the issue on documentation - "Import glass" as well as the existing "Import glass.module" will work in the test cases and examples so documentation could remain the same, because the full path can still be used in the imports.

the full path can still be used in the imports

That's right, but there should only be one canonical path for each object. Once we import everything into the top-level module, then everything should be documented as accessing the symbols from glass. The submodules would effectively become an implementation detail to organise the code.

Once everything is in the top-level module, I think we should always use functions with the module prefix, e.g. glass.partition() instead of from glass import partition; partition().

But, as you point out, the full path can still be used, so we would not break anyone's code :)

It will also be useful to add the __all__ variable in every module to differentiate public and private API.

Another thing to discuss - the repository has relative imports everywhere at the moment, but PEP8 recommends using absolute imports wherever possible -

Absolute imports are recommended, as they are usually more readable and tend to be better behaved (or at least give better error messages) if the import system is incorrectly configured (such as when a directory inside a package ends up on sys.path) ... However, explicit relative imports are an acceptable alternative to absolute imports, especially when dealing with complex package layouts where using absolute imports would be unnecessarily verbose

All of these issues are interconnected, but please let me know if they should be separate issues on the tracker.

Also, glass.core is not documented in the API reference. Is it only supposed to be used internally and not by the users directly?

It will also be useful to add the __all__ variable in every module to differentiate public and private API.

Indeed, although if only the main glass namespace contains public API going forward, we probably don't need to have __all__ in every module.

Another thing to discuss - the repository has relative imports everywhere at the moment, but PEP8 recommends using absolute imports wherever possible -

This is mostly a holdover from when GLASS was more modular and namespace-based. We can get rid of the relative imports.

All of these issues are interconnected, but please let me know if they should be separate issues on the tracker.

This issue seems as good a place as any to discuss.

Also, glass.core is not documented in the API reference. Is it only supposed to be used internally and not by the users directly?

Correct, it contains functions which are not user-facing. It should probably become part of the developer documentation (#185).

All of these issues are interconnected, but please let me know if they should be separate issues on the tracker.

I think it would be good to have, say a checklist in this issue, so this one is "finished" when all the others have been ticked off