feat: enhance file module with improved documentation and tests

docs/api.md

@@ -403,6 +403,22 @@ string The result of the Notecard request.
 
 ## Members
 
+#### `public def `[`add`](#namespacenotecard_1_1note_1a660dda3f8fa6f9afff52e0a3be6bef84)`(card,file,body,payload,binary,sync,port)` 
+
+Add a Note to a Notefile with optional binary data support.
+
+#### Parameters
+* `card` The current Notecard object.
+* `file` The name of the file.
+* `body` A JSON object to add to the note.
+* `payload` An optional base64-encoded string.
+* `binary` When true, indicates the note contains binary data.
+* `sync` Perform an immediate sync after adding.
+* `port` If provided, a unique number to represent a notefile. Required for Notecard LoRa.
+
+#### Returns
+dict The result of the Notecard request. If binary data is included, returns error object with 'err' field on validation failure.
+
 #### `public def `[`changes`](#namespacenotecard_1_1note_1a660dda3f8fa6f9afff52e0a3be6bef84)`(card,file,tracker,maximum,start,stop,deleted,`[`delete`](#namespacenotecard_1_1note_1a591ece0048b58f38acf22d97a533577f)`)` 
 
 Incrementally retrieve changes within a Notefile.
@@ -431,7 +447,7 @@ string The result of the Notecard request.
 
 #### `public def `[`get`](#namespacenotecard_1_1note_1ad7a4c296382c14a8efb54278c127d73b)`(card,file,note_id,`[`delete`](#namespacenotecard_1_1note_1a591ece0048b58f38acf22d97a533577f)`,deleted)` 
 
-Retrieve a note from an inbound or DB Notefile.
+Retrieve a note from an inbound or DB Notefile with binary data support.
 
 #### Parameters
 * `card` The current Notecard object. 
@@ -445,9 +461,7 @@ Retrieve a note from an inbound or DB Notefile.
 * `deleted` Whether to allow retrieval of a deleted note.
 
 #### Returns
-
-#### Returns
-string The result of the Notecard request.
+dict The result of the Notecard request. If the note contains binary data, the 'binary' field in the response will contain the binary data as a bytearray. Returns error object with 'err' field on binary data retrieval failure.
 
 #### `public def `[`delete`](#namespacenotecard_1_1note_1a591ece0048b58f38acf22d97a533577f)`(card,file,note_id)` 
 
@@ -485,7 +499,7 @@ Update a note in a DB Notefile by ID.
 #### Returns
 string The result of the Notecard request.
 
-#### `public def `[`template`](#namespacenotecard_1_1note_1a1e625660366b3766ec9efa8270a7f5bb)`(card,file,body,length)` 
+#### `public def `[`template`](#namespacenotecard_1_1note_1a1e625660366b3766ec9efa8270a7f5bb)`(card,file,body,length,port,format)` 
 
 Create a template for new Notes in a Notefile.
 
@@ -494,14 +508,20 @@ Create a template for new Notes in a Notefile.
 
 * `file` The file name of the notefile. 
 
-* `body` A sample JSON body that specifies field names and values as "hints" for the data type. 
+* `body` A sample JSON body that specifies field names and values as "hints" for the data type. Supported types are boolean, integer, float, and string. Float values that represent whole numbers are automatically converted to integers.
+
+* `length` If provided, the maximum length of a payload (in bytes) that can be sent in Notes for the template Notefile. When specified, enables binary record mode for optimized storage.
 
-* `length` If provided, the maximum length of a payload that can be sent in Notes for the template Notefile.
+* `port` If provided, a unique number between 1 and 100 to represent a notefile. Required for Notecard LoRa.
+
+* `format` If set to "compact", tells the Notecard to omit additional metadata to save storage and bandwidth. In compact mode, only standard metadata fields (_time, _lat, _lon, _loc) are allowed.
+
+* `compact` Legacy parameter. If True, equivalent to setting format="compact". Retained for backward compatibility. New code should use format="compact" instead.
 
 #### Returns
 
 #### Returns
-string The result of the Notecard request.
+dict The result of the Notecard request. Returns error object with an "err" field containing a descriptive message on validation failure.
 
 # namespace `notecard::notecard` 
 
