Merge pull request #36 from TeamSpen210/typing

Add type hints

.gitignore

@@ -39,6 +39,7 @@ htmlcov/
 .coverage.*
 .cache
 .pytest_cache
+.mypy_cache
 nosetests.xml
 coverage.xml
 

MANIFEST.in

@@ -1,6 +1,7 @@
 include README.rst CHEATSHEET.rst LICENSE* CODE_OF_CONDUCT* CONTRIBUTING*
 include .coveragerc .style.yapf
 include test-requirements.txt
+include src/outcome/py.typed
 recursive-include docs *
 prune docs/build
 recursive-include tests *.py

ci.sh

@@ -9,8 +9,11 @@ pip install -U pip setuptools wheel
 python setup.py sdist --formats=zip
 pip install dist/*.zip
 
+# Install dependencies.
+pip install -Ur test-requirements.txt
+
 if [ "$CHECK_FORMATTING" = "1" ]; then
-    pip install yapf==${YAPF_VERSION} isort>=5
+    pip install yapf==${YAPF_VERSION} isort>=5 mypy pyright
     if ! yapf -rpd setup.py src tests; then
         cat <<EOF
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@@ -29,9 +32,6 @@ EOF
         exit 1
     fi
 
-    # required for isort to order test imports correctly
-    pip install -Ur test-requirements.txt
-
     if ! isort --check-only --diff . ; then
         cat <<EOF
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
@@ -49,12 +49,46 @@ in your local checkout.
 EOF
         exit 1
     fi
+
+    if ! mypy src/ tests/type_tests.py ; then
+        cat <<EOF
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Type checking errors were found (listed above). To get more detail, run
+
+   pip install mypy
+   mypy src/ tests/type_tests.py
+
+in your local checkout.
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+EOF
+        exit 1
+    fi
+
+    if ! pyright --verifytypes outcome src/outcome/ ; then
+        cat <<EOF
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+Types are not complete (listed above). To get more detail, run
+
+   pip install pyright
+   pyright --verifytypes outcome src/outcome/
+
+in your local checkout.
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+EOF
+        exit 1
+    fi
+
     exit 0
 fi
 
-# Actual tests
-pip install -Ur test-requirements.txt
-
 pytest -W error -ra -v tests --cov --cov-config=.coveragerc
 
 bash <(curl -s https://codecov.io/bash)

ci/rtd-requirements.txt

@@ -1,4 +1,4 @@
 # RTD is currently installing 1.5.3, which has a bug in :lineno-match:
-sphinx >= 1.6.1
+sphinx >= 4.0, < 6.2
 sphinx_rtd_theme
 sphinxcontrib-trio

docs/source/api.rst

@@ -14,6 +14,18 @@ API Reference
    :members:
    :inherited-members:
 
+.. py:data:: Maybe
+   :value: Value[ResultT] | Error
+
+A convenience alias to a union of both results. This allows type checkers to perform
+exhaustiveness checking when ``isinstance()`` is used with either class::
+
+    outcome: Maybe[int] = capture(some_function, 1, 2, 3)
+    if isinstance(outcome, Value):
+        # Type checkers know it's a Value[int] here.
+    else:
+        # It must be an Error.
+
 .. autoclass:: Value
    :members:
    :inherited-members:

docs/source/conf.py

@@ -18,6 +18,7 @@
 #
 import os
 import sys
+
 # So autodoc can import our package
 sys.path.insert(0, os.path.abspath('../..'))
 
@@ -27,6 +28,13 @@
 nitpick_ignore = [
     # Format is ('sphinx reference type', 'string'), e.g.:
     ('py:obj', 'bytes-like'),
+    # Typevars aren't found, for some reason.
+    ('py:class', 'ArgsT'),
+    ('py:class', 'ArgsT.args'),
+    ('py:class', 'ArgsT.kwargs'),
+    ('py:class', 'ResultT'),
+    ('py:class', 'outcome._impl.ResultT'),
+    ('py:class', 'outcome._impl.ValueT'),
 ]
 
 # -- General configuration ------------------------------------------------
@@ -76,6 +84,7 @@
 #
 # The short X.Y version.
 import outcome
+
 version = outcome.__version__
 # The full version, including alpha/beta/rc tags.
 release = version
@@ -101,7 +110,6 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -113,6 +121,7 @@
 # testing, but also because if we don't then RTD will throw away our
 # html_theme_options.
 import sphinx_rtd_theme
+
 html_theme = 'sphinx_rtd_theme'
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
@@ -135,13 +144,11 @@
 # so a file named 'default.css' will overwrite the builtin 'default.css'.
 html_static_path = ['_static']
 
-
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'outcomedoc'
 
-
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
@@ -166,28 +173,23 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'outcome.tex', 'Trio Documentation',
-     author, 'manual'),
+    (master_doc, 'outcome.tex', 'Trio Documentation', author, 'manual'),
 ]
 
-
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'outcome', 'outcome Documentation',
-     [author], 1)
-]
-
+man_pages = [(master_doc, 'outcome', 'outcome Documentation', [author], 1)]
 
 # -- Options for Texinfo output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'outcome', 'outcome Documentation',
-     author, 'outcome', 'Capture the outcome of Python function call.',
-     'Miscellaneous'),
+    (
+        master_doc, 'outcome', 'outcome Documentation', author, 'outcome',
+        'Capture the outcome of Python function call.', 'Miscellaneous'
+    ),
 ]

newsfragments/36.feature.rst

@@ -0,0 +1,3 @@
+Added type hints to the package. :py:class:`Value` and :py:class`Outcome` are now generic.
+A type alias was also added (:py:data:`Maybe`) for the union of :py:class:`Value`
+and :py:class:`Error`.

pyproject.toml

@@ -4,3 +4,33 @@ filename = "docs/source/history.rst"
 directory = "newsfragments"
 underlines = ["-", "~", "^"]
 issue_format = "`#{issue} <https://github.com/python-trio/outcome/issues/{issue}>`__"
+
+[tool.isort]
+combine_as_imports = true
+profile = "black"
+skip_gitignore = true
+
+[tool.mypy]
+# Be strict about use of Mypy
+strict = true
+warn_unused_ignores = true
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_no_return = true
+warn_unreachable = true
+warn_return_any = true
+
+# Avoid subtle backsliding
+disallow_incomplete_defs = true
+disallow_subclassing_any = true
+disallow_any_unimported = true
+disallow_any_generics = true
+disallow_any_explicit = false
+
+check_untyped_defs = true
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_untyped_decorators = true
+
+# DO NOT use `ignore_errors`; it doesn't apply
+# downstream and users have to deal with them.

setup.cfg

@@ -12,12 +12,16 @@ branch = True
 source =
     outcome
     tests/
+omit =
+    tests/type_tests.py
 
 [coverage:report]
 precision = 1
 exclude_lines =
     pragma: no cover
     abc.abstractmethod
+    if TYPE_CHECKING:
+    @overload
 
 [tool:pytest]
 asyncio_mode = strict

setup.py

@@ -25,6 +25,7 @@
     license='MIT OR Apache-2.0',
     packages=find_packages('src'),
     package_dir={'': 'src'},
+    include_package_data=True,
     install_requires=['attrs>=19.2.0'],
     python_requires='>=3.7',
     keywords='result',

src/outcome/__init__.py

@@ -1,11 +1,19 @@
 """Top-level package for outcome."""
 
-from ._impl import Error, Outcome, Value, acapture, capture
-from ._util import AlreadyUsedError, fixup_module_metadata
-from ._version import __version__
+from ._impl import (
+    Error as Error,
+    Maybe as Maybe,
+    Outcome as Outcome,
+    Value as Value,
+    acapture as acapture,
+    capture as capture,
+)
+from ._util import AlreadyUsedError as AlreadyUsedError, fixup_module_metadata
+from ._version import __version__ as __version__
 
 __all__ = (
-    'Error', 'Outcome', 'Value', 'acapture', 'capture', 'AlreadyUsedError'
+    'Error', 'Outcome', 'Value', 'Maybe', 'acapture', 'capture',
+    'AlreadyUsedError'
 )
 
 fixup_module_metadata(__name__, globals())