Address Copilot + fresh-eyes review on samples

Copilot round-2 (2026-09-17) findings:
- _shared.py: build_auth now validates args.server so non-TTY callers
  hit a clear ValueError instead of TSC.Server(None, ...) downstream.
- explore_favorites.py: favorite-delete cleanup moved inside the
  `with server.auth.sign_in(...)` block; each delete guarded by
  `if my_workbook is not None:` etc. to match the add-side.
- update_workbook_data_freshness_policy.py: all_workbooks[2] -> [0]
  with a follow-up comment; argparse description corrected.

Fresh-eyes findings this pass caught:
- manage_subscriptions.py: drop the --on-extract-refresh path
  entirely (docstring, code branch, argparse flag). That relies on
  SubscriptionItem.on_extract_refresh which lands with #1861 and is
  not present on this branch after the earlier subscription revert.
- extracts.py: `all_workbooks[3]` -> `[0]`; guard the create/delete
  branches against `wb is None` so `--datasource ... --create` no
  longer AttributeErrors on `wb.name`; --workbook/--datasource made
  mutually exclusive to match how the sample is meant to be used.
- publish_datasource.py: raise a clear "no project named X" error
  when the project filter matches zero; fix a swapped-argument print
  so the datasource id no longer prefixes the "Datasource published"
  message with the timestamp reading as the id.
- refresh_tasks.py: subparsers marked required=True so running the
  sample with no subcommand prints usage instead of AttributeError.

