Add Python type annotation

Signed-off-by: Jordan Borean <[email protected]>

Author: jborean93

ci/build.sh

@@ -26,6 +26,12 @@ if [ x"$FLAKE" = "xyes" ]; then
     fi
 fi
 
+python -m mypy .
+MYPY_RES=$?
+if [ $MYPY_RES -ne 0 ]; then
+    exit $MYPY_RES
+fi
+
 # always build in-place so that Sphinx can find the modules
 python setup.py build_ext --inplace $EXTRA_BUILDEXT
 BUILD_RES=$?

docs-requirements.txt

@@ -1,3 +1,4 @@
 Sphinx >= 1.3.1
+sphinx-autoapi
 sphinx-rtd-theme >= 0.2.5b1
 recommonmark >= 0.4.0

docs/source/conf.py

@@ -11,7 +11,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys, os, re
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -30,7 +30,20 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', "sphinx.ext.napoleon", 'gssapi_find_missing', 'requires_rfc']
+extensions = [
+  'sphinx.ext.autodoc',
+  'sphinx.ext.intersphinx',
+  'sphinx.ext.viewcode',
+  'sphinx.ext.napoleon',
+  'autoapi.extension',
+  'gssapi_find_missing',
+  'requires_rfc',
+]
+
+autoapi_generate_api_docs = False
+autoapi_type = 'python'
+autoapi_dirs = ['../../gssapi']
+autoapi_file_patterns = ['*.pyi']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -56,11 +69,55 @@
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-#
+# https://www.python.org/dev/peps/pep-0440/#appendix-b-parsing-version-strings-with-regular-expressions
+setup_py_path = os.path.abspath(os.path.join(__file__, '..', '..', '..', 'setup.py'))
+version_pattern = re.compile(r"""
+^\s*version=['|\"](?P<full_version>
+    (?:
+        (?:(?P<epoch>[0-9]+)!)?                           # epoch
+        (?P<release>[0-9]+(?:\.[0-9]+)*)                  # release segment
+        (?P<pre>                                          # pre-release
+            [-_\.]?
+            (?P<pre_l>(a|b|c|rc|alpha|beta|pre|preview))
+            [-_\.]?
+            (?P<pre_n>[0-9]+)?
+        )?
+        (?P<post>                                         # post release
+            (?:-(?P<post_n1>[0-9]+))
+            |
+            (?:
+                [-_\.]?
+                (?P<post_l>post|rev|r)
+                [-_\.]?
+                (?P<post_n2>[0-9]+)?
+            )
+        )?
+        (?P<dev>                                          # dev release
+            [-_\.]?
+            (?P<dev_l>dev)
+            [-_\.]?
+            (?P<dev_n>[0-9]+)?
+        )?
+    )
+    (?:\+(?P<local>[a-z0-9]+(?:[-_\.][a-z0-9]+)*))?       # local version
+)['|\"],?\s*$
+""", re.VERBOSE | re.IGNORECASE)
+
 # The short X.Y version.
-version = '1.7.2'
+version = ''
 # The full version, including alpha/beta/rc tags.
-release = '1.7.2'
+release = ''
+
+with open(setup_py_path, mode='r') as fd:
+    for line in fd:
+        version_match = version_pattern.match(line)
+        if version_match:
+            version = version_match.group('release')
+            release = version_match.group('full_version')
+            break
+
+if not version or not release:
+    raise Exception("Failed to find version in setup.py")
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/gssapi.raw.rst

@@ -25,44 +25,44 @@ Names
     Instead, they are a special form of name specific to
     a given mechanism.
 
-.. automodule:: gssapi.raw.names
+.. autoapimodule:: gssapi.raw.names
     :members:
     :undoc-members:
 
 Credentials
 ~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.creds
+.. autoapimodule:: gssapi.raw.creds
     :members:
     :undoc-members:
 
 Security Contexts
 ~~~~~~~~~~~~~~~~~
 
-.. automodule::  gssapi.raw.sec_contexts
+.. autoapimodule::  gssapi.raw.sec_contexts
     :members:
     :undoc-members:
 
-.. automodule:: gssapi.raw.message
+.. autoapimodule:: gssapi.raw.message
     :members:
     :undoc-members:
 
 Misc
 ~~~~
 
