[Zope3-dev] Interface declaration API

[Jim Fulton]

There've been a lot of good comments made here and in the wiki,

  http://dev.zope.org/Zope3/BetterInterfaceImplements,

about the function names used in the interface declaration
API. I think that there are two good candidates at this point:

- A proposal that makes a distinction between declaration and query functions.
   Declaration functions use the word "implements" and query functions
   use the word "interfaces".

- A proposal that makes a distinction between:

   o Declaration and query functions. Declaration functions use the
     present tense and quert functions use the past tense.

   o Whether we are talking about interfaces declared for instances of a
     class or interfaces declared directly for objects, where an interesting
     case is when the object we are interested in happens to be a class.

I've updated the interface for this API for *both* proposals by
including two def statements for each function, for which the proposals
differ. I've also added a function to the first proposal to include a
convenience function for declaring the direct-object interfaces for a class
in the class definition.

Here is the updated interface with multiple method names:

   class IImplements(Interface):
     """Declare and check the interfaces of objects

     The functions defined in this interface are used to declare the
     interfaces that objects have and to query the interfaces that have
     been declared.

     Interfaces can be declared for objects in two ways:

     - Interfaces are declared for instances of the object's class

     - Interfaces are declared for the object directly.

     The interfaces declared for an object are, therefore, the union of
     interfaces declared for the object directly and the interfaces
     declared for instances of the object's class.

     """

     def implements(*interfaces):
         """Declare interfaces implemented by instances of a class

         This function is called in a class definition.

         The arguments are one or more interfaces or interface
         specifications (IInterfaceSpecification objects).

         The given interfaces (including the interfaces in the
         specifications) are used to create the class's instance
         interface specification.  An error will be raised if the class
         already has an instance interface specification.  In other
         words, it is an error to call this function more than once in
         a class definition.

         This function is provided for convenience. It provides a more
         convenient way to call classInstanceInterfaces. For example::

           implements(I1)

         is equivalent to calling::

           classInstanceInterfaces(theclass).set(I1)

         after the class has been created.

         """

     def classImplements(*interfaces):
     def classProvides(*interfaces):
         """Declare interfaces implemented directly by a class

         This function is called in a class definition.

         The arguments are one or more interfaces or interface
         specifications (IInterfaceSpecification objects).

         The given interfaces (including the interfaces in the
         specifications) are used to create the class's direct-object
         interface specification.

         Note that the given interfaces have nothing to do with the
         interfaces implemented by instances of the class.

         An error will be raised if the class already has a
         direct-object interface specification.  In other words, it is
         an error to call this function more than once in a class
         definition.

         This function is provided for convenience. It provides a more
         convenient way to call objectInterfaces for a class. For
         example::

           classImplements(I1)

         is equivalent to calling::

           objectInterfaces(theclass).set(I1)

         after the class has been created.

         """

     def moduleImplements(*interfaces):
     def moduleProvides(*interfaces):
         """Declare interfaces implemented by a module

         This function is used in a module definition.

         The arguments are one or more interfaces or interface
         specifications (IInterfaceSpecification objects).

         The given interfaces (including the interfaces in the
         specifications) are used to create the module's direct-object
         interface specification.  An error will be raised if the module
         already has an interface specification.  In other words, it is
         an error to call this function more than once in a module
         definition.

         This function is provided for convenience. It provides a more
         convenient way to call objectInterfaces. For example::

           moduleImplements(I1)

         is equivalent to::

           objectInterfaces(sys.modules[__name__]).set(I1)

         """

     def classInstanceInterfaces(class_):
     def implementedBy(class_):
         """Retrieve interfaces declared for class instance

         The class' interface specification
         (IMutableInterfaceSpecification) is returned. A new
         specification is created for the class if one does not exist.

         """

     def directObjectInterfaces(object):
     def directlyProvidedBy(object):
         """Retrieve interfaces declared directly for the object

         The direct object interface specification
         (IMutableInterfaceSpecification) is returned. A new
         specification is created for the object if one does not exist.

         Not all objects can directly implement interfaces. If an
         object cannot directly implement an interface, a TypeError
         will be raised.

         """

     def interfaces(object):
     def providedBy(object):
         """Return all of the interfaces declared for an object

         An interface specification (IInterfaceSpecification) is
         returned containing the combination of the interfaces
         declared directly for the object and interfaces declared
         for instances of the object's class.

         """

I'd be interested in how prople feel about one of these vs the other.

Jim


-- 
Jim Fulton           mailto:jim@zope.com       Python Powered!
CTO                  (888) 344-4332            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org