[Zope3-dev] More API changes landed

[Garrett Smith]

This is the second installment of changes to various methods in zapi. 
The intent is to cleanup/finalize the API for the beta.

Below is a summary of how various zapi methods should be used. If you 
haven't updated your code, you may see some deprecation warnings in some 
cases, or receive TypeErrors in other cases.

I encourage anyone developing against the head to confirm that you're 
using these methods correctly.

This summary is limited to changes to zope.app.zapi. If you're importing 
methods used in zapi directly (see below), I'd recommend instead import 
zapi and calling the methods as zapi.xxx. For example, instead of

   from zope.component import getService
   service = getService('Foo')

use

   from zope.app import zapi
   service = zapi.getService('Foo')

Summary of Changes:

The foremost change, which has been in place for a couple weeks, is that 
'context' arguments are no longer commonly used with zapi methods. Zope 
knows about 'context' via traversal per request. So calls that used to 
look like:

  zapi.getUtility(context, IFoo, 'bar')

are now spelled:

  zapi.getUtility(IFoo, 'bar')

or, less commonly:

  zapi.getUtility(IFoo, 'bar', context)

As the second form illustrates, 'context' can still be specified, but it 
is the last argument in the list. If you're code is UI related, you 
should not specify 'context' in any of the methods below unless you need 
to acquire something from a context that's different from the currently 
traversed location.

Commonly used methods effected by the change are:

  zapi.getService(name, context=None)
  zapi.getUtility(interface, name='', context=None)
  zapi.getAdapter(object, interface, name='', context=None)
  zapi.getView(object, name, request, providing=Interface,
          context=None)
  zapi.getResource(name, request, providing=Interface, context=None)

Less commonly used methods effected by the change are:

  zapi.getServices(context=None)
  zapi.getServiceDefinitions(context=None)
  zapi.queryUtility(interface, name='', default=None, context=None)
  zapi.getUtilitiesFor(interface, context=None)
  zapi.getAllUtilitiesRegisteredFor(interface, context=None)
  zapi.queryAdapter(object, interface, name='', default=None,
          context=None)
  zapi.getMultiAdapter(objects, interface, name=u'', context=None)
  zapi.queryMultiAdapter(objects, interface, name=u'', default=None,
          context=None)
  zapi.getFactoriesFor(interface, context=None)
  zapi.queryView(object, name, request, default=None,
          providing=Interface, context=None)
  zapi.getMultiView(objects, request, providing=Interface, name='',
          None)
  zapi.queryMultiView(objects, request, providing=Interface, name='',
          default=None, context=None)
  zapi.getViewProviding(object, providing, request, context=None)
  zapi.queryViewProviding(object, providing, request, default=None,
          context=None)
  zapi.queryDefaultViewName(object, request, default=None, context=None)
  zapi.queryResource(name, request, default=None, providing=Interface,
          context=None)

The follow changed today:

- The 'name' and 'default' arguments in queryAdapter and queryUtility 
have been swapped -- the 'name' argument now precedes the 'default' 
argument.

- getNamedAdapter and queryNamedAdapter have been deleted. Use instead 
getAdapter and queryAdapter respectively, supplying the 'name' argument.

- queryService has been deleted. Use getService to obtain a service, 
which raises ComponentLookupError is the service is not available.