Add py.typed and annotate the leaf modules

[jaysonsantos]

Part of the repository modernization effort.

Background

No module in bmemcached/ has type annotations. All type information lives in Sphinx docstring fields, for example bmemcached/protocol.py:239,288,363,409,452. A type checker cannot read these. Some are already stale.

bmemcached/client/mixin.py:153 holds one lone comment-style hint:

# type: (six.string_types, int) -> bool

No other line in that file matches it.

Two type-checker comments exist. Both mark Python 2 code:

• bmemcached/protocol.py:7,9 — # type: ignore[import-not-found] on the urlparse fallback.
• bmemcached/compat.py:5 — import pickle as pickle # type: ignore.

The Python 2 cleanup issues delete both.

bmemcached/py.typed does not exist. Downstream mypy and pyright users cannot read this package's types. See PEP 561.

No mypy config exists. mypy.ini is absent. pyproject.toml holds no [tool.mypy] table.

Scope

Annotate the leaf modules only. Do not annotate bmemcached/protocol.py in this issue.

bmemcached/protocol.py is the core module. Its COMMANDS dict-of-dicts and its tuple response handling need a TypedDict or NamedTuple refactor before they type cleanly. That is separate work.

Plan

1. Add an empty bmemcached/py.typed file.
2. Include py.typed in the built package. Add [tool.setuptools.package-data] to pyproject.toml, or add the path to MANIFEST.in.
3. Annotate bmemcached/exceptions.py. It holds three classes.
4. Annotate bmemcached/utils.py. It holds one function.
5. Annotate bmemcached/client/constants.py. It holds constants only.
6. Add mypy to the test dependency group.
7. Add a [tool.mypy] table. Run --strict on those three files only.
8. Wire the mypy run into tox.ini.

Follow-up order for later issues

Annotate in this order after this issue lands:

1. bmemcached/client/mixin.py. It defines the shared NotImplementedError stubs that the other two clients override.
2. bmemcached/client/distributed.py and bmemcached/client/replicating.py.
3. bmemcached/protocol.py, with the TypedDict refactor.

Acceptance criteria

• bmemcached/py.typed exists and is empty.
• The built wheel holds bmemcached/py.typed. Check with python -m build and an unzip of the wheel.
• bmemcached/exceptions.py, bmemcached/utils.py, and bmemcached/client/constants.py hold full annotations.
• pyproject.toml holds a [tool.mypy] table.
• mypy --strict passes on those three files.
• tox.ini runs the mypy command.
• mypy is in the test dependency group.

Files to change

bmemcached/py.typed (new), pyproject.toml, MANIFEST.in, bmemcached/exceptions.py, bmemcached/utils.py, bmemcached/client/constants.py, tox.ini.

Order

Do the six removal issue first. Do not annotate code that a later issue deletes.

Do the defect-fix issue first. That issue adds MemcachedException.__str__.

Do the PEP 621 issue first. This issue changes pyproject.toml.

[jaysonsantos]

Tracked in #277.

[jaysonsantos]

Deferred. This issue is not implemented in the current modernization run.

It depends on three pull requests that are open and not merged:

• feat: set the Python 3.10 floor and remove the Python 2 support layer #278 — sets the Python 3.10 floor and removes six and bmemcached/compat.py (closes Set the minimum supported Python version to 3.10 #265, Remove the six dependency and delete bmemcached/compat.py #266, Remove the remaining Python 2 idioms #267). This issue must not annotate code that pull request deletes.
• chore: migrate packaging to PEP 621 and replace flake8 with ruff #279 — migrates packaging to a PEP 621 pyproject.toml (closes Migrate setup.py to a PEP 621 pyproject.toml #268, Replace flake8 with ruff and modernize pre-commit #269, Replace requirements_test.txt with a PEP 735 dependency group #270). This issue adds a [tool.mypy] table and a mypy entry in the test dependency group. Both need that file to exist first.
• fix: replace assert guards, add an exception message, and stop a password leak #282 — adds MemcachedException.__str__ and changes the shape of the exception classes (closes Fix five defects: assert guards, exception message, password leak, circular import #273). This issue annotates bmemcached/exceptions.py.

Implement this issue after those three merge.

Two notes for whoever picks it up.

The two # type: ignore comments named in the issue body are already gone. #278 deleted bmemcached/compat.py and replaced the urlparse import fallback in bmemcached/protocol.py with a direct from urllib.parse import SplitResult.

The lone comment-style hint at bmemcached/client/mixin.py:153 reads # type: (six.string_types, int) -> bool today. #278 rewrites it to # type: (str, int) -> bool. Replace it with a real annotation in this issue.