Not fixed in this PR (pre-existing, flagged for follow-up):
- explore_workbook.py:120-149 has three latent bugs (missing `=` on
  `changed`, `c` referenced outside its loop, `--delete` not in this
  script's argparse). This PR only adds the _shared import; the
  bugs pre-date it and belong in a separate cleanup PR.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jacalata

samples/_shared.py

@@ -232,7 +232,17 @@ def build_auth(args: argparse.Namespace) -> TSC.TableauAuth | TSC.PersonalAccess
     Priority is JWT > PAT > username/password: a script that has a JWT
     minted for a specific session should never fall back to a longer-lived
     credential if the JWT-adjacent fields were left set by accident.
+
+    Also validates that `--server` is set. `resolve_credentials` skips prompting
+    in non-interactive contexts (CI, piped stdin), so a missing server URL would
+    otherwise reach `TSC.Server(None, ...)` and fail with a confusing error;
+    catching it here gives the caller a clear message.
     """
+    if not getattr(args, "server", None):
+        raise ValueError(
+            "No Tableau server URL. Provide --server, set the TABLEAU_SERVER env "
+            "var, or run in an interactive terminal to be prompted."
+        )
     site = getattr(args, "site", None) or ""
     if getattr(args, "jwt", None):
         return TSC.JWTAuth(args.jwt, site_id=site)

samples/explore_favorites.py

@@ -59,16 +59,22 @@ def main():
                 )
             )
 
-    server.favorites.delete_favorite_workbook(user, my_workbook)
-    print(f"Workbook deleted from favorites. Workbook Name: {my_workbook.name}, Workbook ID: {my_workbook.id}")
+        # Cleanup — delete the favorites we just created. Must stay inside the
+        # `with server.auth.sign_in(...)` block; a delete after sign-out fails
+        # with a not-signed-in error. Each guard mirrors the "add" check above
+        # so we do not try to delete a favorite we never created.
+        if my_workbook is not None:
+            server.favorites.delete_favorite_workbook(user, my_workbook)
+            print(f"Workbook deleted from favorites. Workbook Name: {my_workbook.name}, Workbook ID: {my_workbook.id}")
 
-    server.favorites.delete_favorite_view(user, my_view)
-    print(f"View deleted from favorites. View Name: {my_view.name}, View ID: {my_view.id}")
+        if my_view is not None:
+            server.favorites.delete_favorite_view(user, my_view)
+            print(f"View deleted from favorites. View Name: {my_view.name}, View ID: {my_view.id}")
 
-    if my_datasource is not None:
-        server.favorites.delete_favorite_datasource(user, my_datasource)
-        print(
-            "Datasource deleted from favorites. Datasource Name: {}, Datasource ID: {}".format(
-                my_datasource.name, my_datasource.id
+        if my_datasource is not None:
+            server.favorites.delete_favorite_datasource(user, my_datasource)
+            print(
+                "Datasource deleted from favorites. Datasource Name: {}, Datasource ID: {}".format(
+                    my_datasource.name, my_datasource.id
+                )
             )
-        )

samples/extracts.py

@@ -18,8 +18,11 @@ def main():
     parser.add_argument("--create", action="store_true")
     parser.add_argument("--delete", action="store_true")
     parser.add_argument("--refresh", action="store_true")
-    parser.add_argument("--workbook", required=False)
-    parser.add_argument("--datasource", required=False)
+    # --workbook / --datasource are mutually exclusive; if neither is passed we
+    # fall back to picking the first workbook on the site (see below).
+    target = parser.add_mutually_exclusive_group()
+    target.add_argument("--workbook")
+    target.add_argument("--datasource")
     args = parser.parse_args()
 
     resolve_credentials(args)
@@ -47,13 +50,17 @@ def main():
             print([workbook.name for workbook in all_workbooks])
 
             if all_workbooks:
-                # Pick one workbook from the list
-                wb = all_workbooks[3]
+                # Fall back to the first workbook on the site. For a real run,
+                # pass --workbook <id> for a workbook you know has an extract.
+                wb = all_workbooks[0]
 
         if args.create:
-            print("create extract on wb ", wb.name)
-            extract_job = server.workbooks.create_extract(wb, includeAll=True)
-            print(extract_job)
+            if wb is None:
+                print("no workbook selected to create an extract on")
+            else:
+                print(f"create extract on workbook {wb.name}")
+                extract_job = server.workbooks.create_extract(wb, includeAll=True)
+                print(extract_job)
 
         if args.refresh:
             extract_job = None
@@ -69,9 +76,12 @@ def main():
             print(extract_job)
 
         if args.delete:
-            print("delete extract on wb ", wb.name)
-            jj = server.workbooks.delete_extract(wb)
-            print(jj)
+            if wb is None:
+                print("no workbook selected to delete an extract from")
+            else:
+                print(f"delete extract on workbook {wb.name}")
+                jj = server.workbooks.delete_extract(wb)
+                print(jj)
 
 
 if __name__ == "__main__":

samples/manage_subscriptions.py

@@ -18,16 +18,6 @@
 #       --schedule-id <schedule_id> \
 #       --subject "Daily sales snapshot"
 #
-#   # Create an "On Extract Refresh" subscription (fires when the referenced
-#   # extract-refresh schedule completes, rather than on the schedule's time
-#   # trigger). --schedule-id must reference an extract-refresh schedule.
-#   python samples/manage_subscriptions.py create \
-#       --target-type view \
-#       --target-id <view_id> \
-#       --schedule-id <extract_refresh_schedule_id> \
-#       --subject "Snapshot when refresh finishes" \
-#       --on-extract-refresh
-#
 #   # Delete an existing subscription.
 #   python samples/manage_subscriptions.py delete --id <subscription_id>
 #
@@ -67,34 +57,19 @@ def handle_create(server, args):
     # The REST API expects lowercase content types ("workbook" or "view").
     target = TSC.Target(args.target_id, args.target_type.lower())
 
-    if args.on_extract_refresh:
-        # Extract-refresh-triggered: the subscription fires when the referenced
-        # extract-refresh schedule finishes running the refresh. On Tableau
-        # Cloud this shows up as schedule type "On Extract Refresh" in the UI.
-        # `SubscriptionItem.on_extract_refresh` wires up schedule_id and the
-        # refreshExtractTriggered flag together so the server accepts the
-        # payload; --schedule-id must reference an extract-refresh schedule.
-        new_sub = TSC.SubscriptionItem.on_extract_refresh(
-            subject=args.subject,
-            extract_refresh_schedule_id=args.schedule_id,
-            user_id=user_id,
-            target=target,
-        )
-    else:
-        new_sub = TSC.SubscriptionItem(
-            subject=args.subject,
-            schedule_id=args.schedule_id,
-            user_id=user_id,
-            target=target,
-        )
+    new_sub = TSC.SubscriptionItem(
+        subject=args.subject,
+        schedule_id=args.schedule_id,
+        user_id=user_id,
+        target=target,
+    )
     if args.message:
         new_sub.message = args.message
     new_sub.attach_image = args.attach_image
     new_sub.attach_pdf = args.attach_pdf
 
     created = server.subscriptions.create(new_sub)
-    trigger = "on-extract-refresh" if args.on_extract_refresh else "on-schedule"
-    print(f"Created {trigger} subscription {created.id} " f"for user {created.user_id} against {created.target}")
+    print(f"Created subscription {created.id} for user {created.user_id} against {created.target}")
 
 
 def handle_delete(server, args):
@@ -139,17 +114,6 @@ def main():
         default=False,
         help="Also attach a PDF snapshot (default: off).",
     )
-    create_p.add_argument(
-        "--on-extract-refresh",
-        action="store_true",
-        default=False,
-        help=(
-            "Fire this subscription when the referenced extract-refresh schedule "
-            "completes, rather than on the schedule's time trigger. --schedule-id "
-            "must reference an extract-refresh schedule (see create_extract_refresh_"
-            "subscription.py for the fully worked example)."
-        ),
-    )
     create_p.set_defaults(func=handle_create)
 
     delete_p = subcommands.add_parser("delete", help="Delete a subscription by ID.")

samples/publish_datasource.py

@@ -66,6 +66,8 @@ def main():
                 TSC.Filter(TSC.RequestOptions.Field.Name, TSC.RequestOptions.Operator.Equals, args.project)
             )
             projects = list(TSC.Pager(server.projects, req_options))
+            if not projects:
+                raise ValueError(f"No project named {args.project!r} on this site.")
             if len(projects) > 1:
                 raise ValueError("The project name is not unique")
             project_id = projects[0].id
@@ -97,11 +99,8 @@ def main():
                 new_datasource, args.file, publish_mode, connection_credentials=new_conn_creds
             )
             print(
-                (
-                    "{}Datasource published. Datasource ID: {}".format(
-                        new_datasource.id, tableauserverclient.datetime_helpers.timestamp()
-                    )
-                )
+                f"[{tableauserverclient.datetime_helpers.timestamp()}] "
+                f"Datasource published. Datasource ID: {new_datasource.id}"
             )
             print("\t\tClosing connection")
 

samples/refresh_tasks.py

@@ -33,7 +33,7 @@ def main():
     parser = argparse.ArgumentParser(description="Get all of the refresh tasks available on a server")
     add_common_arguments(parser)
     # Options specific to this sample
-    subcommands = parser.add_subparsers()
+    subcommands = parser.add_subparsers(dest="command", required=True)
 
     list_arguments = subcommands.add_parser("list")
     list_arguments.set_defaults(func=handle_list)

samples/update_workbook_data_freshness_policy.py

@@ -16,7 +16,9 @@
 
 
 def main():
-    parser = argparse.ArgumentParser(description="Creates sample schedules for each type of frequency.")
+    parser = argparse.ArgumentParser(
+        description="Update a workbook's data freshness policy across the supported schedule types."
+    )
     add_common_arguments(parser)
     # Options specific to this sample:
     # This sample has no additional options, yet. If you add some, please add them here
@@ -37,10 +39,12 @@ def main():
         print([workbook.name for workbook in all_workbooks])
 
         if all_workbooks:
-            # Pick 1 workbook that has live datasource connection.
-            # Assuming 1st workbook met the criteria for sample purposes
-            # Data Freshness Policy is not available on extract & file-based datasource.
-            sample_workbook = all_workbooks[2]
+            # Pick 1 workbook that has a live datasource connection. Data
+            # freshness policy is not available on extract or file-based
+            # datasources, so this sample will print a warning below if the
+            # chosen workbook has none. Adjust the index (or add a lookup by
+            # name) for a workbook on your site with a live connection.
+            sample_workbook = all_workbooks[0]
 
             # Get more info from the workbook selected
             # Troubleshoot: if sample_workbook_extended.data_freshness_policy.option returns with AttributeError