samples: credential helper, pagination fixes, and new jobs/subscriptions samples

samples/_shared.py

@@ -0,0 +1,201 @@
+####
+# Shared helpers for the sample scripts in this directory.
+#
+# The most important thing here is `resolve_credentials`, which lets samples
+# accept a Tableau server URL, site, and credentials from three sources:
+#
+#   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.
+#
+# 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.
+####
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import os
+from pathlib import Path
+from typing import Iterable
+
+import tableauserverclient as TSC
+
+# Recognized environment variable names, in the order we look them up.
+# Older samples used TABLEAU_SERVER etc; keep those working as aliases.
+_ENV_ALIASES: dict[str, tuple[str, ...]] = {
+    "server": ("TABLEAU_SERVER", "SERVER"),
+    "site": ("TABLEAU_SITE", "SITE"),
+    "token_name": ("TABLEAU_TOKEN_NAME", "TOKEN_NAME"),
+    "token_value": ("TABLEAU_TOKEN_VALUE", "TOKEN_VALUE"),
+    "username": ("TABLEAU_USERNAME", "USERNAME"),
+    "password": ("TABLEAU_PASSWORD", "PASSWORD"),
+}
+
+
+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.
+    """
+    parser.add_argument("--server", "-s", help="server address (env: TABLEAU_SERVER)")
+    parser.add_argument("--site", "-t", help="site content URL (env: TABLEAU_SITE)")
+    parser.add_argument(
+        "--token-name",
+        help="name of the personal access token used to sign into the server " "(env: TABLEAU_TOKEN_NAME)",
+    )
+    parser.add_argument(
+        "--token-value",
+        help="value of the personal access token used to sign into the server "
+        "(env: TABLEAU_TOKEN_VALUE). Prefer the env var or interactive prompt over the "
+        "command line so the secret does not land in shell history.",
+    )
+    parser.add_argument(
+        "--username",
+        "-u",
+        help="username to sign into the server (env: TABLEAU_USERNAME). Only used if "
+        "no personal access token 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(
+        "--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.",
+    )
+    parser.add_argument(
+        "--logging-level",
+        "-l",
+        choices=["debug", "info", "error"],
+        default="error",
+        help="desired logging level (set to error by default)",
+    )
+
+
+def _load_env_file(path: Path) -> None:
+    """Very small `.env` loader: `KEY=value` per line, `#` for comments.
+
+    We do not want a runtime dependency on python-dotenv for the samples,
+    so this parses just the common cases. Existing env vars are not
+    overwritten -- a value already in `os.environ` wins.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip().strip("'\"")
+        if key and key not in os.environ:
+            os.environ[key] = value
+
+
+def _first_env(names: Iterable[str]) -> str | None:
+    for name in names:
+        val = os.environ.get(name)
+        if val:
+            return val
+    return None
+
+
+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).
+
+    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.
+    """
+    # 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 each field, prefer the CLI arg, then env, then prompt.
+    for field, env_names in _ENV_ALIASES.items():
+        current = getattr(args, field, None)
+        if current:
+            continue
+        env_val = _first_env(env_names)
+        if env_val:
+            setattr(args, field, env_val)
+
+    if not allow_prompt:
+        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.
+    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)
+
+    if 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
+
+    # 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.")
+    print("(Set TABLEAU_TOKEN_NAME / TABLEAU_TOKEN_VALUE in your env or a .env file to skip this prompt.)")
+    args.token_name = input("Personal access token name: ").strip()
+    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`."""
+    site = getattr(args, "site", None) or ""
+    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."
+    )
+
+
+def sign_in(args: argparse.Namespace, *, use_server_version: bool = True) -> TSC.Server:
+    """Convenience helper: resolve credentials, build the server, and sign in.
+
+    The caller is responsible for calling `server.auth.sign_out()` or using
+    the `with server.auth.sign_in(...)` context manager pattern themselves
+    when they need finer control. This helper is intended for the small
+    samples that just want a signed-in server object to poke at.
+    """
+    resolve_credentials(args)
+    auth = build_auth(args)
+    server = TSC.Server(args.server, use_server_version=use_server_version)
+    server.auth.sign_in(auth)
+    return server

samples/explore_datasource.py

@@ -43,9 +43,10 @@ def main():
     tableau_auth = TSC.PersonalAccessTokenAuth(args.token_name, args.token_value, site_id=args.site)
     server = TSC.Server(args.server, use_server_version=True)
     with server.auth.sign_in(tableau_auth):
-        # Query projects for use when demonstrating publishing and updating
-        all_projects, pagination_item = server.projects.get()
-        default_project = next((project for project in all_projects if project.is_default()), None)
+        # Query projects for use when demonstrating publishing and updating.
+        # Use TSC.Pager (or `.all()` / `.filter()`) to iterate every page;
+        # a raw `server.projects.get()` only returns the first page.
+        default_project = next((project for project in TSC.Pager(server.projects) if project.is_default()), None)
 
         # Publish datasource if publish flag is set (-publish, -p)
         if args.publish:
@@ -59,9 +60,12 @@ def main():
             else:
                 print("Publish failed. Could not find the default project.")
 
