# Appendix B: API Reference

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 failes, 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. The arguments are:

messageText
  The body of the mail message.
mto
  A 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`.

#### ObjectManager 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` properites 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.

Permssion
  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 seperated 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 seperated 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`

### 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

See Also

- Transient Object 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.

Permission required: Access contents information

Raises: BrowserIdManagerErr if ill-formed browser id is found in REQUEST.

#### `isBrowserIdFromCookie(self)`

Returns true if browser id comes from a cookie.

Permission required: Access contents information

Raises: BrowserIdManagerErr. If there is no current browser id.

#### `isBrowserIdNew(self)`

Returns true if browser id is `new`. A browser id is `new` when it is first created and the client has therefore not sent it back to the server in any request.

Permission required: Access contents information

Raises: BrowserIdManagerErr. If there is no current browser id.

#### `encodeUrl(self, url)`

Encodes a provided URL with the current request's browser id and returns the result. For example, the call encodeUrl('http://foo.com/amethod') might return `http://foo.com/amethod?_ZopeId=as9dfu0adfu0ad`.

Permission required: Access contents information

Raises: BrowserIdManagerErr. If there is no current browser id.

#### `flushBrowserIdCookie(self)`

Deletes the browser id cookie from the client browser, iff the `cookies` browser id namespace is being used.

Permission required: Access contents information

Raises: BrowserIdManagerErr. If the `cookies` namespace isn't a browser id namespace at the time of the call.

#### `getBrowserIdName(self)`

Returns a string with the name of the cookie/form variable which is used by the current browser id manager as the name to look up when attempting to obtain the browser id value. For example, `_ZopeId`.

Permission required: Access contents information

#### `isBrowserIdFromForm(self)`

Returns true if browser id comes from a form variable (query string or post).

Permission required: Access contents information

Raises: BrowserIdManagerErr. If there is no current browser id.

#### `hasBrowserId(self)`

Returns true if there is a browser id for this request.

Permission required: Access contents information

#### `setBrowserIdCookieByForce(self, bid)`

Sets the browser id cookie to browser id `bid` by force. Useful when you need to `chain` browser id cookies across domains for the same user (perhaps temporarily using query strings).

Permission required: Access contents information

Raises: BrowserIdManagerErr. If the `cookies` namespace isn't a browser id namespace at the time of the call.

### class `BrowserIdManagerErr`

Error raised during some browser id manager operations, as explained in the API documentation of the Browser Id 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 BrowserIdManagerErr

### class `SessionDataManagerInterface`

Zope Session Data Manager interface.

A Zope Session Data Manager is responsible for maintaining Session Data Objects, and for servicing requests from application code related to Session Data Objects. It also communicates with a Browser Id Manager to provide information about browser ids.

#### `getSessionDataByKey(self, key)`

Returns a Session Data Object associated with `key`. If there is no Session Data Object associated with `key` return None.

Permission required: Access arbitrary user session data

#### `getSessionData(self, create=1)`

Returns a Session Data Object associated with the current browser id. If there is no current browser id, and create is true, returns a new Session Data Object. If there is no current browser id and create is false, returns None.

Permission required: Access session data

#### `getBrowserIdManager(self)`

Returns the nearest acquirable browser id manager.

Raises SessionDataManagerErr if no browser id manager can be found.

Permission required: Access session data

#### `hasSessionData(self)`

Returns true if a Session Data Object associated with the current browser id is found in the Session Data Container. Does not create a Session Data Object if one does not exist.

Permission required: Access session data

## module `TransienceInterfaces`

Transient Objects

### class `TransientObject`

A transient object is a temporary object contained in a transient object container.

Most of the time you'll simply treat a transient object as a dictionary. You can use Python sub-item notation:

            SESSION['foo']=1
            foo=SESSION['foo']
            del SESSION['foo']

When using a transient object from Python-based Scripts or DTML you can use the `get`, `set`, and `delete` methods instead.

Methods of transient objects are not protected by security assertions.

It's necessary to reassign mutuable sub-items when you change them. For example:

            l=SESSION['myList']
            l.append('spam')
            SESSION['myList']=l

This is necessary in order to save your changes. Note that this caveat is true even for mutable subitems which inherit from the Persistence.Persistent class.

#### `delete(self, k)`

Call __delitem__ with key k.

Permission
  Always available

#### `setLastAccessed(self)`

Cause the last accessed time to be set to now.

Permission
  Always available

#### `getCreated(self)`

Return the time the transient object was created in integer seconds-since-the-epoch form.

