typing: add py.typed

[JPHutchins]

Closes #12.

[JPHutchins]

CI error: https://github.com/adafruit/Adafruit_Board_Toolkit/actions/runs/11788175995/job/32834823668?pr=13

Reproducible on local, python 3.12.7:

An unexpected error has occurred: CalledProcessError: command: ('C:\\Users\\jp\\.cache\\pre-commit\\repoltk1wzk_\\py_env-python3.12\\Scripts\\python.EXE', '-mpip', 'install', '.')
return code: 1
stdout:
    Processing c:\users\jp\.cache\pre-commit\repoltk1wzk_
      Installing build dependencies: started
      Installing build dependencies: finished with status 'done'
      Getting requirements to build wheel: started
      Getting requirements to build wheel: finished with status 'error'
stderr:
      error: subprocess-exited-with-error

      Getting requirements to build wheel did not run successfully.
      exit code: 1

      [33 lines of output]
      Traceback (most recent call last):
        File "C:\Users\jp\.cache\pre-commit\repoltk1wzk_\py_env-python3.12\Lib\site-packages\pip\_vendor\pyproject_hooks\_in_process\_in_process.py", line 353, in <module>
          main()
        File "C:\Users\jp\.cache\pre-commit\repoltk1wzk_\py_env-python3.12\Lib\site-packages\pip\_vendor\pyproject_hooks\_in_process\_in_process.py", line 335, in main
          json_out['return_val'] = hook(**hook_input['kwargs'])
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "C:\Users\jp\.cache\pre-commit\repoltk1wzk_\py_env-python3.12\Lib\site-packages\pip\_vendor\pyproject_hooks\_in_process\_in_process.py", line 112, in get_requires_for_build_wheel
          backend = _build_backend()
                    ^^^^^^^^^^^^^^^^
        File "C:\Users\jp\.cache\pre-commit\repoltk1wzk_\py_env-python3.12\Lib\site-packages\pip\_vendor\pyproject_hooks\_in_process\_in_process.py", line 77, in _build_backend
          obj = import_module(mod_path)
                ^^^^^^^^^^^^^^^^^^^^^^^
        File "C:\Program Files\WindowsApps\PythonSoftwareFoundation.Python.3.12_3.12.2032.0_x64__qbz5n2kfra8p0\Lib\importlib\__init__.py", line 90, in import_module
          return _bootstrap._gcd_import(name[level:], package, level)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
        File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
        File "<frozen importlib._bootstrap>", line 1310, in _find_and_load_unlocked
        File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
        File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
        File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
        File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
        File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
        File "<frozen importlib._bootstrap_external>", line 995, in exec_module
        File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
        File "C:\Users\jp\AppData\Local\Temp\pip-build-env-bb5s5mdx\overlay\Lib\site-packages\setuptools\__init__.py", line 16, in <module>
          import setuptools.version
        File "C:\Users\jp\AppData\Local\Temp\pip-build-env-bb5s5mdx\overlay\Lib\site-packages\setuptools\version.py", line 1, in <module>
          import pkg_resources
        File "C:\Users\jp\AppData\Local\Temp\pip-build-env-bb5s5mdx\overlay\Lib\site-packages\pkg_resources\__init__.py", line 2191, in <module>
          register_finder(pkgutil.ImpImporter, find_on_path)
                          ^^^^^^^^^^^^^^^^^^^
      AttributeError: module 'pkgutil' has no attribute 'ImpImporter'. Did you mean: 'zipimporter'?
      [end of output]

      note: This error originates from a subprocess, and is likely not a problem with pip.
    error: subprocess-exited-with-error

    Getting requirements to build wheel did not run successfully.
    exit code: 1

    See above for output.

    note: This error originates from a subprocess, and is likely not a problem with pip.
Check the log at C:\Users\jp\.cache\pre-commit\pre-commit.log

[JPHutchins]

Looks like sphinx-rtd-theme needs to get locked: https://github.com/adafruit/Adafruit_Board_Toolkit/actions/runs/11788475185/job/32835642010

[dhalbert]

Don't do this by rolling Python or sphinx-rtd-theme back. Roll pylint and other things forward. Example: https://github.com/adafruit/Adafruit_CircuitPython_HID/blob/main/.pre-commit-config.yaml.

We don't use py.typed anywhere else, including with other libraries that use mypy. Is this historical?

[JPHutchins]

We don't use py.typed anywhere else, including with other libraries that use mypy. Is this historical?

The py.typed file appears to be a current requirement of the spec: https://typing.readthedocs.io/en/latest/spec/distributing.html#packaging-type-information

