feat: add type hints (#71)

Author: davidlday

.github/workflows/pypi-publish.yml

@@ -1,16 +1,32 @@
 name: Publish to PyPi
 
+permissions:
+  contents: read
+
 on:
   push:
     tags:
       - "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,14 +1,40 @@
 name: Bump Version and Create Release
 
+permissions:
+  contents: read
+
 on:
   push:
     branches:
       - main
 
 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 }}"

poetry.lock

@@ -1,41 +1,60 @@
+[project]
+name = "prosegrinder"
+dynamic = ["version", "classifiers"]
+description = "A text analytics library for prose fiction."
+license = {text = "GPLv3"}
+readme = "README.md"
+requires-python = ">=3.9,<4.0"
+authors = [
+    {name = "David L. Day", email = "[email protected]"}
+]
+keywords = ["text analytics", "prose fiction", "natural language processing", "NLP", "linguistics"]
+dependencies = [
+    "importlib-metadata>=5.1.0",
+    "cmudict>=1.0.11",
+    "narrative>=1.1.1",
+    "pointofview>=1.0.2",
+    "syllables>=1.0.4",
+    "click>=8.1.3"
+]
+
+[project.scripts]
+prosegrinder = "prosegrinder.__main__:cli"
+
+[project.urls]
+homepage = "https://github.com/prosegrinder/python-prosegrinder"
+repository = "https://github.com/prosegrinder/python-prosegrinder"
+"Bug Tracker" = "https://github.com/prosegrinder/python-prosegrinder/issues"
+
 [tool.commitizen]
-version = "1.3.8"
 tag_format = "v$version"
 update_changelog_on_bump = true
 changelog_incremental = true
 bump_message = "bump: $current_version → $new_version"
-version_files = [
-  "pyproject.toml:version",
-]
+version_provider = "poetry"
 
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
-name = "prosegrinder"
 version = "1.3.8"
-description = "A text analytics library for prose fiction."
-authors = ["David L. Day <[email protected]>"]
-license = "GPLv3"
-readme = "README.md"
-
-[tool.poetry.dependencies]
-python = "^3.7.2"
-importlib-metadata = "^5.1.0"
-cmudict = "^1.0.11"
-narrative = "^1.1.1"
-pointofview = "^1.0.2"
-syllables = "^1.0.4"
-click = "^8.1.3"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing"
+]
 
 [tool.poetry.group.dev.dependencies]
-pytest = "^7.2.0"
-pylint = "^2.15.8"
 black = ">=22.12,<24.0"
+mypy = "^1.17.0"
+bandit = "^1.8.6"
+pylint = "^3.3.7"
+pytest = "^8.4.1"
 
-[tool.poetry.scripts]
-prosegrinder = "prosegrinder.__main__:cli"
-
-[tool.pylint."messages control"]
-disable = ["duplicate-code", "too-many-instance-attributes", "too-many-arguments"]
+[tool.pylint.'MESSAGES CONTROL']
+disable = "similarities"

pyproject.toml

@@ -20,17 +20,17 @@
 @click.option(
     "-s", "--save", required=False, type=click.File("w"), help="File to save output to."
 )
-def cli(files, save, indent):
+def cli(files: list[click.File], save: click.File, indent: int) -> None:
     """Setup the command line interface"""
     processed_files = []
     for file in files:
         filename = click.format_filename(file.name)
-        text = file.read()
+        text = file.read()  # type: ignore
         _p = Prose(text)
         _d = {"filename": filename, "statistics": _p.stats}
         processed_files.append(_d)
     _j = json.dumps(processed_files, indent=indent)
     if save:
-        save.write(_j)
+        save.write(_j)  # type: ignore
     else:
         click.echo(_j)

src/prosegrinder/__main__.py

@@ -1,4 +1,5 @@
 """Fragment class for prosegrinder."""
+
 import re
 from collections import Counter
 
@@ -8,10 +9,10 @@
 from prosegrinder.word import Word
 
 
-class Fragment:
+class Fragment:  # pylint: disable=too-many-instance-attributes
     """A fragment of text."""
 
-    def __init__(self, text, dictionary=Dictionary()):
+    def __init__(self, text: str, dictionary: Dictionary = Dictionary()):
         self.text = text
         self.dictionary = dictionary
         self.normalized_sentence = dictionary.normalize_text(text)
@@ -21,8 +22,8 @@ def __init__(self, text, dictionary=Dictionary()):
         ]
         self.word_count = len(self.words)
         self.word_character_count = sum(word.character_count for word in self.words)
