feat: FileId class cleanup, docstrings and typing (#656)

Signed-off-by: Raja Rathour <imraja729@gmail.com>
Signed-off-by: Raja Rathour <193507075+Raja-89@users.noreply.github.com>

Author: Raja-89

CHANGELOG.md

@@ -7,6 +7,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 ## [Unreleased]
 
 ### Added
+- Standardized docstrings, improved error handling, and updated type hinting (`str | None` to `Optional[str]`) for the `FileId` class (#652).
 
 - Add Google-style docstrings to `AccountInfo` class and its methods in `account_info.py`.
 - Added comprehensive Google-style docstrings to the `Logger` class and all utility functions in `src/hiero_sdk_python/logger/logger.py` (#639).

src/hiero_sdk_python/file/file_id.py

@@ -1,7 +1,12 @@
 """
 FileId class.
+
+This module defines the FileId object, which serves as a unique identifier for
+files stored on the Hedera network. It supports string parsing, checksum validation,
+and conversion to and from protobuf structures.
 """
 from dataclasses import dataclass, field
+from typing import Optional 
 
 from hiero_sdk_python.client.client import Client
 from hiero_sdk_python.hapi.services import basic_types_pb2
@@ -17,23 +22,31 @@ class FileId:
     """
     Represents a file ID on the network.
 
-    A file ID consists of three components: shard, realm, and file (number).
+    A file ID consists of three components: shard, realm, and file number.
     These components uniquely identify a file in the network.
 
     Attributes:
         shard (int): The shard number. Defaults to 0.
         realm (int): The realm number. Defaults to 0.
         file (int): The file number. Defaults to 0.
+        checksum (Optional[str]): The calculated checksum for the file ID.
     """
     shard: int = 0
     realm: int = 0
     file: int = 0
-    checksum: str | None = field(default=None, init=False)
+    checksum: Optional[str] = field(default=None, init=False)
 
     @classmethod
     def _from_proto(cls, file_id_proto: basic_types_pb2.FileID) -> 'FileId':
         """
         Creates a FileId instance from a protobuf FileID object.
+
+        Args:
+            file_id_proto (basic_types_pb2.FileID): The protobuf object containing
+                the file ID components.
+
+        Returns:
+            FileId: A new instance of the FileId class.
         """
         return cls(
             shard=file_id_proto.shardNum,
@@ -44,6 +57,9 @@ def _from_proto(cls, file_id_proto: basic_types_pb2.FileID) -> 'FileId':
     def _to_proto(self) -> basic_types_pb2.FileID:
         """
         Converts the FileId instance to a protobuf FileID object.
+
+        Returns:
+            basic_types_pb2.FileID: The protobuf representation of the FileId.
         """
         return basic_types_pb2.FileID(
             shardNum=self.shard,
@@ -54,7 +70,17 @@ def _to_proto(self) -> basic_types_pb2.FileID:
     @classmethod
     def from_string(cls, file_id_str: str) -> 'FileId':
         """
-        Creates a FileId instance from a string in the format 'shard.realm.file'.
+        Parses a string in the format 'shard.realm.file' (with optional checksum) 
+        to create a FileId instance.
+
+        Args:
+            file_id_str (str): The string representation of the File ID.
+
+        Returns:
+            FileId: A new instance with components and checksum (if present).
+
+        Raises:
+            ValueError: If the input string is malformed or cannot be parsed.
         """
         try:
             shard, realm, file, checksum = parse_from_string(file_id_str)
@@ -67,19 +93,30 @@ def from_string(cls, file_id_str: str) -> 'FileId':
             object.__setattr__(file_id, 'checksum', checksum)
 
             return file_id
-        except Exception as e:
+        except Exception as e: 
             raise ValueError(
                 f"Invalid file ID string '{file_id_str}'. Expected format 'shard.realm.file'."
             ) from e
-
     def __str__(self) -> str:
         """
-        Returns a string representation of the FileId instance.
+        Returns the string representation of the FileId in the format 'shard.realm.file'.
+
+        Returns:
+            str: The string representation of the file ID components.
         """
         return f"{self.shard}.{self.realm}.{self.file}"
 
     def validate_checksum(self, client: Client) -> None:
-        """Validate the checksum for the FileId instance"""
+        """
+        Validates the stored checksum against the calculated checksum using the provided client.
+
+        Args:
+            client (Client): The client instance used to retrieve network information 
+                necessary for checksum calculation.
+
+        Raises:
+            ValueError: If the stored checksum is invalid or does not match the calculated value.
+        """
         validate_checksum(
             self.shard,
             self.realm,
@@ -90,12 +127,19 @@ def validate_checksum(self, client: Client) -> None:
 
     def to_string_with_checksum(self, client: Client) -> str:
         """
-        Returns the string representation of the FileId with checksum 
+        Returns the string representation of the FileId with its calculated checksum 
         in 'shard.realm.file-checksum' format.
+
+        Args:
+            client (Client): The client instance used to retrieve network information 
+                necessary for checksum calculation.
+
+        Returns:
+            str: The file ID formatted with its checksum.
         """
         return format_to_string_with_checksum(
             self.shard,
             self.realm,
             self.file,
             client
-        )
+        )