NetBeans Screenshot of the Week #35: Support for Python's __all__ Variable


Let's start with a pretty simple module - an import, a function, and a couple of classes:







(Notice by the way the semantic highlighting here - the unused parameters and variables are marked with a slight grey underline,
method names in bold, parameters in orange. More on that another day.)



Now let's go to a different file and import this module. Code completion is context dependent and shows us
which symbols are being exported by the given module. We see not only our functions and classes, the imported symbol sys
is also being defined by module, meaning that if you do from compl4 import \* you would have sys defined as well:







Python has a way to deal with this: You can specify a variable named __all__, which lets you define exactly what the public API for
this module should be (more details).



Let's go in and define the names we want exported by our module. I will add __all__ = [ "Bar " ] somewhere in the file, to specify that only Bar should be exported:







Look at the file outline / navigator on the left hand side. As soon as I typed in the __all__ line,
the icons changed to show me that only the Bar class and its method are now "public"; there are little
lock icons on everything else! Let's see what code completion offers when we try to import this module again:







Yep, only the public API is exported now. Let's append to the __all__ list to export the func function:







You don't have to rely on icons to tell you if something is wrong though. Let's say I've forgotten all about this, and I decided
to rename my Bar class:







NetBeans checks that all the symbols you declare in your __all list actually exist, and points out any discrepancies. Here, the public Bar class no longer exists since we renamed it.



Here's another little bug I came across related to this. I was checking the __all__ handling on various library files,
in this case posixpath.py. Notice how in the navigator, all the functions are public, except one...







Sure enough, the code looks like it's registering this conditionally added method... Do you spot the problem? There's a dot missing!
As soon as we add it, we get this:







Of course, this last bug was already detected by the
unresolved symbol detector...




Comments:

Strictly speaking, "__all__" does not define the public API of a module or package. It defines what is exported when you do an "import all" (reading "\*" as "all").

Even if you limit the exported items using "__all__", all the attributes of a module are still accessible using "<module>.<attr>" after an "import <module>".

This is unlike similar constructs in languages like Haskell and Perl, where the list of attributes is both the exported and visible API of a module.

"__all__" is used mainly to make modules "import \*" safe and as documentation (and in the case of packages to make "import \*" to actually work properly). I suppose it also comes in handy for tools like Netbeans (and hopefully encourage people to put them in :-) ).

BTW, I am really excited about 6.5 (already using the nightly build; not enough patience) and nbpython. Thanks to you and all the Netbeans team for the great work.

Posted by J on November 13, 2008 at 09:49 AM PST #

I'm so looking forward to the release of this, I'm almost keeping my breath.

I tried out the last "stable" automated build, its awesome, but... where can I report bugs?

Posted by Bård Aase on November 13, 2008 at 06:55 PM PST #

Hi J,
thanks for your feedback! Thanks for the clarification. Yep, I realize I'm taking things a bit further than Python's true private concept. (For a while I used the "protected" icon for private of this nature, and the "private" icon for truly Python private (name mangled) names. It's not there right now but I'm still going to refine this.)

Hi Bård,
file bugs here:

http://ide.netbeans.org/issues/enter_bug.cgi?component=python&issue_type=DEFECT

Posted by Torbjorn Norbye on November 14, 2008 at 02:02 AM PST #

Post a Comment:
Comments are closed for this entry.
About

Tor Norbye

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today