-.. automodule:: gssapi.raw.oids
+.. autoapimodule:: gssapi.raw.oids
     :members:
     :undoc-members:
 
-.. automodule:: gssapi.raw.misc
+.. autoapimodule:: gssapi.raw.misc
     :members:
     :undoc-members:
 
-.. automodule:: gssapi.raw.types
+.. autoapimodule:: gssapi.raw.types
     :members:
     :undoc-members:
 
-.. automodule:: gssapi.raw.chan_bindings
+.. autoapimodule:: gssapi.raw.chan_bindings
     :members:
     :undoc-members:
 
@@ -80,124 +80,124 @@ The following is a list of GSSAPI extensions supported by the low-level API.
 :rfc:`4178` (GSS-API Negotiation Mechanism)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_rfc4178
+.. autoapimodule:: gssapi.raw.ext_rfc4178
     :members:
     :undoc-members:
 
 :rfc:`5587` (GSS-API Extension for Mech Attributes)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_rfc5587
+.. autoapimodule:: gssapi.raw.ext_rfc5587
     :members:
     :undoc-members:
 
 :rfc:`5588` (GSS-API Extension for Storing Delegated Credentials)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_rfc5588
+.. autoapimodule:: gssapi.raw.ext_rfc5588
     :members:
     :undoc-members:
 
 :rfc:`5801` (GSS-API SASL Extensions)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_rfc5801
+.. autoapimodule:: gssapi.raw.ext_rfc5801
     :members:
     :undoc-members:
 
 Credential Store Extensions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_cred_store
+.. autoapimodule:: gssapi.raw.ext_cred_store
     :members:
     :undoc-members:
 
 :rfc:`6680` (GSS-API Naming Extensions)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_rfc6680
-    :members:
-    :undoc-members:
-
-.. automodule:: gssapi.raw.ext_rfc6680_comp_oid
+.. autoapimodule:: gssapi.raw.ext_rfc6680
     :members:
     :undoc-members:
 
 Credentials Import-Export Extensions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_cred_imp_exp
+.. autoapimodule:: gssapi.raw.ext_cred_imp_exp
     :members:
     :undoc-members:
 
 DCE (IOV/AEAD) Extensions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_dce
+.. autoapimodule:: gssapi.raw.ext_dce
     :members:
     :undoc-members:
 
-.. automodule:: gssapi.raw.ext_dce_aead
-    :members:
-    :undoc-members:
+..
+    gssapi.raw.ext_dce_aead is imported with ext_dce so no need to double up.
+
 
 IOV MIC Extensions
 ~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_iov_mic
+.. autoapimodule:: gssapi.raw.ext_iov_mic
     :members:
     :undoc-members:
 
 Global Grid Forum (GGF) Extensions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_ggf
+.. autoapimodule:: gssapi.raw.ext_ggf
     :members:
     :undoc-members:
 
 Services4User Extensions
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_s4u
+.. autoapimodule:: gssapi.raw.ext_s4u
     :members:
     :undoc-members:
 
 Acquiring Credentials With a Password Extensions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_password
+.. autoapimodule:: gssapi.raw.ext_password
     :members:
     :undoc-members:
 
-.. automodule:: gssapi.raw.ext_password_add
+.. autoapimodule:: gssapi.raw.ext_password_add
     :members:
     :undoc-members:
 
 Kerberos Specific Extensions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_krb5
+.. autoapimodule:: gssapi.raw.ext_krb5
     :members:
     :undoc-members:
 
 Other Extensions
 ~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_set_cred_opt
+.. autoapimodule:: gssapi.raw.ext_set_cred_opt
     :members:
     :undoc-members:
 
 Results
 -------
 
+..
+    Use autoapimodule once
+    https://github.com/readthedocs/sphinx-autoapi/issues/323 is resolved.
+
 .. automodule:: gssapi.raw.named_tuples
     :members:
     :undoc-members:
 
 Exceptions
 ----------
 
-.. automodule:: gssapi.raw.exceptions
+.. autoapimodule:: gssapi.raw.exceptions
     :members:
     :undoc-members:
     :show-inheritance: