Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document that Either should not be used in new code #1699

Merged
merged 4 commits into from
Aug 10, 2022
Merged

Document that Either should not be used in new code #1699

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9521a0a
Document that Either should not be used in new code
mdickinson Aug 10, 2022
683cbe3
Wording tweaks, markup fixes
mdickinson Aug 10, 2022
ba57e59
Fix footnote ordering
mdickinson Aug 10, 2022
1f257fb
Move Either below Union in the docs
mdickinson Aug 10, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/source/traits_api_reference/trait_types.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,10 +238,11 @@ Traits
.. autoclass:: ToolbarButton
:show-inheritance:

.. autoclass:: Either
.. autoclass:: Union
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deliberately swapping the order so that Union appears before Either in the docs.

There's also a drive-by fix here: :show-inheritance: was missing for Union, for no reason that I can discern.

:show-inheritance:

.. autoclass:: Union
.. autoclass:: Either
:show-inheritance:

.. autoclass:: Symbol
:show-inheritance:
Expand Down
20 changes: 13 additions & 7 deletions docs/source/traits_user_manual/defining.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,7 +269,7 @@ the table.
.. index:: PythonValue(), Range(), ReadOnly(), Regex()
.. index:: Set() String(), This, Time()
.. index:: ToolbarButton(), true, Tuple(), Type()
.. index:: undefined, UUID(), ValidatedTuple(), WeakRef()
.. index:: undefined, Union(), UUID(), ValidatedTuple(), WeakRef()
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another drive-by fix: Union was missing from this list of index entries.


.. _predefined-traits-beyond-simple-types-table:

Expand Down Expand Up @@ -321,7 +321,7 @@ the table.
+------------------+----------------------------------------------------------+
| Disallow | n/a |
+------------------+----------------------------------------------------------+
| Either | Either( *val1*\ [, *val2*, ..., *valN*, |
| Either [4]_ | Either( *val1*\ [, *val2*, ..., *valN*, |
| | \*\*\ *metadata*] ) |
+------------------+----------------------------------------------------------+
| Enum | Enum( *values*\ [, \*\*\ *metadata*] ) |
Expand Down Expand Up @@ -408,7 +408,7 @@ the table.
| Union | Union( *val1*\ [, *val2*, ..., *valN*, |
| | \*\*\ *metadata*] ) |
+------------------+----------------------------------------------------------+
| UUID [4]_ | UUID( [\*\*\ *metadata*] ) |
| UUID | UUID( [\*\*\ *metadata*] ) |
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped the [4] footnote, which talked about Python 2.5; I've re-used it for Either.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpick: footnote 4 comes before footnote 3 (attached to Function and Method) in the text.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks; fixed. At the same time, I fixed that the current footnotes start from the third natural number, rather than the second as is more conventional.

+------------------+----------------------------------------------------------+
| ValidatedTuple | ValidatedTuple( [\*\ *traits*, *fvalidate* = None, |
| | *fvalidate_info* = '' , \*\*\ *metadata*] ) |
Expand Down Expand Up @@ -644,6 +644,11 @@ prefix. Instantiating the class produces the following::

Either
::::::

.. note::
:class:`~.Either` may eventually be deprecated, and should not be used in
new code. Use the more well-behaved :class:`~.Union` trait type instead.

Another predefined trait that merits special explanation is Either. The
Either trait is intended for attributes that may take a value of more than
a single trait type, including None. The default value of Either is None, even
Expand Down Expand Up @@ -687,7 +692,7 @@ will raise a TraitError if a value of any other type is assigned. For example::
.. _union:

Union
::::::
:::::
mdickinson marked this conversation as resolved.
Show resolved Hide resolved
The Union trait accepts a value that is considered valid by at least one
of the traits in its definition. It is a simpler and therefore less error-prone
alternative to the `Either` trait, which allows more complex constructs and
Expand Down Expand Up @@ -719,7 +724,7 @@ attribute, which accepts either an Str instance or None as its value, a
**salary** trait that accepts an instance of Salary or Float and will raise a
TraitError if a value of any other type is assigned. For example::

>>> from traits.api import HasTraits, Either, Str
>>> from traits.api import HasTraits, Str, Union
>>> class Employee(HasTraits):
... manager_name = Union(Str, None)
...
Expand All @@ -731,7 +736,7 @@ TraitError if a value of any other type is assigned. For example::

The following example illustrates the difference between `Either` and `Union`::

>>> from traits.api import HasTraits, Either, Union, Str
>>> from traits.api import Either, HasTraits, Str, Union
>>> class IntegerClass(HasTraits):
... primes = Either([2], None, {'3':6}, 5, 7, 11)
...
Expand Down Expand Up @@ -1048,7 +1053,8 @@ the metadata attribute::
existing traits.
.. [3] The Function and Method trait types are now deprecated. See |Function|,
|Method|
.. [4] Available in Python 2.5.
.. [4] The Either trait type is likely to be deprecated at some point in the
future. The Union trait type should be preferred to Either in new code.

..
external urls
Expand Down
2 changes: 1 addition & 1 deletion traits/trait_numeric.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -395,7 +395,7 @@ class ArrayOrNone(CArray):
""" A coercing trait whose value may be either a NumPy array or None.

This trait is designed to avoid the comparison issues with numpy arrays
that can arise from the use of constructs like Either(None, Array).
that can arise from the use of constructs like Union(None, Array).

The default value is None.
"""
Expand Down
5 changes: 5 additions & 0 deletions traits/trait_types.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4124,6 +4124,11 @@ def __init__(
class Either(TraitType):
""" A trait type whose value can be any of of a specified list of traits.

Note: this class has many unusual corner-case behaviours and is not
recommended for use in new code. It may eventually be deprecated and
removed. For new code, consider using the :class:`~.Union` trait type
instead.

Parameters
----------
*traits
Expand Down