Add typing and expose py.typed (#135)

CHANGELOG.md

@@ -1,3 +1,7 @@
+## Work in progress
+
+- Added typing to API and expose `py.typed`.
+
 ## 8.0.1
 
 - Added license notice to readme (@C-nit - thx)

README.md

@@ -34,20 +34,20 @@ However, there is an alternative decoding package called [Unidecode](https://git
 
 ```python
 def slugify(
-    text,
-    entities=True,
-    decimal=True,
-    hexadecimal=True,
-    max_length=0,
-    word_boundary=False,
-    separator='-',
-    save_order=False,
-    stopwords=(),
-    regex_pattern=None,
-    lowercase=True,
-    replacements=(),
-    allow_unicode=False
-  ):
+    text: str,
+    entities: bool = True,
+    decimal: bool = True,
+    hexadecimal: bool = True,
+    max_length: int = 0,
+    word_boundary: bool = False,
+    separator: str = DEFAULT_SEPARATOR,
+    save_order: bool = False,
+    stopwords: Iterable[str] = (),
+    regex_pattern: str | None = None,
+    lowercase: bool = True,
+    replacements: Iterable[Iterable[str]] = (),
+    allow_unicode: bool = False,
+) -> str:
   """
   Make a slug from the given text.
   :param text (str): initial text

setup.py

@@ -58,7 +58,10 @@ def status(s):
     url=about['__url__'],
     license=about['__license__'],
     packages=[package],
-    package_data={'': ['LICENSE']},
+    package_data={
+        '': ['LICENSE'],
+        'slugify': ['py.typed'],
+    },
     package_dir={'slugify': 'slugify'},
     include_package_data=True,
     python_requires=python_requires,

slugify/__main__.py

@@ -1,11 +1,13 @@
-from __future__ import print_function, absolute_import
+from __future__ import absolute_import, annotations, print_function
+
 import argparse
 import sys
+from typing import Any
 
 from .slugify import slugify, DEFAULT_SEPARATOR
 
 
-def parse_args(argv):
+def parse_args(argv: list[str]) -> argparse.Namespace:
     parser = argparse.ArgumentParser(description="Slug string")
 
     input_group = parser.add_argument_group(description="Input")
@@ -63,7 +65,7 @@ def split_check(repl):
     return args
 
 
-def slugify_params(args):
+def slugify_params(args: argparse.Namespace) -> dict[str, Any]:
     return dict(
         text=args.input_string,
         entities=args.entities,
@@ -80,7 +82,7 @@ def slugify_params(args):
     )
 
 
-def main(argv=None):  # pragma: no cover
+def main(argv: list[str] | None = None):  # pragma: no cover
     """ Run this program """
     if argv is None:
         argv = sys.argv

slugify/slugify.py

@@ -1,6 +1,9 @@
+from __future__ import annotations
+
 import re
 import sys
 import unicodedata
+from collections.abc import Iterable
 from html.entities import name2codepoint
 
 try:
@@ -22,7 +25,13 @@
 DEFAULT_SEPARATOR = '-'
 
 
-def smart_truncate(string, max_length=0, word_boundary=False, separator=' ', save_order=False):
+def smart_truncate(
+    string: str,
+    max_length: int = 0,
+    word_boundary: bool = False,
+    separator: str = " ",
+    save_order: bool = False,
+) -> str:
     """
     Truncate a string.
     :param string (str): string for modification
@@ -64,9 +73,21 @@ def smart_truncate(string, max_length=0, word_boundary=False, separator=' ', sav
     return truncated.strip(separator)
 
 
-def slugify(text, entities=True, decimal=True, hexadecimal=True, max_length=0, word_boundary=False,
-            separator=DEFAULT_SEPARATOR, save_order=False, stopwords=(), regex_pattern=None, lowercase=True,
-            replacements=(), allow_unicode=False):
+def slugify(
+    text: str,
+    entities: bool = True,
+    decimal: bool = True,
+    hexadecimal: bool = True,
+    max_length: int = 0,
+    word_boundary: bool = False,
+    separator: str = DEFAULT_SEPARATOR,
+    save_order: bool = False,
+    stopwords: Iterable[str] = (),
+    regex_pattern: str | None = None,
+    lowercase: bool = True,
+    replacements: Iterable[Iterable[str]] = (),
+    allow_unicode: bool = False,
+) -> str:
     """
     Make a slug from the given text.
     :param text (str): initial text

slugify/special.py

@@ -1,7 +1,7 @@
-# -*- coding: utf-8 -*-
+from __future__ import annotations
 
 
-def add_uppercase_char(char_list):
+def add_uppercase_char(char_list: list[tuple[str, str]]) -> list[tuple[str, str]]:
     """ Given a replacement char list, this adds uppercase chars to the list """
 
     for item in char_list:
@@ -10,6 +10,7 @@ def add_uppercase_char(char_list):
         if upper_dict not in char_list and char != upper_dict[0]:
             char_list.insert(0, upper_dict)
         return char_list
+    return char_list
 
 
 # Language specific pre translations