vendor/Five/1.2b-r20590

view bbb/OFS_interfaces.py @ 0:3673ed425f80

Vendor import of Five 1.2b+ (r20590)
author fguillaume
date Fri, 02 Dec 2005 20:25:42 +0000
parents
children
line source
1 ##############################################################################
2 #
3 # Copyright (c) 2004, 2005 Zope Corporation and Contributors.
4 # All Rights Reserved.
5 #
6 # This software is subject to the provisions of the Zope Public License,
7 # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
8 # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
9 # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
10 # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
11 # FOR A PARTICULAR PURPOSE.
12 #
13 ##############################################################################
14 """OFS z3 interfaces.
16 $Id: OFS_interfaces.py 19416 2005-11-02 15:18:34Z efge $
17 """
18 from zope.interface import Attribute
19 from zope.interface import Interface
20 from zope.schema import Bool, BytesLine, Tuple
21 from zope.app.traversing.interfaces import IContainmentRoot
23 from AccessControl_interfaces import IOwned
24 from AccessControl_interfaces import IRoleManager
25 from Acquisition_interfaces import IAcquirer
26 from App_interfaces import INavigation
27 from App_interfaces import IUndoSupport
28 from persistent.interfaces import IPersistent
29 from webdav_interfaces import IDAVCollection
30 from webdav_interfaces import IDAVResource
33 # create IOrderedContainer
34 from Products.Five.fiveconfigure import createZope2Bridge
35 from OFS.IOrderSupport import IOrderedContainer as z2IOrderedContainer
36 import OFS_interfaces
38 createZope2Bridge(z2IOrderedContainer, OFS_interfaces, 'IOrderedContainer')
40 del createZope2Bridge
41 del z2IOrderedContainer
42 del OFS_interfaces
45 # XXX: might contain non-API methods and outdated comments;
46 # not synced with ZopeBook API Reference;
47 # based on OFS.CopySupport.CopySource
48 class ICopySource(Interface):
50 """Interface for objects which allow themselves to be copied."""
52 def _canCopy(op=0):
53 """Called to make sure this object is copyable. The op var
54 is 0 for a copy, 1 for a move."""
56 def _notifyOfCopyTo(container, op=0):
57 """Overide this to be pickly about where you go! If you dont
58 want to go there, raise an exception. The op variable is
59 0 for a copy, 1 for a move."""
61 def _getCopy(container):
62 """ """
64 def _postCopy(container, op=0):
65 """Called after the copy is finished to accomodate special cases.
66 The op var is 0 for a copy, 1 for a move."""
68 def _setId(id):
69 """Called to set the new id of a copied object."""
71 def cb_isCopyable():
72 """Is object copyable? Returns 0 or 1"""
74 def cb_isMoveable():
75 """Is object moveable? Returns 0 or 1"""
77 def cb_userHasCopyOrMovePermission():
78 """ """
81 # XXX: might contain non-API methods and outdated comments;
82 # not synced with ZopeBook API Reference;
83 # based on OFS.FTPInterface.FTPInterface
84 class IFTPAccess(Interface):
86 """Provide support for FTP access"""
88 def manage_FTPstat(REQUEST):
89 """Returns a stat-like tuple. (marshalled to a string) Used by
90 FTP for directory listings, and MDTM and SIZE"""
92 def manage_FTPlist(REQUEST):
93 """Returns a directory listing consisting of a tuple of
94 (id,stat) tuples, marshaled to a string. Note, the listing it
95 should include '..' if there is a Folder above the current
96 one.
98 In the case of non-foldoid objects it should return a single
99 tuple (id,stat) representing itself."""
102 # XXX: might contain non-API methods and outdated comments;
103 # not synced with ZopeBook API Reference;
104 # based on OFS.Traversable.Traversable
105 class ITraversable(Interface):
107 def absolute_url(relative=0):
108 """Return the absolute URL of the object.
110 This a canonical URL based on the object's physical
111 containment path. It is affected by the virtual host
112 configuration, if any, and can be used by external
113 agents, such as a browser, to address the object.
115 If the relative argument is provided, with a true value, then
116 the value of virtual_url_path() is returned.
118 Some Products incorrectly use '/'+absolute_url(1) as an
119 absolute-path reference. This breaks in certain virtual
120 hosting situations, and should be changed to use
121 absolute_url_path() instead.
122 """
124 def absolute_url_path():
125 """Return the path portion of the absolute URL of the object.
127 This includes the leading slash, and can be used as an
128 'absolute-path reference' as defined in RFC 2396.
129 """
131 def virtual_url_path():
132 """Return a URL for the object, relative to the site root.
134 If a virtual host is configured, the URL is a path relative to
135 the virtual host's root object. Otherwise, it is the physical
136 path. In either case, the URL does not begin with a slash.
137 """
139 def getPhysicalPath():
140 '''Returns a path (an immutable sequence of strings)
141 that can be used to access this object again
142 later, for example in a copy/paste operation. getPhysicalRoot()
143 and getPhysicalPath() are designed to operate together.
144 '''
146 def unrestrictedTraverse(path, default=None, restricted=0):
147 """Lookup an object by path,
149 path -- The path to the object. May be a sequence of strings or a slash
150 separated string. If the path begins with an empty path element
151 (i.e., an empty string or a slash) then the lookup is performed
152 from the application root. Otherwise, the lookup is relative to
153 self. Two dots (..) as a path element indicates an upward traversal
154 to the acquisition parent.
156 default -- If provided, this is the value returned if the path cannot
157 be traversed for any reason (i.e., no object exists at that path or
158 the object is inaccessible).
160 restricted -- If false (default) then no security checking is performed.
161 If true, then all of the objects along the path are validated with
162 the security machinery. Usually invoked using restrictedTraverse().
163 """
165 def restrictedTraverse(path, default=None):
166 """Trusted code traversal code, always enforces security"""
169 # XXX: might contain non-API methods and outdated comments;
170 # not synced with ZopeBook API Reference;
171 # based on many classes
172 class IZopeObject(Interface):
174 isPrincipiaFolderish = Bool(
175 title=u"Is a folderish object",
176 description=u"Should be false for simple items",
177 )
179 meta_type = BytesLine(
180 title=u"Meta type",
181 description=u"The object's Zope2 meta type",
182 )
185 # XXX: might contain non-API methods and outdated comments;
186 # not synced with ZopeBook API Reference;
187 # based on OFS.SimpleItem.Item and App.Management.Tabs
188 class IManageable(Interface):
190 """Something that is manageable in the ZMI"""
192 manage_tabs = Attribute("""Management tabs""")
194 manage_options = Tuple(
195 title=u"Manage options",
196 )
198 def manage(URL1):
199 """Show management screen"""
201 def manage_afterAdd(item, container):
202 """Gets called after being added to a container"""
204 def manage_beforeDelete(item, container):
205 """Gets called before being deleted"""
207 def manage_afterClone(item):
208 """Gets called after being cloned"""
210 def manage_editedDialog(REQUEST, **args):
211 """Show an 'edited' dialog"""
213 def filtered_manage_options(REQUEST=None):
214 """ """
216 def manage_workspace(REQUEST):
217 """Dispatch to first interface in manage_options
218 """
220 def tabs_path_default(REQUEST):
221 """ """
223 def tabs_path_info(script, path):
224 """ """
226 def class_manage_path():
227 """ """
230 # XXX: might contain non-API methods and outdated comments;
231 # not synced with ZopeBook API Reference;
232 # based on OFS.SimpleItem.Item
233 class IItem(IZopeObject, IManageable, IFTPAccess, IDAVResource,
234 ICopySource, ITraversable, IOwned, IUndoSupport):
236 __name__ = BytesLine(
237 title=u"Name"
238 )
240 title = BytesLine(
241 title=u"Title"
242 )
244 icon = BytesLine(
245 title=u"Icon",
246 description=u"Name of icon, relative to SOFTWARE_URL",
247 )
249 def getId():
250 """Return the id of the object as a string.
252 This method should be used in preference to accessing an id
253 attribute of an object directly. The getId method is public.
254 """
256 def title_or_id():
257 """Returns the title if it is not blank and the id otherwise."""
259 def title_and_id():
260 """Returns the title if it is not blank and the id otherwise. If the
261 title is not blank, then the id is included in parens."""
263 def raise_standardErrorMessage(client=None, REQUEST={},
264 error_type=None, error_value=None, tb=None,
265 error_tb=None, error_message='',
266 tagSearch=None, error_log_url=''):
267 """Raise standard error message"""
270 # XXX: based on OFS.SimpleItem.Item_w__name__
271 class IItemWithName(IItem):
273 """Item with name"""
276 # XXX: based on OFS.SimpleItem.SimpleItem
277 class ISimpleItem(IItem, IPersistent, IAcquirer, IRoleManager):
279 """Not-so-simple item"""
282 # XXX: might contain non-API methods and outdated comments;
283 # not synced with ZopeBook API Reference;
284 # based on OFS.CopySupport.CopyContainer
285 class ICopyContainer(Interface):
287 """Interface for containerish objects which allow cut/copy/paste"""
289 # The following three methods should be overridden to store sub-objects
290 # as non-attributes.
291 def _setOb(id, object):
292 """ """
294 def _delOb(id):
295 """ """
297 def _getOb(id, default=None):
298 """ """
300 def manage_CopyContainerFirstItem(REQUEST):
301 """ """
303 def manage_CopyContainerAllItems(REQUEST):
304 """ """
306 def manage_cutObjects(ids=None, REQUEST=None):
307 """Put a reference to the objects named in ids in the clip board"""
309 def manage_copyObjects(ids=None, REQUEST=None, RESPONSE=None):
310 """Put a reference to the objects named in ids in the clip board"""
312 def _get_id(id):
313 """Allow containers to override the generation of object copy id by
314 attempting to call its _get_id method, if it exists."""
316 def manage_pasteObjects(cb_copy_data=None, REQUEST=None):
317 """Paste previously copied objects into the current object.
318 If calling manage_pasteObjects from python code, pass
319 the result of a previous call to manage_cutObjects or
320 manage_copyObjects as the first argument."""
322 manage_renameForm = Attribute("""Rename management view""")
324 def manage_renameObjects(ids=[], new_ids=[], REQUEST=None):
325 """Rename several sub-objects"""
327 def manage_renameObject(id, new_id, REQUEST=None):
328 """Rename a particular sub-object"""
330 def manage_clone(ob, id, REQUEST=None):
331 """Clone an object, creating a new object with the given id."""
333 def cb_dataValid():
334 """Return true if clipboard data seems valid."""
336 def cb_dataItems():
337 """List of objects in the clip board"""
339 def _verifyObjectPaste(object, validate_src=1):
340 """Verify whether the current user is allowed to paste the passed
341 object into self. This is determined by checking to see if the
342 user could create a new object of the same meta_type of the
343 object passed in and checking that the user actually is
344 allowed to access the passed in object in its existing
345 context.
347 Passing a false value for the validate_src argument will skip
348 checking the passed in object in its existing context. This is
349 mainly useful for situations where the passed in object has no
350 existing context, such as checking an object during an import
351 (the object will not yet have been connected to the
352 acquisition hierarchy)."""
355 # XXX: might contain non-API methods and outdated comments;
356 # not synced with ZopeBook API Reference;
357 # based on OFS.ObjectManager.ObjectManager
358 class IObjectManager(IZopeObject, ICopyContainer, INavigation, IManageable,
359 IAcquirer, IPersistent, IDAVCollection, ITraversable):
361 """Generic object manager
363 This interface provides core behavior for collections of heterogeneous
364 objects.
365 """
367 meta_types = Tuple(
368 title=u"Meta types",
369 description=u"Sub-object types that are specific to this object",
370 )
372 isAnObjectManager = Bool(
373 title=u"Is an object manager",
374 )
376 manage_main = Attribute(""" """)
377 manage_index_main = Attribute(""" """)
378 manage_addProduct = Attribute(""" """)
379 manage_importExportForm = Attribute(""" """)
381 def all_meta_types(interfaces=None):
382 """ """
384 def _subobject_permissions():
385 """ """
387 def filtered_meta_types(user=None):
388 """Return a list of the types for which the user has adequate
389 permission to add that type of object."""
391 def _setOb(id, object):
392 """ """
394 def _delOb(id):
395 """ """
397 def _getOb(id, default=None):
398 """ """
400 def _setObject(id, object, roles=None, user=None, set_owner=1):
401 """ """
403 def _delObject(id, dp=1):
404 """ """
406 def objectIds(spec=None):
407 """List the IDs of the subobjects of the current object.
409 If 'spec' is specified, returns only objects whose meta_types match
410 'spec'.
411 """
413 def objectValues(spec=None):
414 """List the subobjects of the current object.
416 If 'spec' is specified, returns only objects whose meta_types match
417 'spec'.
418 """
420 def objectItems(spec=None):
421 """List (ID, subobject) tuples for subobjects of the current object.
423 If 'spec' is specified, returns only objects whose meta_types match
424 'spec'.
425 """
427 def objectMap():
428 """Return a tuple of mappings containing subobject meta-data"""
430 def superValues(t):
431 """Return all of the objects of a given type located in this object
432 and containing objects."""
434 def manage_delObjects(ids=[], REQUEST=None):
435 """Delete a subordinate object
437 The objects specified in 'ids' get deleted.
438 """
440 def tpValues():
441 """Return a list of subobjects, used by tree tag."""
443 def manage_exportObject(id='', download=None, toxml=None,
444 RESPONSE=None,REQUEST=None):
445 """Exports an object to a file and returns that file."""
447 def manage_importObject(file, REQUEST=None, set_owner=1):
448 """Import an object from a file"""
450 def _importObjectFromFile(filepath, verify=1, set_owner=1):
451 """ """
453 def __getitem__(key):
454 """ """
457 # XXX: might contain non-API methods and outdated comments;
458 # not synced with ZopeBook API Reference;
459 # based on OFS.FindSupport.FindSupport
460 class IFindSupport(Interface):
462 """Find support for Zope Folders"""
464 manage_findFrame = Attribute(""" """)
465 manage_findForm = Attribute(""" """)
466 manage_findAdv = Attribute(""" """)
467 manage_findResult = Attribute(""" """)
469 def ZopeFind(obj, obj_ids=None, obj_metatypes=None,
470 obj_searchterm=None, obj_expr=None,
471 obj_mtime=None, obj_mspec=None,
472 obj_permission=None, obj_roles=None,
473 search_sub=0,
474 REQUEST=None, result=None, pre=''):
475 """Zope Find interface"""
477 PrincipiaFind = ZopeFind
479 def ZopeFindAndApply(obj, obj_ids=None, obj_metatypes=None,
480 obj_searchterm=None, obj_expr=None,
481 obj_mtime=None, obj_mspec=None,
482 obj_permission=None, obj_roles=None,
483 search_sub=0,
484 REQUEST=None, result=None, pre='',
485 apply_func=None, apply_path=''):
486 """Zope Find interface and apply"""
489 # XXX: might contain non-API methods and outdated comments;
490 # not synced with ZopeBook API Reference;
491 # based on OFS.PropertyManager.PropertyManager
492 class IPropertyManager(Interface):
494 """
495 The PropertyManager mixin class provides an object with
496 transparent property management. An object which wants to
497 have properties should inherit from PropertyManager.
499 An object may specify that it has one or more predefined
500 properties, by specifying an _properties structure in its
501 class::
503 _properties=({'id':'title', 'type': 'string', 'mode': 'w'},
504 {'id':'color', 'type': 'string', 'mode': 'w'},
505 )
507 The _properties structure is a sequence of dictionaries, where
508 each dictionary represents a predefined property. Note that if a
509 predefined property is defined in the _properties structure, you
510 must provide an attribute with that name in your class or instance
511 that contains the default value of the predefined property.
513 Each entry in the _properties structure must have at least an 'id'
514 and a 'type' key. The 'id' key contains the name of the property,
515 and the 'type' key contains a string representing the object's type.
516 The 'type' string must be one of the values: 'float', 'int', 'long',
517 'string', 'lines', 'text', 'date', 'tokens', 'selection', or
518 'multiple section'.
520 For 'selection' and 'multiple selection' properties, there is an
521 addition item in the property dictionay, 'select_variable' which
522 provides the name of a property or method which returns a list of
523 strings from which the selection(s) can be chosen.
525 Each entry in the _properties structure may *optionally* provide a
526 'mode' key, which specifies the mutability of the property. The 'mode'
527 string, if present, must contain 0 or more characters from the set
528 'w','d'.
530 A 'w' present in the mode string indicates that the value of the
531 property may be changed by the user. A 'd' indicates that the user
532 can delete the property. An empty mode string indicates that the
533 property and its value may be shown in property listings, but that
534 it is read-only and may not be deleted.
536 Entries in the _properties structure which do not have a 'mode' key
537 are assumed to have the mode 'wd' (writeable and deleteable).
539 To fully support property management, including the system-provided
540 tabs and user interfaces for working with properties, an object which
541 inherits from PropertyManager should include the following entry in
542 its manage_options structure::
544 {'label':'Properties', 'action':'manage_propertiesForm',}
546 to ensure that a 'Properties' tab is displayed in its management
547 interface. Objects that inherit from PropertyManager should also
548 include the following entry in its __ac_permissions__ structure::
550 ('Manage properties', ('manage_addProperty',
551 'manage_editProperties',
552 'manage_delProperties',
553 'manage_changeProperties',)),
554 """
555 manage_propertiesForm = Attribute(""" """)
556 manage_propertyTypeForm = Attribute(""" """)
558 title = BytesLine(
559 title=u"Title"
560 )
562 _properties = Tuple(
563 title=u"Properties",
564 )
566 propertysheets = Attribute(""" """)
568 def valid_property_id(id):
569 """ """
571 def hasProperty(id):
572 """Return true if object has a property 'id'"""
574 def getProperty(id, d=None):
575 """Get the property 'id', returning the optional second
576 argument or None if no such property is found."""
578 def getPropertyType(id):
579 """Get the type of property 'id', returning None if no
580 such property exists"""
582 def _wrapperCheck(object):
583 """Raise an error if an object is wrapped."""
585 def _setPropValue(id, value):
586 """ """
588 def _delPropValue(id):
589 """ """
591 def _setProperty(id, value, type='string'):
592 """Set property.
594 For selection and multiple selection properties the value argument
595 indicates the select variable of the property.
596 """
598 def _updateProperty(id, value):
599 """Update the value of an existing property.
601 If value is a string, an attempt will be made to convert the value to
602 the type of the existing property.
603 """
605 def _delProperty(id):
606 """ """
608 def propertyIds():
609 """Return a list of property ids """
611 def propertyValues():
612 """Return a list of actual property objects """
614 def propertyItems():
615 """Return a list of (id,property) tuples """
617 def _propertyMap():
618 """Return a tuple of mappings, giving meta-data for properties """
620 def propertyMap():
621 """
622 Return a tuple of mappings, giving meta-data for properties.
623 Return copies of the real definitions for security.
624 """
626 def propertyLabel(id):
627 """Return a label for the given property id
628 """
630 def propdict():
631 """ """
633 # Web interface
635 def manage_addProperty(id, value, type, REQUEST=None):
636 """Add a new property via the web. Sets a new property with
637 the given id, type, and value."""
639 def manage_editProperties(REQUEST):
640 """Edit object properties via the web.
641 The purpose of this method is to change all property values,
642 even those not listed in REQUEST; otherwise checkboxes that
643 get turned off will be ignored. Use manage_changeProperties()
644 instead for most situations.
645 """
647 def manage_changeProperties(REQUEST=None, **kw):
648 """Change existing object properties.
650 Change object properties by passing either a mapping object
651 of name:value pairs {'foo':6} or passing name=value parameters
652 """
654 def manage_changePropertyTypes(old_ids, props, REQUEST=None):
655 """Replace one set of properties with another
657 Delete all properties that have ids in old_ids, then add a
658 property for each item in props. Each item has a new_id,
659 new_value, and new_type. The type of new_value should match
660 new_type.
661 """
663 def manage_delProperties(ids=None, REQUEST=None):
664 """Delete one or more properties specified by 'ids'."""
667 # XXX: based on OFS.Folder.Folder
668 class IFolder(IObjectManager, IPropertyManager, IRoleManager,
669 IDAVCollection, IItem, IFindSupport):
671 """Folders are basic container objects that provide a standard
672 interface for object management. Folder objects also implement a
673 management interface and can have arbitrary properties."""
676 # XXX: based on OFS.OrderedFolder.OrderedFolder
677 class IOrderedFolder(IOrderedContainer, IFolder):
679 """Ordered folder"""
682 # XXX: might contain non-API methods and outdated comments;
683 # not synced with ZopeBook API Reference;
684 # based on OFS.Application.Application
685 class IApplication(IFolder, IContainmentRoot):
687 """Top-level system object"""
689 isTopLevelPrincipiaApplicationObject = Bool(
690 title=u"Is top level Principa application object",
691 )
693 HelpSys = Attribute("Help system")
695 p_ = Attribute(""" """)
696 misc_ = Attribute("Misc.")
698 def PrincipiaRedirect(destination, URL1):
699 """Utility function to allow user-controlled redirects"""
701 Redirect = ZopeRedirect = PrincipiaRedirect
703 def __bobo_traverse__(REQUEST, name=None):
704 """Bobo traverse"""
706 def PrincipiaTime(*args):
707 """Utility function to return current date/time"""
709 ZopeTime = PrincipiaTime
711 def ZopeAttributionButton():
712 """Returns an HTML fragment that displays the 'powered by zope'
713 button along with a link to the Zope site."""
715 test_url = ZopeAttributionButton
717 def absolute_url(relative=0):
718 '''The absolute URL of the root object is BASE1 or "/".'''
720 def absolute_url_path():
721 '''The absolute URL path of the root object is BASEPATH1 or "/".'''
723 def virtual_url_path():
724 '''The virtual URL path of the root object is empty.'''
726 def getPhysicalPath():
727 '''Returns a path that can be used to access this object again
728 later, for example in a copy/paste operation. Designed to
729 be used with getPhysicalRoot().
730 '''
732 def getPhysicalRoot():
733 """Returns self"""
735 def fixupZClassDependencies(rebuild=0):
736 """ """
738 def checkGlobalRegistry():
739 """Check the global (zclass) registry for problems, which can
740 be caused by things like disk-based products being deleted.
741 Return true if a problem is found"""
744 ##################################################
745 # Event interfaces
747 from zope.app.event.interfaces import IObjectEvent
749 class IObjectWillBeMovedEvent(IObjectEvent):
750 """An object will be moved."""
751 oldParent = Attribute("The old location parent for the object.")
752 oldName = Attribute("The old location name for the object.")
753 newParent = Attribute("The new location parent for the object.")
754 newName = Attribute("The new location name for the object.")
756 class IObjectWillBeAddedEvent(IObjectWillBeMovedEvent):
757 """An object will be added to a container."""
759 class IObjectWillBeRemovedEvent(IObjectWillBeMovedEvent):
760 """An object will be removed from a container"""
762 class IObjectClonedEvent(IObjectEvent):
763 """An object has been cloned (a la Zope 2).
765 This is for Zope 2 compatibility, subscribers should really use
766 IObjectCopiedEvent or IObjectAddedEvent, depending on their use
767 cases.
769 event.object is the copied object, already added to its container.
770 Note that this event is dispatched to all sublocations.
771 """