Encapsulation vs. code reuse?

[Stefan Schwarzer]

Hello Pythoneers :-)

(see below for the background of these questions)

- How should one (not?) use undocumented attributes of a module, class etc.?

- Should the code or the documentation have the highest priority for using
  a module?

- What are the consequences with regard to own coding and documenting
  practices?

For example, I happened to need the translation of a shell-style glob to
a regular expression. Fortunately, exactly this is contained in the fnmatch
module. Unfortunately, this function is not mentioned in the HTML
documentation, so it might disappear when someone decides to recode the
module and strips out the translate function as it now works.

My current solution is that I have copied the translate function from the
module to one of my own, so my program would still run with a newer Python
release (than 1.5.2). However, that doesn't seem really elegant to me, but
I can't think of a better solution yet. Any ideas?

A worse case is the ConfigParser module, particularly the read method. It
does not raise exceptions if a file is not readable (it catches and pass'es
them). Furthermore, it accepts only files, not arbitrary file-like objects
like StringIO objects.

On the other hand, __read would be exactly what I wish. But even the name
with the two leading underscores suggests that this is a method only for
internal use (and thus may be prone to changes) and not to be used from
'outsiders'.

Personally, I use the convention of prepending all 'helper attributes'
with an underscore to note that they are for 'internal' use and may change.
All other attributes are open for users of the module.

So, any comments on this topic? :o)

Stefan