Adding typing hints

Author: ThosRTanner

.flake8

@@ -3,12 +3,18 @@ builtins = _
 exclude =
     .git,
     __pycache__,
-    .venv/,venv/,
+    .venv/,
+    venv*/,
     .tox/,
-    build/,dist/,*egg,
+    build/,
+    dist/,
+    *egg,
     docs/conf.py,
-    zookeeper/
+    zookeeper/,
 # See black's documentation for E203
 max-line-length = 79
-extend-ignore = BLK100,E203
+# I am not sure what version of flake8 hound is using
+# but it gives a lot of undefined names for comments (F821)
+# and redefinition of unused variables (F811)
+extend-ignore = BLK100,E203,F811,F821
 

.gitignore

@@ -30,10 +30,12 @@ zookeeper/
 .project
 .pydevproject
 .tox
-venv
+venv*/
 /.settings
 /.metadata
+__pycache__/
 
 !.gitignore
 !.git-blame-ignore-revs
 
+.vscode/settings.json

AGENTS.md

@@ -0,0 +1,141 @@
+# Agent Guidelines for Kazoo
+
+This document provides guidelines for agents and tools working with the Kazoo codebase.
+
+## Python Version Compatibility
+
+Kazoo supports Python 3.8+, with explicit targeting of py38, py39, py310, py311, py312, py313, and py314. When writing or modifying code:
+
+- **Use `from __future__ import annotations`** at the top of every module to enable postponed evaluation of type annotations (PEP 563). This allows using native Python type names rather than importing uppercase versions from `typing`.
+- Example: Use `list[str]` instead of `List[str]`, `dict[str, int]` instead of `Dict[str, int]`, etc.
+- This is required for py38+ compatibility when using modern type hint syntax.
+
+## Code Style
+
+### Type Hints
+
+- All functions and methods should have appropriate type hints.
+- Use native Python type syntax with `from __future__ import annotations` rather than `typing` module types where possible.
+- Example imports:
+  ```python
+  from __future__ import annotations
+  from typing import Any, Optional, Callable, Union
+  ```
+
+### Constructor (`__init__`) Methods
+
+- `__init__` methods with arguments should **not** include a return type hint.
+- **Correct**: `def __init__(self, client: Any):`
+- **Incorrect**: `def __init__(self, client: Any) -> None:`
+- This is a repository-specific style rule to keep constructor signatures consistent and avoid unnecessary return annotations.
+- Note: `__init__` methods with no arguments (other than `self`) must include `-> None`
+
+### Line Length
+
+- Maximum line length: 79 characters (enforced by Black formatter).
+- Configuration: `tool.black` in `pyproject.toml` specifies `line-length = 79`.
+
+### Formatting
+
+- Code is formatted with Black.
+- Target versions: py38, py39, py310, py311, py312, py313, py314.
+
+## Type Checking
+
+Kazoo uses mypy for static type checking with strict type checking enabled.
+
+### Using mypy with VS Code
+
+You have to install the **Pylance** extension sadly, as a language server is needed for other extensions, and the default language server is broken for python 3.8
+
+However, you should disable it by specifying
+
+```json
+{
+    "python.analysis.ignore": ["kazoo/**"]
+}
+```
+
+Install the **mypy** extension directly:
+
+1. Install the extension:
+   - Open VS Code Extensions (`Ctrl+Shift+X`)
+   - Search for "mypy" and install the official mypy extension
+   
+2. The mypy extension will automatically use the configuration from `pyproject.toml`, but it needs a couple of configuration changes:
+```json
+    "mypy-type-checker.importStrategy": "fromEnvironment",
+    "mypy-type-checker.args": [ "--exclude=(kazoo|docs)/[^/]+\\.py" ],
+```
+
+3. To see type checking errors in the editor:
+   - Errors appear as red squiggly underlines
+   - Hover over errors to see detailed messages
+   - Open the **Problems panel** (`Ctrl+Shift+M`) to view all errors
+
+### mypy Configuration
+
+Kazoo's mypy configuration (in `pyproject.toml` under `[tool.mypy]`) enforces strict type checking:
+
+**Strict Mode Settings:**
+- `strict = true`: Enables all strict type checking flags
+- `disallow_subclassing_any = true`: Prevents subclassing untyped classes
+- `disallow_untyped_calls = true`: All function calls must use typed functions
+- `disallow_untyped_defs = true`: All functions must have type hints
+- `disallow_incomplete_defs = true`: Type hints must be complete (no partial types)
+- `disallow_untyped_decorators = true`: Decorators must be typed
+- `check_untyped_defs = true`: Check bodies of untyped functions
+- `implicit_optional = false`: Optional types must be explicit
+- `strict_optional = true`: Strict handling of None types
+
+**Error Messages:**
+- `show_error_context = true`: Shows surrounding code context
+- `show_column_numbers = true`: Displays exact column numbers
+- `pretty = true`: Colorized output for better readability
+- `color_output = true`: Enables colored terminal output
+- `show_absolute_path = true`: Shows full file paths
+
+**Key Setting:**
+- `disallow_subclassing_any = true`: Prevents subclassing untyped classes, ensuring all external dependencies are properly typed or have stubs
+
+### Running mypy from Terminal
+
+Run type checking from the command line:
+```bash
+# Check the entire project
+mypy kazoo/
+
+# Check specific files/directories
+mypy kazoo/client.py
+mypy kazoo/handlers/
+```
+
+## Testing
+
+- Tests use pytest with the following configuration:
+  - Per-test timeout: 180 seconds
+  - Verbosity: `-ra -v --color=yes`
+  - Log level: INFO
+- Test files are located in `kazoo/tests/`.
+
+## Module Organization
+
+- **Core client**: `kazoo/client.py`
+- **Handlers** (async frameworks): `kazoo/handlers/`
+  - `threading.py`: Standard threading handler
+  - `gevent.py`: Gevent-based async handler
+  - `eventlet.py`: Eventlet-based async handler
+- **Recipes** (higher-level abstractions): `kazoo/recipe/`
+  - `barrier.py`, `election.py`, `lock.py`, `queue.py`, etc.
+- **Protocol**: `kazoo/protocol/`
+  - Connection handling, serialization, state management
+- **Testing utilities**: `kazoo/testing/`
+  - Test harness and common test utilities
+
+## Best Practices
+
+1. **Preserve backward compatibility**: Kazoo is a widely-used library; changes should not break existing APIs.
+2. **Document changes**: Update docstrings and add entries to `CHANGES.md` for significant modifications.
+3. **Run tests**: Use `pytest` or `tox` to ensure changes don't break existing functionality.
+4. **Type hints first**: Design type hints carefully; they are enforced by mypy and serve as API documentation.
+5. **Follow PEP 8**: Adhere to Python style guidelines as enforced by Black and checked by linters.