fix: improve timeout error messages and document TSC_CHUNK_SIZE_MB

tableauserverclient/server/endpoint/datasources_endpoint.py

@@ -580,7 +580,9 @@ def publish(
         as_job : bool, default False
             If True, the publish operation is asynchronous and returns a job
             item. If False, the publish operation is synchronous and returns a
-            datasource item.
+            datasource item. For large files on slow connections, if uploads
+            time out you can tune the chunk size with the TSC_CHUNK_SIZE_MB
+            environment variable (default: 50).
 
         Returns
         -------
@@ -670,8 +672,16 @@ def publish(
         try:
             server_response = self.post_request(url, xml_request, content_type)
         except InternalServerError as err:
-            if err.code == 504 and not as_job:
-                err.content = "Timeout error while publishing. Please use asynchronous publishing to avoid timeouts."
+            if err.code == 504:
+                if as_job:
+                    err.content = (
+                        "Timeout error during chunked file upload. Try reducing the chunk size by setting the "
+                        "TSC_CHUNK_SIZE_MB environment variable to a lower value (current default: 50)."
+                    )
+                else:
+                    err.content = (
+                        "Timeout error while publishing. Please use asynchronous publishing to avoid timeouts."
+                    )
             raise err
 
         if as_job:

tableauserverclient/server/endpoint/workbooks_endpoint.py

@@ -854,7 +854,9 @@ def publish(
         as_job : bool, default False
             Set to True to run the upload as a job (asynchronous upload). If set
             to True a job will start to perform the publishing process and a Job
-            object is returned. Defaults to False.
+            object is returned. Defaults to False. For large files on slow
+            connections, if uploads time out you can tune the chunk size with
+            the TSC_CHUNK_SIZE_MB environment variable (default: 50).
 
         skip_connection_check : bool, default False
             Set to True to skip connection check at time of upload. Publishing
@@ -976,8 +978,16 @@ def publish(
         try:
             server_response = self.post_request(url, xml_request, content_type, parameters)
         except InternalServerError as err:
-            if err.code == 504 and not as_job:
-                err.content = "Timeout error while publishing. Please use asynchronous publishing to avoid timeouts."
+            if err.code == 504:
+                if as_job:
+                    err.content = (
+                        "Timeout error during chunked file upload. Try reducing the chunk size by setting the "
+                        "TSC_CHUNK_SIZE_MB environment variable to a lower value (current default: 50)."
+                    )
+                else:
+                    err.content = (
+                        "Timeout error while publishing. Please use asynchronous publishing to avoid timeouts."
+                    )
             raise err
 
         if as_job:

test/test_datasource.py

@@ -763,6 +763,22 @@ def test_synchronous_publish_timeout_error(server) -> None:
             )
 
 
+def test_async_publish_timeout_error(server) -> None:
+    with requests_mock.mock() as m:
+        m.register_uri("POST", server.datasources.baseurl, status_code=504)
+
+        new_datasource = TSC.DatasourceItem(project_id="")
+        publish_mode = server.PublishMode.CreateNew
+
+        with pytest.raises(InternalServerError, match="TSC_CHUNK_SIZE_MB"):
+            server.datasources.publish(
+                new_datasource,
+                TEST_ASSET_DIR / "SampleDS.tds",
+                publish_mode,
+                as_job=True,
+            )
+
+
 def test_delete_extracts(server) -> None:
     server.version = "3.10"
     with requests_mock.mock() as m:

test/test_workbook.py

@@ -879,6 +879,17 @@ def test_synchronous_publish_timeout_error(server: TSC.Server) -> None:
             server.workbooks.publish(new_workbook, TEST_ASSET_DIR / "SampleWB.twbx", publish_mode)
 
 
+def test_async_publish_timeout_error(server: TSC.Server) -> None:
+    with requests_mock.mock() as m:
+        m.register_uri("POST", server.workbooks.baseurl, status_code=504)
+
+        new_workbook = TSC.WorkbookItem(project_id="")
+        publish_mode = server.PublishMode.CreateNew
+
+        with pytest.raises(InternalServerError, match="TSC_CHUNK_SIZE_MB"):
+            server.workbooks.publish(new_workbook, TEST_ASSET_DIR / "SampleWB.twbx", publish_mode, as_job=True)
+
+
 def test_delete_extracts_all(server: TSC.Server) -> None:
     server.version = "3.10"
     server.workbooks.baseurl