Appendix B

This reference describes the interfaces to the most common set of basic Zope objects. This reference is useful while writing DTML, Perl, and Python scripts that create and manipulate Zope objects.

module `AccessControl`

AccessControl: Security functions and classes

The functions and classes in this module are available to Python-based Scripts and Page Templates.

class `SecurityManager`

A security manager provides methods for checking access and managing executable context and policies

`calledByExecutable(self)`

Return a boolean value indicating if this context was called by an executable.

permission: Always available

`validate(accessed=None, container=None, name=None, value=None, roles=None)`

Validate access.

Arguments:

accessed: the object that was being accessed
container: the object the value was found in
name: The name used to access the value
value: The value retrieved though the access.
roles: The roles of the object if already known.

The arguments may be provided as keyword arguments. Some of these arguments may be omitted, however, the policy may reject access in some cases when arguments are omitted. It is best to provide all the values possible.

permission: Always available

`checkPermission(self, permission, object)`

Check whether the security context allows the given permission on the given object.

permission: Always available

`getUser(self)`

Get the current authenticated user. See the AuthenticatedUser class.

permission: Always available

`validateValue(self, value, roles=None)`

Convenience for common case of simple value validation.

permission: Always available

`def getSecurityManager()`

Returns the security manager. See the SecurityManager class.

module `AuthenticatedUser`

class `AuthenticatedUser`

This interface needs to be supported by objects that are returned by user validation and used for access control.

`getUserName()`

Return the name of a user

Permission: Always available

`getId()`

Get the ID of the user. The ID can be used from Python to get the user from the user's UserDatabase.

Permission: Always available

`has_role(roles, object=None)`

Return true if the user has at least one role from a list of roles, optionally in the context of an object.

Permission: Always available

`getRoles()`

Return a list of the user's roles.

Permission: Always available

`has_permission(permission, object)`

Return true if the user has a permission on an object.

Permission: Always available

`getRolesInContext(object)`

Return the list of roles assigned to the user, including local roles assigned in context of an object.

Permission: Always available

`getDomains()`

Return the list of domain restrictions for a user.

Permission: Always available

module `DTMLDocument`

class `DTMLDocument(ObjectManagerItem, PropertyManager)`

A DTML Document is a Zope object that contains and executes DTML code. It is useful to represent web pages.

`manage_edit(data, title)`

Change the DTML Document, replacing its contents with data and changing its title.

The data argument may be a file object or a string.

Permission: Change DTML Documents

`document_src()`

Returns the unrendered source text of the DTML Document.

Permission: View management screens

`call(client=None, REQUEST={}, RESPONSE=None, **kw)`

Calling a DTMLDocument causes the Document to interpret the DTML code that it contains. The method returns the result of the interpretation, which can be any kind of object.

To accomplish its task, DTML Document often needs to resolve various names into objects. For example, when the code '<dtml-var spam>' is executed, the DTML engine tries to resolve the name spam.

In order to resolve names, the Document must be passed a namespace to look them up in. This can be done several ways:

By passing a client object -- If the argument client is passed, then names are looked up as attributes on the argument.
By passing a REQUEST mapping -- If the argument REQUEST is passed, then names are looked up as items on the argument. If the object is not a mapping, an TypeError will be raised when a name lookup is attempted.
By passing keyword arguments -- names and their values can be passed as keyword arguments to the Document.

The namespace given to a DTML Document is the composite of these three methods. You can pass any number of them or none at all. Names are looked up first in the keyword arguments, then in the client, and finally in the mapping.

A DTMLDocument implicitly pass itself as a client argument in addition to the specified client, so names are looked up in the DTMLDocument itself.

Passing in a namespace to a DTML Document is often referred to as providing the Document with a context.

DTML Documents can be called three ways.

From DTML

A DTML Document can be called from another DTML Method or Document:

          <dtml-var standard_html_header>            <dtml-var aDTMLDocument>          <dtml-var standard_html_footer>

In this example, the Document aDTMLDocument is being called from another DTML object by name. The calling method passes the value this as the client argument and the current DTML namespace as the REQUEST argument. The above is identical to this following usage in a DTML Python expression:

          <dtml-var standard_html_header>            <dtml-var "aDTMLDocument(_.None, _)">          <dtml-var standard_html_footer>

From Python

Products, External Methods, and Scripts can call a DTML Document in the same way as calling a DTML Document from a Python expression in DTML; as shown in the previous example.

By the Publisher

When the URL of a DTML Document is fetched from Zope, the DTML Document is called by the publisher. The REQUEST object is passed as the second argument to the Document.

Permission: View

`get_size()`

Returns the size of the unrendered source text of the DTML Document in bytes.

Permission: View

ObjectManager Constructor

`manage_addDocument(id, title)`

Add a DTML Document to the current ObjectManager

module `DTMLMethod`

class `DTMLMethod(ObjectManagerItem)`

A DTML Method is a Zope object that contains and executes DTML code. It can act as a template to display other objects. It can also hold small pieces of content which are inserted into other DTML Documents or DTML Methods.

The DTML Method's id is available via the document_id variable and the title is available via the document_title variable.

`manage_edit(data, title)`

Change the DTML Method, replacing its contents with data and changing its title.

The data argument may be a file object or a string.

Permission: Change DTML Methods

`document_src()`

Returns the unrendered source text of the DTML Method.

Permission: View management screens

`call(client=None, REQUEST={}, **kw)`

Calling a DTMLMethod causes the Method to interpret the DTML code that it contains. The method returns the result of the interpretation, which can be any kind of object.

To accomplish its task, DTML Method often needs to resolve various names into objects. For example, when the code '<dtml-var spam>' is executed, the DTML engine tries to resolve the name spam.

In order to resolve names, the Method must be passed a namespace to look them up in. This can be done several ways:

By passing a client object -- If the argument client is passed, then names are looked up as attributes on the argument.
By passing a REQUEST mapping -- If the argument REQUEST is passed, then names are looked up as items on the argument. If the object is not a mapping, an TypeError will be raised when a name lookup is attempted.
By passing keyword arguments -- names and their values can be passed as keyword arguments to the Method.

