Friday Finking: Imports, Namespaces, Poisoning, Readability

[DL Neil]

How do you prefer to balance all of the above when import-ing?


Python offers a number of options for importing modules, eg

     import module, ...
     from importable import object, ...

most of which can be augmented with the "as preferred_name" syntax.
(ignoring the much-reviled "*" (import everything, not private) variation)


The basic application of the as-clause, is a means of avoiding conflict 
within the namespace. Thus, if the name "vector" is already used within 
the module, we can:

     from importable import vector as direction
     ...
     go( direction )

Another common use is abbreviation - despite modern editors offering 
look-ahead guesses and superceding the typing-saver it once was; eg:

     import numpy as np
     from importable import vector as v

The "np" is not as good an example (for this discussion) because it is 
very commonly-used and therefore well-understood (at least amongst the 
Stats and DataSc communities). However, the "v" suffers the same fate as 
abbreviated object-names everywhere - after a while, one starts to 
forget exactly what the opaque name actually means.


In between the intense COVID-19 busy-ness, I have been attempting a 
contEd course (and perversely choosing to use Python instead of their 
chosen language) and thus am 'discovering' (PSL's) pygame library. 
Accordingly:

     import pygame as pg

So, after employing that, every time I encountered the abbreviation I 
had to stop and think: 'what is this "pg" thing?'. Agreed, that's part 
of the "learning process" - and in-time, even my sluggish grey-matter 
managed to reach the point of readability (but can I assume the same of 
my reader/colleagues/course-tutor?).

However, as I started building helper functions and my own objects 
'around' the pygame library, without much thought, I followed the pattern:

     import pygame as pg                   # this is from PSL
     import pygame_utilities as pgu        # this is from my own work
     ...
     if pgu.has_alpha( ink_color_tuple ): ...

It didn't take long before I was being stopped, to think: "where did 
"pgu" come-from?" (remember, being a good, little, boy*, all of my 
import statements are parked way-up at the top of the code-listing).


The opposite approach - specifically avoiding abbreviations and the 
readability issues they may carry, and bravely facing the challenge of 
avoiding name-clashes, might involve something like:

     from pygame_plane_geometry import ( CartesianError,
                                         GeometricNtuple,
     					CartesianCoordinate,
                                         Vector,
                                         Polygon,
                                         ...
                                         )
     ...
     position = CartesianCoordinate( 1, 2 )

Now, we will enjoy much-improved readability - but will have to rely 
upon the IDE's 'pop-up', to see an object's init/signature (for 
example). Thus, we face an extra concern of 'where do I find this 
module?' to be able to clarify or examine any detail.


The final 'crunch' then - to enjoy full readability AND avoid naming 
conflict AND offer full source-location information:

     import pygame_plane_geometry
     ...
     position = pygame_plane_geometry.CartesianCoordinate( 1, 2 )

Lovely stuff! Except that we're either 'banging on the door' of 
column-79, or our eyes are tiring from 'all that reading'. Maybe?


Finking/discussion:

- how do you like to balance these three (and any other criteria)?

- is your preference (or selection) influenced by the facilities offered 
by your favorite editor/IDE?

- does your decision differ according to whether the 'target module' is 
one of yours, from the PSL, from some third party, corporate, ...?

- do you prefer PSL's importlib over Python's native import-s, for one 
of these (or any other) reason?

- AOB?


WebRefs:
https://docs.python.org/3/tutorial/modules.html
https://docs.python.org/3/reference/import.html


* if you believe that, I have a bridge from Brooklyn available at an 
absolute bargain price...
(https://nycwalks.com/blog/the-brooklyn-bridge-if-you-believe-that-i-have-a-bridge-in-brooklyn-to-sell-to-you/)
-- 
Regards,
=dn