feat: add FileContentsQuery (#217)

* feat: add FileContentsQuery

Signed-off-by: dosi <[email protected]>

* feat: add integration tests for FileContentsQuery

Signed-off-by: dosi <[email protected]>

* test: add unit tests for FileContentsQuery

Signed-off-by: dosi <[email protected]>

* docs: add file contents query example

Signed-off-by: dosi <[email protected]>

* docs: add FileContentsQuery to examples README

Signed-off-by: dosi <[email protected]>

* chore: add FileContentsQuery to __init__.py

Signed-off-by: dosi <[email protected]>

---------

Signed-off-by: dosi <[email protected]>

Author: Dosik13

examples/README.md

@@ -49,6 +49,7 @@ You can choose either syntax or even mix both styles in your projects.
 - [File Transactions](#file-transactions)
   - [Creating a File](#creating-a-file)
   - [Querying File Info](#querying-file-info)
+  - [Querying File Contents](#querying-file-contents)
   - [Deleting a File](#deleting-a-file)
 - [Miscellaneous Queries](#miscellaneous-queries)
   - [Querying Transaction Record](#querying-transaction-record)
@@ -963,6 +964,26 @@ print(file_info)
 
 ```
 
+### Querying File Contents
+
+#### Pythonic Syntax:
+```
+file_contents_query = FileContentsQuery(file_id=file_id)
+file_contents = file_contents_query.execute(client)
+print(str(file_contents)) # decode bytes to string
+```
+
+#### Method Chaining:
+```
+file_contents = (
+    FileContentsQuery()
+    .set_file_id(file_id)
+    .execute(client)
+)
+print(str(file_contents)) # decode bytes to string
+
+```
+
 ### Deleting a File
 
 #### Pythonic Syntax:

examples/query_file_contents.py

@@ -0,0 +1,74 @@
+"""
+This example demonstrates how to query file contents using the Python SDK.
+"""
+
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from hiero_sdk_python import AccountId, Client, Network, PrivateKey
+from hiero_sdk_python.file.file_contents_query import FileContentsQuery
+from hiero_sdk_python.file.file_create_transaction import FileCreateTransaction
+from hiero_sdk_python.response_code import ResponseCode
+
+load_dotenv()
+
+
+def setup_client():
+    """Initialize and set up the client with operator account"""
+    network = Network(network="testnet")
+    client = Client(network)
+
+    operator_id = AccountId.from_string(os.getenv("OPERATOR_ID"))
+    operator_key = PrivateKey.from_string(os.getenv("OPERATOR_KEY"))
+    client.set_operator(operator_id, operator_key)
+
+    return client
+
+
+def create_file(client: Client):
+    """Create a test file"""
+    file_private_key = PrivateKey.generate_ed25519()
+
+    receipt = (
+        FileCreateTransaction()
+        .set_keys([file_private_key.public_key(), client.operator_private_key.public_key()])
+        .set_contents(b"Test contents to be queried!")
+        .set_file_memo("Test file for query")
+        .freeze_with(client)
+        .sign(file_private_key)
+        .execute(client)
+    )
+
+    if receipt.status != ResponseCode.SUCCESS:
+        print(f"File creation failed with status: {ResponseCode(receipt.status).name}")
+        sys.exit(1)
+
+    file_id = receipt.file_id
+    print(f"\nFile created with ID: {file_id}")
+
+    return file_id
+
+
+def query_file_contents():
+    """
+    Demonstrates querying file contents by:
+    1. Setting up client with operator account
+    2. Creating a test file
+    3. Querying the file contents
+    """
+    client = setup_client()
+
+    # Create a test file first
+    file_id = create_file(client)
+
+    contents = FileContentsQuery().set_file_id(file_id).execute(client)
+
+    # The contets are returned as bytes and we need to decode them
+    print("\nFile Contents:")
+    print(str(contents))
+
+
+if __name__ == "__main__":
+    query_file_contents()

src/hiero_sdk_python/__init__.py

@@ -83,6 +83,7 @@
 from .file.file_create_transaction import FileCreateTransaction
 from .file.file_info_query import FileInfoQuery
 from .file.file_info import FileInfo
+from .file.file_contents_query import FileContentsQuery
 from .file.file_delete_transaction import FileDeleteTransaction
 
 __all__ = [
@@ -167,5 +168,6 @@
     "FileCreateTransaction",
     "FileInfoQuery",
     "FileInfo",
+    "FileContentsQuery",
     "FileDeleteTransaction",
 ]

src/hiero_sdk_python/file/file_contents_query.py

@@ -0,0 +1,140 @@
+"""
+Query to get the contents of a file on the network.
+"""
+
+from typing import Optional
+
+from hiero_sdk_python.channels import _Channel
+from hiero_sdk_python.client.client import Client
+from hiero_sdk_python.executable import _Method
+from hiero_sdk_python.file.file_id import FileId
+from hiero_sdk_python.hapi.services import (
+    file_get_contents_pb2,
+    query_pb2,
+    response_pb2,
+)
+from hiero_sdk_python.hapi.services.file_get_contents_pb2 import FileGetContentsResponse
+from hiero_sdk_python.query.query import Query
+
+
+class FileContentsQuery(Query):
+    """
+    A query to retrieve the contents of a specific File.
+
+    This class constructs and executes a query to retrieve the contents
+    of a file on the network.
+
+    """
+
+    def __init__(self, file_id: Optional[FileId] = None) -> None:
+        """
+        Initializes a new FileContentsQuery instance with an optional file_id.
+
+        Args:
+            file_id (Optional[FileId], optional): The ID of the file to query.
+        """
+        super().__init__()
+        self.file_id = file_id
+
+    def set_file_id(self, file_id: Optional[FileId]) -> "FileContentsQuery":
+        """
+        Sets the ID of the file to query.
+
+        Args:
+            file_id (Optional[FileId]): The ID of the file.
+
+        Returns:
+            FileContentsQuery: Returns self for method chaining.
+        """
+        self.file_id = file_id
+        return self
+
+    def _make_request(self) -> query_pb2.Query:
+        """
+        Constructs the protobuf request for the query.
+
+        Builds a FileGetContentsQuery protobuf message with the
+        appropriate header and file ID.
+
+        Returns:
+            Query: The protobuf query message.
+
+        Raises:
+            ValueError: If the file ID is not set.
+            Exception: If any other error occurs during request construction.
+        """
+        try:
+            if not self.file_id:
+                raise ValueError("File ID must be set before making the request.")
+
+            query_header = self._make_request_header()
+
+            file_contents_query = file_get_contents_pb2.FileGetContentsQuery()
+            file_contents_query.header.CopyFrom(query_header)
+            file_contents_query.fileID.CopyFrom(self.file_id._to_proto())
+
+            query = query_pb2.Query()
+            query.fileGetContents.CopyFrom(file_contents_query)
+
+            return query
+        except Exception as e:
+            print(f"Exception in _make_request: {e}")
+            raise
+
+    def _get_method(self, channel: _Channel) -> _Method:
+        """
+        Returns the appropriate gRPC method for the file contents query.
+
+        Implements the abstract method from Query to provide the specific
+        gRPC method for getting file contents.
+
+        Args:
+            channel (_Channel): The channel containing service stubs
+
+        Returns:
+            _Method: The method wrapper containing the query function
+        """
+        return _Method(transaction_func=None, query_func=channel.file.getFileContent)
+
+    def execute(self, client: Client) -> str:
+        """
+        Executes the file contents query.
+
+        Sends the query to the Hedera network and processes the response
+        to return the file contents.
+
+        This function delegates the core logic to `_execute()`, and may propagate
+        exceptions raised by it.
+
+        Args:
+            client (Client): The client instance to use for execution
+
+        Returns:
+            str: The contents of the file from the network
+
+        Raises:
+            PrecheckError: If the query fails with a non-retryable error
+            MaxAttemptsError: If the query fails after the maximum number of attempts
+            ReceiptStatusError: If the query fails with a receipt status error
+        """
+        self._before_execute(client)
+        response = self._execute(client)
+
+        return response.fileGetContents.fileContents.contents
+
+    def _get_query_response(
+        self, response: response_pb2.Response
+    ) -> FileGetContentsResponse:
+        """
+        Extracts the file contents response from the full response.
+
+        Implements the abstract method from Query to extract the
+        specific file contents response object.
+
+        Args:
+            response: The full response from the network
+
+        Returns:
+            The file get contents response object
+        """
+        return response.fileGetContents

tests/integration/file_contents_query_e2e_test.py

@@ -0,0 +1,107 @@
+"""
+Integration tests for FileContentsQuery.
+"""
+
+import pytest
+
+from hiero_sdk_python.exceptions import PrecheckError
+from hiero_sdk_python.file.file_contents_query import FileContentsQuery
+from hiero_sdk_python.file.file_create_transaction import FileCreateTransaction
+from hiero_sdk_python.file.file_id import FileId
+from hiero_sdk_python.hbar import Hbar
+from tests.integration.utils_for_test import env
+
+FILE_CONTENT = b"Hello, World"
+
+
+@pytest.mark.integration
+def test_integration_file_contents_query_can_execute(env):
+    """Test that the FileContentsQuery can be executed successfully."""
+    # Create a file
+    receipt = (
+        FileCreateTransaction()
+        .set_keys([env.operator_key.public_key()])
+        .set_contents(FILE_CONTENT)
+        .set_transaction_memo("python sdk e2e tests")
+        .execute(env.client)
+    )
+    file_id = receipt.file_id
+    assert file_id is not None, "File ID should not be None"
+
+    # Query the file contents
+    contents = FileContentsQuery().set_file_id(file_id).execute(env.client)
+    assert contents == FILE_CONTENT, "File contents mismatch"
+
+
+@pytest.mark.integration
+def test_integration_file_contents_query_get_cost(env):
+    """Test that the FileContentsQuery can calculate query costs."""
+    # Create a file
+    receipt = (
+        FileCreateTransaction()
+        .set_keys([env.operator_key.public_key()])
+        .set_contents(FILE_CONTENT)
+        .set_transaction_memo("python sdk e2e tests")
+        .execute(env.client)
+    )
+    file_id = receipt.file_id
+    assert file_id is not None, "File ID should not be None"
+
+    # Create the query and get its cost
+    file_contents = FileContentsQuery().set_file_id(file_id)
+
+    cost = file_contents.get_cost(env.client)
+
+    # Execute with the exact cost
+    contents = file_contents.set_query_payment(cost).execute(env.client)
+
+    assert contents == FILE_CONTENT, "File contents mismatch"
+
+
+@pytest.mark.integration
+def test_integration_file_contents_query_empty_contents(env):
+    """Test that FileContentsQuery can execute with empty contents."""
+    # Create a file with no contents
+    receipt = (
+        FileCreateTransaction()
+        .set_keys([env.operator_key.public_key()])
+        .set_transaction_memo("python sdk e2e tests")
+        .execute(env.client)
+    )
+    file_id = receipt.file_id
+    assert file_id is not None, "File ID should not be None"
+
+    # Query the empty file contents
+    contents = FileContentsQuery().set_file_id(file_id).execute(env.client)
+
+    assert contents == b"", "File contents should be empty"
+
+
+@pytest.mark.integration
+def test_integration_file_contents_query_insufficient_payment(env):
+    """Test that FileContentsQuery fails with insufficient payment."""
+    # Create a test file first
+    receipt = FileCreateTransaction().set_contents(FILE_CONTENT).execute(env.client)
+    file_id = receipt.file_id
+    assert file_id is not None, "File ID should not be None"
+
+    # Create query and set very low payment
+    file_contents = FileContentsQuery().set_file_id(file_id)
+    file_contents.set_query_payment(Hbar.from_tinybars(1))  # Set very low query payment
+
+    with pytest.raises(
+        PrecheckError, match="failed precheck with status: INSUFFICIENT_TX_FEE"
+    ):
+        file_contents.execute(env.client)
+
+
+@pytest.mark.integration
+def test_integration_file_contents_query_fails_with_invalid_file_id(env):
+    """Test that the FileContentsQuery fails with an invalid file ID."""
+    # Create a file ID that doesn't exist on the network
+    file_id = FileId(0, 0, 999999999)
+
+    with pytest.raises(
+        PrecheckError, match="failed precheck with status: INVALID_FILE_ID"
+    ):
+        FileContentsQuery(file_id).execute(env.client)