Permission
  Always available

#### `values(self)`

Return sequence of value elements.

Permission
  Always available

#### `has_key(self, k)`

Return true if item referenced by key k exists.

Permission
  Always available

#### `getLastAccessed(self)`

Return the time the transient object was last accessed in integer seconds-since-the-epoch form.

Permission
  Always available

#### `getId(self)`

Returns a meaningful unique id for the object.

Permission
  Always available

#### `update(self, d)`

Merge dictionary d into ourselves.

Permission
  Always available

#### `clear(self)`

Remove all key/value pairs.

Permission
  Always available

#### `items(self)`

Return sequence of (key, value) elements.

Permission
  Always available

#### `keys(self)`

Return sequence of key elements.

Permission
  Always available

#### `get(self, k, default=marker)`

Return value associated with key k. If k does not exist and default is not marker, return default, else raise KeyError.

Permission
  Always available

#### `set(self, k, v)`

Call __setitem__ with key k, value v.

Permission
  Always available

#### `getContainerKey(self)`

Returns the key under which the object is "filed" in its container. getContainerKey will often return a differnt value than the value returned by getId.

Permission
  Always available

#### `invalidate(self)`

Invalidate (expire) the transient object.

Causes the transient object container's "before destruct" method related to this object to be called as a side effect.

Permission
  Always available

### class `MaxTransientObjectsExceeded`

An exception importable from the Products.Transience.Transience module which is raised when an attempt is made to add an item to a TransientObjectContainer that is `full`.

This exception may be caught in PythonScripts through a normal import. A successful import of the exception can be achieved via:

            from Products.Transience import MaxTransientObjectsExceeded

### class `TransientObjectContainer`

TransientObjectContainers hold transient objects, most often, session data.

You will rarely have to script a transient object container. You'll almost always deal with a TransientObject itself which you'll usually get as `REQUEST.SESSION`.

#### `new(self, k)`

Creates a new subobject of the type supported by this container with key "k" and returns it.

If an object already exists in the container with key "k", a KeyError is raised.

"k" must be a string, else a TypeError is raised.

If the container is `full`, a MaxTransientObjectsExceeded will be raised.

Permission
  `Create Transient Objects`

#### `setDelNotificationTarget(self, f)`

Cause the `before destruction` function to be `f`.

If `f` is not callable and is a string, treat it as a Zope path to a callable function.

`before destruction` functions need accept a single argument: `item`, which is the item being destroyed.

Permission
  `Manage Transient Object Container`

#### `getTimeoutMinutes(self)`

Return the number of minutes allowed for subobject inactivity before expiration.

Permission
  `View management screens`

#### `has_key(self, k)`

Return true if container has value associated with key k, else return false.

Permission
  `Access Transient Objects`

#### `setAddNotificationTarget(self, f)`

Cause the `after add` function to be `f`.

If `f` is not callable and is a string, treat it as a Zope path to a callable function.

`after add` functions need accept a single argument: `item`, which is the item being added to the container.

Permission
  `Manage Transient Object Container`

#### `getId(self)`

Returns a meaningful unique id for the object.

Permission
  Always available

#### `setTimeoutMinutes(self, timeout_mins)`

Set the number of minutes of inactivity allowable for subobjects before they expire.

Permission
  `Manage Transient Object Container`

#### `new_or_existing(self, k)`

If an object already exists in the container with key "k", it is returned.

Otherwiser, create a new subobject of the type supported by this container with key "k" and return it.

"k" must be a string, else a TypeError is raised.

If the container is `full`, a MaxTransientObjectsExceeded exception be raised.

Permission
  `Create Transient Objects`

#### `get(self, k, default=None)`

Return value associated with key k. If value associated with k does not exist, return default.

Permission
  `Access Transient Objects`

#### `getAddNotificationTarget(self)`

Returns the current `after add` function, or None.

Permission
  `View management screens`

#### `getDelNotificationTarget(self)`

Returns the current `before destruction` function, or None.

Permission
  `View management screens`

## module `UserFolder`

### class `UserFolder`

User Folder objects are containers for user objects. Programmers can work with collections of user objects using the API shared by User Folder implementations.

#### `userFolderEditUser(name, password, roles, domains, **kw)`

API method for changing user object attributes. Note that not all user folder implementations support changing of user object attributes. Implementations that do not support changing of user object attributes will raise an error for this method.

Permission
  Manage users

#### `userFolderDelUsers(names)`

