ci: add pre-commit hooks for local linting and refactor publish workflow to PR-based TestPyPI

Author: devinslick

.github/workflows/publish.yml

@@ -94,4 +94,4 @@ jobs:
           path: dist/
 
       - name: Publish package distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -48,4 +48,4 @@ fmd-server/
 fmd-android/
 
 #credentials file
-examples/tests/credentials.txt
+examples/tests/credentials.txt

.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+# Pre-commit hooks configuration
+# See https://pre-commit.com for more information
+repos:
+  # General file cleanup
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: '^tests/functional/'
+      - id: end-of-file-fixer
+        exclude: '^tests/functional/'
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files
+        args: ['--maxkb=1000']
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: mixed-line-ending
+        args: ['--fix=lf']
+
+  # Python code formatting with black
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black
+        language_version: python3
+
+  # Python linting with flake8
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.1.1
+    hooks:
+      - id: flake8
+        args: ['--count', '--show-source', '--statistics']
+        exclude: '^tests/functional/'
+
+  # Python type checking with mypy
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - types-aiofiles
+          - aiohttp
+          - argon2-cffi
+          - cryptography
+        args: ['--install-types', '--non-interactive']
+        exclude: '^tests/'

README.md

@@ -114,7 +114,7 @@ Tips:
     - `set_ringer_mode("normal|vibrate|silent")`
     - `get_device_stats()`
 
-  
+
   - Low‑level: `decrypt_data_blob(b64_blob)`
 
 - `Device` helper (per‑device convenience)
@@ -171,4 +171,4 @@ This client targets the FMD ecosystem:
 - https://gitlab.com/fmd-foss
 - Public community instance: https://fmd.nulide.de/
 
-MIT © 2025 Devin Slick
+MIT © 2025 Devin Slick

docs/HOME_ASSISTANT_REVIEW.md

@@ -79,7 +79,7 @@ async def _make_api_request(self, ..., timeout: int = 30):
 - `pyproject.toml`: `2.0.0.dev8` (PEP 440 compliant)
 - `_version.py`: `2.0.0-dev8` (uses hyphen instead of dot)
 
-**Location:** 
+**Location:**
 - `pyproject.toml` line 3
 - `fmd_api/_version.py` line 1
 
@@ -143,7 +143,7 @@ if resp.status == 429:
 class FmdClient:
     async def __aenter__(self):
         return self
-    
+
     async def __aexit__(self, exc_type, exc, tb):
         await self.close()
 ```
@@ -191,9 +191,9 @@ async with await FmdClient.create(...) as client:
 - Line ~88: Logs may include auth details
 - Line ~203: Logs full JSON responses which may contain tokens
 
-**Fix:** 
+**Fix:**
 - Sanitize all log output
-- Mask tokens: `log.debug(f"Token: {token[:8]}...")` 
+- Mask tokens: `log.debug(f"Token: {token[:8]}...")`
 - Add guards: `if log.isEnabledFor(logging.DEBUG):`
 
 **HA Rationale:** Security and privacy requirement for production systems.
@@ -364,7 +364,7 @@ async def decrypt_data_blob_async(self, data_b64: str) -> bytes:
 async def get_locations(...) -> List[str]:
     """
     ...
-    
+
     Raises:
         AuthenticationError: If authentication fails
         FmdApiException: If server returns error
@@ -384,7 +384,7 @@ async def get_locations(...) -> List[str]:
 
 **Location:** Test configuration
 
-**Fix:** 
+**Fix:**
 - Add `pytest-cov` to dev dependencies
 - Configure coverage in `pyproject.toml`
 - Add coverage reporting to CI workflow

docs/MIGRATE_FROM_V1.md

@@ -175,16 +175,16 @@ from fmd_api import FmdApi
 
 async def main():
     api = await FmdApi.create("https://fmd.example.com", "alice", "secret")
-    
+
     # Request new location
     await api.request_location('gps')
     await asyncio.sleep(30)
-    
+
     # Get locations
     blobs = await api.get_all_locations(1)
     location_json = api.decrypt_data_blob(blobs[0])
     location = json.loads(location_json)
-    
+
     print(f"Lat: {location['lat']}, Lon: {location['lon']}")
     await api.close()
 
@@ -199,16 +199,16 @@ from fmd_api import FmdClient
 
 async def main():
     client = await FmdClient.create("https://fmd.example.com", "alice", "secret")
-    
+
     # Request new location
     await client.request_location('gps')
     await asyncio.sleep(30)
-    
+
     # Get locations
     blobs = await client.get_locations(1)
     location_json = client.decrypt_data_blob(blobs[0])
     location = json.loads(location_json)
-    
+
     print(f"Lat: {location['lat']}, Lon: {location['lon']}")
     await client.close()
 
@@ -223,14 +223,14 @@ from fmd_api import FmdClient, Device
 async def main():
     client = await FmdClient.create("https://fmd.example.com", "alice", "secret")
     device = Device(client, "alice")
-    
+
     # Request and get location (simplified)
     await client.request_location('gps')
     await asyncio.sleep(30)
-    
+
     location = await device.get_location(force=True)
     print(f"Lat: {location.lat}, Lon: {location.lon}")
-    
+
     await client.close()
 
 asyncio.run(main())
@@ -244,16 +244,16 @@ from fmd_api import FmdApi, FmdCommands
 
 async def control_device():
     api = await FmdApi.create("https://fmd.example.com", "alice", "secret")
-    
+
     # Using constants
     await api.send_command(FmdCommands.RING)
     await api.send_command(FmdCommands.BLUETOOTH_ON)
-    
+
     # Using convenience methods
     await api.toggle_bluetooth(True)
     await api.toggle_do_not_disturb(True)
     await api.set_ringer_mode('vibrate')
-    
+
     await api.close()
 ```
 