-        # Gets all datasource items
-        all_datasources, pagination_item = server.datasources.get()
+        # Gets all datasource items. `.get()` returns only one page; use
+        # TSC.Pager to iterate every page. The first response also gives us
+        # the total_available count without paging through everything.
+        first_page, pagination_item = server.datasources.get()
         print(f"\nThere are {pagination_item.total_available} datasources on site: ")
+        all_datasources = list(TSC.Pager(server.datasources))
         print([datasource.name for datasource in all_datasources])
 
         if all_datasources:

samples/explore_favorites.py

@@ -43,8 +43,9 @@ def main():
         server.favorites.get(user)
         print(user.favorites)
 
-        # get list of workbooks
-        all_workbook_items, pagination_item = server.workbooks.get()
+        # get list of workbooks. `.get()` only returns one page; use
+        # TSC.Pager to iterate every workbook on the site.
+        all_workbook_items = list(TSC.Pager(server.workbooks))
         if all_workbook_items is not None and len(all_workbook_items) > 0:
             my_workbook = all_workbook_items[0]
             server.favorites.add_favorite(user, Resource.Workbook, all_workbook_items[0])
@@ -59,7 +60,7 @@ def main():
                 server.favorites.add_favorite_view(user, my_view)
                 print(f"View added to favorites. View Name: {my_view.name}, View ID: {my_view.id}")
 
-        all_datasource_items, pagination_item = server.datasources.get()
+        all_datasource_items = list(TSC.Pager(server.datasources))
         if all_datasource_items:
             my_datasource = all_datasource_items[0]
         server.favorites.add_favorite_datasource(user, my_datasource)

samples/explore_webhooks.py

@@ -54,9 +54,11 @@ def main():
             new_webhook = server.webhooks.create(new_webhook)
             print(f"Webhook created. ID: {new_webhook.id}")
 
-        # Gets all webhook items
-        all_webhooks, pagination_item = server.webhooks.get()
+        # Gets all webhook items. `.get()` returns only one page; use
+        # TSC.Pager to iterate every webhook on the site.
+        first_page, pagination_item = server.webhooks.get()
         print(f"\nThere are {pagination_item.total_available} webhooks on site: ")
+        all_webhooks = list(TSC.Pager(server.webhooks))
         print([webhook.name for webhook in all_webhooks])
 
         if all_webhooks:

samples/explore_workbook.py

@@ -53,8 +53,9 @@ def main():
         # Publish workbook if publish flag is set (-publish, -p)
         overwrite_true = TSC.Server.PublishMode.Overwrite
         if args.publish:
-            all_projects, pagination_item = server.projects.get()
-            default_project = next((project for project in all_projects if project.is_default()), None)
+            # Use TSC.Pager rather than a raw `.get()` because `.get()` only
+            # returns the first page of results.
+            default_project = next((project for project in TSC.Pager(server.projects) if project.is_default()), None)
 
             if default_project is not None:
                 new_workbook = TSC.WorkbookItem(default_project.id)
@@ -63,9 +64,11 @@ def main():
             else:
                 print("Publish failed. Could not find the default project.")
 
-        # Gets all workbook items
-        all_workbooks, pagination_item = server.workbooks.get()
+        # Gets all workbook items. Note that `.get()` only returns the first
+        # page of results; use TSC.Pager to iterate every page.
+        first_page, pagination_item = server.workbooks.get()
         print(f"\nThere are {pagination_item.total_available} workbooks on site: ")
+        all_workbooks = list(TSC.Pager(server.workbooks))
         print([workbook.name for workbook in all_workbooks])
 
         if all_workbooks:
@@ -123,9 +126,9 @@ def main():
                     f.write(sample_workbook.preview_image)
                 print(f"\nDownloaded preview image of workbook to {os.path.abspath(args.preview_image)}")
 
-            # get custom views
-            cvs, _ = server.custom_views.get()
-            for c in cvs:
+            # Get custom views. `.get()` only returns the first page;
+            # use TSC.Pager to iterate every custom view on the site.
+            for c in TSC.Pager(server.custom_views):
                 print(c)
 
             # for the last custom view in the list

samples/extracts.py

@@ -53,9 +53,11 @@ def main():
             if ds is None:
                 raise ValueError(f"Datasource not found for id {args.datasource}")
         else:
-            # Gets all workbook items
-            all_workbooks, pagination_item = server.workbooks.get()
+            # Gets all workbook items. `.get()` returns only the first page,
+            # so we use TSC.Pager to iterate every page.
+            first_page, pagination_item = server.workbooks.get()
             print(f"\nThere are {pagination_item.total_available} workbooks on site: ")
+            all_workbooks = list(TSC.Pager(server.workbooks))
             print([workbook.name for workbook in all_workbooks])
 
             if all_workbooks:

samples/getting_started/3_hello_universe.py

@@ -40,7 +40,7 @@ def main():
             for project in projects:
                 print(project.name)
 
-        workbooks, pagination = server.datasources.get()
+        workbooks, pagination = server.workbooks.get()
         if workbooks:
             print(f"{pagination.total_available} workbooks")
             print(workbooks[0])