API method for deleting one or more user objects. Note that not all user folder implementations support deletion of user objects. Implementations that do not support deletion of user objects will raise an error for this method.

Permission
  Manage users

#### `userFolderAddUser(name, password, roles, domains, **kw)`

API method for creating a new user object. Note that not all user folder implementations support dynamic creation of user objects. Implementations that do not support dynamic creation of user objects will raise an error for this method.

Permission
  Manage users

#### `getUsers()`

Returns a sequence of all user objects which reside in the user folder.

Permission
  Manage users

#### `getUserNames()`

Returns a sequence of names of the users which reside in the user folder.

Permission
  Manage users

#### `getUser(name)`

Returns the user object specified by name. If there is no user named `name` in the user folder, return None.

Permission
  Manage users

## module `Vocabulary`

### class `Vocabulary`

A Vocabulary manages words and language rules for text indexing. Text indexing is done by the ZCatalog and other third party Products.

#### `words()`

Return list of words.

#### `insert(word)`

Insert a word in the Vocabulary.

#### `query(pattern)`

Query Vocabulary for words matching pattern.

#### ObjectManager Constructor

##### `manage_addVocabulary(id, title, globbing=None, REQUEST=None)`

Add a Vocabulary object to an ObjectManager.

## module `ZCatalog`

### class `ZCatalog`

ZCatalog object

A ZCatalog contains arbitrary index like references to Zope objects. ZCatalog's can index either `Field` values of object, `Text` values, or `KeyWord` values:

ZCatalogs have three types of indexes:

Text
  Text indexes index textual content. The index can be used to search for objects containing certain words.
Field
  Field indexes index atomic values. The index can be used to search for objects that have certain properties.
Keyword
  Keyword indexes index sequences of values. The index can be used to search for objects that match one or more of the search terms.

The ZCatalog can maintain a table of extra data about cataloged objects. This information can be used on search result pages to show information about a search result.

The meta-data table schema is used to build the schema for ZCatalog Result objects. The objects have the same attributes as the column of the meta-data table.

ZCatalog does not store references to the objects themselves, but rather to a unique identifier that defines how to get to the object. In Zope, this unique identifier is the object's relative path to the ZCatalog (since two Zope objects cannot have the same URL, this is an excellent unique qualifier in Zope).

#### `schema()`

Returns a sequence of names that correspond to columns in the meta-data table.

#### `__call__(REQUEST=None, **kw)`

Search the catalog, the same way as `searchResults`.

#### `uncatalog_object(uid)`

Uncatalogs the object with the unique identifier `uid`.

#### `getobject(rid, REQUEST=None)`

Return a cataloged object given a `data_record_id_`

#### `indexes()`

Returns a sequence of names that correspond to indexes.

#### `getpath(rid)`

Return the path to a cataloged object given a `data_record_id_`

#### `index_objects()`

Returns a sequence of actual index objects.

#### `searchResults(REQUEST=None, **kw)`

Search the catalog. Search terms can be passed in the REQUEST or as keyword arguments.

Search queries consist of a mapping of index names to search parameters. You can either pass a mapping to searchResults as the variable `REQUEST` or you can use index names and search parameters as keyword arguments to the method, in other words:

              searchResults(title='Elvis Exposed',
                            author='The Great Elvonso')

