feat: add type hints

.github/workflows/pypi-publish.yml

@@ -6,11 +6,24 @@ on:
       - "v*"
 
 jobs:
-  lint:
-    uses: prosegrinder/.github/.github/workflows/poetry-lint.yaml@main
+  black:
+    uses: prosegrinder/.github/.github/workflows/poetry-black.yaml@main
+
+  pylint:
+    uses: prosegrinder/.github/.github/workflows/poetry-pylint.yaml@main
+
+  mypy:
+    uses: prosegrinder/.github/.github/workflows/poetry-mypy.yaml@main
+
+  bandit:
+    uses: prosegrinder/.github/.github/workflows/poetry-bandit.yaml@main
 
   test:
-    needs: lint
+    needs:
+      - pylint
+      - black
+      - mypy
+      - bandit
     uses: prosegrinder/.github/.github/workflows/poetry-test.yaml@main
 
   publish:

.github/workflows/python-ci.yml

@@ -1,5 +1,8 @@
 name: Python Poetry CI
 
+permissions:
+  contents: read
+
 on:
   pull_request:
 
@@ -8,11 +11,24 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  lint:
-    uses: prosegrinder/.github/.github/workflows/poetry-lint.yaml@main
+  black:
+    uses: prosegrinder/.github/.github/workflows/poetry-black.yaml@main
+
+  pylint:
+    uses: prosegrinder/.github/.github/workflows/poetry-pylint.yaml@main
+
+  mypy:
+    uses: prosegrinder/.github/.github/workflows/poetry-mypy.yaml@main
+
+  bandit:
+    uses: prosegrinder/.github/.github/workflows/poetry-bandit.yaml@main
 
   test:
-    needs: lint
+    needs:
+      - pylint
+      - black
+      - mypy
+      - bandit
     uses: prosegrinder/.github/.github/workflows/poetry-test.yaml@main
 
   cz-dry-run:

.github/workflows/python-release.yml

@@ -1,5 +1,8 @@
 name: Bump Version and Create Release
 
+permissions:
+  contents: write
+
 on:
   push:
     branches:
@@ -10,9 +13,32 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  black:
+    uses: prosegrinder/.github/.github/workflows/poetry-black.yaml@main
+
+  pylint:
+    uses: prosegrinder/.github/.github/workflows/poetry-pylint.yaml@main
+
+  mypy:
+    uses: prosegrinder/.github/.github/workflows/poetry-mypy.yaml@main
+
+  bandit:
+    uses: prosegrinder/.github/.github/workflows/poetry-bandit.yaml@main
+
+  test:
+    needs:
+      - pylint
+      - black
+      - mypy
+      - bandit
+    uses: prosegrinder/.github/.github/workflows/poetry-test.yaml@main
+
   release:
-    if: "!startsWith(github.event.head_commit.message, 'bump:')"
+    needs: test
+    if: ${{ !startsWith(github.event.head_commit.message, 'bump:') }}
     # Don't run 'bump:'
+    permissions:
+      contents: write
     uses: prosegrinder/.github/.github/workflows/poetry-release.yaml@main
     secrets:
       VERSION_BUMP_TAG_TOKEN: "${{ secrets.VERSION_BUMP_TAG_TOKEN }}"

pyproject.toml

