FrontPage APINamingConvention / backlinks

Naming Convention Proposal

Note - this document is still a work in progress. Please do not make inline comments in the proposal - use the APINamingConventionDiscussion to make comments.

Contact

JimFulton

Problem

Zope is a bit inconsistent in it's naming conventions. The current convention is:

• Names starting with underscores are "private", meaning that they can't be accessed via URL or by through-the-web (TTW) code.

• Names starting with manage_ (and the name manage) are meant for "manager". Methods with these names in file-based Python classes automagically get the roles (__roles__): ("Manager",).

There are no other conventions to distinguish or organize API methods.

The current approach has the following serious drawbacks:

• The use of _ and manage_ names is used as somewhat of a crutch to avoid making security decisions (deciding permissions).

• It is likely that the number of API functions will explode as Zope matures and as many non-web interfaces are provided. Some of the interfaces may be non-web user interfaces, but many of these interfaces will be application programming interfaces to be used from Python, Perl, XML-RPC, SOAP, etc.. This will lead to name conflicts between method names and sub-object names in object managers. (An implementation of a model-view architecture might mitigate this to some degree.)

  We have already run into cases where name clashes between sub-objects and API names. For fun, try creating an object named target in a folder.

Proposed Solution

I propose that the following naming convention be adopted for all new API methods.

• API method names will be of the form:

  ZInterfaceName_MethodName

  The name will be in two parts separated by an underscore. The first part will begin with the letter Z followed by a capitalized "camel-case' interface name. The second part will be a capitalized "camel-case" method name.

• The name of a method will not imply the Zope security setting. Any API definition must specify the security setting for an object. Valid security settings will include:

  Public (aka anonymous)

  Always accessible

  Permission

  Accessible by any request with a specified permission

  Private

  not accessible via a URL or from TTW code

  Method Private

  not accessible via a URL and only accessible by TTW code in method of same class or subclass.

• Names beginning with underscores should be used for method and other attributes that are a part of the private implementation of an object. (Note that, in the future, the publisher might allow objects not accessed as attributes (e.g. objects accessed via __bobo_traverse__) with names beginning with _ to be published.)

Note that this naming convention is based on the Python C API naming convention.

Opportunistically, old APIs^x may be retrofitted to the new naming convention, however, it is likely that old names will be retained for backward compatibility.

Alternatives

Implement model-view

We could reduce this problem somewhat my introducting model-view. I fear that this would be unduly disruptive.

Use items for sub-objects

If all we want to address is object manager name conflicts, we might have object managers provide access to sub-objects via items rather than attributes. So, if one wanted to access foo in folder spam from Python, they would have to use:

        spam['foo']

rather than:

        spam.foo

This would play havoc with acquisition, unless, of course, the object manager item method provided acquisition semantics. This, however, would introduce name space problems again.

In any case, this would be extremely disruptive.

Risk Factors

• Names may be considered overly verbose.

Deliverables

A page on the Interfaces Wiki Documenting the naming convention.