@@ -659,4 +679,4 @@ Initialize the [Notecard](#classnotecard_1_1notecard_1_1_notecard) before a rese
 
 Ensure that the passed-in card is a Notecard.
 
-Generated by [Moxygen](https://sourcey.com/moxygen)
+Generated by [Moxygen](https://sourcey.com/moxygen)

notecard/file.py

@@ -9,7 +9,6 @@
 # This module contains helper methods for calling file.* Notecard API commands.
 # This module is optional and not required for use with the Notecard.
 
-import notecard
 from notecard.validators import validate_card_object
 
 
@@ -23,14 +22,31 @@ def changes(card, tracker=None, files=None):
         files (array): A list of Notefiles to retrieve changes for.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request containing:
+            - changes (int): Notes with pending changes
+            - total (int): Total Notes
+            - info (dict): Per-file details
     """
     req = {"req": "file.changes"}
     if tracker:
         req["tracker"] = tracker
-    if files:
+    if files is not None:  # Allow empty list
         req["files"] = files
-    return card.Transaction(req)
+
+    response = card.Transaction(req)
+    if "err" in response:
+        return response
+    # Check for required fields first
+    if not all(key in response for key in ['total', 'changes', 'info']):
+        return {"err": "Missing required fields in response"}
+    # Then validate field types
+    if not isinstance(response['total'], int):
+        return {"err": "Malformed response: total must be an integer"}
+    if not isinstance(response['changes'], int):
+        return {"err": "Malformed response: changes must be an integer"}
+    if not isinstance(response['info'], dict):
+        return {"err": "Malformed response: info must be a dictionary"}
+    return response
 
 
 @validate_card_object
@@ -42,27 +58,47 @@ def delete(card, files=None):
         files (array): A list of Notefiles to delete.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request. An empty object {} indicates
+            success.
     """
     req = {"req": "file.delete"}
     if files:
         req["files"] = files
-    return card.Transaction(req)
+    response = card.Transaction(req)
+    return response
 
 
 @validate_card_object
-def stats(card):
-    """Obtain statistics about local notefiles.
+def stats(card, file=None):
+    """Get resource statistics about local Notefiles.
 
     Args:
         card (Notecard): The current Notecard object.
+        file (string, optional): Return stats for the specified Notefile only.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request containing:
+            - total (int): Total Notes across all Notefiles
+            - changes (int): Notes pending sync
+            - sync (bool): True if sync is recommended
     """
     req = {"req": "file.stats"}
-
-    return card.Transaction(req)
+    if file:
+        req["file"] = file
+    response = card.Transaction(req)
+    if "err" in response:
+        return response
+    # Check for required fields
+    if not all(key in response for key in ['total', 'changes', 'sync']):
+        return {"err": "Missing required fields in response"}
+    # Validate field types
+    if not isinstance(response['total'], int):
+        return {"err": "Malformed response: total must be an integer"}
+    if not isinstance(response['changes'], int):
+        return {"err": "Malformed response: changes must be an integer"}
+    if not isinstance(response['sync'], bool):
+        return {"err": "Malformed response: sync must be a boolean"}
+    return response
 
 
 @validate_card_object
@@ -73,8 +109,19 @@ def pendingChanges(card):
         card (Notecard): The current Notecard object.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request containing pending changes
+            information.
     """
     req = {"req": "file.changes.pending"}
-
-    return card.Transaction(req)
+    response = card.Transaction(req)
+    if "err" in response:
+        return response
+    # Validate response format - should contain total and changes
+    if not all(key in response for key in ['total', 'changes']):
+        return {"err": "Missing required fields in response"}
+    # Validate field types
+    if not isinstance(response.get('total'), int):
+        return {"err": "Malformed response: total must be an integer"}
+    if not isinstance(response.get('changes'), int):
+        return {"err": "Malformed response: changes must be an integer"}
+    return response

notecard/note.py

@@ -9,26 +9,28 @@
 # This module contains helper methods for calling note.* Notecard API commands.
 # This module is optional and not required for use with the Notecard.
 
-import notecard
 from notecard.validators import validate_card_object
 
 
 @validate_card_object
-def add(card, file=None, body=None, payload=None, sync=None, port=None):
+def add(card, file=None, body=None, payload=None, binary=None, sync=None, port=None):
     """Add a Note to a Notefile.
 
     Args:
         card (Notecard): The current Notecard object.
         file (string): The name of the file.
         body (JSON object): A developer-defined tracker ID.
         payload (string): An optional base64-encoded string.
+        binary (bool): When true, indicates the note contains binary data.
         sync (bool): Perform an immediate sync after adding.
         port (int): If provided, a unique number to represent a notefile.
             Required for Notecard LoRa.
 
     Returns:
         string: The result of the Notecard request.
     """
+    from notecard import binary_helpers
+
     req = {"req": "note.add"}
     if file:
         req["file"] = file
@@ -40,6 +42,12 @@ def add(card, file=None, body=None, payload=None, sync=None, port=None):
         req["port"] = port
     if sync is not None:
         req["sync"] = sync
+
+    if binary is not None:
+        if not isinstance(binary, bool):
+            return {"err": "binary parameter must be a boolean"}
+        req["binary"] = binary
+
     return card.Transaction(req)
 
 
@@ -93,8 +101,11 @@ def get(card, file="data.qi", note_id=None, delete=None, deleted=None):
         deleted (bool): Whether to allow retrieval of a deleted note.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request. If the note contains binary data,
+        the 'binary' field in the response will contain the binary data as a bytearray.
     """
+    from notecard import binary_helpers
+
     req = {"req": "note.get"}
     req["file"] = file
     if note_id:
@@ -103,6 +114,7 @@ def get(card, file="data.qi", note_id=None, delete=None, deleted=None):
         req["delete"] = delete
     if deleted is not None:
         req["deleted"] = deleted
+
     return card.Transaction(req)
 
 
@@ -154,34 +166,80 @@ def update(card, file=None, note_id=None, body=None, payload=None):
 
 
 @validate_card_object
-def template(card, file=None, body=None, length=None, port=None, compact=False):
+def template(card, file=None, body=None, length=None, port=None,
+             format=None, compact=None, verify=None, delete=None):
     """Create a template for new Notes in a Notefile.
 
     Args:
         card (Notecard): The current Notecard object.
         file (string): The file name of the notefile.
         body (JSON): A sample JSON body that specifies field names and
-            values as "hints" for the data type.
+            values as "hints" for the data type. Supported types are:
+            boolean, integer, float, and string.
         length (int): If provided, the maximum length of a payload that
             can be sent in Notes for the template Notefile.
         port (int): If provided, a unique number to represent a notefile.
             Required for Notecard LoRa.
-        compact (boolean): If true, sets the format to compact to tell the
-            Notecard to omit this additional metadata to save on storage
-            and bandwidth. Required for Notecard LoRa.
+        format (string): If set to "compact", tells the Notecard to omit
+            additional metadata to save on storage and bandwidth.
+        compact (bool): Legacy parameter. If True, equivalent to setting
+            format="compact". Retained for backward compatibility.
+        verify (bool): When True, verifies the template against existing
+            notes in the Notefile.
+        delete (bool): When True, deletes the template from the Notefile.
 
     Returns:
-        string: The result of the Notecard request.
+        dict: The result of the Notecard request. Returns error object if
+        validation fails.
     """
     req = {"req": "note.template"}
     if file:
         req["file"] = file
+
     if body:
+        for key, value in body.items():
+            if not isinstance(value, (bool, int, float, str)):
+                return {
+                    "err": (
+                        f"Field '{key}' has unsupported type. "
+                        "Must be boolean, integer, float, or string.")
+                }
+            if isinstance(value, float) and value.is_integer():
+                body[key] = int(value)
         req["body"] = body
-    if length:
+
+    if verify is not None:
+        if not isinstance(verify, bool):
+            return {"err": "verify parameter must be a boolean"}
+
+    if length is not None:
+        if not isinstance(length, int) or length < 0:
+            return {"err": "Length must be a non-negative integer"}
         req["length"] = length
-    if port:
+
+    if port is not None:
+        if not isinstance(port, int) or not (1 <= port <= 100):
+            return {"err": "Port must be an integer between 1 and 100"}
         req["port"] = port
-    if compact:
+
+    if compact is True:
+        format = "compact"
+
+    if format == "compact":
         req["format"] = "compact"
+        if body:
+            allowed_metadata = {"_time", "_lat", "_lon", "_loc"}
+            for key in body.keys():
+                if key.startswith("_") and key not in allowed_metadata:
+                    return {
+                        "err": (
+                            f"Field '{key}' is not allowed in compact mode. "
+                            f"Only {allowed_metadata} are allowed.")
+                    }
+
+    if verify is not None:
+        req["verify"] = verify
+    if delete is not None:
+        req["delete"] = delete
+
     return card.Transaction(req)

test/fluent_api/conftest.py

@@ -9,6 +9,14 @@
 import notecard  # noqa: E402
 
 
+@pytest.fixture
+def card():
+    """Create a mock Notecard instance for testing."""
+    card = notecard.Notecard()
+    card.Transaction = MagicMock()
+    return card
+
+
 @pytest.fixture
 def run_fluent_api_notecard_api_mapping_test():
     def _run_test(fluent_api, notecard_api_name, req_params, rename_map=None):

test/fluent_api/test_file.py

@@ -25,6 +25,11 @@
             'file.stats',
             {}
         ),
+        (
+            file.stats,
+            'file.stats',
+            {'file': 'test.qo'}
+        ),
         (
             file.pendingChanges,
             'file.changes.pending',