Package organization

[Thomas Lotze]

Hi,

I've two questions concerning organizing and naming things when writing
a Python package.

- Naming of classes: I'm writing a library that reads PDF files. I have
a data structure that represents the large-scale structure of a PDF
file (header, trailer, incremental updates etc), and I'll have others,
e.g. one that represents the document as a collection of logical
objects (page descriptions, images etc).

Assume I have a package called PDF. Should the classes then be called
simply File and Objects, as it is clear what they do as they are
imported from PDF? Or should they be called PDFFile and PDFObjects, as
the names would be too undescriptive otherwise?

- Organizing subpackages and interfaces: I'm using the zope.interface
package in order to define interface classes. In a small package
called foo, one might define interfaces IReadableFoo and IWritableFoo
in foo.interfaces.

However, in a large package foo with subpackages bar and baz,
interface definitions might either sit in foo.bar.interfaces and
foo.baz.interfaces, or in foo.interfaces.bar and foo.interfaces.baz.
Which is preferable?

Thanks for any thought on this.

 

[F. Petitjean]

Le Wed, 22 Jun 2005 20:42:24 +0200, Thomas Lotze a écrit :

Hi,

I've two questions concerning organizing and naming things when writing
a Python package.

Assume I have a package called PDF. Should the classes then be called
simply File and Objects, as it is clear what they do as they are
imported from PDF? Or should they be called PDFFile and PDFObjects, as
the names would be too undescriptive otherwise?

As you whish
if in the package ie in the __init__.py (not the best idea)
from PDF import File as PDFFile # always possible

if File is defined in a module Objects
from PDF.Objects import File # as PDFFile is always possible.

Have you installed the reportlab package ? It is full of from ... import
... and it generates PDF.

 

[Thomas Lotze]

As you whish

Damn freedom of choice *g

if in the package ie in the __init__.py (not the best idea) from PDF
import File as PDFFile # always possible

Technically, this is clear - however I don't like the idea of giving the
same thing different names, especially if there's a chance that other
people get to look at and try to understand the code...

Using short names being unique by virtue of the subpackage hierarchy
internally and leaving it to the user (which might even be another
subpackage of the library) to import it as something more descriptive in
his context is probably the easiest, cleanest and least obtrusive thing,
as I think about it.

Have you installed the reportlab package ? It is full of from ... import
.. and it generates PDF.

I do know ReportLab. IIRC, last time I looked, it didn't simply expose an
API that models and operates on a PDF document's structures, but was
designed to produce PDF files with a certain kind of content. It didn't
seem to be of much easy use for anything wildly different from that.

 

[Terry Hancock]

Assume I have a package called PDF. Should the classes then be called
simply File and Objects, as it is clear what they do as they are
imported from PDF? Or should they be called PDFFile and PDFObjects, as
the names would be too undescriptive otherwise?

If you import PDF instead of importing from PDF, you will get that anyway:

import PDF

then you can refer to:

PDF.File
and
PDF.Object

the only downside to this is that you are using a "." operator each time,
which is a (TINY) performance hit. In tightly optimized loops, some folks
recommend avoiding this. But then, so what?

PDE_File = PDF.File

and the problem goes away.

This always seems cleaner to me than:

PDF.PDFFile etc, which drives me crazy to read. Useless repetition just
gets annoying.

 

[Marc 'BlackJack' Rintsch]

Assume I have a package called PDF. Should the classes then be called
simply File and Objects, as it is clear what they do as they are
imported from PDF? Or should they be called PDFFile and PDFObjects, as
the names would be too undescriptive otherwise?

It depends on the length of the module name in my projects. There's not
much difference in importing `PDFFile` from the module or using
`PDF.File`. If the name of the module is long, I prefer to explicitly
import the names I need from the module. In that case it's nice to have a
more descriptive name than `File`.

Ciao,
Marc 'BlackJack' Rintsch