@@ -1,27 +1,37 @@
-[tool.commitizen]
-version = "1.0.33"
-tag_format = "v$version"
-update_changelog_on_bump = true
-changelog_incremental = true
-bump_message = "bump: $current_version → $new_version"
-version_files = [
-  "pyproject.toml:version",
+[project]
+name = "cmudict"
+dynamic = [ "version", "classifiers" ]
+description = "A versioned python wrapper package for The CMU Pronouncing Dictionary data files."
+license = { text = "GPL-3.0-or-later" }
+readme = "README.md"
+requires-python = ">=3.9,<4.0"
+authors = [
+    { name = "David L. Day", email = "[email protected]" }
+]
+keywords = ["cmudict"]
+dependencies = [
+    "importlib-metadata >=5",
+    "importlib-resources >=5",
 ]
 
+[project.urls]
+homepage = "https://github.com/prosegrinder/python-cmudict"
+repository = "https://github.com/prosegrinder/python-cmudict"
+"Bug Tracker" = "https://github.com/prosegrinder/python-cmudict/issues"
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
+[tool.commitizen]
+tag_format = "v$version"
+update_changelog_on_bump = true
+changelog_incremental = true
+bump_message = "bump: $current_version → $new_version"
+version_provider = "poetry"
+
 [tool.poetry]
-name = "cmudict"
 version = "1.0.33"
-description = "A versioned python wrapper package for The CMU Pronouncing Dictionary data files."
-authors = ["David L. Day <[email protected]>"]
-license = "GPL-3.0-or-later"
-homepage = "https://github.com/prosegrinder/python-cmudict"
-repository = "https://github.com/prosegrinder/python-cmudict"
-readme = "README.md"
-keywords = ["cmudict"]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
@@ -35,17 +45,14 @@ exclude = [
     "src/cmudict/data/.git"
 ]
 
-[tool.poetry.dependencies]
-python = "^3.8"
-importlib-metadata = ">=5"
-importlib-resources = ">=5"
-
 [tool.poetry.group.dev.dependencies]
 pytest = ">=6.2.2"
 coverage = {extras = ["toml"], version = ">=6.5"}
 pytest-cov = ">=4.0"
 pylint = ">=3"
 black = ">=22.10"
+mypy = "^1.17.0"
+bandit = "^1.8.6"
 
 [tool.pytest.ini_options]
 filterwarnings = [

src/cmudict/__init__.py

@@ -4,17 +4,11 @@
 files. Compatible with NLTK's CMUDictCorpusReader.
 """
 
+import atexit
 import re
-import sys
-from collections import defaultdict
 from contextlib import ExitStack
-import atexit
-
-if sys.version_info >= (3, 9):
-    from importlib import metadata, resources
-else:
-    import importlib_metadata as metadata
-    import importlib_resources as resources
+from importlib import metadata, resources
+from typing import IO, Dict, List, Optional, Tuple
 
 __version__ = metadata.version(__name__)
 
@@ -28,17 +22,19 @@
 atexit.register(file_manager.close)
 
 
-def _stream(resource_name):
-    stream = resources.files(__name__).joinpath(resource_name).open("rb")
+def _stream(resource_name: str) -> IO[bytes]:
+    stream: IO[bytes] = resources.files(__name__).joinpath(resource_name).open("rb")
     return stream
 
 
-def _string(resource_name):
+def _string(resource_name: str) -> str:
     with resources.files(__name__).joinpath(resource_name).open() as file:
         return file.read()
 
 
-def _entries(stream, comment_string=None):
+def _entries(
+    stream: IO[bytes], comment_string: Optional[str] = None
+) -> List[Tuple[str, List[str]]]:
     cmudict_entries = []
     for line in stream:
         parts = []
@@ -52,113 +48,117 @@ def _entries(stream, comment_string=None):
 
 
 # pylint: disable-next=redefined-builtin
-def dict():
+def dict() -> Dict[str, List[List[str]]]:
     """
     Compatibility with NLTK.
     Returns the cmudict lexicon as a dictionary, whose keys are
     lowercase words and whose values are lists of pronunciations.
     """
-    default = defaultdict(list)
+    default: Dict[str, List[List[str]]] = {}
     for key, value in entries():
+        if key not in default:
+            default[key] = []
         default[key].append(value)
     return default
 
 
-def dict_stream():
+def dict_stream() -> IO[bytes]:
     """Return a readable file-like object of the cmudict.dict file."""
-    stream = _stream(CMUDICT_DICT)
+    stream: IO[bytes] = _stream(CMUDICT_DICT)
     return stream
 
 
-def dict_string():
+def dict_string() -> str:
     """Return the contents of cmudict.dict as a string."""
     string = _string(CMUDICT_DICT)
     return string
 
 
-def license_string():
+def license_string() -> str:
     """Return the contents of LICENSE as a string."""
     string = _string(CMUDICT_LICENSE)
     return string
 
 
-def phones():
+def phones() -> List[Tuple[str, List[str]]]:
     """Return a list of phones used in the main dict."""
-    cmu_phones = []
+    cmu_phones: List[Tuple[str, List[str]]] = []
     for line in phones_stream():
         parts = line.decode("utf-8").strip().split()
         cmu_phones.append((parts[0], parts[1:]))
     return cmu_phones
 
 
-def phones_stream():
+def phones_stream() -> IO[bytes]:
     """Return a readable file-like object of the cmudict.phones file."""
-    p_stream = _stream(CMUDICT_PHONES)
+    p_stream: IO[bytes] = _stream(CMUDICT_PHONES)
     return p_stream
 
 
-def phones_string():
+def phones_string() -> str:
     """Return the contents of cmudict.phones as a string."""
     string = _string(CMUDICT_PHONES)
     return string
 
 
-def symbols():
+def symbols() -> List[str]:
     """Return a list of symbols."""
-    cmu_symbols = []
+    cmu_symbols: List[str] = []
     for line in symbols_stream():
         cmu_symbols.append(line.decode("utf-8").strip())
     return cmu_symbols
 
 
-def symbols_stream():
+def symbols_stream() -> IO[bytes]:
     """Return a readable file-like object of the cmudict.symbols file."""
-    stream = _stream(CMUDICT_SYMBOLS)
+    stream: IO[bytes] = _stream(CMUDICT_SYMBOLS)
     return stream
 
 
-def symbols_string():
+def symbols_string() -> str:
     """Return the contents of cmudict.symbols as a string."""
     string = _string(CMUDICT_SYMBOLS)
     return string
 
 
 # pylint: disable-next=invalid-name
-def vp():
+def vp() -> Dict[str, List[List[str]]]:
     """Return a list of punctuation pronounciations."""
-    cmu_vp = defaultdict(list)
+    cmu_vp: Dict[str, List[List[str]]] = {}
     with vp_stream() as stream:
         for key, value in _entries(stream):
+            if not key in cmu_vp:
+                cmu_vp[key] = []
             cmu_vp[key].append(value)
     return cmu_vp
 
 
-def vp_stream():
+def vp_stream() -> IO[bytes]:
     """Return a readable file-like object of the cmudict.vp file."""
-    stream = _stream(CMUDICT_VP)
+    stream: IO[bytes] = _stream(CMUDICT_VP)
     return stream
 
 
-def vp_string():
+def vp_string() -> str:
     """Return the contents of cmudict.vp as a string."""
     string = _string(CMUDICT_VP)
     return string
 
 
 # The .entries(), .raw(), and .words() functions
 # maintain compatability with NTLK.
-def entries():
+def entries() -> List[Tuple[str, List[str]]]:
     """
     Compatibility with NLTK.
     Returns the cmudict lexicon as a list of entries
     containing (word, transcriptions) tuples.
     """
     with dict_stream() as stream:
-        cmu_entries = _entries(stream, "#")
+        cmu_entries: List[Tuple[str, List[str]]] = _entries(stream, "#")
     return cmu_entries
 
 
-def raw():
+def raw() -> str:
     """
     Compatibility with NLTK.
     Returns the cmudict lexicon as a raw string.
@@ -167,7 +167,7 @@ def raw():
     return string
 
 
-def words():
+def words() -> List[str]:
     """
     Compatibility with NLTK.
     Returns a list of all words defined in the cmudict lexicon.