Provide type annotations for the public API

.github/workflows/tests.yml

@@ -43,3 +43,29 @@ jobs:
         uses: codecov/codecov-action@v3
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
+
+  typesafety:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - run: |
+          python -m venv .venv
+          source .venv/bin/activate
+          pip install --upgrade pip
+          # Tell setuptools to *not* create a PEP 660 import hook and to use
+          # symlinks instead, so that pyright can still find the package. See
+          # https://microsoft.github.io/pyright/#/import-resolution?id=editable-installs
+          pip install --editable . --config-settings editable_mode=strict
+
+      - run: echo "$PWD/.venv/bin" >> $GITHUB_PATH
+
+      - uses: jakebailey/pyright-action@v1
+        with:
+          ignore-external: true
+          verify-types: "aocd"

aocd/__init__.py

@@ -1,4 +1,5 @@
 import sys
+import typing as t
 from functools import partial
 
 from . import _ipykernel
@@ -11,13 +12,34 @@
 from . import post
 from . import runner
 from . import utils
+from . import types
 from .exceptions import AocdError
 from .get import get_data
 from .get import get_day_and_year
 from .post import submit as _impartial_submit
 
+__all__ = [
+    "_ipykernel",
+    "cli",
+    "cookies",
+    "data",
+    "examples",
+    "exceptions",
+    "get",
+    "models",
+    "post",
+    "runner",
+    "submit",
+    "types",
+    "utils",
+]
 
-def __getattr__(name):
+if t.TYPE_CHECKING:
+    data: str
+    submit = _impartial_submit
+
+
+def __getattr__(name: str) -> t.Any:
     if name == "data":
         day, year = get_day_and_year()
         return get_data(day=day, year=year)

aocd/cli.py

@@ -13,7 +13,7 @@
 from .utils import get_plugins
 
 
-def main():
+def main() -> None:
     """Get your puzzle input data, caching it if necessary, and print it on stdout."""
     aoc_now = datetime.datetime.now(tz=AOC_TZ)
     days = range(1, 26)

aocd/cookies.py

@@ -12,10 +12,10 @@
 from .utils import get_owner
 
 
-log = logging.getLogger(__name__)
+log: logging.Logger = logging.getLogger(__name__)
 
 
-def get_working_tokens():
+def get_working_tokens() -> dict[str, str]:
     """Check browser cookie storage for session tokens from .adventofcode.com domain."""
     log.debug("checking for installation of browser-cookie3 package")
     try:
@@ -66,7 +66,7 @@ def get_working_tokens():
     return result
 
 
-def scrape_session_tokens():
+def scrape_session_tokens() -> None:
     """Scrape AoC session tokens from your browser's cookie storage."""
     aocd_token_path = AOCD_CONFIG_DIR / "token"
     aocd_tokens_path = AOCD_CONFIG_DIR / "tokens.json"

aocd/examples.py

@@ -1,7 +1,10 @@
+from __future__ import annotations
+
 import argparse
 import logging
 import re
 import sys
+import typing as t
 from dataclasses import dataclass
 from datetime import datetime
 from itertools import zip_longest
@@ -16,7 +19,11 @@
 from aocd.utils import get_plugins
 
 
-log = logging.getLogger(__name__)
+log: logging.Logger = logging.getLogger(__name__)
+
+_AnswerElem = t.Literal[
+    "a_code", "a_li", "a_pre", "a_em", "b_code", "b_li", "b_pre", "b_em"
+]
 
 
 @dataclass
@@ -34,17 +41,17 @@ class Page:
     soup: bs4.BeautifulSoup  # The raw_html string parsed into a bs4.BeautifulSoup instance
     year: int  # AoC puzzle year (2015+) parsed from html title
     day: int  # AoC puzzle day (1-25) parsed from html title
-    article_a: bs4.element.Tag  # The bs4 tag for the first <article> in the page, i.e. part a
-    article_b: bs4.element.Tag  # The bs4 tag for the second <article> in the page, i.e. part b. It will be `None` if part b locked
+    article_a: bs4.Tag  # The bs4 tag for the first <article> in the page, i.e. part a
+    article_b: bs4.Tag | None  # The bs4 tag for the second <article> in the page, i.e. part b. It will be `None` if part b locked
     a_raw: str  # The first <article> html as a string
-    b_raw: str  # The second <article> html as a string. Will be `None` if part b locked
+    b_raw: str | None  # The second <article> html as a string. Will be `None` if part b locked
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         part_a_only = "*" if self.article_b is None else ""
         return f"<Page({self.year}, {self.day}){part_a_only} at {hex(id(self))}>"
 
     @classmethod
-    def from_raw(cls, html):
+    def from_raw(cls, html: str) -> Page:
         soup = _get_soup(html)
         title_pat = r"^Day (\d{1,2}) - Advent of Code (\d{4})$"
         title_text = soup.title.text
@@ -77,7 +84,7 @@ def from_raw(cls, html):
         )
         return page
 
-    def __getattr__(self, name):
+    def __getattr__(self, name: _AnswerElem) -> t.Sequence[str]:
         if not name.startswith(("a_", "b_")):
             raise AttributeError(name)
         part, sep, tag = name.partition("_")
@@ -118,12 +125,12 @@ class Example(NamedTuple):
     """
 
     input_data: str
-    answer_a: str = None
-    answer_b: str = None
-    extra: str = None
+    answer_a: str | None = None
+    answer_b: str | None = None
+    extra: str | None = None
 
     @property
-    def answers(self):
+    def answers(self) -> tuple[str | None, str | None]:
         return self.answer_a, self.answer_b
 
 
@@ -144,7 +151,7 @@ def _get_unique_real_inputs(year, day):
     return list({}.fromkeys(strs))
 
 
-def main():
+def main() -> None:
     """
     Summarize an example parser's results with historical puzzles' prose, and
     compare the performance against a reference implementation

aocd/get.py

@@ -1,8 +1,11 @@
+from __future__ import annotations
+
 import datetime
 import os
 import re
 import traceback
-from logging import getLogger
+import typing as t
+from logging import Logger, getLogger
 
 from ._ipykernel import get_ipynb_path
 from .exceptions import AocdError
@@ -14,10 +17,15 @@
 from .utils import blocker
 
 
-log = getLogger(__name__)
+log: Logger = getLogger(__name__)
 
 
-def get_data(session=None, day=None, year=None, block=False):
+def get_data(
+    session: str | None = None,
+    day: int | None = None,
+    year: int | None = None,
+    block: bool = False,
+) -> str:
     """
     Get data for day (1-25) and year (2015+).
     User's session cookie (str) is needed - puzzle inputs differ by user.
@@ -45,7 +53,7 @@ def get_data(session=None, day=None, year=None, block=False):
         return puzzle.input_data
 
 
-def most_recent_year():
+def most_recent_year() -> int:
     """
     This year, if it's December.
     The most recent year, otherwise.
@@ -60,7 +68,7 @@ def most_recent_year():
     return year
 
 
-def current_day():
+def current_day() -> int:
     """
     Most recent day, if it's during the Advent of Code. Happy Holidays!
     Day 1 is assumed, otherwise.
@@ -73,7 +81,7 @@ def current_day():
     return day
 
 
-def get_day_and_year():
+def get_day_and_year() -> tuple[int, int | None]:
     """
     Returns tuple (day, year).