# Copyright (c) Jupyter Development Team.
# Distributed under the terms of the Modified BSD License.
"""
Trait types for html widgets.
"""
import re
import traitlets
import datetime as dt
_color_names = ['aliceblue', 'antiquewhite', 'aqua', 'aquamarine', 'azure', 'beiae', 'bisque', 'black', 'blanchedalmond', 'blue', 'blueviolet', 'brown', 'burlywood', 'cadetblue', 'chartreuse', 'chocolate', 'coral', 'cornflowerblue', 'cornsilk', 'crimson', 'cyan', 'darkblue', 'darkcyan', 'darkgoldenrod', 'darkgray', 'darkgrey', 'darkgreen', 'darkkhaki', 'darkmagenta', 'darkolivegreen', 'darkorange', 'darkorchid', 'darkred', 'darksalmon', 'darkseagreen', 'darkslateblue', 'darkslategray', 'darkslategrey', 'darkturquoise', 'darkviolet', 'deeppink', 'deepskyblue', 'dimgray', 'dimgrey', 'dodgerblue', 'firebrick', 'floralwhite', 'forestgreen', 'fuchsia', 'gainsboro', 'ghostwhite', 'gold', 'goldenrod', 'gray', 'grey', 'green', 'greenyellow', 'honeydew', 'hotpink', 'indianred ', 'indigo ', 'ivory', 'khaki', 'lavender', 'lavenderblush', 'lawngreen', 'lemonchiffon', 'lightblue', 'lightcoral', 'lightcyan', 'lightgoldenrodyellow', 'lightgray', 'lightgrey', 'lightgreen', 'lightpink', 'lightsalmon', 'lightseagreen', 'lightskyblue', 'lightslategray', 'lightslategrey', 'lightsteelblue', 'lightyellow', 'lime', 'limegreen', 'linen', 'magenta', 'maroon', 'mediumaquamarine', 'mediumblue', 'mediumorchid', 'mediumpurple', 'mediumseagreen', 'mediumslateblue', 'mediumspringgreen', 'mediumturquoise', 'mediumvioletred', 'midnightblue', 'mintcream', 'mistyrose', 'moccasin', 'navajowhite', 'navy', 'oldlace', 'olive', 'olivedrab', 'orange', 'orangered', 'orchid', 'palegoldenrod', 'palegreen', 'paleturquoise', 'palevioletred', 'papayawhip', 'peachpuff', 'peru', 'pink', 'plum', 'powderblue', 'purple', 'rebeccapurple', 'red', 'rosybrown', 'royalblue', 'saddlebrown', 'salmon', 'sandybrown', 'seagreen', 'seashell', 'sienna', 'silver', 'skyblue', 'slateblue', 'slategray', 'slategrey', 'snow', 'springgreen', 'steelblue', 'tan', 'teal', 'thistle', 'tomato', 'transparent', 'turquoise', 'violet', 'wheat', 'white', 'whitesmoke', 'yellow', 'yellowgreen']
# Regex colors #fff and #ffffff
_color_hex = r'#[a-fA-F0-9]{3}(?:[a-fA-F0-9]{3})?'
_color_hex_re = re.compile(fr'^{_color_hex}$')
# Regex colors #ffff and #ffffffff (includes alpha value)
_color_hexa = r'#[a-fA-F0-9]{4}(?:[a-fA-F0-9]{4})?'
_color_hexa_re = re.compile(fr'^{_color_hexa}$')
# Helpers (float percent, int percent with optional surrounding whitespace)
_color_frac_percent = r'\s*(\d+(\.\d*)?|\.\d+)?%?\s*'
_color_int_percent = r'\s*\d+%?\s*'
# rgb(), rgba(), hsl() and hsla() format strings
_color_rgb = r'rgb\({ip},{ip},{ip}\)'
_color_rgba = r'rgba\({ip},{ip},{ip},{fp}\)'
_color_hsl = r'hsl\({fp},{fp},{fp}\)'
_color_hsla = r'hsla\({fp},{fp},{fp},{fp}\)'
# Regex colors rgb/rgba/hsl/hsla
_color_rgbhsl = '({})|({})|({})|({})'.format(
_color_rgb, _color_rgba, _color_hsl, _color_hsla
).format(ip=_color_int_percent, fp=_color_frac_percent)
_color_rgbhsl_re = re.compile(_color_rgbhsl)
# Support for CSS variables.
# For production rules, see: https://drafts.csswg.org/css-syntax-3/#tokenization
_escape = r'\\([0-9a-fA-F]{1-6}\s?|[^0-9a-fA-F\s])'
_non_ascii = r''.join(
(
r'\u00B7',
r'\u00C0-\u00D6',
r'\u00C0-\u00D6',
r'\u00D8-\u00F6',
r'\u00F8-\u037D',
r'\u037F-\u1FFF',
r'\u200C',
r'\u200D',
r'\u203F',
r'\u2040',
r'\u2070-\u218F',
r'\u2C00-\u2FEF',
r'\u3001-\uD7FF',
r'\uF900-\uFDCF',
r'\uFDF0-\uFFFD',
r'\u10000'
)
)
# Custom CSS identifier
_custom_ident = fr'--([a-zA-Z0-9_\-{_non_ascii}]|{_escape})+'
# Matching for CSS variables with valid color fallback declaration values.
#
# A CSS variable consists of a custom identifier starting with '--'.
# The 'var()' function can be used for substituting the custom property into
# the value of another property.
#
# Here we further restrict the fallback values to be valid colors.
_css_color = fr'({"|".join(_color_names)}|({_color_rgbhsl})|({_color_hex})|({_color_hexa}))'
_css_var_fallback_color = fr'var\({_custom_ident}(,\s*({_css_color}\s*)?)?\)'
_color_var_re = re.compile(_css_var_fallback_color)
[docs]class Color(traitlets.Unicode):
"""A string holding a valid HTML color such as 'blue', '#060482', '#A80'"""
info_text = 'a valid HTML color'
default_value = traitlets.Undefined
def validate(self, obj, value):
if value is None and self.allow_none:
return value
if isinstance(value, str):
if (value.lower() in _color_names or _color_hex_re.match(value) or
_color_hexa_re.match(value) or _color_rgbhsl_re.match(value) or
_color_var_re.match(value)):
return value
self.error(obj, value)
[docs]class Datetime(traitlets.TraitType):
"""A trait type holding a Python datetime object"""
klass = dt.datetime
default_value = dt.datetime(1900, 1, 1)
[docs]class Date(traitlets.TraitType):
"""A trait type holding a Python date object"""
klass = dt.date
default_value = dt.date(1900, 1, 1)
[docs]class Time(traitlets.TraitType):
"""A trait type holding a Python time object"""
klass = dt.date
default_value = dt.time()
def datetime_to_json(pydt, manager):
"""Serialize a Python datetime object to json.
Instantiating a JavaScript Date object with a string assumes that the
string is a UTC string, while instantiating it with constructor arguments
assumes that it's in local time:
>>> cdate = new Date('2015-05-12')
Mon May 11 2015 20:00:00 GMT-0400 (Eastern Daylight Time)
>>> cdate = new Date(2015, 4, 12) // Months are 0-based indices in JS
Tue May 12 2015 00:00:00 GMT-0400 (Eastern Daylight Time)
Attributes of this dictionary are to be passed to the JavaScript Date
constructor.
"""
if pydt is None:
return None
else:
try:
utcdt = pydt.astimezone(dt.timezone.utc)
except (ValueError, OSError):
# If year is outside valid range for conversion,
# use it as-is
utcdt = pydt
return dict(
year=utcdt.year,
month=utcdt.month - 1, # Months are 0-based indices in JS
date=utcdt.day,
hours=utcdt.hour, # Hours, Minutes, Seconds and Milliseconds
minutes=utcdt.minute, # are plural in JS
seconds=utcdt.second,
milliseconds=utcdt.microsecond / 1000,
)
def datetime_from_json(js, manager):
"""Deserialize a Python datetime object from json."""
if js is None:
return None
else:
try:
return dt.datetime(
js["year"],
js["month"] + 1, # Months are 1-based in Python
js["date"],
js["hours"],
js["minutes"],
js["seconds"],
js["milliseconds"] * 1000,
).astimezone()
except (ValueError, OSError):
# If year is outside valid range for conversion,
# return UTC datetime
return dt.datetime(
js["year"],
js["month"] + 1, # Months are 1-based in Python
js["date"],
js["hours"],
js["minutes"],
js["seconds"],
js["milliseconds"] * 1000,
dt.timezone.utc,
)
datetime_serialization = {
'from_json': datetime_from_json,
'to_json': datetime_to_json
}
[docs]def naive_to_json(pydt, manager):
"""Serialize a naive Python datetime object to json.
Instantiating a JavaScript Date object with a string assumes that the
string is a UTC string, while instantiating it with constructor arguments
assumes that it's in local time:
>>> cdate = new Date('2015-05-12')
Mon May 11 2015 20:00:00 GMT-0400 (Eastern Daylight Time)
>>> cdate = new Date(2015, 4, 12) // Months are 0-based indices in JS
Tue May 12 2015 00:00:00 GMT-0400 (Eastern Daylight Time)
Attributes of this dictionary are to be passed to the JavaScript Date
constructor.
"""
if pydt is None:
return None
else:
naivedt = pydt.replace(tzinfo=None)
return dict(
year=naivedt.year,
month=naivedt.month - 1, # Months are 0-based indices in JS
date=naivedt.day,
hours=naivedt.hour, # Hours, Minutes, Seconds and Milliseconds
minutes=naivedt.minute, # are plural in JS
seconds=naivedt.second,
milliseconds=naivedt.microsecond / 1000,
)
[docs]def naive_from_json(js, manager):
"""Deserialize a naive Python datetime object from json."""
if js is None:
return None
else:
return dt.datetime(
js["year"],
js["month"] + 1, # Months are 1-based in Python
js["date"],
js["hours"],
js["minutes"],
js["seconds"],
js["milliseconds"] * 1000,
)
naive_serialization = {"from_json": naive_from_json, "to_json": naive_to_json}
[docs]def date_to_json(pydate, manager):
"""Serialize a Python date object.
Attributes of this dictionary are to be passed to the JavaScript Date
constructor.
"""
if pydate is None:
return None
else:
return dict(
year=pydate.year,
month=pydate.month - 1, # Months are 0-based indices in JS
date=pydate.day
)
[docs]def date_from_json(js, manager):
"""Deserialize a Javascript date."""
if js is None:
return None
else:
return dt.date(
js['year'],
js['month'] + 1, # Months are 1-based in Python
js['date'],
)
date_serialization = {
'from_json': date_from_json,
'to_json': date_to_json
}
[docs]class ByteMemoryView(traitlets.TraitType):
"""A trait for memory views of bytes."""
default_value = memoryview(b'')
info_text = 'a memory view object'
def validate(self, obj, value):
if isinstance(value, memoryview) and value.format == 'B':
return value
self.error(obj, value)
def default_value_repr(self):
return repr(self.default_value.tobytes())
[docs]class CByteMemoryView(ByteMemoryView):
"""A casting version of the byte memory view trait."""
def validate(self, obj, value):
if isinstance(value, memoryview) and value.format == 'B':
return value
try:
mv = memoryview(value)
if mv.format != 'B':
mv = mv.cast('B')
return mv
except Exception:
self.error(obj, value)
[docs]def time_to_json(pyt, manager):
"""Serialize a Python time object to json."""
if pyt is None:
return None
else:
return dict(
hours=pyt.hour, # Hours, Minutes, Seconds and Milliseconds
minutes=pyt.minute, # are plural in JS
seconds=pyt.second,
milliseconds=pyt.microsecond / 1000,
)
[docs]def time_from_json(js, manager):
"""Deserialize a Python time object from json."""
if js is None:
return None
else:
return dt.time(
js["hours"], js["minutes"], js["seconds"], js["milliseconds"] * 1000
)
time_serialization = {"from_json": time_from_json, "to_json": time_to_json}
[docs]def datetime_to_json(pydt, manager):
"""Serialize a Python datetime object to json.
Instantiating a JavaScript Date object with a string assumes that the
string is a UTC string, while instantiating it with constructor arguments
assumes that it's in local time:
>>> cdate = new Date('2015-05-12')
Mon May 11 2015 20:00:00 GMT-0400 (Eastern Daylight Time)
>>> cdate = new Date(2015, 4, 12) // Months are 0-based indices in JS
Tue May 12 2015 00:00:00 GMT-0400 (Eastern Daylight Time)
Attributes of this dictionary are to be passed to the JavaScript Date
constructor.
"""
if pydt is None:
return None
else:
try:
utcdt = pydt.astimezone(dt.timezone.utc)
except (ValueError, OSError):
# If year is outside valid range for conversion,
# use it as-is
utcdt = pydt
return dict(
year=utcdt.year,
month=utcdt.month - 1, # Months are 0-based indices in JS
date=utcdt.day,
hours=utcdt.hour, # Hours, Minutes, Seconds and Milliseconds
minutes=utcdt.minute, # are plural in JS
seconds=utcdt.second,
milliseconds=utcdt.microsecond / 1000,
)
[docs]def datetime_from_json(js, manager):
"""Deserialize a Python datetime object from json."""
if js is None:
return None
else:
try:
return dt.datetime(
js["year"],
js["month"] + 1, # Months are 1-based in Python
js["date"],
js["hours"],
js["minutes"],
js["seconds"],
js["milliseconds"] * 1000,
dt.timezone.utc,
).astimezone()
except (ValueError, OSError):
# If year is outside valid range for conversion,
# return naive datetime
return dt.datetime(
js["year"],
js["month"] + 1, # Months are 1-based in Python
js["date"],
js["hours"],
js["minutes"],
js["seconds"],
js["milliseconds"] * 1000,
dt.timezone.utc,
)
datetime_serialization = {"from_json": datetime_from_json, "to_json": datetime_to_json}
[docs]class InstanceDict(traitlets.Instance):
"""An instance trait which coerces a dict to an instance.
This lets the instance be specified as a dict, which is used
to initialize the instance.
Also, we default to a trivial instance, even if args and kwargs
is not specified."""
def validate(self, obj, value):
if isinstance(value, dict):
return super().validate(obj, self.klass(**value))
else:
return super().validate(obj, value)
def make_dynamic_default(self):
return self.klass(*(self.default_args or ()),
**(self.default_kwargs or {}))
# The regexp is taken
# from https://github.com/d3/d3-format/blob/main/src/formatSpecifier.js
_number_format_re = re.compile(r'^(?:(.)?([<>=^]))?([+\-\( ])?([$#])?(0)?(\d+)?(,)?(\.\d+)?([a-z%])?$', re.I)
# The valid types are taken from
# https://github.com/d3/d3-format/blob/main/src/formatTypes.js
_number_format_types = {
'e', 'f', 'g', 'r', 's', '%', 'p', 'b', 'o', 'd', 'x',
'X', 'c', ''
}
[docs]class TypedTuple(traitlets.Container):
"""A trait for a tuple of any length with type-checked elements."""
klass = tuple
_cast_types = (list,)
def bytes_from_json(js, obj):
return None if js is None else js.tobytes()
bytes_serialization = {
'from_json': bytes_from_json,
}
Try Jupyter Widgets