The namespace given to a DTML Method is the composite of these three methods. You can pass any number of them or none at all. Names will be looked up first in the keyword argument, next in the client and finally in the mapping.

Unlike DTMLDocuments, DTMLMethods do not look up names in their own instance dictionary.

Passing in a namespace to a DTML Method is often referred to as providing the Method with a context.

DTML Methods can be called three ways:

From DTML

A DTML Method can be called from another DTML Method or Document:

          <dtml-var standard_html_header>            <dtml-var aDTMLMethod>          <dtml-var standard_html_footer>

In this example, the Method aDTMLMethod is being called from another DTML object by name. The calling method passes the value this as the client argument and the current DTML namespace as the REQUEST argument. The above is identical to this following usage in a DTML Python expression:

          <dtml-var standard_html_header>            <dtml-var "aDTMLMethod(_.None, _)">          <dtml-var standard_html_footer>

From Python

Products, External Methods, and Scripts can call a DTML Method in the same way as calling a DTML Method from a Python expression in DTML; as shown in the previous example.

By the Publisher

When the URL of a DTML Method is fetched from Zope, the DTML Method is called by the publisher. The REQUEST object is passed as the second argument to the Method.

Permission: View

`get_size()`

Returns the size of the unrendered source text of the DTML Method in bytes.

Permission: View

ObjectManager Constructor

`manage_addDTMLMethod(id, title)`

Add a DTML Method to the current ObjectManager

module `DateTime`

class `DateTime`

The DateTime object provides an interface for working with dates and times in various formats. DateTime also provides methods for calendar operations, date and time arithmetic and formatting.

DateTime objects represent instants in time and provide interfaces for controlling its representation without affecting the absolute value of the object.

DateTime objects may be created from a wide variety of string or numeric data, or may be computed from other DateTime objects. DateTimes support the ability to convert their representations to many major timezones, as well as the ability to create a DateTime object in the context of a given timezone.

DateTime objects provide partial numerical behavior:

Two date-time objects can be subtracted to obtain a time, in days between the two.
A date-time object and a positive or negative number may be added to obtain a new date-time object that is the given number of days later than the input date-time object.
A positive or negative number and a date-time object may be added to obtain a new date-time object that is the given number of days later than the input date-time object.
A positive or negative number may be subtracted from a date-time object to obtain a new date-time object that is the given number of days earlier than the input date-time object.

DateTime objects may be converted to integer, long, or float numbers of days since January 1, 1901, using the standard int, long, and float functions (Compatibility Note: int, long and float return the number of days since 1901 in GMT rather than local machine timezone). DateTime objects also provide access to their value in a float format usable with the python time module, provided that the value of the object falls in the range of the epoch-based time module.

A DateTime object should be considered immutable; all conversion and numeric operations return a new DateTime object rather than modify the current object.

A DateTime object always maintains its value as an absolute UTC time, and is represented in the context of some timezone based on the arguments used to create the object. A DateTime object's methods return values based on the timezone context.

Note that in all cases the local machine timezone is used for representation if no timezone is specified.

DateTimes may be created with from zero to seven arguments.

If the function is called with no arguments, then the current date/time is returned, represented in the timezone of the local machine.
If the function is invoked with a single string argument which is a recognized timezone name, an object representing the current time is returned, represented in the specified timezone.
If the function is invoked with a single string argument representing a valid date/time, an object representing that date/time will be returned.
As a general rule, any date-time representation that is recognized and unambiguous to a resident of North America is acceptable.(The reason for this qualification is that in North America, a date like: 2/1/1994 is interpreted as February 1, 1994, while in some parts of the world, it is interpreted as January 2, 1994.) A date/time string consists of two components, a date component and an optional time component, separated by one or more spaces. If the time component is omitted, 12:00am is assumed. Any recognized timezone name specified as the final element of the date/time string will be used for computing the date/time value. (If you create a DateTime with the string Mar 9, 1997 1:45pm US/Pacific, the value will essentially be the same as if you had captured time.time() at the specified date and time on a machine in that timezone):
```
          e=DateTime("US/Eastern")          # returns current date/time, represented in US/Eastern.          x=DateTime("1997/3/9 1:45pm")          # returns specified time, represented in local machine zone.          y=DateTime("Mar 9, 1997 13:45:00")          # y is equal to x
```
The date component consists of year, month, and day values. The year value must be a one-, two-, or four-digit integer. If a one- or two-digit year is used, the year is assumed to be in the twentieth century. The month may be an integer, from 1 to 12, a month name, or a month abbreviation, where a period may optionally follow the abbreviation. The day must be an integer from 1 to the number of days in the month. The year, month, and day values may be separated by periods, hyphens, forward slashes, or spaces. Extra spaces are permitted around the delimiters. Year, month, and day values may be given in any order as long as it is possible to distinguish the components. If all three components are numbers that are less than 13, then a month-day-year ordering is assumed.
The time component consists of hour, minute, and second values separated by colons. The hour value must be an integer between 0 and 23 inclusively. The minute value must be an integer between 0 and 59 inclusively. The second value may be an integer value between 0 and 59.999 inclusively. The second value or both the minute and second values may be omitted. The time may be followed by am or pm in upper or lower case, in which case a 12-hour clock is assumed.
If the DateTime function is invoked with a single Numeric argument, the number is assumed to be a floating point value such as that returned by time.time().
A DateTime object is returned that represents the gmt value of the time.time() float represented in the local machine's timezone.
If the function is invoked with two numeric arguments, then the first is taken to be an integer year and the second argument is taken to be an offset in days from the beginning of the year, in the context of the local machine timezone. The date-time value returned is the given offset number of days from the beginning of the given year, represented in the timezone of the local machine. The offset may be positive or negative. Two-digit years are assumed to be in the twentieth century.

If the function is invoked with two arguments, the first a float representing a number of seconds past the epoch in gmt (such as those returned by time.time()) and the second a string naming a recognized timezone, a DateTime with a value of that gmt time will be returned, represented in the given timezone.:

          import time          t=time.time()          now_east=DateTime(t,'US/Eastern')          # Time t represented as US/Eastern          now_west=DateTime(t,'US/Pacific')          # Time t represented as US/Pacific          # now_east == now_west          # only their representations are different

