l.a.w.d.DateTimeWidget(TextWidget) : class documentation

Part of lp.app.widgets.date View In Hierarchy

Known subclasses: lp.app.widgets.date.DateWidget

A date and time selection widget with popup selector.

>>> from lp.services.webapp.servers import LaunchpadTestRequest
>>> from zope.schema import Field
>>> field = Field(__name__='foo', title=u'Foo')
>>> widget = DateTimeWidget(field, LaunchpadTestRequest())

The datetime popup widget shows the time zone in which it will return the time:

>>> print widget()  #doctest: +ELLIPSIS
<BLANKLINE>
<...in time zone: UTC...

The datetime popup widget links to the page which allows the user to change their system time zone.

>>> print widget()  #doctest: +ELLIPSIS
<BLANKLINE>
<...<a href="/people/+me/+editlocation">...

If there is a required time zone, then that overrides the user or system default, and the user is not invited to change the time zone:

>>> widget.required_time_zone = pytz.timezone('America/Los_Angeles')
>>> print widget()  #doctest: +ELLIPSIS
<BLANKLINE>
<...in time zone: America/Los_Angeles...
>>> 'change time zone' not in widget()
True
>>> 'login to set time zone' not in widget()
True

If there is a from_date then the date provided must be later than that. If an earlier date is provided, then getInputValue will raise WidgetInputError. The message gives the required date/time in the widget time zone even if the date provided was in a different time zone.

>>> widget.request.form[widget.name] = '2005-07-03'
>>> widget.from_date = datetime(2006, 5, 23,
...                             tzinfo=pytz.timezone('UTC'))
>>> print widget.getInputValue()  #doctest: +ELLIPSIS
Traceback (most recent call last):
...
WidgetInputError: (...Please pick a date after 2006-05-22 17:00:00...)

If the date provided is greater than from_date then the widget works as expected.

>>> widget.request.form[widget.name] = '2009-09-14'
>>> print widget.getInputValue()  #doctest: +ELLIPSIS
2009-09-14 00:00:00-07:00

If to_date is provided then getInputValue() will enforce this too.

>>> widget.to_date = datetime(2008, 1, 26,
...                           tzinfo=pytz.timezone('UTC'))
>>> print widget.getInputValue()  #doctest: +ELLIPSIS
Traceback (most recent call last):
...
WidgetInputError: (...Please pick a date before 2008-01-25 16:00:00...)

A datetime picker can be disabled initially:

>>> 'disabled' in widget()
False
>>> widget.disabled = True
>>> 'disabled' in widget()
True
Method __init__ Undocumented
Method supported_input_formats Undocumented
Method time_zone The widget time zone.
Method time_zone_name The name of the widget time zone for display in the widget.
Method disabled_flag Return a string to make the form input disabled if necessary.
Method daterange The javascript variable giving the allowed date range to pick.
Method getInputValue Return the date, if it is in the allowed date range.
Method formvalue Return the value for the form to render, accessed via the
Method _align_date_constraints_with_time_zone Ensure that from_date and to_date use the widget time zone.
Method _checkSupportedFormat Checks that the input is in a usable format.
Method _toFieldValue Return parsed input (datetime) as a date.
Method _parseInput Convert a string to a datetime value.
Method _toFormValue Convert a date to its string representation.
def __init__(self, context, request):
Undocumented
@property
def supported_input_formats(self):
Undocumented
def time_zone(self):

The widget time zone.

This will either give you the user's time zone, or the system default time zone of 'UTC', or a specific "required time zone" in cases where this widget is being used to pick a time in an externally-defined time zone. For example, when a person will join a conference in the time zone in which the conference is being held.

>>> from zope.publisher.browser import TestRequest
>>> from zope.schema import Field
>>> field = Field(__name__='foo', title=u'Foo')
>>> widget = DateTimeWidget(field, TestRequest())

The time zone is a time zone object, not the string representation of that.

>>> print type(widget.time_zone)
<class 'pytz.UTC'>

The widget required_time_zone is None by default.

>>> print widget.required_time_zone
None

The widget "system time zone" is generally UTC. It is the logged in users time zone, with a fallback to UTC if there is no logged in user. Although this isn't used directly, it influences the outcome of widget.time_zone.

>>> print widget.system_time_zone
UTC

