Use picture and get consistently in methods

Author: devinslick

README.md

@@ -120,9 +120,9 @@ Tips:
 - `Device` helper (per‑device convenience)
   - `await device.refresh()` → hydrate cached state
   - `await device.get_location()` → parsed last location
-  - `await device.fetch_pictures(n)` + `await device.download_photo(item)`
-  - Commands: `await device.play_sound()`, `await device.take_front_photo()`,
-    `await device.take_rear_photo()`, `await device.lock(message=None)`,
+  - `await device.get_pictures(n)` + `await device.get_picture(item)`
+  - 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)`
 
 ### Example: Lock device with a message

docs/MIGRATE_FROM_V1.md

@@ -73,8 +73,8 @@ client = await FmdClient.create("https://fmd.example.com", "alice", "secret")
 
 | V1 | V2 (FmdClient) | V2 (Device) | Notes |
 |----|----------------|-------------|-------|
-| `await api.take_picture('back')` | `await client.take_picture('back')` | `await device.take_rear_photo()` | Device method preferred |
-| `await api.take_picture('front')` | `await client.take_picture('front')` | `await device.take_front_photo()` | Device method preferred |
+| `await api.take_picture('back')` | `await client.take_picture('back')` | `await device.take_rear_picture()` | Device method preferred (old: take_rear_photo deprecated) |
+| `await api.take_picture('front')` | `await client.take_picture('front')` | `await device.take_front_picture()` | Device method preferred (old: take_front_photo deprecated) |
 > Note: `Device.lock(message=None)` now supports passing an optional message string. The server may ignore the
 > message if UI or server versions don't yet consume it, but the base lock command will still be executed.
 
@@ -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.fetch_pictures(10)` | Both available |
-| N/A | N/A | `await device.download_photo(blob)` | New helper method |
+| `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) |
 
 ### 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.fetch_pictures(10)
-photo_result = await device.download_photo(pictures[0])
+pictures = await device.get_pictures(10)
+photo_result = await device.get_picture(pictures[0])
 ```
 
 ---

docs/PROPOSAL.md

@@ -18,7 +18,7 @@ Date: 2025-11-01
 
 Top-level components:
 - FmdClient: an async client that manages session, authentication tokens, request throttling, and device discovery.
-- Device: represents a single device and exposes async methods to interact with it (async refresh(), async play_sound(), async get_location(), async take_front_photo(), async take_rear_photo(), async lock_device(), async wipe_device(), etc).
+- Device: represents a single device and exposes async methods to interact with it (async refresh(), async play_sound(), async get_location(), async take_front_picture(), async take_rear_picture(), async lock_device(), async wipe_device(), etc).
 - Exceptions: typed exceptions for common error cases (AuthenticationError, DeviceNotFoundError, FmdApiError, RateLimitError).
 - Utilities: small helpers for caching, TTL-based per-device caches, retry/backoff, JSON parsing.
 
@@ -52,8 +52,8 @@ async def example():
     await device.play_sound()
 
     # Take front and rear photos
-    front = await device.take_front_photo()
-    rear = await device.take_rear_photo()
+  front = await device.take_front_picture()
+  rear = await device.take_rear_picture()
 
     # Lock device with message
     await device.lock_device(message="Lost phone — call me")
@@ -95,9 +95,9 @@ Core classes and signatures (proposal):
     - async get_location(self, *, force: bool = False) -> Optional[Location]
       - Returns last known location (calls refresh if expired or force=True)
     - async play_sound(self, *, volume: Optional[int] = None) -> None
-    - async take_front_photo(self) -> Optional[bytes]
+  - async take_front_picture(self) -> Optional[bytes]
       - Requests a front-facing photo; returns raw bytes of image if available.
-    - async take_rear_photo(self) -> Optional[bytes]
+  - async take_rear_picture(self) -> Optional[bytes]
       - Requests a rear-facing photo; returns raw bytes of image if available.
     - async lock_device(self, *, passcode: Optional[str] = None, message: Optional[str] = None) -> None
     - async wipe_device(self, *, confirm: bool = False) -> None
@@ -130,7 +130,7 @@ Core classes and signatures (proposal):
 - All request payloads, parsing, and business rules will reuse the logic currently implemented in the repository (parsing of responses, mapping fields to device properties, handling of play sound semantics, etc.). No functional changes to endpoints or command behavior are intended.
 - Where current code uses synchronous HTTP (requests), the new client will use asyncio/aiohttp to make non-blocking calls. Helpers will be introduced to convert existing request/response handling functions to async easily.
 - Device.refresh() mirrors current "get devices" and "refresh device" flows: fetch the device status endpoint, parse location, battery, and update fields.
-- Photo functions: take_front_photo() and take_rear_photo() call the corresponding FMD endpoints (if supported). They should return either a PhotoResult object (preferred) or None if not supported by the device/account. Implementations should include sensible timeouts and handle partial results gracefully.
+- Photo functions: take_front_picture() and take_rear_picture() call the corresponding FMD endpoints (if supported). They should return either a PhotoResult object (preferred) or None if not supported by the device/account. Implementations should include sensible timeouts and handle partial results gracefully.
 - Caching: to avoid hitting rate limits and reduce backend load, a per-device TTL cache will be implemented (configurable; default 30 seconds). get_location() uses cached data unless force=True or stale.
 - Rate limiting: a shared RateLimiter object will enforce a maximum requests-per-second or requests-per-minute per client instance. Simple token-bucket or asyncio.Semaphore + sleep-backoff will be sufficient.
 - Retries: transient HTTP errors will be retried with an exponential backoff (configurable; default 3 retries).

fmd_api/device.py

@@ -8,6 +8,7 @@
 
 import json
 from datetime import datetime, timezone
