Optional trait type

docs/source/traits_api_reference/trait_types.rst

@@ -241,6 +241,9 @@ Traits
 .. autoclass:: Union
    :show-inheritance:
 
+.. autoclass:: Optional
+   :show-inheritance:
+
 .. autoclass:: Either
    :show-inheritance:
 

docs/source/traits_user_manual/defining.rst

@@ -265,7 +265,7 @@ the table.
 .. index:: Directory(), Disallow, Either(), Enum()
 .. index:: Event(), Expression(), false, File()
 .. index:: Instance(), List(), Method(), Module()
-.. index:: Password(), Property(), Python()
+.. index:: Optional(), Password(), Property(), Python()
 .. index:: PythonValue(), Range(), ReadOnly(), Regex()
 .. index:: Set() String(), This, Time()
 .. index:: ToolbarButton(), true, Tuple(), Type()
@@ -355,6 +355,8 @@ the table.
 +------------------+----------------------------------------------------------+
 | Module           | Module([\*\*\ *metadata*])                               |
 +------------------+----------------------------------------------------------+
+| Optional         | Optional(*trait*\ [, \*\*\ *metadata*])                  |
++------------------+----------------------------------------------------------+
 | Password         | Password([*value* = '', *minlen* = 0, *maxlen* =         |
 |                  | sys.maxsize, *regex* = '', \*\*\ *metadata*])            |
 +------------------+----------------------------------------------------------+
@@ -700,6 +702,45 @@ The following example illustrates the difference between `Either` and `Union`::
     ...     primes = Union([2], None, {'3':6}, 5, 7, 11)
     ValueError: Union trait declaration expects a trait type or an instance of trait type or None, but got [2] instead
 
+.. index:: Optional trait
+
+.. _optional:
+
+Optional
+::::::::
+The Optional trait is a shorthand for ``Union(None, *trait*)``. It allows
+the value of the trait to be either None or a specified type. The default
+value of the trait is None unless specified by ``default_value``.
+
+.. index::
+   pair: Optional trait; examples
+
+The following is an example of using Optional::
+
+    # optional.py --- Example of Optional predefined trait
+
+    from traits.api import HasTraits, Optional, Str
+
+    class Person(HasTraits):
+        name = Str
+        nickname = Optional(Str)
+
+This example defines a ``Person`` with a ``name`` and an optional ``nickname``.
+Their ``nickname`` can be ``None`` or a string. For example::
+
+    >>> from traits.api import HasTraits, Optional, Str
+    >>> class Person(HasTraits):
+    ...     name = Str
+    ...     nickname = Optional(Str)
+    ...
+    >>> joseph = Person(name="Joseph")
+    >>> # Joseph has no nickname
+    >>> joseph.nickname is None
+    True
+    >>> joseph.nickname = "Joe"
+    >>> joseph.nickname
+    'Joe'
+
 .. index:: Either trait
 
 .. _either:

traits/api.py

@@ -105,6 +105,7 @@
     ToolbarButton,
     Either,
     Union,
+    Optional,
     Type,
     Subclass,
     Symbol,

traits/api.pyi

@@ -109,6 +109,7 @@ from .trait_types import (
     ToolbarButton as ToolbarButton,
     Either as Either,
     Union as Union,
+    Optional as Optional,
     Type as Type,
     Subclass as Subclass,
     Symbol as Symbol,

traits/tests/test_constant.py

@@ -72,3 +72,19 @@ class TestClass(HasTraits):
 
         # Check directly that both refer to the same object.
         self.assertIs(obj1.c_atr, obj2.c_atr)
+
+    @unittest.expectedFailure
+    def test_constant_validator(self):
+        """
+        XFAIL: `validate` on Constant is permissive.
+
+        See enthought/traits#1784
+        """
+        class TestClass(HasTraits):
+            attribute = Constant(123)
+
+        a = TestClass()
+        const_trait = a.traits()["attribute"]
+
+        with self.assertRaises(TraitError):
+            const_trait.validate(a, "attribute", 456)