is the same as:

              searchResults({'title' : 'Elvis Exposed',
                             'author : 'The Great Elvonso'})

In these examples, `title` and `author` are indexes. This query will return any objects that have the title Elvis Exposed AND also are authored by The Great Elvonso. Terms that are passed as keys and values in a searchResults() call are implicitly ANDed together. To OR two search results, call searchResults() twice and add concatenate the results like this:

              results = ( searchResults(title='Elvis Exposed') +
                          searchResults(author='The Great Elvonso') )

This will return all objects that have the specified title OR the specified author.

There are some special index names you can pass to change the behavior of the search query:

sort_on
  This parameters specifies which index to sort the results on.
sort_order
  You can specify `reverse` or `descending`. Default behavior is to sort ascending.

##### There are some rules to consider when querying this method:

- an empty query mapping (or a bogus REQUEST) returns all items in the catalog.
- results from a query involving only field/keyword indexes, e.g. {'id':'foo'} and no `sort_on` will be returned unsorted.
- results from a complex query involving a field/keyword index and a text index, e.g. {'id':'foo','PrincipiaSearchSource':'bar'} and no `sort_on` will be returned unsorted.
- results from a simple text index query e.g.{'PrincipiaSearchSource':'foo'} will be returned sorted in descending order by `score`. A text index cannot beused as a `sort_on` parameter, and attempting to do so will raise an error.

Depending on the type of index you are querying, you may be able to provide more advanced search parameters that can specify range searches or wildcards. These features are documented in The Zope Book.

#### `uniqueValuesFor(name)`

returns the unique values for a given FieldIndex named `name`.

#### `catalog_object(obj, uid)`

Catalogs the object `obj` with the unique identifier `uid`.

#### ObjectManager Constructor

##### `manage_addZCatalog(id, title, vocab_id=None)`

Add a ZCatalog object.

`vocab_id` is the name of a Vocabulary object this catalog should use. A value of None will cause the Catalog to create its own private vocabulary.

## module `ZSQLMethod`

### class `ZSQLMethod`

ZSQLMethods abstract SQL code in Zope.

SQL Methods behave like methods of the folders they are accessed in. In particular, they can be used from other methods, like Documents, ExternalMethods, and even other SQL Methods.

Database methods support the Searchable Object Interface. Search interface wizards can be used to build user interfaces to them. They can be used in joins and unions. They provide meta-data about their input parameters and result data.

For more information, see the searchable-object interface specification.

Database methods support URL traversal to access and invoke methods on individual record objects. For example, suppose you had an `employees` database method that took a single argument `employee_id`. Suppose that employees had a `service_record` method (defined in a record class or acquired from a folder). The `service_record` method could be accessed with a URL like:

             employees/employee_id/1234/service_record

Search results are returned as Record objects. The schema of a Record objects matches the schema of the table queried in the search.

#### `manage_edit(title, connection_id, arguments, template)`

Change database method properties.

The `connection_id` argument is the id of a database connection that resides in the current folder or in a folder above the current folder. The database should understand SQL.

The `arguments` argument is a string containing an arguments specification, as would be given in the SQL method creation form.

The `template` argument is a string containing the source for the SQL Template.

#### `__call__(REQUEST=None, **kw)`

Call the ZSQLMethod.

The arguments to the method should be passed via keyword arguments, or in a single mapping object. If no arguments are given, and if the method was invoked through the Web, then the method will try to acquire and use the Web REQUEST object as the argument mapping.

The returned value is a sequence of record objects.

#### ObjectManager Constructor

##### `manage_addZSQLMethod(id, title, connection_id, arguments, template)`

Add an SQL Method to an ObjectManager.

The `connection_id` argument is the id of a database connection that resides in the current folder or in a folder above the current folder. The database should understand SQL.

The `arguments` argument is a string containing an arguments specification, as would be given in the SQL method cration form.

The `template` argument is a string containing the source for the SQL Template.

## module `ZTUtils`

### ZTUtils: Page Template Utilities

The classes in this module are available from Page Templates.

### class `Batch`

Batch - a section of a large sequence.

You can use batches to break up large sequences (such as search results) over several pages.

Batches provide Page Templates with similar functions as those built-in to `<dtml-in>`.

You can access elements of a batch just as you access elements of a list. For example:

            >>> b=Batch(range(100), 10)
            >>> b[5]
            4
            >>> b[10]
            IndexError: list index out of range

Batches have these public attributes:

start
  The first element number (counting from 1).
first
  The first element index (counting from 0). Note that this is that same as start - 1.
end
  The last element number (counting from 1).
orphan
  The desired minimum batch size. This controls how sequences are split into batches. If a batch smaller than the orphan size would occur, then no split is performed, and a batch larger than the batch size results.
overlap
  The number of elements that overlap between batches.
length
  The actual length of the batch. Note that this can be different than size due to orphan settings.
size
  The desired size. Note that this can be different than the actual length of the batch due to orphan settings.
previous
  The previous batch or None if this is the first batch.
next
  The next batch or None if this is the last batch.

#### `__init__(self, sequence, size, start=0, end=0, orphan=0, overlap=0)`

Creates a new batch given a sequence and a desired batch size.

sequence
  The full sequence.
size
  The desired batch size.
start
  The index of the start of the batch (counting from 0).
end
  The index of the end of the batch (counting from 0).
orphan
  The desired minimum batch size. This controls how sequences are split into batches. If a batch smaller than the orphan size would occur, then no split is performed, and a batch larger than the batch size results.
overlap
  The number of elements that overlap between batches.

## module `math`

### math: Python `math` module

The `math` module provides trigonometric and other math functions. It is a standard Python module.

Since Zope 2.4 requires Python 2.1, make sure to consult the Python 2.1 documentation.

#### See Also

Python `math` module documentation at Python.org

## module `random`

### random: Python `random` module

The `random` module provides pseudo-random number functions. With it, you can generate random numbers and select random elements from sequences. This module is a standard Python module.

Since Zope 2.4 requires Python 2.1, make sure to consult the Python 2.1 documentation.

#### See Also

Python `random` module documentation at Python.org

## module `sequence`

### sequence: Sequence sorting module

This module provides a `sort` function for use with DTML, Page Templates, and Python-based Scripts.

### `def sort(seq, sort)`

Sort the sequence seq of objects by the optional sort schema sort. sort is a sequence of tuples `(key, func, direction)` that describe the sort order.

key
  Attribute of the object to be sorted.
func
  Defines the compare function (optional). Allowed values:
  "cmp"
    Standard Python comparison function
  "nocase"
    Case-insensitive comparison
  "strcoll" or "locale"
    Locale-aware string comparison
  "strcoll_nocase" or "locale_nocase"
    Locale-aware case-insensitive string comparison
  other
    A specified, user-defined comparison function, should return 1, 0, -1.
  direction
    defines the sort direction for the key (optional). (allowed values: "asc", "desc")

#### DTML Examples

Sort child object (using the `objectValues` method) by id (using the `getId` method), ignoring case:

                 <dtml-in expr="_.sequence.sort(objectValues(),
                                                (('getId', 'nocase'),))">
                   <dtml-var getId> <br>
                 </dtml-in>

Sort child objects by title (ignoring case) and date (from newest to oldest):

                 <dtml-in expr="_.sequence.sort(objectValues(),
                                                (('title', 'nocase'),
                                                 ('bobobase_modification_time',
                                                 'cmp', 'desc')
                                                ))">
                   <dtml-var title> <dtml-var bobobase_modification_time> <br>
                 </dtml-in>

