added api_get_table_schema for TableClient (#104)

* added `api_get_table_schema` for TableClient

* added returned example

* fmt

* fmt

Author: misterbrunet

libs/foundry-dev-tools/src/foundry_dev_tools/clients/tables.py

@@ -9,7 +9,7 @@
 if TYPE_CHECKING:
     import requests
 
-    from foundry_dev_tools.utils.api_types import FolderRid, SourceRid
+    from foundry_dev_tools.utils.api_types import Branch, FolderRid, SourceRid, TableRid
 
 
 class TablesClient(APIClient):
@@ -143,3 +143,44 @@ def list_tables(self, connection_rid: SourceRid) -> list[dict]:
             response_json = self.api_list_tables(connection_rid=connection_rid, page_token=next_page_token).json()
             tables.extend(response_json["tables"])
         return tables
+
+    def api_get_table_schema(self, table_rid: TableRid, branches: list[Branch], **kwargs) -> requests.Response:
+        """Retrieves schema for a Foundry table object per given list of branches.
+
+        Args:
+            table_rid: The RID of the table to get schema for.
+            branches: List of branch names to get schema for.
+            **kwargs: gets passed to :py:meth:`APIClient.api_request`
+
+        Returns:
+            requests.Response: The API response containing the table schema.
+
+        Example::
+            >>> response = tables_client.api_get_table_schema("ri.foundry.main.dataset.abc123", ["master"])
+            >>> schema = response.json()
+            >>> schema
+            {
+                "fieldSchemaList": [
+                    {
+                        "type": "DECIMAL",
+                        "name": "column_A",
+                        "nullable": false,
+                        "precision": 38,
+                        "scale": 0
+                    },
+                    {
+                        "type": "STRING",
+                        "name": "column_B",
+                        "nullable": false
+                    }
+                ],
+                "primaryKey": null,
+                "customMetadata": {"format": "snowflake"}
+            }
+        """
+        return self.api_request(
+            "POST",
+            api_path=f"tables/{table_rid}/schema",
+            json={"branches": branches},
+            **kwargs,
+        )