[Zope3-dev] defining interfaces

[Steve Alexander]

Garrett Smith wrote:
> There appears to be several ways in which interfaces are defined in the
> Zope3 package. What is the recommended approach for people creating
> simple products and/or complex frameworks?

To explain this, we need a the concept of a Project as some cohesive 
piece of software implementation.


A project might take the form of

* A single python module (a .py file)

* A single python package (a directory containing an __init__.py file)
   that contains various modules.

* A python package that contains other modules and packages.


A Project might have no interfaces, or it might have a few interfaces, 
or it might have a whole bunch of interfaces. If a project has no 
interfaces, we have no problem of where to put them.

When a project is a single python module, then the interfaces should
go in that module, preferably at the start.

When a project is a package, if it has just a few interfaces, they 
should go in a module called 'interfaces.py'.

When a project is a package, and it has lots of interfaces, they should
be arranged in modules under a package called 'interfaces', where the 
arrangement of interface modules and packages mirrors the arrangement of 
the modules and packages that provide implementation for the project.


Here's an example:

Let's say I have /home/stuff on my PYTHONPATH.  My company is called 
"FooCorp", so to avoid namespace conflicts, I'll put all my projects 
inside a 'foocorp' package.

/home/stuff                      directory on the PYTHONPATH
/home/stuff/__init__.py          makes /home/stuff into a package
/home/stuff/foocorp              directory to contain my projects
/home/stuff/foocorp/__init__.py  makes /home/stuff/foocorp a package

A very small project called 'Bar Toolkit' might all live in a module 
called 'bartools.py'. The interfaces would live in that module.

/home/stuff/foocorp/bartools.py  interfaces and implementation of bar
                                  toolkit

However, if I want people to provide alternative implementations for the 
software in the 'Bar Toolkit', I'll want to provide the interfaces 
separately. There are a few ways to do this. I might add the interfaces 
to a general 'interfaces.py' module. But, that causes problems for 
installing and updating other projects in /home/stuff/foocorp.
Instead, I might define the interfaces in 
/home/stuff/foocorp/interfaces/bartools.py.

/home/stuff/foocorp/interfaces   package for foocorp interfaces that
                                  aren't in their own project package
/home/stuff/foocorp/interfaces/__init__.py
                                  makes /home/stuff/foocorp/interfaces a
                                  package
/home/stuff/foocorp/interfaces/bartools.py
                                  interface declarartions for bartools.


I could instead choose to make the interfaces available in a separate 
module at the same level as bartools.py, and call this module 
ibartools.py. However, this approach is discouraged.

/home/stuff/foocorp/ibartools.py  alternative location for bartools
                                   interfaces


Let's talk about a larger project, "Baz Toolkit". This consists of 
several modules in a package for implementation, and five or six 
interfaces collected into one file.

/home/stuff/foocorp/baztools     directory for baz toolkit
/home/stuff/foocorp/baztools/__init__.py
                                  file to make directory into a package
                                  that might contain some implementation
/home/stuff/foocorp/baztools/system.py
                                  some more implementation for baztools
/home/stuff/foocorp/baztools/browser.py
                                  browser views provided for baztools
/home/stuff/foocorp/baztools/adapters.py
                                  perhaps adapters can go here, if there
                                  are a bunch of them that don't fit
                                  elsewhere
/home/stuff/foocorp/baztools/interfaces.py
                                  all the interfaces for the baztoolkit


Let's say I have a much larger project, "Spoo Toolkit". This consists of 
many subpackages of a main package. Each subpackage has its own 
interfaces. I also want to split off the browser views from the main 
implementation. So, I have three trees: Main implementation, Browser 
views, Interfaces.

/home/stuff/foocorp/spootools    directory for spoo toolkit
/home/stuff/foocorp/spootools/__init__.py
                                  makes this a python package.
                                  might contain implementation,
                                  but may well not do, if we want to
                                  consider spootools just a
                                  'namespace-only package'.
/home/stuff/foocorp/spootools/systema.py
/home/stuff/foocorp/spootools/systemb.py
                                  implementation in modules
/home/stuff/foocorp/spootools/systemc
                                  directory for subsystem c
/home/stuff/foocorp/spootools/systemc/__init__.py
                                  make directory a package
                                  contains some implementation
/home/stuff/foocorp/spootools/systemc/subsysx.py
                                  subsystemx of systemc
/home/stuff/foocorp/spootools/interfaces
                                  directory for interfaces
/home/stuff/foocorp/spootools/interfaces/__init__.py
                                  make directory a package
                                  contains important interfaces
                                  used in systema and systemb
/home/stuff/foocorp/spootools/interfaces/systemc.py
                                  contains interfaces for systemc
                                  and subsystemx
/home/stuff/foocorp/spootools/browser
                                  contains browser views
                                  fill in the __init__.py and other
                                  modules and directories as you need!

--
Steve Alexander