Rename methods get_picture/get_pictures/fetch_pictures/download_photo for clarity

Author: devinslick

README.md

@@ -120,7 +120,7 @@ Tips:
 - `Device` helper (per‑device convenience)
   - `await device.refresh()` → hydrate cached state
   - `await device.get_location()` → parsed last location
-  - `await device.get_pictures(n)` + `await device.get_picture(item)`
+  - `await device.get_picture_blobs(n)` + `await device.decode_picture(blob)`
   - Commands: `await device.play_sound()`, `await device.take_front_picture()`,
     `await device.take_rear_picture()`, `await device.lock(message=None)`,
     `await device.wipe(confirm=True)`

docs/MIGRATE_FROM_V1.md

@@ -92,8 +92,8 @@ client = await FmdClient.create("https://fmd.example.com", "alice", "secret")
 
 | V1 | V2 (FmdClient) | V2 (Device) | Notes |
 |----|----------------|-------------|-------|
-| `await api.get_pictures(10)` | `await client.get_pictures(10)` | `await device.get_pictures(10)` | Both available (old: fetch_pictures deprecated) |
-| N/A | N/A | `await device.get_picture(blob)` | Helper method (old: download_photo deprecated) |
+| `await api.get_pictures(10)` | `await client.get_pictures(10)` | `await device.get_picture_blobs(10)` | Both available (old: get_pictures/fetch_pictures deprecated) |
+| N/A | N/A | `await device.decode_picture(blob)` | Helper method (old: get_picture/download_photo deprecated) |
 
 ### Export Data
 
@@ -153,8 +153,8 @@ await device.lock(message="Lost device")     # Lock with message
 await device.wipe(confirm=True)              # Factory reset (DESTRUCTIVE)
 
 # Pictures
-pictures = await device.get_pictures(10)
-photo_result = await device.get_picture(pictures[0])
+pictures = await device.get_picture_blobs(10)
+photo_result = await device.decode_picture(pictures[0])
 ```
 
 ---

fmd_api/device.py

@@ -93,11 +93,11 @@ async def take_rear_photo(self) -> bool:
 
     async def fetch_pictures(self, num_to_get: int = -1) -> List[dict]:
         warnings.warn(
-            "Device.fetch_pictures() is deprecated; use get_pictures()",
+            "Device.fetch_pictures() is deprecated; use get_picture_blobs()",
             DeprecationWarning,
             stacklevel=2,
         )
-        return await self.get_pictures(num_to_get=num_to_get)
+        return await self.get_picture_blobs(num_to_get=num_to_get)
 
     async def download_photo(self, picture_blob_b64: str) -> PhotoResult:
         """
@@ -122,12 +122,28 @@ async def take_rear_picture(self) -> bool:
         return await self.client.take_picture("back")
 
     async def get_pictures(self, num_to_get: int = -1) -> List[dict]:
-        """Get picture blobs (metadata) from the server.
+        """Deprecated: use get_picture_blobs()."""
+        warnings.warn(
+            "Device.get_pictures() is deprecated; use get_picture_blobs()",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return await self.get_picture_blobs(num_to_get=num_to_get)
 
-        Returns the raw list from the server (typically base64-encoded encrypted blobs)."""
+    async def get_picture(self, picture_blob_b64: str) -> PhotoResult:
+        """Deprecated: use decode_picture()."""
+        warnings.warn(
+            "Device.get_picture() is deprecated; use decode_picture()",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return await self.decode_picture(picture_blob_b64)
+
+    async def get_picture_blobs(self, num_to_get: int = -1) -> List[dict]:
+        """Get raw picture blobs (base64-encoded encrypted strings) from the server."""
         return await self.client.get_pictures(num_to_get=num_to_get)
 
-    async def get_picture(self, picture_blob_b64: str) -> PhotoResult:
+    async def decode_picture(self, picture_blob_b64: str) -> PhotoResult:
         """Decrypt and decode a single picture blob into a PhotoResult."""
         decrypted = self.client.decrypt_data_blob(picture_blob_b64)
         # decrypted is bytes, often containing a base64-encoded image (as text)

tests/functional/test_device.py

@@ -32,11 +32,11 @@ async def main():
         loc = await device.get_location()
         print("Cached location:", loc)
         # fetch pictures and attempt to download the first one
-        pics = await device.get_pictures(5)
+        pics = await device.get_picture_blobs(5)
         print("Pictures listed:", len(pics))
         if pics:
             try:
-                photo = await device.get_picture(pics[0])
+                photo = await device.decode_picture(pics[0])
                 fn = "device_photo.jpg"
                 with open(fn, "wb") as f:
                     f.write(photo.data)

tests/unit/test_device.py

@@ -75,10 +75,10 @@ def decrypt(self, packet, padding_obj):
         client.access_token = "token"
         device = Device(client, "alice")
         try:
-            pics = await device.get_pictures()
+            pics = await device.get_picture_blobs()
             assert len(pics) == 1
             # download the picture and verify we got PNGDATA bytes
-            photo = await device.get_picture(pics[0])
+            photo = await device.decode_picture(pics[0])
             assert photo.data == b"PNGDATA"
             assert photo.mime_type.startswith("image/")
         finally:
@@ -626,8 +626,8 @@ def decrypt(self, packet, padding_obj):
 
 
 @pytest.mark.asyncio
-async def test_device_get_pictures():
-    """Test Device.get_pictures method."""
+async def test_device_get_picture_blobs():
+    """Test Device.get_picture_blobs method."""
     client = FmdClient("https://fmd.example.com")
     client.access_token = "token"
 
@@ -639,7 +639,7 @@ async def test_device_get_pictures():
         m.put("https://fmd.example.com/api/v1/pictures", payload={"Data": mock_pictures})
 
         try:
-            pictures = await device.get_pictures(num_to_get=1)
+            pictures = await device.get_picture_blobs(num_to_get=1)
             assert len(pictures) == 1
             assert pictures[0]["id"] == 0
         finally: