samples: fix argparse blocker + 7 bugs, add JWT + on-extract-refresh

Round of fixes for the sample-scripts refactor after fresh-eyes review.

Blocker: publish_workbook.py reused `-u` for --thumbnails-user-id while
_shared.py add_common_arguments already binds `-u` to --username, so
argparse raised ArgumentError on module load and the script would not
start. Renamed to `-U`.

Real bugs:
- _shared.py .env search now checks cwd, samples/, and repo root (in that
  order) so the docstring stops lying about "next to the sample or cwd."
- resolve_credentials now gates input()/getpass on sys.stdin.isatty()
  as the docstring already promised, so piped/CI invocations no longer
  hang forever.
- manage_subscriptions.py --attach-image switched to
  argparse.BooleanOptionalAction so users can actually pass
  --no-attach-image; the previous store_true+default=True made the flag
  a permanent True.
- Header docstring in _shared.py no longer claims "no existing command
  line breaks" (which was false: -p migrated from --token-name to
  --password in an earlier commit). Documented the tabcmd-aligned short
  flags instead.
- Corrected Python-version headers on login.py, list_jobs.py,
  manage_subscriptions.py, publish_workbook.py, refresh_tasks.py,
  move_workbook_sites.py, publish_datasource.py, and
  update_workbook_data_freshness_policy.py -- repo floor is 3.10 per
  pyproject.toml.
- list_jobs._wait_for_job: reordered excepts so JobCancelledException
  (a subclass of JobFailedException) is caught first, otherwise
  cancelled jobs were reported as failed with the wrong exit code.
- login.py sign-in banner now branches on JWTAuth as well, so JWT
  logins no longer print "Username: None". Header env-var list updated
  to include TABLEAU_JWT / TABLEAU_JWT_FILE.

New JWT support: _shared.py add_common_arguments now exposes --jwt and
--jwt-file, resolves TABLEAU_JWT / TABLEAU_JWT_FILE from env, reads a
JWT file path into args.jwt during resolve_credentials, and returns
TSC.JWTAuth from build_auth when a JWT is present. JWT takes priority
over PAT and username/password.

Extract-refresh subscription: manage_subscriptions.py create now
accepts --on-extract-refresh, which calls
SubscriptionItem.on_extract_refresh() to construct a subscription that
fires when the referenced extract-refresh schedule completes (the flow
introduced in #1861). Rebased this branch onto
jac/subscription-refresh-extract-triggered so the flag lands on top of
the new API without conflicts.

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

Author: jacalata

samples/_shared.py

@@ -6,22 +6,31 @@
 #
 #   1. Command-line arguments (useful for CI, but note that these end up in
 #      shell history and process listings, so avoid them for real secrets).
-#   2. Environment variables. If a `.env` file exists next to the sample
-#      being run, or in the current working directory, we load it first --
-#      only the standard `KEY=value` lines, no external dependency required.
-#   3. Interactive prompts. Missing values are asked for on stdin; secrets
-#      are read with `getpass.getpass` so they are not echoed.
+#   2. Environment variables. We look for a `.env` file in the current
+#      working directory, in the samples/ directory, and at the repository
+#      root, in that order, and load whichever we find first -- only the
+#      standard `KEY=value` lines, no external dependency required.
+#   3. Interactive prompts. Missing values are asked for on stdin when
+#      stdin is a terminal; secrets are read with `getpass.getpass` so they
+#      are not echoed. In non-interactive contexts (CI, piped input) we skip
+#      the prompts and let `build_auth` raise instead of hanging on `input()`.
 #
 # CLI args take precedence, then environment, then interactive prompt.
 # This lets a user set defaults in a `.env` file and override individual
 # values on the command line.
+#
+# Sign-in short flags follow the tabcmd convention (-s server, -t site,
+# -u username, -p password). --token-name and --token-value do not have
+# short flags because tabcmd does not either and re-using a letter here
+# would silently accept a token as a password on old command lines.
 ####
 
 from __future__ import annotations
 
 import argparse
 import getpass
 import os
+import sys
 from pathlib import Path
 from typing import Iterable
 
@@ -36,15 +45,21 @@
     "token_value": ("TABLEAU_TOKEN_VALUE", "TOKEN_VALUE"),
     "username": ("TABLEAU_USERNAME", "USERNAME"),
     "password": ("TABLEAU_PASSWORD", "PASSWORD"),
+    "jwt": ("TABLEAU_JWT", "JWT"),
+    "jwt_file": ("TABLEAU_JWT_FILE", "JWT_FILE"),
 }
 
 
 def add_common_arguments(parser: argparse.ArgumentParser) -> None:
     """Add the sign-in and logging arguments used by every sample.
 
-    Kept in sync with the historical inline definitions so no existing
-    command line breaks. All arguments are optional -- missing values
-    are pulled from the environment or prompted for interactively.
+    Short flags follow the tabcmd convention: -s server, -t site,
+    -u username, -p password, -l logging-level. --token-name /
+    --token-value and --jwt / --jwt-file intentionally have no short
+    flag; re-using letters here risked silently accepting a token as
+    a password on scripts that pre-date the shared helper. All args
+    are optional; missing values are pulled from the environment or
+    prompted for interactively.
     """
     parser.add_argument("--server", "-s", help="server address (env: TABLEAU_SERVER)")
     parser.add_argument("--site", "-t", help="site content URL (env: TABLEAU_SITE)")
@@ -62,17 +77,28 @@ def add_common_arguments(parser: argparse.ArgumentParser) -> None:
         "--username",
         "-u",
         help="username to sign into the server (env: TABLEAU_USERNAME). Only used if "
-        "no personal access token is supplied.",
+        "no personal access token or JWT is supplied.",
     )
     parser.add_argument(
         "--password",
         "-p",
         help="password (env: TABLEAU_PASSWORD). Prefer the env var or interactive " "prompt over the command line.",
     )
+    parser.add_argument(
+        "--jwt",
+        help="encoded JSON Web Token for Connected-App sign-in (env: TABLEAU_JWT). "
+        "Mutually exclusive with token/username auth; see JWTAuth in the docs.",
+    )
+    parser.add_argument(
+        "--jwt-file",
+        help="path to a file whose contents are the encoded JWT (env: TABLEAU_JWT_FILE). "
+        "Useful for pipelines that mint a JWT into a file rather than an env var.",
+    )
     parser.add_argument(
         "--env-file",
         help="path to a .env-style file with KEY=value lines to load. If omitted, "
-        ".env in the current directory is loaded automatically when present.",
+        ".env is looked for in the current directory, the samples/ directory, and "
+        "the repository root, and the first one found is loaded.",
     )
     parser.add_argument(
         "--logging-level",
@@ -113,23 +139,39 @@ def _first_env(names: Iterable[str]) -> str | None:
     return None
 
 
+def _candidate_env_paths() -> list[Path]:
+    """Locations we check for a .env file, in priority order.
+
+    cwd first (so the invoker can override), then the directory that holds
+    this shared module (samples/), then the repository root one level up.
+    """
+    module_dir = Path(__file__).resolve().parent
+    return [
+        Path.cwd() / ".env",
+        module_dir / ".env",
+        module_dir.parent / ".env",
+    ]
+
+
 def resolve_credentials(args: argparse.Namespace, *, allow_prompt: bool = True) -> None:
     """Fill in server/site/credential values on `args` from env or prompt.
 
     Precedence for each field: existing value on `args` > environment variable
-    > interactive prompt (if allow_prompt and stdin is a terminal).
+    > interactive prompt (only when allow_prompt is true AND stdin is a TTY).
 
-    Pass `allow_prompt=False` in CI environments where blocking on input would
-    hang the job; the caller should then verify the fields it needs are set.
+    Pass `allow_prompt=False`, or run with stdin redirected (CI, piped input),
+    to skip the prompts entirely; the caller should then verify the fields it
+    needs are set, or let `build_auth` raise a clear ValueError.
     """
     # Load `.env` file if one is requested or available.
     env_file = getattr(args, "env_file", None)
     if env_file:
         _load_env_file(Path(env_file))
     else:
-        default_env = Path.cwd() / ".env"
-        if default_env.is_file():
-            _load_env_file(default_env)
+        for candidate in _candidate_env_paths():
+            if candidate.is_file():
+                _load_env_file(candidate)
+                break
 
     # For each field, prefer the CLI arg, then env, then prompt.
     for field, env_names in _ENV_ALIASES.items():
@@ -140,31 +182,42 @@ def resolve_credentials(args: argparse.Namespace, *, allow_prompt: bool = True)
         if env_val:
             setattr(args, field, env_val)
 
-    if not allow_prompt:
+    # If a JWT file was provided, read its contents into args.jwt (unless the
+    # caller also passed --jwt directly, in which case the direct value wins).
+    jwt_file = getattr(args, "jwt_file", None)
+    if jwt_file and not getattr(args, "jwt", None):
+        try:
+            args.jwt = Path(jwt_file).read_text(encoding="utf-8").strip()
+        except OSError as exc:
+            raise SystemExit(f"Could not read --jwt-file {jwt_file!r}: {exc}") from exc
+
+    # Skip prompting entirely if the caller opted out or stdin is not a
+    # terminal. `input()` on a closed/piped stdin either blocks forever or
+    # raises EOFError; neither is what a scripted invocation wants.
+    if not allow_prompt or not sys.stdin.isatty():
         return
 
     # Prompt for what's still missing. We only prompt for the pieces we
-    # actually need: server URL, and one of token or username/password.
+    # actually need: server URL, and one of JWT / token / username+password.
     if not getattr(args, "server", None):
         args.server = input("Tableau server URL: ").strip()
 
     # Site is optional (empty string is the default site) so we don't prompt.
 
-    has_token = getattr(args, "token_name", None) and getattr(args, "token_value", None)
-    has_user = getattr(args, "username", None) and getattr(args, "password", None)
+    has_jwt = bool(getattr(args, "jwt", None))
+    has_token = bool(getattr(args, "token_name", None) and getattr(args, "token_value", None))
+    has_user = bool(getattr(args, "username", None) and getattr(args, "password", None))
 
-    if has_token or has_user:
+    if has_jwt or has_token or has_user:
         return
 
-    # Nothing configured yet. Ask which auth method to use.
-    if getattr(args, "token_name", None) or getattr(args, "username", None):
-        # Partial info supplied -- fill in the matching missing piece.
-        if getattr(args, "token_name", None) and not getattr(args, "token_value", None):
-            args.token_value = getpass.getpass(f"Personal access token value for '{args.token_name}': ")
-            return
-        if getattr(args, "username", None) and not getattr(args, "password", None):
-            args.password = getpass.getpass(f"Password for '{args.username}': ")
-            return
+    # Partial info supplied -- fill in the matching missing piece.
+    if getattr(args, "token_name", None) and not getattr(args, "token_value", None):
+        args.token_value = getpass.getpass(f"Personal access token value for '{args.token_name}': ")
+        return
+    if getattr(args, "username", None) and not getattr(args, "password", None):
+        args.password = getpass.getpass(f"Password for '{args.username}': ")
+        return
 
     # Fully unspecified: default to PAT since that's what the docs recommend.
     print("No credentials found in args or environment. Sign in with a personal access token.")
@@ -173,16 +226,24 @@ def resolve_credentials(args: argparse.Namespace, *, allow_prompt: bool = True)
     args.token_value = getpass.getpass("Personal access token value: ")
 
 
-def build_auth(args: argparse.Namespace) -> TSC.TableauAuth | TSC.PersonalAccessTokenAuth:
-    """Return the appropriate auth object based on what's set on `args`."""
+def build_auth(args: argparse.Namespace) -> TSC.TableauAuth | TSC.PersonalAccessTokenAuth | TSC.JWTAuth:
+    """Return the appropriate auth object based on what's set on `args`.
+
+    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.
+    """
     site = getattr(args, "site", None) or ""
+    if getattr(args, "jwt", None):
+        return TSC.JWTAuth(args.jwt, site_id=site)
     if getattr(args, "token_name", None) and getattr(args, "token_value", None):
         return TSC.PersonalAccessTokenAuth(args.token_name, args.token_value, site_id=site)
     if getattr(args, "username", None) and getattr(args, "password", None):
         return TSC.TableauAuth(args.username, args.password, site_id=site)
     raise ValueError(
-        "No usable credentials found. Provide --token-name/--token-value, "
-        "--username/--password, or set the corresponding env vars."
+        "No usable credentials found. Provide --jwt/--jwt-file, "
+        "--token-name/--token-value, --username/--password, or set the "
+        "corresponding env vars."
     )
 
 

samples/list_jobs.py

@@ -20,7 +20,7 @@
 #   # Wait for a specific job to finish.
 #   python samples/list_jobs.py --wait <job_id>
 #
-# To run the script, you must have installed Python 3.9 or later.
+# To run the script, you must have installed Python 3.10 or later.
 ####
 
 import argparse
@@ -119,13 +119,16 @@ def _wait_for_job(server, job_id, timeout):
     """Poll a single job until it finishes, using the built-in helper."""
     try:
         job = server.jobs.wait_for_job(job_id, timeout=timeout)
+    except JobCancelledException:
+        # JobCancelledException is a subclass of JobFailedException, so this
+        # branch must come first or cancelled jobs get reported as failed
+        # with the wrong exit code.
+        print(f"Job {job_id} was cancelled.")
+        raise SystemExit(2)
     except JobFailedException as exc:
         # The exception carries the failed JobItem so callers can inspect it.
         print(f"Job {job_id} failed: notes={exc.job.notes}")
         raise SystemExit(1) from exc
-    except JobCancelledException:
-        print(f"Job {job_id} was cancelled.")
-        raise SystemExit(2)
 
     print(f"Job {job_id} finished. finish_code={job.finish_code}  notes={job.notes}")
 

samples/login.py

@@ -1,13 +1,14 @@
 ####
 # This script demonstrates how to log in to Tableau Server Client.
 #
-# To run the script, you must have installed Python 3.7 or later.
+# To run the script, you must have installed Python 3.10 or later.
 #
 # Credentials can be supplied on the command line, from environment variables
 # (TABLEAU_SERVER, TABLEAU_SITE, TABLEAU_TOKEN_NAME, TABLEAU_TOKEN_VALUE,
-# TABLEAU_USERNAME, TABLEAU_PASSWORD), from a `.env` file in the current
-# working directory, or interactively via getpass. Prefer env or a .env file
-# over CLI args so secrets do not end up in your shell history.
+# TABLEAU_USERNAME, TABLEAU_PASSWORD, TABLEAU_JWT, TABLEAU_JWT_FILE), from a
+# `.env` file in the current working directory (or samples/, or repo root),
+# or interactively via getpass. Prefer env or a .env file over CLI args so
+# secrets do not end up in your shell history.
 ####
 
 import argparse
@@ -35,10 +36,13 @@ def set_up_and_log_in():
 
 def sample_connect_to_server(args):
     tableau_auth = build_auth(args)
-    if isinstance(tableau_auth, TSC.PersonalAccessTokenAuth):
-        print(f"\nSigning in...\nServer: {args.server}\nSite: {args.site}\nToken name: {args.token_name}")
+    if isinstance(tableau_auth, TSC.JWTAuth):
+        identifier = "JWT (Connected App)"
+    elif isinstance(tableau_auth, TSC.PersonalAccessTokenAuth):
+        identifier = f"Token name: {args.token_name}"
     else:
-        print(f"\nSigning in...\nServer: {args.server}\nSite: {args.site}\nUsername: {args.username}")
+        identifier = f"Username: {args.username}"
+    print(f"\nSigning in...\nServer: {args.server}\nSite: {args.site}\n{identifier}")
 
     # Only set this to False if you are running against a server you trust AND you know why the cert is broken
     check_ssl_certificate = True

samples/manage_subscriptions.py

@@ -18,10 +18,20 @@
 #       --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>
 #
-# To run the script, you must have installed Python 3.9 or later.
+# To run the script, you must have installed Python 3.10 or later.
 ####
 
 import argparse
@@ -56,19 +66,35 @@ 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())
-    new_sub = TSC.SubscriptionItem(
-        subject=args.subject,
-        schedule_id=args.schedule_id,
-        user_id=user_id,
-        target=target,
-    )
+
+    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,
+        )
     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)
-    print(f"Created subscription {created.id} for user {created.user_id} against {created.target}")
+    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}")
 
 
 def handle_delete(server, args):
@@ -98,8 +124,32 @@ def main():
         "--user-id",
         help="User to subscribe. Defaults to the signed-in user.",
     )
-    create_p.add_argument("--attach-image", action="store_true", default=True, help="Attach a PNG snapshot (default).")
-    create_p.add_argument("--attach-pdf", action="store_true", default=False, help="Also attach a PDF snapshot.")
+    # BooleanOptionalAction (Python 3.9+) gives us --attach-image / --no-attach-image
+    # so users can opt out of the default PNG snapshot. Same for the PDF pair for
+    # symmetry, even though its default is False.
+    create_p.add_argument(
+        "--attach-image",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Attach a PNG snapshot (default: on; pass --no-attach-image to disable).",
+    )
+    create_p.add_argument(
+        "--attach-pdf",
+        action=argparse.BooleanOptionalAction,
+        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/move_workbook_sites.py

@@ -4,7 +4,7 @@
 # a workbook that matches a given name, download the workbook,
 # and then publish it to the destination site.
 #
-# To run the script, you must have installed Python 3.7 or later.
+# To run the script, you must have installed Python 3.10 or later.
 ####
 
 import argparse