From 0a9f42bf9b2121b209f8336246fc466a072acc01 Mon Sep 17 00:00:00 2001
From: Seth Morton <seth.m.morton@gmail.com>
Date: Wed, 27 Oct 2021 09:23:26 -0700
Subject: Expose some internal types to the user

---
 docs/api.rst        | 22 ++++++++++++++++++++++
 natsort/__init__.py | 11 ++++++++++-
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/docs/api.rst b/docs/api.rst
index 86a26ee..c9818c7 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -117,3 +117,25 @@ Given your chosen algorithm (selected using the :class:`~natsort.ns` enum),
 the corresponding regular expression to locate numbers will be returned.
 
 .. autofunction:: numeric_regex_chooser
+
+Help With Type Hinting
+++++++++++++++++++++++
+
+If you need to explictly specify the types that natsort accepts or returns
+in your code, the following types have been exposed for your convenience.
+
++--------------------------------+----------------------------------------------------------------------------------------+
+| Type                           | Purpose                                                                                |
++================================+========================================================================================+
+|:attr:`natsort.NatsortKeyType`  | Returned by :func:`natsort.natsort_keygen`, and type of :attr:`natsort.natsort_key`    |
++--------------------------------+----------------------------------------------------------------------------------------+
+|:attr:`natsort.OSSortKeyType`   | Returned by :func:`natsort.os_sort_keygen`, and type of :attr:`natsort.os_sort_key`    |
++--------------------------------+----------------------------------------------------------------------------------------+
+|:attr:`natsort.KeyType`         | Type of `key` argument to :func:`natsort.natsorted` and :func:`natsort.natsort_keygen` |
++--------------------------------+----------------------------------------------------------------------------------------+
+|:attr:`natsort.PathKeyType`     | Type of `key` argument to :func:`natsort.os_sorted` and :func:`natsort.os_sort_keygen` |
++--------------------------------+----------------------------------------------------------------------------------------+
+|:attr:`natsort.NatsortInType`   | The input type of :attr:`natsort.NatsortKeyType`                                       |
++--------------------------------+----------------------------------------------------------------------------------------+
+|:attr:`natsort.NatsortOutType`  | The output type of :attr:`natsort.NatsortKeyType`                                      |
++--------------------------------+----------------------------------------------------------------------------------------+
diff --git a/natsort/__init__.py b/natsort/__init__.py
index a83c9a7..266d75e 100644
--- a/natsort/__init__.py
+++ b/natsort/__init__.py
@@ -1,6 +1,9 @@
 # -*- coding: utf-8 -*-
 
 from natsort.natsort import (
+    NatsortKeyType,
+    OSSortKeyType,
+    PathKeyType,
     as_ascii,
     as_utf8,
     decoder,
@@ -19,7 +22,7 @@ from natsort.natsort import (
     os_sorted,
     realsorted,
 )
-from natsort.utils import chain_functions
+from natsort.utils import KeyType, NatsortInType, NatsortOutType, chain_functions
 
 __version__ = "7.1.1"
 
@@ -42,6 +45,12 @@ __all__ = [
     "os_sort_key",
     "os_sort_keygen",
     "os_sorted",
+    "NatsortKeyType",
+    "OSSortKeyType",
+    "PathKeyType",
+    "KeyType",
+    "NatsortInType",
+    "NatsortOutType",
 ]
 
 # Add the ns keys to this namespace for convenience.
-- 
cgit v1.2.1