When there is no required_time_zone, then we get the system time zone.

>>> print widget.required_time_zone
None
>>> print widget.time_zone
UTC

When there is a required_time_zone, we get it:

>>> widget.required_time_zone = pytz.timezone('Africa/Maseru')
>>> print widget.time_zone
Africa/Maseru
@property
def time_zone_name(self):
The name of the widget time zone for display in the widget.
def _align_date_constraints_with_time_zone(self):
Ensure that from_date and to_date use the widget time zone.
@property
def disabled_flag(self):
Return a string to make the form input disabled if necessary.

Returns None otherwise, to omit the disabled attribute completely.

def daterange(self):

The javascript variable giving the allowed date range to pick.

>>> from zope.publisher.browser import TestRequest
>>> from zope.schema import Field
>>> from datetime import datetime
>>> field = Field(__name__='foo', title=u'Foo')
>>> widget = DateTimeWidget(field, TestRequest())
>>> from_date = datetime(2004, 4, 5)
>>> to_date = datetime(2004, 4, 10)

The default date range is unlimited:

>>> print widget.from_date
None
>>> print widget.to_date
None

If there is no date range, we return None so it won't be included on the template at all:

>>> widget.from_date = None
>>> widget.to_date = None
>>> print widget.daterange
None

The daterange is correctly expressed as JavaScript in all the different permutations of to/from dates:

>>> widget.from_date = from_date
>>> widget.to_date = None
>>> widget.daterange
'[[2004,04,05],null]'
>>> widget.from_date = None
>>> widget.to_date = to_date
>>> widget.daterange
'[null,[2004,04,10]]'
>>> widget.from_date = from_date
>>> widget.to_date = to_date
>>> widget.daterange
'[[2004,04,05],[2004,04,10]]'

The date range is displayed in the page when the widget is displayed:

>>> '[[2004,04,05],[2004,04,10]]' in widget()
True
def getInputValue(self):
Return the date, if it is in the allowed date range.
def _checkSupportedFormat(self, input):
Checks that the input is in a usable format.
def _toFieldValue(self, input):
Return parsed input (datetime) as a date.
def _parseInput(self, input):

Convert a string to a datetime value.

>>> from zope.publisher.browser import TestRequest
>>> from zope.schema import Field
>>> field = Field(__name__='foo', title=u'Foo')
>>> widget = DateTimeWidget(field, TestRequest())
>>> widget.required_time_zone = pytz.timezone('UTC')
>>> widget.time_zone
<UTC>

The widget converts an empty string to the missing value:

>>> widget._parseInput('') == field.missing_value
True

The widget prints out times in UTC:

>>> print widget._parseInput('2006-01-01 12:00:00')
2006-01-01 12:00:00+00:00

But it will handle other time zones:

>>> widget.required_time_zone = pytz.timezone('Australia/Perth')
>>> print widget._parseInput('2006-01-01 12:00:00')
2006-01-01 12:00:00+08:00

Invalid dates result in a ConversionError:

>>> print widget._parseInput('not a date')  #doctest: +ELLIPSIS
Traceback (most recent call last):
  ...
ConversionError: ('Invalid date value', ...)
def _toFormValue(self, value):

Convert a date to its string representation.

>>> from zope.publisher.browser import TestRequest
>>> from zope.schema import Field
>>> field = Field(__name__='foo', title=u'Foo')
>>> widget = DateTimeWidget(field, TestRequest())

The 'missing' value is converted to an empty string:

>>> widget._toFormValue(field.missing_value)
u''

DateTimes are displayed without the corresponding time zone information:

>>> dt = datetime(2006, 1, 1, 12, 0, 0,
...                        tzinfo=pytz.timezone('UTC'))
>>> widget._toFormValue(dt)
'2006-01-01 12:00:00'

The date value will be converted to the widget's time zone before being displayed:

>>> widget.required_time_zone = pytz.timezone('America/New_York')
>>> widget._toFormValue(dt)
'2006-01-01 07:00:00'
def formvalue(self):
Return the value for the form to render, accessed via the formvalue property.

This will be data from the request, or the fields value if the form has not been submitted. This method should return an object that makes the template simple and readable.

API Documentation for Launchpad, generated by pydoctor at 2022-06-16 00:00:12.