If the function is invoked with three or more numeric arguments, then the first is taken to be an integer year, the second is taken to be an integer month, and the third is taken to be an integer day. If the combination of values is not valid, then a DateTimeError is raised. Two-digit years are assumed to be in the twentieth century. The fourth, fifth, and sixth arguments specify a time in hours, minutes, and seconds; hours and minutes should be positive integers and seconds is a positive floating point value, all of these default to zero if not given. An optional string may be given as the final argument to indicate timezone (the effect of this is as if you had taken the value of time.time() at that time on a machine in the specified timezone).

If a string argument passed to the DateTime constructor cannot be parsed, it will raise DateTime.SyntaxError. Invalid date, time, or timezone components will raise a DateTime.DateTimeError.

The module function Timezones() will return a list of the timezones recognized by the DateTime module. Recognition of timezone names is case-insensitive.

`strftime(format)`

Return date time string formatted according to format

See Python's time.strftime function.

`dow()`

Return the integer day of the week, where Sunday is 0

Permission: Always available

`aCommon()`

Return a string representing the object's value in the format: Mar 1, 1997 1:45 pm

Permission: Always available

`h_12()`

Return the 12-hour clock representation of the hour

Permission: Always available

`Mon_()`

Compatibility: see pMonth

Permission: Always available

`HTML4()`

Return the object in the format used in the HTML4.0 specification, one of the standard forms in ISO8601.

See HTML 4.0 Specification

Dates are output as: YYYY-MM-DDTHH:MM:SSZ T, Z are literal characters. The time is in UTC.

Permission: Always available

`greaterThanEqualTo(t)`

Compare this DateTime object to another DateTime object OR a floating point number such as that which is returned by the python time module. Returns true if the object represents a date/time greater than or equal to the specified DateTime or time module style time. Revised to give more correct results through comparison of long integer milliseconds.

Permission: Always available

`dayOfYear()`

Return the day of the year, in context of the timezone representation of the object

Permission: Always available

`lessThan(t)`

Compare this DateTime object to another DateTime object OR a floating point number such as that which is returned by the python time module. Returns true if the object represents a date/time less than the specified DateTime or time module style time. Revised to give more correct results through comparison of long integer milliseconds.

Permission: Always available

`AMPM()`

Return the time string for an object to the nearest second.

Permission: Always available

`isCurrentHour()`

Return true if this object represents a date/time that falls within the current hour, in the context of this object's timezone representation

Permission: Always available

`Month()`

Return the full month name

Permission: Always available

`mm()`

Return month as a 2 digit string

Permission: Always available

`ampm()`

Return the appropriate time modifier (am or pm)

Permission: Always available

`hour()`

Return the 24-hour clock representation of the hour

Permission: Always available

`aCommonZ()`

Return a string representing the object's value in the format: Mar 1, 1997 1:45 pm US/Eastern

Permission: Always available

`Day_()`

Compatibility: see pDay

Permission: Always available

`pCommon()`

Return a string representing the object's value in the format: Mar. 1, 1997 1:45 pm

Permission: Always available

`minute()`

Return the minute

Permission: Always available

`day()`

Return the integer day

Permission: Always available

`earliestTime()`

Return a new DateTime object that represents the earliest possible time (in whole seconds) that still falls within the current object's day, in the object's timezone context

Permission: Always available

`Date()`

Return the date string for the object.

Permission: Always available

`Time()`

Return the time string for an object to the nearest second.

Permission: Always available

`isFuture()`

Return true if this object represents a date/time later than the time of the call

Permission: Always available

`greaterThan(t)`

Compare this DateTime object to another DateTime object OR a floating point number such as that which is returned by the python time module. Returns true if the object represents a date/time greater than the specified DateTime or time module style time. Revised to give more correct results through comparison of long integer milliseconds.

Permission: Always available

`TimeMinutes()`

Return the time string for an object not showing seconds.

Permission: Always available

`yy()`

Return calendar year as a 2 digit string

Permission: Always available

`isCurrentDay()`

Return true if this object represents a date/time that falls within the current day, in the context of this object's timezone representation

Permission: Always available

`dd()`

Return day as a 2 digit string

Permission: Always available

`rfc822()`

Return the date in RFC 822 format

Permission: Always available

`isLeapYear()`

