feat: enhance file module with improved documentation and tests

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,28 @@ 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)
+
+    # Only validate types if fields are present (omitempty)
+    if 'changes' in response and not isinstance(response['changes'], int):
+        return {"err": "Malformed response: changes must be an integer"}
+    if 'total' in response and not isinstance(response['total'], int):
+        return {"err": "Malformed response: total must be an integer"}
+    if 'info' in response and not isinstance(response['info'], dict):
+        return {"err": "Malformed response: info must be a dictionary"}
+
+    return response
 
 
 @validate_card_object
@@ -42,27 +55,45 @@ 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"}
+    if file:
+        req["file"] = file
 
-    return card.Transaction(req)
+    response = card.Transaction(req)
+
+    # Only validate types if fields are present (omitempty)
+    if 'total' in response and not isinstance(response['total'], int):
+        return {"err": "Malformed response: total must be an integer"}
+    if 'changes' in response and not isinstance(response['changes'], int):
+        return {"err": "Malformed response: changes must be an integer"}
+    if 'sync' in response and not isinstance(response['sync'], bool):
+        return {"err": "Malformed response: sync must be a boolean"}
+
+    return response
 
 
 @validate_card_object
@@ -73,8 +104,16 @@ 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"}
+    response = card.Transaction(req)
+
+    # Only validate types if fields are present (omitempty)
+    if 'total' in response and not isinstance(response['total'], int):
+        return {"err": "Malformed response: total must be an integer"}
+    if 'changes' in response and not isinstance(response['changes'], int):
+        return {"err": "Malformed response: changes must be an integer"}
 
-    return card.Transaction(req)
+    return response

notecard/note.py

@@ -9,19 +9,20 @@
 # 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.
+        body (dict): A JSON object containing the note data.
         payload (string): An optional base64-encoded string.
+        binary (bool): When True, indicates that the note's payload field
+            contains binary data that should be base64-encoded.
         sync (bool): Perform an immediate sync after adding.
         port (int): If provided, a unique number to represent a notefile.
             Required for Notecard LoRa.
@@ -40,12 +41,23 @@ 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:
+        req["binary"] = binary
+
     return card.Transaction(req)
 
 
 @validate_card_object
-def changes(card, file=None, tracker=None, maximum=None,
-            start=None, stop=None, deleted=None, delete=None):
+def changes(
+    card,
+    file=None,
+    tracker=None,
+    maximum=None,
+    start=None,
+    stop=None,
+    deleted=None,
+    delete=None,
+):
     """Incrementally retrieve changes within a Notefile.
 
     Args:
@@ -93,7 +105,8 @@ 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 binary data is present,
+        the 'binary' field contains the decoded data.
     """
     req = {"req": "note.get"}
     req["file"] = file
@@ -103,6 +116,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 +168,63 @@ 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,
+    *,  # Force keyword arguments for clarity
+    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.
+        body (dict): A sample JSON body that specifies field names and
+            values as type hints. Supported: bool, int, float, str.
         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 "compact", omits additional metadata to save
+            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:
         req["body"] = body
-    if length:
+
+    if length is not None:
         req["length"] = length
-    if port:
+
+    if port is not None:
         req["port"] = port
-    if compact:
+
+    if compact is True:
+        format = "compact"
+
+    if format == "compact":
         req["format"] = "compact"
+
+    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',

test/fluent_api/test_file_changes.py

@@ -0,0 +1,92 @@
+"""Tests for file.changes functionality."""
+from notecard import file
+
+
+def test_file_changes_basic(run_fluent_api_notecard_api_mapping_test):
+    """Test file.changes with no parameters."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.changes, 'file.changes', {})
+
+
+def test_file_changes_with_tracker(run_fluent_api_notecard_api_mapping_test):
+    """Test file.changes with tracker parameter."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.changes, 'file.changes', {'tracker': 'my_tracker'})
+
+
+def test_file_changes_with_files(run_fluent_api_notecard_api_mapping_test):
+    """Test file.changes with files parameter."""
+    run_fluent_api_notecard_api_mapping_test(
+        file.changes, 'file.changes', {'files': ['file1.qo', 'file2.qo']})
+
+
+def test_file_changes_with_all_params(
+        run_fluent_api_notecard_api_mapping_test):
+    """Test file.changes with all parameters."""
+    params = {'tracker': 'my_tracker', 'files': ['file1.qo', 'file2.qo']}
+    run_fluent_api_notecard_api_mapping_test(
+        file.changes, 'file.changes', params)
+
+
+def test_file_changes_response(card):
+    """Test file.changes response structure."""
+    card.Transaction.return_value = {
+        'changes': 5,
+        'total': 42,
+        'info': {
+            'file1.qo': {'changes': 2, 'total': 20},
+            'file2.qo': {'changes': 3, 'total': 22}
+        }
+    }
+    response = file.changes(card)
+    assert isinstance(response, dict)
+    if 'changes' in response:
+        assert isinstance(response['changes'], int)
+    if 'total' in response:
+        assert isinstance(response['total'], int)
+    if 'info' in response:
+        assert isinstance(response['info'], dict)
+        for filename, file_info in response['info'].items():
+            assert isinstance(file_info, dict)
+            if 'changes' in file_info:
+                assert isinstance(file_info['changes'], int)
+            if 'total' in file_info:
+                assert isinstance(file_info['total'], int)
+
+
+def test_file_changes_with_invalid_tracker(card):
+    """Test file.changes with invalid tracker format."""
+    card.Transaction.return_value = {"err": "Invalid tracker format"}
+    response = file.changes(card, tracker="@@@!!!")
+    assert "err" in response
+    assert "Invalid tracker format" in response["err"]
+
+
+def test_file_changes_with_malformed_response(card):
+    """Test handling of malformed response data."""
+    card.Transaction.return_value = {
+        "changes": "not-an-integer",
+        "total": None,
+        "info": "should-be-object"
+    }
+    response = file.changes(card)
+    assert "err" in response
+    assert "malformed response" in response["err"].lower()
+
+
+def test_file_changes_with_missing_info(card):
+    """Test handling of response with optional fields omitted."""
+    card.Transaction.return_value = {"changes": 5}  # Missing total and info
+    response = file.changes(card)
+    assert isinstance(response, dict)
+    if 'changes' in response:
+        assert isinstance(response['changes'], int)
+    # No error expected for missing optional fields
+
+
+def test_file_changes_with_nonexistent_files(card):
+    """Test file.changes with non-existent files."""
+    card.Transaction.return_value = {"err": "File not found"}
+    response = file.changes(card, files=["nonexistent.qo"])
+    assert "err" in response
+    assert "File not found" in response["err"]