+import warnings
 from typing import Optional, AsyncIterator, List, Dict, Any
 
 from .models import Location, PhotoResult
@@ -75,13 +76,28 @@ async def play_sound(self) -> bool:
         return await self.client.send_command("ring")
 
     async def take_front_photo(self) -> bool:
-        return await self.client.take_picture("front")
+        warnings.warn(
+            "Device.take_front_photo() is deprecated; use take_front_picture()",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return await self.take_front_picture()
 
     async def take_rear_photo(self) -> bool:
-        return await self.client.take_picture("back")
+        warnings.warn(
+            "Device.take_rear_photo() is deprecated; use take_rear_picture()",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return await self.take_rear_picture()
 
     async def fetch_pictures(self, num_to_get: int = -1) -> List[dict]:
-        return await self.client.get_pictures(num_to_get=num_to_get)
+        warnings.warn(
+            "Device.fetch_pictures() is deprecated; use get_pictures()",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return await self.get_pictures(num_to_get=num_to_get)
 
     async def download_photo(self, picture_blob_b64: str) -> PhotoResult:
         """
@@ -90,6 +106,29 @@ async def download_photo(self, picture_blob_b64: str) -> PhotoResult:
         The fmd README says picture data is double-encoded: encrypted blob -> base64 string -> image bytes.
         We decrypt the blob to get a base64-encoded image string; decode that to bytes and return.
         """
+        warnings.warn(
+            "Device.download_photo() is deprecated; use get_picture()",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return await self.get_picture(picture_blob_b64)
+
+    async def take_front_picture(self) -> bool:
+        """Request a picture from the front camera."""
+        return await self.client.take_picture("front")
+
+    async def take_rear_picture(self) -> bool:
+        """Request a picture from the rear camera."""
+        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.
+
+        Returns the raw list from the server (typically base64-encoded encrypted blobs)."""
+        return await self.client.get_pictures(num_to_get=num_to_get)
+
+    async def get_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)
         try:

tests/functional/test_device.py

@@ -1,5 +1,5 @@
 """
-Test: Device class flows (refresh, get_location, fetch_pictures, download_photo)
+Test: Device class flows (refresh, get_location, get_pictures, get_picture)
 Usage:
   python tests/functional/test_device.py
 """
@@ -32,17 +32,17 @@ async def main():
         loc = await device.get_location()
         print("Cached location:", loc)
         # fetch pictures and attempt to download the first one
-        pics = await device.fetch_pictures(5)
+        pics = await device.get_pictures(5)
         print("Pictures listed:", len(pics))
         if pics:
             try:
-                photo = await device.download_photo(pics[0])
+                photo = await device.get_picture(pics[0])
                 fn = "device_photo.jpg"
                 with open(fn, "wb") as f:
                     f.write(photo.data)
                 print("Saved device photo to", fn)
             except Exception as e:
-                print("Failed to download photo:", e)
+                print("Failed to get picture:", e)
     finally:
         await client.close()
 

tests/unit/test_device.py

@@ -46,7 +46,7 @@ def decrypt(self, packet, padding_obj):
 
 
 @pytest.mark.asyncio
-async def test_device_fetch_and_download_picture(monkeypatch):
+async def test_device_get_and_decode_picture(monkeypatch):
     client = FmdClient("https://fmd.example.com")
     # Provide dummy private key that decrypts session packet into all-zero key
 
@@ -75,10 +75,10 @@ def decrypt(self, packet, padding_obj):
         client.access_token = "token"
         device = Device(client, "alice")
         try:
-            pics = await device.fetch_pictures()
+            pics = await device.get_pictures()
             assert len(pics) == 1
             # download the picture and verify we got PNGDATA bytes
-            photo = await device.download_photo(pics[0])
+            photo = await device.get_picture(pics[0])
             assert photo.data == b"PNGDATA"
             assert photo.mime_type.startswith("image/")
         finally:
@@ -344,7 +344,7 @@ def decrypt(self, packet, padding_obj):
 
 @pytest.mark.asyncio
 async def test_device_picture_commands():
-    """Test Device picture-related command shortcuts."""
+    """Test Device picture-related command shortcuts (new names)."""
     client = FmdClient("https://fmd.example.com")
     client.access_token = "token"
 
@@ -358,16 +358,16 @@ def sign(self, message_bytes, pad, algo):
     device = Device(client, "test-device")
 
     with aioresponses() as m:
-        # take_front_photo
+        # take_front_picture
         m.post("https://fmd.example.com/api/v1/command", status=200, body="OK")
-        # take_rear_photo
+        # take_rear_picture
         m.post("https://fmd.example.com/api/v1/command", status=200, body="OK")
 
         try:
-            result1 = await device.take_front_photo()
+            result1 = await device.take_front_picture()
             assert result1 is True
 
-            result2 = await device.take_rear_photo()
+            result2 = await device.take_rear_picture()
             assert result2 is True
         finally:
             await client.close()
@@ -626,8 +626,8 @@ def decrypt(self, packet, padding_obj):
 
 
 @pytest.mark.asyncio
-async def test_device_fetch_pictures():
-    """Test Device.fetch_pictures method."""
+async def test_device_get_pictures():
+    """Test Device.get_pictures method."""
     client = FmdClient("https://fmd.example.com")
     client.access_token = "token"
 
@@ -639,7 +639,7 @@ async def test_device_fetch_pictures():
         m.put("https://fmd.example.com/api/v1/pictures", payload={"Data": mock_pictures})
 
         try:
-            pictures = await device.fetch_pictures(num_to_get=1)
+            pictures = await device.get_pictures(num_to_get=1)
             assert len(pictures) == 1
             assert pictures[0]["id"] == 0
         finally: