From af409b71cae19ac928485ecbd1ac1f27f6b9a572 Mon Sep 17 00:00:00 2001 From: Monica Renneke Date: Mon, 24 Aug 2026 16:50:20 -0400 Subject: [PATCH 1/3] Clarify placeholder-editing guidance and add run-timing output - Add inline "DO NOT UPDATE" markers on the validate_inputs() checks and a bounded "SET THE VARIABLES BELOW" section around the settings block, so the block a reader actually edits is visually distinct from the validation logic and from the values already preset for them (API_URL, EXTRACTION_PROMPT). - Print a start/end timestamp and elapsed run time after the job output is downloaded, so readers can see how long a run actually took without needing an external stopwatch. Co-Authored-By: Claude Sonnet 5 --- transform/sample-code/extract-quickstart.py | 31 ++++++++++++++++--- transform/sample-code/partition-quickstart.py | 30 +++++++++++++++--- 2 files changed, 53 insertions(+), 8 deletions(-) diff --git a/transform/sample-code/extract-quickstart.py b/transform/sample-code/extract-quickstart.py index 63d673e..dcbe322 100644 --- a/transform/sample-code/extract-quickstart.py +++ b/transform/sample-code/extract-quickstart.py @@ -8,32 +8,44 @@ from unstructured_client.models.shared import BodyCreateJob, InputFiles -# Set the variables below this validation function before running this script. +# Set the variables BELOW THIS VALIDATION FUNCTION before running this script. def validate_inputs(api_key, input_dir, output_dir): # Checks that the settings below have been changed from their placeholder values. - if api_key in ("YOUR_API_KEY_HERE", ""): + # Be sure to EDIT THE VARIABLE SETTINGS BELOW THIS BLOCK, + # and NOT THE STRINGS HERE that we validate against. + if api_key in ("YOUR_API_KEY_HERE", ""): # <-- DO NOT UPDATE raise SystemExit("Set API_KEY to your Unstructured API key before running this script.") - if input_dir in ("/full/path/to/your/input/directory", ""): + if input_dir in ("/full/path/to/your/input/directory", ""): # <-- DO NOT UPDATE raise SystemExit("Set INPUT_DIR to the local directory containing the file (or files) you want to process before running this script.") - if output_dir in ("/full/path/to/your/output/directory", ""): + if output_dir in ("/full/path/to/your/output/directory", ""): # <-- DO NOT UPDATE raise SystemExit("Set OUTPUT_DIR to the local directory where you want the results saved before running this script.") +# ---------------------------------------------------------------------------------- +# SET THE VARIABLES BELOW as they apply to you. +# ---------------------------------------------------------------------------------- # API_KEY is included here as a local variable for ease of use in this quickstart. # This isn't best practice outside of local testing on your own machine. Once # you've added your real key, don't share this file or check it into any # repositories. API_KEY = "YOUR_API_KEY_HERE" +# API_URL is already preset for you. Do not change the value. API_URL = "https://platform-api.transform.unstructured.io/api/v1" # The local directory containing the file (or files) you want to process. +# This folder should contain only the file(s) you want to process, since the +# script processes every file it finds here. INPUT_DIR = "/full/path/to/your/input/directory" # The local directory where you want the results saved. +# Use a different folder than INPUT_DIR, or on a second run the script will +# also try to process the JSON files already saved here. OUTPUT_DIR = "/full/path/to/your/output/directory" +# EXTRACTION_PROMPT is already preset for you. # EXTRACTION_PROMPT tells the LLM how to format, normalize, or present the values your # schema already defines. It doesn't describe which fields to extract. The schema # further down in this script does that. EXTRACTION_PROMPT = "Dates are in MM/DD/YYYY format on the form. Represent them as YYYY-MM-DD. Combine the home address, city, state, and ZIP code fields into a single address string." +# ---------------------------------------------------------------------------------- validate_inputs(API_KEY, INPUT_DIR, OUTPUT_DIR) @@ -43,6 +55,8 @@ def validate_inputs(api_key, input_dir, output_dir): ) # Step 1: Create the job. +start_time = time.monotonic() +start_timestamp = time.strftime("%Y-%m-%d %H:%M:%S") input_files = [] for filename in os.listdir(INPUT_DIR): full_path = os.path.join(INPUT_DIR, filename) @@ -170,3 +184,12 @@ def validate_inputs(api_key, input_dir, output_dir): with open(output_path, "w") as f: json.dump(response.any, f, indent=4) print(f"Saved: {output_path}") + +end_timestamp = time.strftime("%Y-%m-%d %H:%M:%S") +elapsed_seconds = int(time.monotonic() - start_time) +elapsed_minutes, elapsed_remainder_seconds = divmod(elapsed_seconds, 60) + +print("") +print(f"Start time: {start_timestamp}") +print(f"End time: {end_timestamp}") +print(f"Elapsed time: {elapsed_seconds} seconds ({elapsed_minutes}m {elapsed_remainder_seconds}s)") diff --git a/transform/sample-code/partition-quickstart.py b/transform/sample-code/partition-quickstart.py index cedac13..d7716e5 100644 --- a/transform/sample-code/partition-quickstart.py +++ b/transform/sample-code/partition-quickstart.py @@ -8,27 +8,38 @@ from unstructured_client.models.shared import BodyCreateJob, InputFiles -# Set the variables below this validation function before running this script. +# Set the variables BELOW THIS VALIDATION FUNCTION before running this script. def validate_inputs(api_key, input_dir, output_dir): # Checks that the settings below have been changed from their placeholder values. - if api_key in ("YOUR_API_KEY_HERE", ""): + # Be sure to EDIT THE VARIABLE SETTINGS BELOW THIS BLOCK, + # and NOT THE STRINGS HERE that we validate against. + if api_key in ("YOUR_API_KEY_HERE", ""): # <-- DO NOT UPDATE raise SystemExit("Set API_KEY to your Unstructured API key before running this script.") - if input_dir in ("/full/path/to/your/input/directory", ""): + if input_dir in ("/full/path/to/your/input/directory", ""): # <-- DO NOT UPDATE raise SystemExit("Set INPUT_DIR to the local directory containing the file (or files) you want to process before running this script.") - if output_dir in ("/full/path/to/your/output/directory", ""): + if output_dir in ("/full/path/to/your/output/directory", ""): # <-- DO NOT UPDATE raise SystemExit("Set OUTPUT_DIR to the local directory where you want the results saved before running this script.") +# ---------------------------------------------------------------------------------- +# SET THE VARIABLES BELOW as they apply to you. +# ---------------------------------------------------------------------------------- # API_KEY is included here as a local variable for ease of use in this quickstart. # This isn't best practice outside of local testing on your own machine. Once # you've added your real key, don't share this file or check it into any # repositories. API_KEY = "YOUR_API_KEY_HERE" +# API_URL is already preset for you. Do not change the value. API_URL = "https://platform-api.transform.unstructured.io/api/v1" # The local directory containing the file (or files) you want to process. +# This folder should contain only the file(s) you want to process, since the +# script processes every file it finds here. INPUT_DIR = "/full/path/to/your/input/directory" # The local directory where you want the results saved. +# Use a different folder than INPUT_DIR, or on a second run the script will +# also try to process the JSON files already saved here. OUTPUT_DIR = "/full/path/to/your/output/directory" +# ---------------------------------------------------------------------------------- validate_inputs(API_KEY, INPUT_DIR, OUTPUT_DIR) @@ -38,6 +49,8 @@ def validate_inputs(api_key, input_dir, output_dir): ) # Step 1: Create the job. +start_time = time.monotonic() +start_timestamp = time.strftime("%Y-%m-%d %H:%M:%S") input_files = [] for filename in os.listdir(INPUT_DIR): full_path = os.path.join(INPUT_DIR, filename) @@ -109,3 +122,12 @@ def validate_inputs(api_key, input_dir, output_dir): with open(output_path, "w") as f: json.dump(response.any, f, indent=4) print(f"Saved: {output_path}") + +end_timestamp = time.strftime("%Y-%m-%d %H:%M:%S") +elapsed_seconds = int(time.monotonic() - start_time) +elapsed_minutes, elapsed_remainder_seconds = divmod(elapsed_seconds, 60) + +print("") +print(f"Start time: {start_timestamp}") +print(f"End time: {end_timestamp}") +print(f"Elapsed time: {elapsed_seconds} seconds ({elapsed_minutes}m {elapsed_remainder_seconds}s)") From 67a3a8bf03e3f915784137e45588d31146f0a816 Mon Sep 17 00:00:00 2001 From: Monica Renneke Date: Mon, 24 Aug 2026 17:22:51 -0400 Subject: [PATCH 2/3] Remove run-timing output per review feedback Keep the validate_inputs() clarity comments and the "SET THE VARIABLES BELOW" section from this PR; drop the start/end timestamp and elapsed time printing added in the previous commit. Co-Authored-By: Claude Sonnet 5 --- transform/sample-code/extract-quickstart.py | 11 ----------- transform/sample-code/partition-quickstart.py | 11 ----------- 2 files changed, 22 deletions(-) diff --git a/transform/sample-code/extract-quickstart.py b/transform/sample-code/extract-quickstart.py index dcbe322..e6bec5d 100644 --- a/transform/sample-code/extract-quickstart.py +++ b/transform/sample-code/extract-quickstart.py @@ -55,8 +55,6 @@ def validate_inputs(api_key, input_dir, output_dir): ) # Step 1: Create the job. -start_time = time.monotonic() -start_timestamp = time.strftime("%Y-%m-%d %H:%M:%S") input_files = [] for filename in os.listdir(INPUT_DIR): full_path = os.path.join(INPUT_DIR, filename) @@ -184,12 +182,3 @@ def validate_inputs(api_key, input_dir, output_dir): with open(output_path, "w") as f: json.dump(response.any, f, indent=4) print(f"Saved: {output_path}") - -end_timestamp = time.strftime("%Y-%m-%d %H:%M:%S") -elapsed_seconds = int(time.monotonic() - start_time) -elapsed_minutes, elapsed_remainder_seconds = divmod(elapsed_seconds, 60) - -print("") -print(f"Start time: {start_timestamp}") -print(f"End time: {end_timestamp}") -print(f"Elapsed time: {elapsed_seconds} seconds ({elapsed_minutes}m {elapsed_remainder_seconds}s)") diff --git a/transform/sample-code/partition-quickstart.py b/transform/sample-code/partition-quickstart.py index d7716e5..0172773 100644 --- a/transform/sample-code/partition-quickstart.py +++ b/transform/sample-code/partition-quickstart.py @@ -49,8 +49,6 @@ def validate_inputs(api_key, input_dir, output_dir): ) # Step 1: Create the job. -start_time = time.monotonic() -start_timestamp = time.strftime("%Y-%m-%d %H:%M:%S") input_files = [] for filename in os.listdir(INPUT_DIR): full_path = os.path.join(INPUT_DIR, filename) @@ -122,12 +120,3 @@ def validate_inputs(api_key, input_dir, output_dir): with open(output_path, "w") as f: json.dump(response.any, f, indent=4) print(f"Saved: {output_path}") - -end_timestamp = time.strftime("%Y-%m-%d %H:%M:%S") -elapsed_seconds = int(time.monotonic() - start_time) -elapsed_minutes, elapsed_remainder_seconds = divmod(elapsed_seconds, 60) - -print("") -print(f"Start time: {start_timestamp}") -print(f"End time: {end_timestamp}") -print(f"Elapsed time: {elapsed_seconds} seconds ({elapsed_minutes}m {elapsed_remainder_seconds}s)") From a73ddf1f7505bdd5d1053673dae818726dc022c9 Mon Sep 17 00:00:00 2001 From: Monica Renneke Date: Mon, 24 Aug 2026 17:50:39 -0400 Subject: [PATCH 3/3] Reorder settings before validation, drop redundant guard comments Move the editable settings block (API_KEY, INPUT_DIR, OUTPUT_DIR) before validate_inputs(), so a reader hits what they need to edit before the validation logic. Simplify validate_inputs()'s comments now that the settings a reader edits sit visually apart from the function entirely, rather than needing inline markers to distinguish them. Matches the same restructuring in docs PR #1090's quickstart-python.mdx. Co-Authored-By: Claude Sonnet 5 --- transform/sample-code/extract-quickstart.py | 31 +++++++++---------- transform/sample-code/partition-quickstart.py | 28 +++++++---------- 2 files changed, 26 insertions(+), 33 deletions(-) diff --git a/transform/sample-code/extract-quickstart.py b/transform/sample-code/extract-quickstart.py index e6bec5d..c6f9680 100644 --- a/transform/sample-code/extract-quickstart.py +++ b/transform/sample-code/extract-quickstart.py @@ -7,20 +7,6 @@ from unstructured_client.models.operations import CreateJobRequest, DownloadJobOutputRequest from unstructured_client.models.shared import BodyCreateJob, InputFiles - -# Set the variables BELOW THIS VALIDATION FUNCTION before running this script. -def validate_inputs(api_key, input_dir, output_dir): - # Checks that the settings below have been changed from their placeholder values. - # Be sure to EDIT THE VARIABLE SETTINGS BELOW THIS BLOCK, - # and NOT THE STRINGS HERE that we validate against. - if api_key in ("YOUR_API_KEY_HERE", ""): # <-- DO NOT UPDATE - raise SystemExit("Set API_KEY to your Unstructured API key before running this script.") - if input_dir in ("/full/path/to/your/input/directory", ""): # <-- DO NOT UPDATE - raise SystemExit("Set INPUT_DIR to the local directory containing the file (or files) you want to process before running this script.") - if output_dir in ("/full/path/to/your/output/directory", ""): # <-- DO NOT UPDATE - raise SystemExit("Set OUTPUT_DIR to the local directory where you want the results saved before running this script.") - - # ---------------------------------------------------------------------------------- # SET THE VARIABLES BELOW as they apply to you. # ---------------------------------------------------------------------------------- @@ -29,8 +15,6 @@ def validate_inputs(api_key, input_dir, output_dir): # you've added your real key, don't share this file or check it into any # repositories. API_KEY = "YOUR_API_KEY_HERE" -# API_URL is already preset for you. Do not change the value. -API_URL = "https://platform-api.transform.unstructured.io/api/v1" # The local directory containing the file (or files) you want to process. # This folder should contain only the file(s) you want to process, since the # script processes every file it finds here. @@ -39,13 +23,26 @@ def validate_inputs(api_key, input_dir, output_dir): # Use a different folder than INPUT_DIR, or on a second run the script will # also try to process the JSON files already saved here. OUTPUT_DIR = "/full/path/to/your/output/directory" +# ---------------------------------------------------------------------------------- + +# Validate the variable settings +def validate_inputs(api_key, input_dir, output_dir): + if api_key in ("YOUR_API_KEY_HERE", ""): + raise SystemExit("Set API_KEY to your Unstructured API key before running this script.") + if input_dir in ("/full/path/to/your/input/directory", ""): + raise SystemExit("Set INPUT_DIR to the local directory containing the file (or files) you want to process before running this script.") + if output_dir in ("/full/path/to/your/output/directory", ""): + raise SystemExit("Set OUTPUT_DIR to the local directory where you want the results saved before running this script.") + +# API_URL is already preset for you. Do not change the value. +API_URL = "https://platform-api.transform.unstructured.io/api/v1" # EXTRACTION_PROMPT is already preset for you. # EXTRACTION_PROMPT tells the LLM how to format, normalize, or present the values your # schema already defines. It doesn't describe which fields to extract. The schema # further down in this script does that. EXTRACTION_PROMPT = "Dates are in MM/DD/YYYY format on the form. Represent them as YYYY-MM-DD. Combine the home address, city, state, and ZIP code fields into a single address string." -# ---------------------------------------------------------------------------------- + validate_inputs(API_KEY, INPUT_DIR, OUTPUT_DIR) diff --git a/transform/sample-code/partition-quickstart.py b/transform/sample-code/partition-quickstart.py index 0172773..62b0823 100644 --- a/transform/sample-code/partition-quickstart.py +++ b/transform/sample-code/partition-quickstart.py @@ -7,20 +7,6 @@ from unstructured_client.models.operations import CreateJobRequest, DownloadJobOutputRequest from unstructured_client.models.shared import BodyCreateJob, InputFiles - -# Set the variables BELOW THIS VALIDATION FUNCTION before running this script. -def validate_inputs(api_key, input_dir, output_dir): - # Checks that the settings below have been changed from their placeholder values. - # Be sure to EDIT THE VARIABLE SETTINGS BELOW THIS BLOCK, - # and NOT THE STRINGS HERE that we validate against. - if api_key in ("YOUR_API_KEY_HERE", ""): # <-- DO NOT UPDATE - raise SystemExit("Set API_KEY to your Unstructured API key before running this script.") - if input_dir in ("/full/path/to/your/input/directory", ""): # <-- DO NOT UPDATE - raise SystemExit("Set INPUT_DIR to the local directory containing the file (or files) you want to process before running this script.") - if output_dir in ("/full/path/to/your/output/directory", ""): # <-- DO NOT UPDATE - raise SystemExit("Set OUTPUT_DIR to the local directory where you want the results saved before running this script.") - - # ---------------------------------------------------------------------------------- # SET THE VARIABLES BELOW as they apply to you. # ---------------------------------------------------------------------------------- @@ -29,8 +15,6 @@ def validate_inputs(api_key, input_dir, output_dir): # you've added your real key, don't share this file or check it into any # repositories. API_KEY = "YOUR_API_KEY_HERE" -# API_URL is already preset for you. Do not change the value. -API_URL = "https://platform-api.transform.unstructured.io/api/v1" # The local directory containing the file (or files) you want to process. # This folder should contain only the file(s) you want to process, since the # script processes every file it finds here. @@ -41,6 +25,18 @@ def validate_inputs(api_key, input_dir, output_dir): OUTPUT_DIR = "/full/path/to/your/output/directory" # ---------------------------------------------------------------------------------- +# Validate the variable settings +def validate_inputs(api_key, input_dir, output_dir): + if api_key in ("YOUR_API_KEY_HERE", ""): + raise SystemExit("Set API_KEY to your Unstructured API key before running this script.") + if input_dir in ("/full/path/to/your/input/directory", ""): + raise SystemExit("Set INPUT_DIR to the local directory containing the file (or files) you want to process before running this script.") + if output_dir in ("/full/path/to/your/output/directory", ""): + raise SystemExit("Set OUTPUT_DIR to the local directory where you want the results saved before running this script.") + +# API_URL is already preset for you. Do not change the value. +API_URL = "https://platform-api.transform.unstructured.io/api/v1" + validate_inputs(API_KEY, INPUT_DIR, OUTPUT_DIR) client = UnstructuredClient(