Return true if the current year (in the context of the object's timezone) is a leap year

Permission: Always available

`fCommon()`

Return a string representing the object's value in the format: March 1, 1997 1:45 pm

Permission: Always available

`isPast()`

Return true if this object represents a date/time earlier than the time of the call

Permission: Always available

`fCommonZ()`

Return a string representing the object's value in the format: March 1, 1997 1:45 pm US/Eastern

Permission: Always available

`timeTime()`

Return the date/time as a floating-point number in UTC, in the format used by the python time module. Note that it is possible to create date/time values with DateTime that have no meaningful value to the time module.

Permission: Always available

`toZone(z)`

Return a DateTime with the value as the current object, represented in the indicated timezone.

Permission: Always available

`lessThanEqualTo(t)`

Compare this DateTime object to another DateTime object OR a floating point number such as that which is returned by the python time module. Returns true if the object represents a date/time less than or equal to the specified DateTime or time module style time. Revised to give more correct results through comparison of long integer milliseconds.

Permission: Always available

`Mon()`

Compatibility: see aMonth

Permission: Always available

`parts()`

Return a tuple containing the calendar year, month, day, hour, minute second and timezone of the object

Permission: Always available

`isCurrentYear()`

Return true if this object represents a date/time that falls within the current year, in the context of this object's timezone representation

Permission: Always available

`PreciseAMPM()`

Return the time string for the object.

Permission: Always available

`AMPMMinutes()`

Return the time string for an object not showing seconds.

Permission: Always available

`equalTo(t)`

Compare this DateTime object to another DateTime object OR a floating point number such as that which is returned by the python time module. Returns true if the object represents a date/time equal to the specified DateTime or time module style time. Revised to give more correct results through comparison of long integer milliseconds.

Permission: Always available

`pDay()`

Return the abbreviated (with period) name of the day of the week

Permission: Always available

`notEqualTo(t)`

Compare this DateTime object to another DateTime object OR a floating point number such as that which is returned by the python time module. Returns true if the object represents a date/time not equal to the specified DateTime or time module style time. Revised to give more correct results through comparison of long integer milliseconds.

Permission: Always available

`h_24()`

Return the 24-hour clock representation of the hour

Permission: Always available

`pCommonZ()`

Return a string representing the object's value in the format: Mar. 1, 1997 1:45 pm US/Eastern

Permission: Always available

`isCurrentMonth()`

Return true if this object represents a date/time that falls within the current month, in the context of this object's timezone representation

Permission: Always available

`DayOfWeek()`

Compatibility: see Day

Permission: Always available

`latestTime()`

Return a new DateTime object that represents the latest possible time (in whole seconds) that still falls within the current object's day, in the object's timezone context

Permission: Always available

`dow_1()`

Return the integer day of the week, where Sunday is 1

Permission: Always available

`timezone()`

Return the timezone in which the object is represented.

Permission: Always available

`year()`

Return the calendar year of the object

Permission: Always available

`PreciseTime()`

Return the time string for the object.

Permission: Always available

`ISO()`

Return the object in ISO standard format

Dates are output as: YYYY-MM-DD HH:MM:SS

Permission: Always available

`millis()`

Return the millisecond since the epoch in GMT.

Permission: Always available

`second()`

Return the second

Permission: Always available

`month()`

Return the month of the object as an integer

Permission: Always available

`pMonth()`

Return the abbreviated (with period) month name.

Permission: Always available

`aMonth()`

Return the abbreviated month name.

Permission: Always available

`isCurrentMinute()`

Return true if this object represents a date/time that falls within the current minute, in the context of this object's timezone representation

Permission: Always available

`Day()`

Return the full name of the day of the week

Permission: Always available

`aDay()`

Return the abbreviated name of the day of the week

Permission: Always available

module `ExternalMethod`

class `ExternalMethod`

Web-callable functions that encapsulate external Python functions.

The function is defined in an external file. This file is treated like a module, but is not a module. It is not imported directly, but is rather read and evaluated. The file must reside in the Extensions subdirectory of the Zope installation, or in an Extensions subdirectory of a product directory.

Due to the way ExternalMethods are loaded, it is not currently possible to import Python modules that reside in the Extensions directory. It is possible to import modules found in the lib/python directory of the Zope installation, or in packages that are in the lib/python directory.

`manage_edit(title, module, function, REQUEST=None)`

Change the External Method.

See the description of manage_addExternalMethod for a description of the arguments module and function.

Note that calling manage_edit causes the "module" to be effectively reloaded. This is useful during debugging to see the effects of changes, but can lead to problems of functions rely on shared global data.

`call(*args, **kw)`

Call the External Method.

Calling an External Method is roughly equivalent to calling the original actual function from Python. Positional and keyword parameters can be passed as usual. Note however that unlike the case of a normal Python method, the "self" argument must be passed explicitly. An exception to this rule is made if:

The supplied number of arguments is one less than the required number of arguments, and
The name of the function's first argument is self.

In this case, the URL parent of the object is supplied as the first argument.

ObjectManager Constructor

`manage_addExternalMethod(id, title, module, function)`

Add an external method to an ObjectManager.

In addition to the standard object-creation arguments, id and title, the following arguments are defined:

function: The name of the python function. This can be a an ordinary Python function, or a bound method.
module: The name of the file containing the function definition.

The module normally resides in the Extensions directory, however, the file name may have a prefix of product., indicating that it should be found in a product directory.

For example, if the module is: ACMEWidgets.foo, then an attempt will first be made to use the file lib/python/Products/ACMEWidgets/Extensions/foo.py. If this fails, then the file Extensions/ACMEWidgets.foo.py will be used.

module `File`

class `File(ObjectManagerItem, PropertyManager)`

A File is a Zope object that contains file content. A File object can be used to upload or download file information with Zope.

Using a File object in Zope is easy. The most common usage is to display the contents of a file object in a web page. This is done by simply referencing the object from DTML:

      <dtml-var standard_html_header>        <dtml-var FileObject>      <dtml-var standard_html_footer>

A more complex example is presenting the File object for download by the user. The next example displays a link to every File object in a folder for the user to download:

      <dtml-var standard_html_header>      <ul>        <dtml-in "ObjectValues('File')">          <li><a href="<dtml-var absolute_url>"><dtml-var          id></a></li>        </dtml-in>      </ul>      <dtml-var standard_html_footer>

In this example, the absolute_url method and id are used to create a list of HTML hyperlinks to all of the File objects in the current Object Manager.

Also see ObjectManager for details on the objectValues method.

`getContentType()`

Returns the content type of the file.

Permission: View

`update_data(data, content_type=None, size=None)`

Updates the contents of the File with data.

The data argument must be a string. If content_type is not provided, then a content type will not be set. If size is not provided, the size of the file will be computed from data.

Permission: Python only

`getSize()`

Returns the size of the file in bytes.

Permission: View

ObjectManager Constructor

`manage_addFile(id, file="", title="", precondition="", content_type="")`

Add a new File object.

Creates a new File object id with the contents of file

module `Folder`

class `Folder(ObjectManagerItem, ObjectManager, PropertyManager)`

A Folder is a generic container object in Zope.

Folders are the most common ObjectManager subclass in Zope.

ObjectManager Constructor

`manage_addFolder(id, title)`

Add a Folder to the current ObjectManager

Permission: Add Folders

module `Image`

class `Image(File)`

An Image is a Zope object that contains image content. An Image object can be used to upload or download image information with Zope.

Image objects have two properties the define their dimension, height and width. These are calculated when the image is uploaded. For image types that Zope does not understand, these properties may be undefined.

Using a Image object in Zope is easy. The most common usage is to display the contents of an image object in a web page. This is done by simply referencing the object from DTML:

      <dtml-var standard_html_header>        <dtml-var ImageObject>      <dtml-var standard_html_footer>

This will generate an HTML IMG tag referencing the URL to the Image. This is equivalent to:

      <dtml-var standard_html_header>        <dtml-with ImageObject>          <img src="<dtml-var absolute_url>">        </dtml-with>      <dtml-var standard_html_footer>

You can control the image display more precisely with the tag method. For example:

      <dtml-var "ImageObject.tag(border='5', align='left')">

`tag(height=None, width=None, alt=None, scale=0, xscale=0, yscale=0, **args)`

This method returns a string which contains an HTML IMG tag reference to the image.

Optionally, the height, width, alt, scale, xscale and yscale arguments can be provided which are turned into HTML IMG tag attributes. Note, height and width are provided by default, and alt comes from the title_or_id method.

Keyword arguments may be provided to support other or future IMG tag attributes. The one exception to this is the HTML Cascading Style Sheet tag class. Because the word class is a reserved keyword in Python, you must instead use the keyword argument css_class. This will be turned into a class HTML tag attribute on the rendered img tag.

Permission: View

ObjectManager Constructor

`manage_addImage(id, file, title="", precondition="", content_type="")`

Add a new Image object.

Creates a new Image object id with the contents of file.

module `MailHost`

class `MailHost`

MailHost objects work as adapters to Simple Mail Transfer Protocol (SMTP) servers. MailHosts are used by DTML sendmail tags to find the proper host to deliver mail to.

`send(messageText, mto=None, mfrom=None, subject=None, encode=None)`

Sends an email message where the messageText is an rfc822 formatted message. This allows you complete control over the message headers, including setting any extra headers such as Cc: and Bcc:. The arguments are:

messageText: The mail message. It can either be a rfc822 formed text with header fields, or just a body without any header fields. The other arguments given will override the header fields in the message, if they exist.
mto: A comma-separated string or list of recipient(s) of the message.
mfrom: The address of the message sender.
subject: The subject of the message.
encode: The rfc822 defined encoding of the message. The default of None means no encoding is done. Valid values are base64, quoted-printable and uuencode.

`simple_send(self, mto, mfrom, subject, body)`

Sends a message. Only To:, From: and Subject: headers can be set. The arguments are:

mto: A comma-separated string or list of recipient(s) of the message.
mfrom: The address of the message sender.
subject: The subject of the message.
body: The body of the message.

MailHost Constructor

`manage_addMailHost(id, title="", smtp_host=None, localhost=localhost, smtp_port=25, timeout=1.0)`

Add a mailhost object to an ObjectManager.

module `ObjectManager`

class `ObjectManager`

An ObjectManager contains other Zope objects. The contained objects are Object Manager Items.

To create an object inside an object manager use manage_addProduct:

      self.manage_addProduct['OFSP'].manage_addFolder(id, title)

In DTML this would be:

        <dtml-call "manage_addProduct['OFSP'].manage_addFolder(id, title)">

These examples create a new Folder inside the current ObjectManager.

manage_addProduct is a mapping that provides access to product constructor methods. It is indexed by product id.

Constructor methods are registered during product initialization and should be documented in the API docs for each addable object.

`objectItems(type=None)`

This method returns a sequence of (id, object) tuples.

Like objectValues and objectIds, it accepts one argument, either a string or a list to restrict the results to objects of a given meta_type or set of meta_types.

Each tuple's first element is the id of an object contained in the Object Manager, and the second element is the object itself.

Example:

        <dtml-in objectItems>         id: <dtml-var sequence-key>,         type: <dtml-var meta_type>        <dtml-else>          There are no sub-objects.        </dtml-in>

Permission: Access contents information

`superValues(type)`

This method returns a list of objects of a given meta_type(es) contained in the Object Manager and all its parent Object Managers.

The type argument specifies the meta_type(es). It can be a string specifying one meta_type, or it can be a list of strings to specify many.

Permission: Python only

`objectValues(type=None)`

This method returns a sequence of contained objects.

Like objectItems and objectIds, it accepts one argument, either a string or a list to restrict the results to objects of a given meta_type or set of meta_types.

Example:

        <dtml-in expr="objectValues('Folder')">          <dtml-var icon>          This is the icon for the: <dtml-var id> Folder<br>.        <dtml-else>          There are no Folders.        </dtml-in>

The results were restricted to Folders by passing a meta_type to objectValues method.

Permission: Access contents information

`objectIds(type=None)`

This method returns a list of the ids of the contained objects.

Optionally, you can pass an argument specifying what object meta_type(es) to restrict the results to. This argument can be a string specifying one meta_type, or it can be a list of strings to specify many.

Example:

        <dtml-in objectIds>          <dtml-var sequence-item>        <dtml-else>          There are no sub-objects.        </dtml-in>

This DTML code will display all the ids of the objects contained in the current Object Manager.

Permission: Access contents information

module `ObjectManagerItem`

class `ObjectManagerItem`

A Zope object that can be contained within an Object Manager. Almost all Zope objects that can be managed through the web are Object Manager Items.

ObjectMangerItems have these instance attributes:

title

The title of the object.

This is an optional one-line string description of the object.

meta_type

A short name for the type of the object.

This is the name that shows up in product add list for the object and is used when filtering objects by type.

This attribute is provided by the object's class and should not be changed directly.

REQUEST

The current web request.

This object is acquired and should not be set.

`title_or_id()`

If the title is not blank, return it, otherwise return the id.

Permission: Always available

`getPhysicalRoot()`

Returns the top-level Zope Application object.

Permission: Python only

`manage_workspace()`

This is the web method that is called when a user selects an item in a object manager contents view or in the Zope Management navigation view.

Permission: View management screens

`getPhysicalPath()`

Get the path of an object from the root, ignoring virtual hosts.

Permission: Always available

`unrestrictedTraverse(path, default=None)`

Return the object obtained by traversing the given path from the object on which the method was called. This method begins with "unrestricted" because (almost) no security checks are performed.

If an object is not found then the default argument will be returned.

Permission: Python only

`getId()`

Returns the object's id.

The id is the unique name of the object within its parent object manager. This should be a string, and can contain letters, digits, underscores, dashes, commas, and spaces.

This method replaces direct access to the id attribute.

Permission: Always available

`absolute_url(relative=None)`

Return the absolute url to the object.

If the relative argument is provided with a true value, then the URL returned is relative to the site object. Note, if virtual hosts are being used, then the path returned is a logical, rather than a physical path.

Permission: Always available

`this()`

Return the object.

This turns out to be handy in two situations. First, it provides a way to refer to an object in DTML expressions.

The second use for this is rather deep. It provides a way to acquire an object without getting the full context that it was acquired from. This is useful, for example, in cases where you are in a method of a non-item subobject of an item and you need to get the item outside of the context of the subobject.

Permission: Always available

`restrictedTraverse(path, default=None)`

Return the object obtained by traversing the given path from the object on which the method was called, performing security checks along the way.

If an object is not found then the default argument will be returned.

Permission: Always available

`title_and_id()`

If the title is not blank, the return the title followed by the id in parentheses. Otherwise return the id.

Permission: Always available

module `PropertyManager`

class `PropertyManager`

A Property Manager object has a collection of typed attributes called properties. Properties can be managed through the web or via DTML.

In addition to having a type, properties can be writable or read-only and can have default values.

`propertyItems()`

Return a list of (id, property) tuples.

Permission: Access contents information

`propertyValues()`

Returns a list of property values.

Permission: Access contents information

`propertyMap()`

Returns a tuple of mappings, giving meta-data for properties. The meta-data includes id, type, and mode.

Permission: Access contents information

`propertyIds()`

Returns a list of property ids.

Permission: Access contents information

`getPropertyType(id)`

Get the type of property id. Returns None if no such property exists.

Permission: Access contents information

`getProperty(id, d=None)`

Return the value of the property id. If the property is not found the optional second argument or None is returned.

Permission: Access contents information

`hasProperty(id)`

Returns a true value if the Property Manager has the property id. Otherwise returns a false value.

Permission: Access contents information

module `PropertySheet`

class `PropertySheet`

A PropertySheet is an abstraction for organizing and working with a set of related properties. Conceptually it acts like a container for a set of related properties and meta-data describing those properties. A PropertySheet may or may not provide a web interface for managing its properties.

`xml_namespace()`

Return a namespace string usable as an xml namespace for this property set. This may be an empty string if there is no default namespace for a given property sheet (especially property sheets added in ZClass definitions).

Permission: Python only

`propertyItems()`

Return a list of (id, property) tuples.

Permission: Access contents information

`propertyValues()`

Returns a list of actual property values.

Permission: Access contents information

`getPropertyType(id)`

Get the type of property id. Returns None if no such property exists.

Permission: Python only

`propertyInfo()`

Returns a mapping containing property meta-data.

Permission: Python only

`getProperty(id, d=None)`

Get the property id, returning the optional second argument or None if no such property is found.

Permission: Python only

`manage_delProperties(ids=None, REQUEST=None)`

Delete one or more properties with the given ids. The ids argument should be a sequence (tuple or list) containing the ids of the properties to be deleted. If ids is empty no action will be taken. If any of the properties named in ids does not exist, an error will be raised.

Some objects have "special" properties defined by product authors that cannot be deleted. If one of these properties is named in ids, an HTML error message is returned.

If no value is passed in for REQUEST, the method will return None. If a value is provided for REQUEST (as it will be when called via the web), the property management form for the object will be rendered and returned.

This method may be called via the web, from DTML or from Python code.

Permission: Manage Properties

`manage_changeProperties(REQUEST=None, **kw)`

Change existing object properties by passing either a mapping object as REQUEST containing name:value pairs or by passing name=value keyword arguments.

Some objects have "special" properties defined by product authors that cannot be changed. If you try to change one of these properties through this method, an error will be raised.

Note that no type checking or conversion happens when this method is called, so it is the caller's responsibility to ensure that the updated values are of the correct type. This should probably change.

If a value is provided for REQUEST (as it will be when called via the web), the method will return an HTML message dialog. If no REQUEST is passed, the method returns None on success.

This method may be called via the web, from DTML or from Python code.

Permission: Manage Properties

`manage_addProperty(id, value, type, REQUEST=None)`

Add a new property with the given id, value and type.

These are the property types:

boolean: 1 or 0.
date: A DateTime value, for example 12/31/1999 15:42:52 PST.
float: A decimal number, for example 12.4.
int: An integer number, for example, 12.
lines: A list of strings, one per line.
long: A long integer, for example 12232322322323232323423.
string: A string of characters, for example This is a string.
text: A multi-line string, for example a paragraph.
tokens: A list of strings separated by white space, for example one two three.
selection: A string selected by a pop-up menu.
multiple selection: A list of strings selected by a selection list.

This method will use the passed in type to try to convert the value argument to the named type. If the given value cannot be converted, a ValueError will be raised.

The value given for selection and multiple selection properties may be an attribute or method name. The attribute or method must return a sequence values.

If the given type is not recognized, the value and type given are simply stored blindly by the object.

If no value is passed in for REQUEST, the method will return None. If a value is provided for REQUEST (as it will when called via the web), the property management form for the object will be rendered and returned.

This method may be called via the web, from DTML or from Python code.

Permission: Manage Properties

`propertyMap()`

Returns a tuple of mappings, giving meta-data for properties.

Permission: Python only

`propertyIds()`

Returns a list of property ids.

Permission: Access contents information

`hasProperty(id)`

Returns true if self has a property with the given id, false otherwise.

Permission: Access contents information

module `PropertySheets`

class `PropertySheets`

A PropertySheet is an abstraction for organizing and working with a set of related properties. Conceptually it acts like a container for a set of related properties and meta-data describing those properties. PropertySheet objects are accessed through a PropertySheets object that acts as a collection of PropertySheet instances.

Objects that support property sheets (objects that support the PropertyManager interface or ZClass objects) have a propertysheets attribute (a PropertySheets instance) that is the collection of PropertySheet objects. The PropertySheets object exposes an interface much like a Python mapping, so that individual PropertySheet objects may be accessed via dictionary-style key indexing.

`get(name, default=None)`

Return the PropertySheet identified by name, or the value given in default if the named PropertySheet is not found.

Permission: Python only

`values()`

Return a sequence of all of the PropertySheet objects in the collection.

Permission: Python only

`items()`

Return a sequence containing an (id, object) tuple for each PropertySheet object in the collection.

Permission: Python only

module `PythonScript`

class `PythonScript(Script)`

Python Scripts contain python code that gets executed when you call the script by:

Calling the script through the web by going to its location with a web browser.
Calling the script from another script object.
Calling the script from a method object, such as a DTML Method.

Python Scripts can contain a "safe" subset of the python language. Python Scripts must be safe because they can be potentially edited by many different users through an insecure medium like the web. The following safety issues drive the need for secure Python Scripts:

Because many users can use Zope, a Python Script must make sure it does not allow a user to do something they are not allowed to do, like deleting an object they do not have permission to delete. Because of this requirement, Python Scripts do many security checks in the course of their execution.
Because Python Scripts can be edited through the insecure medium of the web, they are not allowed access to the Zope server's file-system. Normal Python builtins like open are, therefore, not allowed.
Because many standard Python modules break the above two security restrictions, only a small subset of Python modules may be imported into a Python Scripts with the "import" statement unless they have been validated by Zope's security policy. Currently, the following standard python modules have been validated:
- string
- math
- whrandom and random
- Products.PythonScripts.standard
Because it allows you to execute arbitrary python code, the python "exec" statement is not allowed in Python methods.
Because they may represent or cause security violations, some Python builtin functions are not allowed. The following Python builtins are not allowed:
- open
- input
- raw_input
- eval
- execfile
- compile
- type
- coerce
- intern
- dir
- globals
- locals
- vars
- buffer
- reduce
Other builtins are restricted in nature. The following builtins are restricted:
range
Due to possible memory denial of service attacks, the range builtin is restricted to creating ranges less than 10,000 elements long.
filter, map, tuple, list
For the same reason, builtins that construct lists from sequences do not operate on strings.
getattr, setattr, delattr
Because these may enable Python code to circumvent Zope's security system, they are replaced with custom, security constrained versions.
In order to be consistent with the Python expressions available to DTML, the builtin functions are augmented with a small number of functions and a class:
- test
- namespace
- render
- same_type
- DateTime
Because the "print" statement cannot operate normally in Zope, its effect has been changed. Rather than sending text to stdout, "print" appends to an internal variable. The special builtin name "printed" evaluates to the concatenation of all text printed so far during the current execution of the script.

`document_src(REQUEST=None, RESPONSE=None)`

Return the text of the read method, with content type text/plain set on the RESPONSE.

`ZPythonScript_edit(params, body)`

Change the parameters and body of the script. This method accepts two arguments:

params: The new value of the Python Script's parameters. Must be a comma separated list of values in valid python function signature syntax. If it does not contain a valid signature string, a SyntaxError is raised.
body: The new value of the Python Script's body. Must contain valid Python syntax. If it does not contain valid Python syntax, a SyntaxError is raised.

`ZPythonScript_setTitle(title)`

Change the script's title. This method accepts one argument, title which is the new value for the script's title and must be a string.

`ZPythonScriptHTML_upload(REQUEST, file="")`

Pass the text in file to the write method.

`write(text)`

Change the script by parsing the text argument into parts. Leading lines that begin with ## are stripped off, and if they are of the form ##name=value, they are used to set meta-data such as the title and parameters. The remainder of the text is set as the body of the Python Script.

`ZScriptHTML_tryParams()`

Return a list of the required parameters with which to test the script.

`read()`

Return the body of the Python Script, with a special comment block prepended. This block contains meta-data in the form of comment lines as expected by the write method.

`ZPythonScriptHTML_editAction(REQUEST, title, params, body)`

Change the script's main parameters. This method accepts the following arguments:

REQUEST: The current request.
title: The new value of the Python Script's title. This must be a string.
params: The new value of the Python Script's parameters. Must be a comma separated list of values in valid python function signature syntax. If it does not contain a valid signature string, a SyntaxError is raised.
body: The new value of the Python Script's body. Must contain valid Python syntax. If it does not contain valid Python syntax, a SyntaxError is raised.

ObjectManager Constructor

`manage_addPythonScript(id, REQUEST=None)`

Add a Python script to a folder.

module `Request`

class `Request`

The request object encapsulates all of the information regarding the current request in Zope. This includes, the input headers, form data, server data, and cookies.

The request object is a mapping object that represents a collection of variable to value mappings. In addition, variables are divided into five categories:

Environment variables
These variables include input headers, server data, and other request-related data. The variable names are as specified in the CGI specification
Form data
These are data extracted from either a URL-encoded query string or body, if present.
Cookies
These are the cookie data, if present.
Lazy Data
These are callables which are deferred until explicitly referenced, at which point they are resolved (called) and the result stored as "other" data, ie regular request data.
Thus, they are "lazy" data items. An example is SESSION objects.
Lazy data in the request may only be set by the Python method set_lazy(name,callable) on the REQUEST object. This method is not callable from DTML or through the web.
Other
Data that may be set by an application object.

The request object may be used as a mapping object, in which case values will be looked up in the order: environment variables, other variables, form data, and then cookies.

These special variables are set in the Request:

PARENTS: A list of the objects traversed to get to the published object. So, PARENTS[0] would be the ancestor of the published object.
REQUEST: The Request object.
RESPONSE: The Response object.
PUBLISHED: The actual object published as a result of url traversal.
URL: The URL of the Request without query string.
URLn: URL0 is the same as URL. URL1 is the same as URL0 with the last path element removed. URL2 is the same as URL1 with the last element removed. Etcetera.
For example if URL='http://localhost/foo/bar', then URL1='http://localhost/foo' and URL2='http://localhost'.
URLPATHn: URLPATH0 is the path portion of URL, URLPATH1 is the path portion of URL1, and so on.
For example if URL='http://localhost/foo/bar', then URLPATH1='/foo' and URLPATH2='/'.
BASEn: BASE0 is the URL up to but not including the Zope application object. BASE1 is the URL of the Zope application object. BASE2 is the URL of the Zope application object with an additional path element added in the path to the published object. Etcetera.
For example if URL='http://localhost/Zope.cgi/foo/bar', then BASE0='http://localhost', BASE1='http://localhost/Zope.cgi', and BASE2='http://localhost/Zope.cgi/foo'.
BASEPATHn: BASEPATH0 is the path portion of BASE0, BASEPATH1 is the path portion of BASE1, and so on. BASEPATH1 is the externally visible path to the root Zope folder, equivalent to CGI's SCRIPT_NAME, but virtual-host aware.
For example if URL='http://localhost/Zope.cgi/foo/bar', then BASEPATH0='/', BASEPATH1='/Zope.cgi', and BASEPATH2='/Zope.cgi/foo'.

`get_header(name, default=None)`

Return the named HTTP header, or an optional default argument or None if the header is not found. Note that both original and CGI header names without the leading HTTP_ are recognized, for example, Content-Type, CONTENT_TYPE and HTTP_CONTENT_TYPE should all return the Content-Type header, if available.

Permission: Always available

`items()`

Returns a sequence of (key, value) tuples for all the keys in the REQUEST object.

Permission: Always available

`keys()`

Returns a sorted sequence of all keys in the REQUEST object.

Permission: Always available

`setVirtualRoot(path, hard=0)`

Alters URL, URLn, URLPATHn, BASEn, BASEPATHn, and absolute_url() so that the current object has path path. If hard is true, PARENTS is emptied.

Provides virtual hosting support. Intended to be called from publishing traversal hooks.

Permission: Always available

`values()`

Returns a sequence of values for all the keys in the REQUEST object.

Permission: Always available

`set(name, value)`

Create a new name in the REQUEST object and assign it a value. This name and value is stored in the Other category.

Permission: Always available

`has_key(key)`

Returns a true value if the REQUEST object contains key, returns a false value otherwise.

Permission: Always available

`setServerURL(protocol=None, hostname=None, port=None)`

Sets the specified elements of SERVER_URL, also affecting URL, URLn, BASEn, and absolute_url().

Provides virtual hosting support.

Permission: Always available

module `Response`

class `Response`

The Response object represents the response to a Zope request.

`setHeader(name, value)`

Sets an HTTP return header "name" with value "value", clearing the previous value set for the header, if one exists. If the literal flag is true, the case of the header name is preserved, otherwise word-capitalization will be performed on the header name on output.

Permission: Always available

`setCookie(name, value, **kw)`

Set an HTTP cookie on the browser

The response will include an HTTP header that sets a cookie on cookie-enabled browsers with a key "name" and value "value". This overwrites any previously set value for the cookie in the Response object.

Permission: Always available

`addHeader(name, value)`

Set a new HTTP return header with the given value, while retaining any previously set headers with the same name.

Permission: Always available

`appendHeader(name, value, delimiter=,)`

Append a value to a cookie

Sets an HTTP return header "name" with value "value", appending it following a comma if there was a previous value set for the header.

Permission: Always available

`write(data)`

Return data as a stream

HTML data may be returned using a stream-oriented interface. This allows the browser to display partial results while computation of a response to proceed.

The published object should first set any output headers or cookies on the response object.

Note that published objects must not generate any errors after beginning stream-oriented output.

Permission: Always available

`setStatus(status, reason=None)`

Sets the HTTP status code of the response; the argument may either be an integer or one of the following strings:

OK, Created, Accepted, NoContent, MovedPermanently, MovedTemporarily, NotModified, BadRequest, Unauthorized, Forbidden, NotFound, InternalError, NotImplemented, BadGateway, ServiceUnavailable

that will be converted to the correct integer value.

Permission: Always available

`setBase(base)`

Set the base URL for the returned document.

Permission: Always available

`expireCookie(name, **kw)`

Cause an HTTP cookie to be removed from the browser

The response will include an HTTP header that will remove the cookie corresponding to "name" on the client, if one exists. This is accomplished by sending a new cookie with an expiration date that has already passed. Note that some clients require a path to be specified - this path must exactly match the path given when creating the cookie. The path can be specified as a keyword argument.

Permission: Always available

`appendCookie(name, value)`

Returns an HTTP header that sets a cookie on cookie-enabled browsers with a key "name" and value "value". If a value for the cookie has previously been set in the response object, the new value is appended to the old one separated by a colon.

Permission: Always available

`redirect(location, lock=0)`

Cause a redirection without raising an error. If the "lock" keyword argument is passed with a true value, then the HTTP redirect response code will not be changed even if an error occurs later in request processing (after redirect() has been called).

Permission: Always available

module Script Script module

This provides generic script support

class `Script`

Web-callable script base interface.

`ZScriptHTML_tryAction(REQUEST, argvars)`

Apply the test parameters provided by the dictionary argvars. This will call the current script with the given arguments and return the result.

module `SessionInterfaces`

Session API

class `SessionDataManagerErr`

Error raised during some session data manager operations, as explained in the API documentation of the Session Data Manager.

This exception may be caught in PythonScripts. A successful import of the exception for PythonScript use would need to be:

       from Products.Sessions import SessionDataManagerErr

class `BrowserIdManagerInterface`

Zope Browser Id Manager interface.

A Zope Browser Id Manager is responsible for assigning ids to site visitors, and for servicing requests from Session Data Managers related to the browser id.

`getBrowserId(self, create=1)`

If create=0, returns a the current browser id or None if there is no browser id associated with the current request. If create=1, returns the current browser id or a newly-created browser id if there is no browser id associated with the current request. This method is useful in conjunction with getBrowserIdName if you wish to embed the browser-id-name/browser-id combination as a hidden value in a POST-based form. The browser id is opaque, has no business meaning, and its length, type, and composition are subject to change.