@@ -263,16 +263,16 @@ from fmd_api import FmdClient
 
 async def control_device():
     client = await FmdClient.create("https://fmd.example.com", "alice", "secret")
-    
+
     # Use strings directly (constants removed)
     await client.send_command('ring')
     await client.send_command('bluetooth on')
-    
+
     # Using convenience methods (renamed from toggle_* to set_*)
     await client.set_bluetooth(True)
     await client.set_do_not_disturb(True)
     await client.set_ringer_mode('vibrate')
-    
+
     await client.close()
 ```
 
@@ -283,15 +283,15 @@ from fmd_api import FmdClient, Device
 async def control_device():
     client = await FmdClient.create("https://fmd.example.com", "alice", "secret")
     device = Device(client, "alice")
-    
+
     # Use device methods for cleaner API
     await device.play_sound()
-    
+
     # Settings still use client
     await client.set_bluetooth(True)
     await client.set_do_not_disturb(True)
     await client.set_ringer_mode('vibrate')
-    
+
     await client.close()
 ```
 
@@ -304,13 +304,13 @@ from fmd_api import FmdApi
 
 async def get_history():
     api = await FmdApi.create("https://fmd.example.com", "alice", "secret")
-    
+
     blobs = await api.get_all_locations(10)
     for blob in blobs:
         location_json = api.decrypt_data_blob(blob)
         location = json.loads(location_json)
         print(f"Date: {location['date']}, Lat: {location['lat']}, Lon: {location['lon']}")
-    
+
     await api.close()
 ```
 
@@ -321,11 +321,11 @@ from fmd_api import FmdClient, Device
 async def get_history():
     client = await FmdClient.create("https://fmd.example.com", "alice", "secret")
     device = Device(client, "alice")
-    
+
     # Async iterator with automatic decryption
     async for location in device.get_history(limit=10):
         print(f"Date: {location.date}, Lat: {location.lat}, Lon: {location.lon}")
-    
+
     await client.close()
 ```
 

docs/PROPOSAL.md

@@ -1,7 +1,7 @@
 # Proposal: fmd_api v2 — Device-centric async interface
 
-Status: Draft  
-Author: devinslick (proposal by Copilot Space)  
+Status: Draft
+Author: devinslick (proposal by Copilot Space)
 Date: 2025-11-01
 
 ## Goals
@@ -286,4 +286,4 @@ This proposal updates the earlier draft to:
 - Include explicit methods for taking front and rear photos.
 - Drop an in-code legacy compatibility layer and instead provide a small migration README.
 
-If you approve, I will create a branch and a PR that implements the core FmdClient and Device class with the initial methods (authenticate, get_devices, get_device, Device.refresh, Device.get_location, Device.play_sound, Device.take_front_photo, Device.take_rear_photo), plus tests and example usage.
+If you approve, I will create a branch and a PR that implements the core FmdClient and Device class with the initial methods (authenticate, get_devices, get_device, Device.refresh, Device.get_location, Device.play_sound, Device.take_front_photo, Device.take_rear_photo), plus tests and example usage.

docs/PROPOSED_BRANCH_AND_STRUCTURE.md

@@ -42,4 +42,4 @@ Next steps after branch creation:
 5. Iterate on rate-limiter/cache and add streaming helpers for export_data_zip.
 
 If you'd like, I can now generate the initial skeleton files for this branch (client.py, device.py, types.py, exceptions.py, helpers.py, docs/MIGRATE_FROM_V1.md, examples/async_example.py, PROPOSAL.md). Which files would you like me to create first?
-```
+```

fmd_api/client.py

@@ -317,13 +317,9 @@ async def _make_api_request(
                         continue
 
                     # Transient server errors -> retry (except for unsafe command POSTs)
-                    if resp.status in (500, 502, 503, 504) and not (
-                        is_command and method.upper() == "POST"
-                    ):
+                    if resp.status in (500, 502, 503, 504) and not (is_command and method.upper() == "POST"):
                         if attempts_left > 0:
-                            delay = _compute_backoff(
-                                self.backoff_base, backoff_attempt, self.backoff_max, self.jitter
-                            )
+                            delay = _compute_backoff(self.backoff_base, backoff_attempt, self.backoff_max, self.jitter)
                             log.warning(
                                 f"Server error {resp.status}. "
                                 f"Retrying in {delay:.2f}s ({attempts_left} retries left)..."
@@ -350,11 +346,7 @@ async def _make_api_request(
                                 # Sanitize: don't log full JSON which may contain tokens/sensitive data
                                 if log.isEnabledFor(logging.DEBUG):
                                     # Log safe metadata only
-                                    keys = (
-                                        list(json_data.keys())
-                                        if isinstance(json_data, dict)
-                                        else "non-dict"
-                                    )
+                                    keys = list(json_data.keys()) if isinstance(json_data, dict) else "non-dict"
                                     log.debug(f"{endpoint} JSON response received with keys: {keys}")
                                 return json_data["Data"]
                             except (KeyError, ValueError, json.JSONDecodeError) as e:

pyproject.toml

@@ -45,6 +45,7 @@ dev = [
     "black",
     "flake8",
     "mypy",
+    "pre-commit",
 ]
 
 # --- IMPORTANT CHANGE ---
@@ -77,4 +78,4 @@ exclude_lines = [
     "raise NotImplementedError",
     "if __name__ == .__main__.:",
     "if TYPE_CHECKING:",
-]
+]