[dhalbert]

You can just remove get_html_theme_path. We did that in all the libraries here:
https://github.com/adafruit/adabot/blob/e5167422e54508450b6fc28243181d82ccd2b0c3/patches/0001-remove-deprecated-get_html_theme_path-call.patch#L4
Also switch back to python 3.x from 3.10`.

[JPHutchins]

Looks like it's just the docs problem:

Run sphinx-build -E -W -b html . _build/html
  sphinx-build -E -W -b html . _build/html
  shell: /usr/bin/bash -e {0}
  env:
    pythonLocation: /opt/hostedtoolcache/Python/3.1[2](https://github.com/adafruit/Adafruit_Board_Toolkit/actions/runs/11801627587/job/32875412141?pr=13#step:13:2).7/x64
    PKG_CONFIG_PATH: /opt/hostedtoolcache/Python/[3](https://github.com/adafruit/Adafruit_Board_Toolkit/actions/runs/11801627587/job/32875412141?pr=13#step:13:3).12.7/x64/lib/pkgconfig
    Python_ROOT_DIR: /opt/hostedtoolcache/Python/3.12.7/x6[4](https://github.com/adafruit/Adafruit_Board_Toolkit/actions/runs/11801627587/job/32875412141?pr=13#step:13:4)
    Python2_ROOT_DIR: /opt/hostedtoolcache/Python/3.12.7/x[6](https://github.com/adafruit/Adafruit_Board_Toolkit/actions/runs/11801627587/job/32875412141?pr=13#step:13:6)4
    Python3_ROOT_DIR: /opt/hostedtoolcache/Python/3.12.7/x64
    LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.12.[7](https://github.com/adafruit/Adafruit_Board_Toolkit/actions/runs/11801627587/job/32875412141?pr=13#step:13:7)/x64/lib
Running Sphinx v8.1.3
WARNING: Calling get_html_theme_path is deprecated. If you are calling it to define html_theme_path, you are safe to remove that code.
loading translations [en]... done
making output directory... done
Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`.
loading intersphinx inventory 'python' from https://docs.python.org/3.4/objects.inv ...
loading intersphinx inventory 'CircuitPython' from https://circuitpython.readthedocs.io/en/latest/objects.inv ...
intersphinx inventory has moved: https://circuitpython.readthedocs.io/en/latest/objects.inv -> https://docs.circuitpython.org/en/latest/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 3 source files that are out of date
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [ 33%] api
reading sources... [ 67%] examples
reading sources... [[10](https://github.com/adafruit/Adafruit_Board_Toolkit/actions/runs/11801627587/job/32875412141?pr=13#step:13:10)0%] index

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... 
copying static files... 
Writing evaluated template result to /home/runner/work/Adafruit_Board_Toolkit/Adafruit_Board_Toolkit/docs/_build/html/_static/basic.css
Writing evaluated template result to /home/runner/work/Adafruit_Board_Toolkit/Adafruit_Board_Toolkit/docs/_build/html/_static/language_data.js
Writing evaluated template result to /home/runner/work/Adafruit_Board_Toolkit/Adafruit_Board_Toolkit/docs/_build/html/_static/documentation_options.js
Writing evaluated template result to /home/runner/work/Adafruit_Board_Toolkit/Adafruit_Board_Toolkit/docs/_build/html/_static/js/versions.js
copying static files: done
copying extra files... 
copying extra files: done
copying assets: done
writing output... [ 33%] api
writing output... [ 67%] examples
writing output... [100%] index

generating indices... genindex py-modindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 1 warning (with warnings treated as errors).
Error: Process completed with exit code 1.

This can be resolved be removing the -W flag, locking sphinx-rtd-theme, or addressing the deprecation warning:

WARNING: Calling get_html_theme_path is deprecated. If you are calling it to define html_theme_path, you are safe to remove that code.

Which do you prefer?

[dhalbert]

Probably a good idea to compare the ancillary files here with any library that has a had a recent release.

[dhalbert]

Some discussion of py.typed here which is a little illuminating: python/typing#1429. @FoamyGuy are you aware of py.typed? I am surprised we have not seen this issue in other libraries used with CPython, etc.

[JPHutchins]

I am surprised we have not seen this issue in other libraries used with CPython, etc.

Well, not all Python devs are as ... scrupulous ... as I am 🍸 .

[dhalbert]

Thanks! Fine to take this for now while we study py.typed. Mainly we needed to update the build, as you found out.

[FoamyGuy]

I was not aware of py.typed I will read into that a bit more.