#### Page Template Examples

You can use the `sequence.sort` function in Python expressions to sort objects. Here's an example that mirrors the DTML example above:

                 <table tal:define="objects here/objectValues;
                                    sort_on python:(('title', 'nocase', 'asc'),
                                                    ('bobobase_modification_time', 'cmp', 'desc'));
                                    sorted_objects python:sequence.sort(objects, sort_on)">
                   <tr tal:repeat="item sorted_objects">
                     <td tal:content="item/title">title</td>
                     <td tal:content="item/bobobase_modification_time">
                       modification date</td>
                   </tr>
                 </table>

This example iterates over a sorted list of object, drawing a table row for each object. The objects are sorted by title and modification time.

#### See Also

Python cmp function

## module `standard`

1. PythonScripts.standard: Utility functions and classes

   The functions and classes in this module are available from Python-based scripts, DTML, and Page Templates.

### `def structured_text(s)`

Convert a string in structured-text format to HTML.

#### See Also

Structured-Text Rules

### `def html_quote(s)`

Convert characters that have special meaning in HTML to HTML character entities.

#### See Also

Python `cgi` module_in_cgi_module.html `escape` function.

### `def url_quote_plus(s)`

Like url_quote but also replace blank space characters with `+`. This is needed for building query strings in some cases.

#### See Also

Python `urllib` module `url_quote_plus` function.

### `def dollars_and_cents(number)`

Show a numeric value with a dollar symbol and two decimal places.

### `def sql_quote(s)`

Convert single quotes to pairs of single quotes. This is needed to safely include values in Standard Query Language (SQL) strings.

### `def whole_dollars(number)`

Show a numeric value with a dollar symbol.

### `def url_quote(s)`

Convert characters that have special meaning in URLS to HTML character entities using decimal values.

#### See Also

Python `urllib` module `url_quote` function.

### class `DTML`

DTML - temporary, security-restricted DTML objects

#### `__init__(source, **kw)`

Create a DTML object with source text and keyword variables. The source text defines the DTML source content. The optinal keyword arguments define variables.

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

Render the DTML.

To accomplish its task, DTML 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, you must be pass a namespace to the DTML. 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 object 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.

### `def thousand_commas(number)`

Insert commas every three digits to the left of a decimal point in values containing numbers. For example, the value, "12000 widgets" becomes "12,000 widgets".

### `def newline_to_br(s)`

Convert newlines and carriage-return and newline combinations to break tags.

## module `string`

### string: Python `string` module

The `string` module provides string manipulation, conversion, and searching functions. It is a standard Python module.

Since Zope 2.4 requires Python 2.1, make sure to consult the Python 2.1 documentation.

#### See Also

Python `string` module documentation at Python.org