From ad1a337a1e7542ae916dea57d89c02d82d31bd6d Mon Sep 17 00:00:00 2001
From: Mark Dickinson <mdickinson@enthought.com>
Date: Thu, 30 Jun 2022 08:09:25 +0100
Subject: [PATCH] Fix mypy complaints about TraitError (#1658)

Projects using traits-stubs reported that mypy was complaining about not having information about TraitError. This PR should fix that.

I've also added some instructions on local development to the README, since I have to figure this out every time.

(cherry picked from commit 4f17157f54751c002dcb2cb56fc388c633c7d5ab)
---
 traits-stubs/README.rst                       | 45 +++++++++++++++++++
 traits-stubs/traits-stubs/api.pyi             |  6 +++
 .../examples/completeness.py                  | 26 +++++++++++
 3 files changed, 77 insertions(+)
 create mode 100644 traits-stubs/traits_stubs_tests/examples/completeness.py

diff --git a/traits-stubs/README.rst b/traits-stubs/README.rst
index 899eaa2c6..9cea74237 100644
--- a/traits-stubs/README.rst
+++ b/traits-stubs/README.rst
@@ -26,6 +26,51 @@ Alternatively, some IDEs (including VS Code and PyCharm) can be configured to
 perform type checking as you edit.
 
 
+Development
+-----------
+
+To test traits stubs locally:
+
+- Create a fresh venv and activate it, for example with::
+
+  $ python -m venv --clear ~/.venvs/traits-stubs && source ~/.venvs/traits-stubs/bin/activate
+
+- Make sure all build-related packages are up to date
+
+  $ python -m pip install --upgrade pip setuptools wheel
+
+- Install the Traits library into the environment (non-editable install)
+
+  $ python -m pip install .
+
+- Install traits stubs in editable mode (from the repo, not from PyPI).
+
+  $ python -m pip install -e traits-stubs/
+
+- Install mypy (or your favourite type checker)
+
+  $ python -m pip install mypy
+
+- From the traits-stubs directory, run mypy on individual files in
+  traits_stubs_tests/examples with e.g.,
+
+  $ python -m mypy traits_stubs_tests/examples/completeness.py
+
+- From the traits-stubs directory, run the test suite with:
+
+  $ python -m unittest discover -v traits_stubs_tests
+
+Note: it's easy to get confusing results if you accidentally use the wrong
+version of mypy. To avoid that, you can make sure that you *don't* have mypy
+installed globally, and/or always invoke mypy using ``python -m mypy`` from
+within the environment.
+
+Note: the unittest run can give the wrong result in the presence of a stale
+``.mypy_cache``. If you're getting a pass where you expect to get a failure
+(or vice versa), try deleting the local cache and trying again.
+
+
+
 Dependencies
 ------------
 
diff --git a/traits-stubs/traits-stubs/api.pyi b/traits-stubs/traits-stubs/api.pyi
index 474b824be..dd42b02ce 100644
--- a/traits-stubs/traits-stubs/api.pyi
+++ b/traits-stubs/traits-stubs/api.pyi
@@ -18,6 +18,12 @@ from .constants import (
     RICH_COMPARE as RICH_COMPARE,
 )
 
+from .trait_errors import (
+    TraitError as TraitError,
+    TraitNotificationError as TraitNotificationError,
+    DelegationError as DelegationError,
+)
+
 from .traits import (
     Color as Color,
     Default as Default,
diff --git a/traits-stubs/traits_stubs_tests/examples/completeness.py b/traits-stubs/traits_stubs_tests/examples/completeness.py
new file mode 100644
index 000000000..40c863a65
--- /dev/null
+++ b/traits-stubs/traits_stubs_tests/examples/completeness.py
@@ -0,0 +1,26 @@
+# (C) Copyright 2020-2022 Enthought, Inc., Austin, TX
+# All rights reserved.
+#
+# This software is provided without warranty under the terms of the BSD
+# license included in LICENSE.txt and may be redistributed only under
+# the conditions described in the aforementioned license. The license
+# is also available online at http://www.enthought.com/licenses/BSD.txt
+#
+# Thanks for using Enthought open source!
+
+"""
+A selection of code snippets used to test completeness of the stubs.
+"""
+
+from traits.api import HasStrictTraits, Str, TraitError
+
+
+class HasName(HasStrictTraits):
+    name = Str()
+
+
+def try_assigning_age(x: HasName, new_name: str):
+    try:
+        x.age = new_name
+    except TraitError:
+        raise ValueError(f"Bad age: {new_name}")