[Zope3-checkins] CVS: Zope3/src/zope/interfaces - __init__.py:1.2 configuration.py:1.2 event.py:1.2 i18n.py:1.2
Jim Fulton
jim@zope.com
Wed, 25 Dec 2002 09:15:43 -0500
Update of /cvs-repository/Zope3/src/zope/interfaces
In directory cvs.zope.org:/tmp/cvs-serv20790/src/zope/interfaces
Added Files:
__init__.py configuration.py event.py i18n.py
Log Message:
Grand renaming:
- Renamed most files (especially python modules) to lower case.
- Moved views and interfaces into separate hierarchies within each
project, where each top-level directory under the zope package
is a separate project.
- Moved everything to src from lib/python.
lib/python will eventually go away. I need access to the cvs
repository to make this happen, however.
There are probably some bits that are broken. All tests pass
and zope runs, but I haven't tried everything. There are a number
of cleanups I'll work on tomorrow.
=== Zope3/src/zope/interfaces/__init__.py 1.1 => 1.2 ===
--- /dev/null Wed Dec 25 09:15:43 2002
+++ Zope3/src/zope/interfaces/__init__.py Wed Dec 25 09:15:12 2002
@@ -0,0 +1,2 @@
+#
+# This file is necessary to make this directory a package.
=== Zope3/src/zope/interfaces/configuration.py 1.1 => 1.2 ===
--- /dev/null Wed Dec 25 09:15:43 2002
+++ Zope3/src/zope/interfaces/configuration.py Wed Dec 25 09:15:12 2002
@@ -0,0 +1,96 @@
+##############################################################################
+#
+# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Configuration directives that have subdirectives
+
+$Id$
+"""
+from zope.interface import Interface
+
+class INonEmptyDirective(Interface):
+
+ def __call__(context,**kw):
+ """Compute subdirective handler
+
+ context -- an execution context that the directive may use for
+ things like resolving names
+
+ kw -- a dictionary containing the values of any attributes
+ that were specified on the directive
+
+ Return an ISubdirectiveHandler.
+ """
+
+
+"""Configuration directives that do not have subdirectives
+
+$Id$
+"""
+from zope.interface import Interface
+
+class IEmptyDirective(Interface):
+
+ def __call__(context,**kw):
+ """Compute configuration actions
+
+ context -- an execution context that the directive may use for
+ things like resolving names
+
+ kw -- a dictionary containing the values of any attributes
+ that were specified on the directive
+
+ Return a sequence of configuration actions. Each action is a
+ tuple with:
+
+ - A discriminator, value used to identify conflicting
+ actions. Actions conflict if they have the same values
+ for their discriminators.
+
+ - callable object
+
+ - argument tuple
+
+ - and, optionally, a keyword argument dictionary.
+
+ The callable object will be called with the argument tuple and
+ keyword arguments to perform the action.
+ """
+
+
+"""Psuedo-directive (or meta-meta directive) to handle subdirectives
+
+$Id$
+"""
+from zope.interface import Interface
+
+class ISubdirectiveHandler(Interface):
+ """Handle subdirectives
+
+ Provide methods for registered subdirectives. The methods are
+ typically IEmptyDirective objects. They could, theoretically be
+ INonEmptyDirective objects.
+
+ Also provide a call that can provide additional configuration
+ actions.
+
+ """
+
+ def __call__():
+ """Return a sequence of configuration actions.
+
+ See IEmptyDirective for a definition of configuration actions.
+
+ This method should be called *after* any subdirective methods are
+ called during the processing of the (sub)directive whose subdirectives
+ are being processed. It may return an empty list.
+ """
=== Zope3/src/zope/interfaces/event.py 1.1 => 1.2 ===
--- /dev/null Wed Dec 25 09:15:43 2002
+++ Zope3/src/zope/interfaces/event.py Wed Dec 25 09:15:12 2002
@@ -0,0 +1,215 @@
+##############################################################################
+#
+# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""
+
+Revision information:
+$Id$
+"""
+
+from zope.interface import Interface
+
+class IEvent(Interface):
+ """The Base interface for Events"""
+
+
+"""
+
+Revision information:
+$Id$
+"""
+
+from zope.interface import Interface
+
+class IEventFilter(Interface):
+ """Interface for predicates used to filter events."""
+
+ def __call__(event):
+ """Return true if event passes, or false."""
+
+
+"""
+
+Revision information:
+$Id$
+"""
+
+from zope.interface import Interface
+
+
+class ISubscribable(Interface):
+ """Objects that broadcast events to subscribers."""
+
+ def subscribe(subscriber, event_type=IEvent, filter=None):
+ """Add subscriber to the list of subscribers for the channel.
+
+ subscriber must implement ISubscriber.
+
+ event_type, if supplied, is the event interface
+ about which subscriber should be notified, and must implement
+ IEvent. The subscriber will be notified of all events of this
+ event_type and of subclasses of this event_type.
+ The default value, IEvent, as the parent type, is effectively a single
+ catch-all event type that will pass all event types to the subscriber.
+
+ filter, if supplied, must implement IEventFilter; subscriber
+ will be notified of events only if they pass.
+
+ A subscriber may subscribe more than once, even if it has
+ already been subscribed with the same event type and
+ filter. In this case the subscriber will receive multiple
+ calls to its notify method.
+
+ If the subscriber implements ISubscriptionAware, this function
+ will call the subscriber's subscribedTo method.
+ """
+
+ def unsubscribe(subscriber, event_type=None, filter=None):
+ """Unsubscribe subscriber from receiving event types from this
+ subscribable.
+
+ If event_type is None, the default value, the subscriber is
+ unsubscribed completely for all event types from this
+ subscribable (and its parents, if the subscribable is a placeful
+ service). The filter argument is ignored in this case. If no
+ subscriptions for this subscriber are present, no error is
+ raised.
+
+ If event_type is supplied, this method will unsubscribe the
+ subscriber from one subscription exactly matching the
+ event_type/filter pair given (the default filter being None).
+ If other subscriptions are present they will remain. If the
+ subscription cannot be found and the subscribable is a placeful
+ service, the unsubscription request is passed to parent
+ services. Raises NotFound if subscriber wasn't
+ subscribed as expected.
+
+ If the subscriber implements ISubscriptionAware, this function
+ will call the subscriber's unsubscribedFrom method for each
+ individual unsubscribe.
+ """
+
+ def listSubscriptions(subscriber, event_type=None):
+ """Returns an iterator of the subscriptions to this channel for
+ the subscriber. If event_type is supplied, the list is limited
+ to that exact event_type. If the subscribable is a placeful
+ service, the list will include subscriptions to parent services.
+ The subscriber is matched via equality (not identity). No
+ subscriptions returns an empty iterator. Each subscription is
+ represented as a tuple (event_type, filter)."""
+
+
+"""
+
+Revision information:
+$Id$
+"""
+
+from zope.interface import Interface
+
+class ISubscriber(Interface):
+ """Interface for objects which receiving event notifications."""
+
+ def notify(event):
+ """ISubscribables call this method to indicate an event.
+
+ This method must not block!
+
+ This method may raise an exception to veto the event.
+ """
+
+class IIndirectSubscriber(ISubscriber):
+ """Interface for objects that handle subscriptions for another object."""
+
+ def __eq__(other):
+ """Compare two indirect subscribers
+
+ Two indirect subscribers are the same if they reference the
+ same object.
+ """
+
+
+
+
+
+"""
+
+Revision information:
+$Id$
+"""
+
+
+
+
+class IEventChannel(ISubscribable, ISubscriber):
+ """Interface for objects which distribute events to subscribers. """
+
+
+
+
+"""
+
+Revision information:
+$Id$
+"""
+from zope.interface import Interface
+
+# these are method calls and not events because they are traditional messages
+# between two objects, not events of general interest.
+
+class ISubscriptionAware(Interface):
+
+ def subscribedTo(subscribable, event_type, filter):
+ """Alerts the object that it has subscribed, via a call from
+ itself or from another object, to the subscribable. The
+ event_type and filter match the arguments provided to the
+ ISubscribable.subscribe.
+
+ The subscribable must be appropriately placefully wrapped (note
+ that the global event service will have no wrapping)."""
+
+ def unsubscribedFrom(subscribable, event_type, filter):
+ """Alerts the object that it has unsubscribed, via a call from
+ itself or from another object, to the subscribable. The
+ event_type and filter match the exact event_type and filter of
+ the deleted subscription, rather than, necessarily, the
+ arguments provided to the ISubscribable.unsubscribe.
+
+ The subscribable must be appropriately placefully wrapped (note
+ that the global event service will have no wrapping)."""
+
+
+"""
+
+Revision information:
+$Id$
+"""
+
+
+
+
+class IEventService(ISubscribable):
+ """The EventService service is the 'root channel'.
+
+ Its subscribers include other channels.
+
+ It is also the 'default destination' for events
+ when they are generated.
+ """
+
+ def publish(event):
+ """Notify all subscribers of the channel of event.
+
+ Events will often be propagated to higher level IEventServices;
+ This is a policy decision for the IEventService.
+ """
=== Zope3/src/zope/interfaces/i18n.py 1.1 => 1.2 ===
--- /dev/null Wed Dec 25 09:15:43 2002
+++ Zope3/src/zope/interfaces/i18n.py Wed Dec 25 09:15:12 2002
@@ -0,0 +1,463 @@
+##############################################################################
+#
+# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Internationalization of content objects.
+
+$Id$
+"""
+
+from zope.interface import Interface
+
+
+class II18nAware(Interface):
+ """Internationalization aware content object.
+ """
+
+ def getDefaultLanguage():
+ """Return the default language."""
+
+ def setDefaultLanguage(language):
+ """Set the default language, which will be used if the language is not
+ specified, or not available.
+ """
+
+ def getAvailableLanguages():
+ """Find all the languages that are available."""
+
+
+
+"""
+
+$Id$
+"""
+
+from zope.interface import Interface
+
+
+class IReadMessageCatalog(Interface):
+ """A catalog (mapping) of message ids to message text strings.
+
+ This interface provides a method for translating a message or message id,
+ including text with interpolation. The message catalog basically serves
+ as a fairly simple mapping object.
+
+ A single message catalog represents a specific language and domain.
+ Therefore you will have the following constructor arguments:
+
+ language -- The language of the returned messages. This is a read-only
+ attribute.
+
+ domain -- The translation domain for these messages. This is a read-only
+ attribute. See ITranslationService.
+
+ When we refer to text here, we mean text that follows the standard Zope 3
+ text representation.
+
+ Note: The IReadMessageCatalog is the absolut minimal version required for
+ the TranslationService to function.
+ """
+
+ def getMessage(msgid):
+ """Get the appropriate text for the given message id.
+
+ An exception is raised if the message id is not found.
+ """
+
+ def queryMessage(msgid, default=None):
+ """Look for the appropriate text for the given message id.
+
+ If the message id is not found, default is returned.
+ """
+
+ def getLanguage():
+ """Return the language this message catalog is representing."""
+
+ def getDomain():
+ """Return the domain this message catalog is serving."""
+
+ def getIdentifier():
+ """Return a identifier for this message catalog. Note that this
+ identifier does not have to be unique as several message catalog
+ could serve the same domain and language.
+
+ Also, there are no restrictions on the form of the identifier.
+ """
+
+
+class IWriteMessageCatalog(Interface):
+ """If this interfaces is implemented by a message catalog, then we will be
+ able to update our messages.
+
+ Note that not all methods here require write access, but they should
+ not be required for an IReadMEssageCatalog and are used for editing
+ only. Therefore this is the more suitable interface to put them.
+ """
+
+ def getFullMessage(msgid):
+ """Get the message data and meta data as a nice dictionary. More
+ advanced implementation might choose to return an object with
+ the data, but the object should then implement IEnumerableMapping.
+
+ An exception is raised if the message id is not found.
+ """
+
+ def setMessage(msgid, message, mod_time=None):
+ """Set a message to the catalog. If mod_time is None use the current
+ time instead as modification time."""
+
+ def deleteMessage(msgid):
+ """Delete a message from the catalog."""
+
+ def getMessageIds():
+ """Get a list of all the message ids."""
+
+ def getMessages():
+ """Get a list of all the messages."""
+
+
+class IMessageCatalog(IReadMessageCatalog, IWriteMessageCatalog):
+ """Most message catalogs should support this interface.
+ """
+
+
+"""Translation Service related Interfaces.
+
+$Id$
+"""
+
+from zope.interface import Interface
+
+
+class IReadTranslationService(Interface):
+ """The Translation Service
+
+ This interface provides methods for translating text, including text with
+ interpolation.
+
+ When we refer to text here, we mean text that follows the standard Zope 3
+ text representation.
+
+ Standard arguments in the methods described below:
+
+ domain -- The domain is used to specify which translation to use.
+ Different products will often use a specific domain naming
+ translations supplied with the product.
+
+ A favorite example is: How do you translate "Sun"? Is it
+ our star, the abbreviation of Sunday or the company?
+ Specifying the domain, such as "Stars" or "DaysOfWeek" will
+ solve this problem for us.
+
+ msgid -- The id of the message that should be translated. This may be
+ an implicit or an explicit message id.
+
+ mapping -- The object to get the interpolation data from.
+
+ target_language -- The language to translate to.
+
+ context -- An object that provides contextual information for
+ determining client language preferences. It must implement
+ or have an adapter that implements IUserPreferredLanguages.
+
+ Note that one of target_language or context must be passed. Otherwise
+ a TypeError will be raised.
+
+ Also note that language tags are defined by RFC 1766.
+ """
+
+ def translate(domain, msgid, mapping=None,
+ context=None, target_language=None):
+ """Return the translation for the message referred to by msgid.
+
+ Return None if no translation is found.
+
+ However, the method does a little more than a vanilla translation.
+ The method also looks for a possible language to translate to.
+ After a translation it also replaces any $name variable variables
+ inside the post-translation string.
+
+ Note: The TranslationService interface does not support simplified
+ translation methods, since it is totally hidden by ZPT and in
+ Python you should use a Domain object, since it supports all
+ the simplifications.
+ """
+
+ def getDomain(domain):
+ """Get the domain for the passed domain name.
+
+ The domain supports the IDomain interface
+ """
+
+
+class IWriteTranslationService(Interface):
+ """This interface describes the methods that are necessary for an editable
+ Translation Service to work.
+
+ For a translation service to be editable its 'messages' have to support
+ the following information: id, string, domain, language, date
+
+ Most of the information will be natural, since they are required by the
+ translation service, but especially the date is not a necessary info
+ (in fact, it is meta data)
+ """
+
+ def getMessageIdsOfDomain(domain, filter='%'):
+ """Get all the message ids of a particular domain."""
+
+ def getMessagesOfDomain(domain):
+ """Get all the messages of a particular domain."""
+
+ def getMessage(msgid, domain, langauge):
+ """Get the full message of a particular domain and language."""
+
+ def getAllLanguages():
+ """Find all the languages that are available"""
+
+ def getAllDomains():
+ """Find all available domains."""
+
+ def getAvailableLanguages(domain):
+ """Find all the languages that are available for this domain"""
+
+ def getAvailableDomains(language):
+ """Find all available domains."""
+
+ def addMessage(domain, msgid, msg, language, mod_time=None):
+ """Add a message to the translation service.
+
+ If mod_time is None, then the current time should be inserted.
+ """
+
+ def updateMessage(domain, msgid, msg, language, mod_time=None):
+ """Update a message in the translation service.
+
+ If mod_time is None, then the current time should be inserted.
+ """
+
+ def deleteMessage(domain, msgid, language):
+ """Delete a messahe in the translation service."""
+
+ def addLanguage(language):
+ """Add Language to Translation Service"""
+
+ def addDomain(domain):
+ """Add Domain to Translation Service"""
+
+ def deleteLanguage(language):
+ """Delete a Domain from the Translation Service."""
+
+ def deleteDomain(domain):
+ """Delete a Domain from the Translation Service."""
+
+
+class ISyncTranslationService(Interface):
+ """This interface allows translation services to be synchronized. The
+ following four synchronization states can exist:
+
+ 0 - uptodate: The two messages are in sync.
+ Default Action: Do nothing.
+
+ 1 - new: The message exists on the foreign TS, but is locally unknown.
+ Default Action: Add the message to the local catalog.
+
+ 2 - older: The local version of the message is older than the one on
+ the server.
+ Default Action: Update the local message.
+
+ 3 - newer: The local version is newer than the foreign version.
+ Default Action: Do nothing.
+
+ 4 - deleted: The message does not exist in the foreign TS.
+ Default Action: Delete local version of message/
+ """
+
+ def getMessagesMapping(domains, languages, foreign_messages):
+ """Creates a mapping of the passed foreign messages and the local ones.
+ Returns a status report in a dictionary with keys of the form
+ (msgid, domain, language) and values being a tuple of:
+
+ foreign_mod_date, local_mod_date
+ """
+
+ def synchronize(messages_mapping):
+ """Update the local message catalogs based on the foreign data.
+ """
+
+
+class ITranslationService(IReadTranslationService, IWriteTranslationService,
+ ISyncTranslationService):
+ """This is the common and full-features translation service. Almost all
+ translation service implementations will use this interface.
+
+ An exception to this is the GlobalMessageCatalog as it will be read-only.
+ """
+
+
+"""Translation Service Message Import Filter Interface
+
+$Id$
+"""
+
+from zope.interface import Interface
+
+class IMessageImportFilter(Interface):
+ """The Import Filter for Translation Service Messages.
+
+ Classes implementing this interface should usually be Adaptors, as
+ they adapt the IEditableTranslationService interface."""
+
+
+ def importMessages(domains, languages, file):
+ """Import all messages that are defined in the specified domains and
+ languages.
+
+ Note that some implementations might limit to only one domain and
+ one language. A good example for that is a GettextFile.
+ """
+
+
+"""
+
+$Id$
+"""
+
+from zope.interface import Interface
+
+class ILanguageAvailability(Interface):
+
+ def getAvailableLanguages():
+ """Return a sequence of language tags for available languages
+ """
+
+
+"""
+
+$Id$
+"""
+
+from zope.interface import Interface
+
+class IUserPreferredLanguages(Interface):
+
+ """This interface provides language negotiation based on user preferences.
+ """
+
+ def getPreferredLanguages():
+ """Return a sequence of user preferred languages.
+ """
+
+
+"""
+
+$Id$
+"""
+
+from zope.interface import Interface
+
+class IDomain(Interface):
+ """A translation domain.
+
+ Since it is often tedious to always specify a domain and a place for a
+ particular translation, the idea of a Domain object was created, which
+ allows to save the place and domain for a set of translations.
+
+ Usage:
+
+ domain = translationService.getDomain('domain')
+ domain.translate('MyProductTitle', context)
+ """
+
+ def translate(msgid, mapping=None, context=None, target_language=None):
+ """Translate the the source to its appropriate language.
+
+ See ITranslationService for details.
+ """
+
+
+"""Translation Service Message Export Filter Interface
+
+$Id$
+"""
+
+from zope.interface import Interface
+
+class IMessageExportFilter(Interface):
+ """The Export Filter for Translation Service Messages.
+
+ Classes implementing this interface should usually be Adaptors, as
+ they adapt the IEditableTranslationService interface."""
+
+
+ def exportMessages(domains, languages):
+ """Export all messages that are defined in the specified domains and
+ languages.
+
+ Note that some implementations might limit to only one domain and
+ one language. A good example for that is a GettextFile.
+ """
+
+
+"""
+
+$Id$
+"""
+
+from zope.interface import Interface
+
+class INegotiator(Interface):
+
+ """A language negotiation service.
+ """
+
+ def getLanguage(langs, env):
+ """Return the matching language to use.
+
+ The decision of which language to use is based on the list of
+ available languages, and the given user environment. An
+ IUserPreferredLanguages adapter for the environment is obtained and
+ the list of acceptable languages is retrieved from the environment.
+
+ If no match is found between the list of available languages and the
+ list of acceptable languages, None is returned.
+
+ Arguments:
+
+ langs -- sequence of languages (not necessarily ordered)
+
+ env -- environment passed to the service to determine a sequence
+ of user prefered languages
+ """
+
+ # XXX I'd like for there to be a symmetric interface method, one in
+ # which an adaptor is gotten for both the first arg and the second
+ # arg. I.e. getLanguage(obj, env)
+ # But this isn't a good match for the iTranslationService.translate()
+ # method. :(
+
+
+"""See IUserPreferredCharsets.
+
+$Id$
+"""
+
+from zope.interface import Interface
+
+class IUserPreferredCharsets(Interface):
+ """This interface provides charset negotiation based on user preferences.
+ """
+
+ def getPreferredCharsets():
+ """Return a sequence of user preferred charsets. Note that the order
+ should describe the order of preference. Therefore the first
+ character set in the list is the most preferred one.
+ """