-        _pf = Counter()
-        _pc = 0
+        _pf: Counter = Counter()
+        _pc: int = 0
         for word in self.words:
             _pf.update(word.phone_frequency)
             _pc += word.phone_count
@@ -41,7 +42,7 @@ def __init__(self, text, dictionary=Dictionary()):
         self.third_person_word_count = sum(
             word.is_third_person_word for word in self.words
         )
-        self.word_frequency = dict(Counter(self.words))
+        self.word_frequency = dict(Counter(word.text for word in self.words))
         self.unique_words = self.word_frequency.keys()
         self.unique_word_count = len(self.unique_words)
         self.pov = pointofview.NONE
@@ -52,17 +53,19 @@ def __init__(self, text, dictionary=Dictionary()):
         elif self.third_person_word_count > 0:
             self.pov = pointofview.THIRD
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         """Equality operator for instance variables."""
+        if not isinstance(other, Fragment):
+            return False
         return self.text == other.text
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         """Hash operator for instance variables."""
         return hash(self.text)
 
-    def frequency(self, word_string):
+    def frequency(self, word_string: str) -> int:
         """Returns the frequency of a word in the fragment."""
-        return self.word_frequency[word_string]
+        return self.word_frequency.get(word_string, 0)
 
     @property
     def stats(self):

src/prosegrinder/fragment.py

@@ -1,15 +1,20 @@
 """Fragment container class for prosegrinder."""
+
 from collections import Counter
+from collections.abc import Sequence
 
 import pointofview
 
 from prosegrinder.dictionary import Dictionary
+from prosegrinder.fragment import Fragment
 
 
-class FragmentContainer:
+class FragmentContainer:  # pylint: disable=too-many-instance-attributes
     """A container for fragments."""
 
-    def __init__(self, fragments, dictionary=Dictionary()):
+    def __init__(
+        self, fragments: Sequence[Fragment], dictionary: Dictionary = Dictionary()
+    ):
         self.dictionary = dictionary
         self.fragments = fragments or []
         self.fragment_count = len(self.fragments)
@@ -38,9 +43,9 @@ def __init__(self, fragments, dictionary=Dictionary()):
         self.third_person_word_count = sum(
             fragment.third_person_word_count for fragment in self.fragments
         )
-        _wf = Counter()
-        _pf = Counter()
-        _pc = 0
+        _wf: Counter = Counter()
+        _pf: Counter = Counter()
+        _pc: int = 0
         for fragment in self.fragments:
             _wf.update(fragment.words)
             _pf.update(fragment.phone_frequency)
@@ -58,14 +63,16 @@ def __init__(self, fragments, dictionary=Dictionary()):
         elif self.third_person_word_count > 0:
             self.pov = pointofview.THIRD
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         """Equality operator for instance variables."""
+        if not isinstance(other, FragmentContainer):
+            return False
         return self.fragments == other.fragments
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         """Hash operator for instance variables."""
         return hash(self.fragments)
 
-    def frequency(self, word_string):
+    def frequency(self, word_string: str) -> int:
         """Gets the frequency of a word in the fragment container."""
         return self.word_frequency[self.dictionary.get_word(word_string)]

src/prosegrinder/fragment_container.py

@@ -1,4 +1,5 @@
 """Paragraph class for prosegrinder."""
+
 import re
 
 import narrative
@@ -14,7 +15,7 @@ class Paragraph(FragmentContainer):
 
     RE_PARAGRAPH = re.compile(".*(?=\\n|$)")
 
-    def __init__(self, text, dictionary=Dictionary()):
+    def __init__(self, text: str, dictionary: Dictionary = Dictionary()):
         self.text = text
         self.dictionary = dictionary
         self.sentences = Sentence.parse_sentences(self.text, self.dictionary)
@@ -29,12 +30,16 @@ def __init__(self, text, dictionary=Dictionary()):
         self.pov = self.narrative.pov
         super().__init__(self.sentences, self.dictionary)
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         """Equality operator for instance variables."""
+        if not isinstance(other, Paragraph):
+            return False
         return self.text == other.text
 
     @staticmethod
-    def parse_paragraphs(text, dictionary=Dictionary()):
+    def parse_paragraphs(
+        text: str, dictionary: Dictionary = Dictionary()
+    ) -> list["Paragraph"]:
         """Parses a text into a list of Paragraph objects."""
         return [
             Paragraph(paragraph, dictionary)