Update samples and tests to pass content range as plain strings directly

Co-authored-by: changjian-wang <15209050+changjian-wang@users.noreply.github.com>

Author: Copilot

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_analyze_binary_async.py

@@ -136,24 +136,55 @@ async def main() -> None:
         # [END analyze_binary_with_combined_content_range]
 
         # [START analyze_binary_with_raw_content_range]
-        # You can also pass a range string directly to the ContentRange constructor.
-        # This is equivalent to using the factory methods and is useful for dynamically
-        # constructed or user-supplied ranges.
-        # Analyze pages 1-3, page 5, and pages 9 onward using a raw range string.
-        # This is equivalent to: ContentRange.combine(ContentRange.pages(1, 3), ContentRange.page(5), ContentRange.pages_from(9))
-        print("\nAnalyzing with raw ContentRange string '1-3,5,9-'...")
-        raw_range_poller = await client.begin_analyze_binary(
+        # You can also pass content range as a plain string directly, without using
+        # ContentRange factory methods. The wire format is the same as what the factory methods produce.
+
+        # "1-3" — pages 1 through 3 (equivalent to ContentRange.pages(1, 3))
+        print("\nAnalyzing pages 1-3 with raw string '1-3'...")
+        raw_pages_poller = await client.begin_analyze_binary(
+            analyzer_id="prebuilt-documentSearch",
+            binary_input=multi_page_bytes,
+            content_range="1-3",
+        )
+        raw_pages_result: AnalysisResult = await raw_pages_poller.result()
+
+        if isinstance(raw_pages_result.contents[0], DocumentContent):
+            raw_pages_doc = raw_pages_result.contents[0]
+            print(
+                f"Raw '1-3' returned pages"
+                f" {raw_pages_doc.start_page_number} - {raw_pages_doc.end_page_number}"
+            )
+
+        # "9-" — pages 9 onward (equivalent to ContentRange.pages_from(9))
+        print("\nAnalyzing pages 9 onward with raw string '9-'...")
+        raw_from_poller = await client.begin_analyze_binary(
+            analyzer_id="prebuilt-documentSearch",
+            binary_input=multi_page_bytes,
+            content_range="9-",
+        )
+        raw_from_result: AnalysisResult = await raw_from_poller.result()
+
+        if isinstance(raw_from_result.contents[0], DocumentContent):
+            raw_from_doc = raw_from_result.contents[0]
+            print(
+                f"Raw '9-' returned pages"
+                f" {raw_from_doc.start_page_number} - {raw_from_doc.end_page_number}"
+            )
+
+        # "1-3,5,9-" — combined ranges (equivalent to ContentRange.combine(pages(1,3), page(5), pages_from(9)))
+        print("\nAnalyzing combined pages (1-3, 5, 9-) with raw string '1-3,5,9-'...")
+        raw_combine_poller = await client.begin_analyze_binary(
             analyzer_id="prebuilt-documentSearch",
             binary_input=multi_page_bytes,
-            content_range=ContentRange("1-3,5,9-"),
+            content_range="1-3,5,9-",
         )
-        raw_range_result: AnalysisResult = await raw_range_poller.result()
+        raw_combine_result: AnalysisResult = await raw_combine_poller.result()
 
-        if isinstance(raw_range_result.contents[0], DocumentContent):
-            raw_doc = raw_range_result.contents[0]
+        if isinstance(raw_combine_result.contents[0], DocumentContent):
+            raw_combine_doc = raw_combine_result.contents[0]
             print(
-                f"Raw ContentRange analysis returned pages"
-                f" {raw_doc.start_page_number} - {raw_doc.end_page_number}"
+                f"Raw '1-3,5,9-' returned pages"
+                f" {raw_combine_doc.start_page_number} - {raw_combine_doc.end_page_number}"
             )
         # [END analyze_binary_with_raw_content_range]
 

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_analyze_url_async.py

@@ -262,18 +262,16 @@ async def main() -> None:
         # [END analyze_video_url_with_additional_content_ranges]
 
         # [START analyze_video_url_with_raw_content_range]
-        # You can also pass a range string directly to the ContentRange constructor.
-        # Time ranges use milliseconds on the wire. This is useful for dynamically
-        # constructed or user-supplied ranges.
-        # Analyze the first 5 seconds using a raw range string (milliseconds).
-        # This is equivalent to: ContentRange.time_range(timedelta(0), timedelta(seconds=5))
-        print("\nAnalyzing first 5 seconds of video with raw ContentRange string '0-5000'...")
+        # You can also pass content range as a plain string directly for video time ranges.
+        # Time ranges use milliseconds. This is useful for dynamically constructed or user-supplied ranges.
+        # "0-5000" — analyze the first 5 seconds (equivalent to ContentRange.time_range(timedelta(0), timedelta(seconds=5)))
+        print("\nAnalyzing first 5 seconds of video with raw string '0-5000'...")
         raw_video_range_poller = await client.begin_analyze(
             analyzer_id="prebuilt-videoSearch",
             inputs=[
                 AnalysisInput(
                     url=video_url,
-                    content_range=str(ContentRange("0-5000")),
+                    content_range="0-5000",
                 )
             ],
         )
@@ -282,7 +280,7 @@ async def main() -> None:
         for raw_media in raw_video_range_result.contents:
             raw_video_content = cast(AudioVisualContent, raw_media)
             print(
-                f"Raw ContentRange segment:"
+                f"Raw '0-5000' segment:"
                 f" {raw_video_content.start_time_ms} ms - {raw_video_content.end_time_ms} ms"
             )
         # [END analyze_video_url_with_raw_content_range]
@@ -398,24 +396,24 @@ async def main() -> None:
         # [END analyze_audio_url_with_additional_content_ranges]
 
         # [START analyze_audio_url_with_raw_content_range]
-        # You can also pass a range string directly for audio time ranges.
-        # Analyze audio from 5 seconds onward using a raw range string (milliseconds).
-        # This is equivalent to: ContentRange.time_range_from(timedelta(seconds=5))
-        print("\nAnalyzing audio from 5 seconds onward with raw ContentRange string '5000-'...")
+        # You can also pass content range as a plain string directly for audio time ranges.
+        # Time ranges use milliseconds. This is useful for dynamically constructed or user-supplied ranges.
+        # "5000-" — analyze from 5 seconds onward (equivalent to ContentRange.time_range_from(timedelta(seconds=5)))
+        print("\nAnalyzing audio from 5 seconds onward with raw string '5000-'...")
         raw_audio_range_poller = await client.begin_analyze(
             analyzer_id="prebuilt-audioSearch",
             inputs=[
                 AnalysisInput(
                     url=audio_url,
-                    content_range=str(ContentRange("5000-")),
+                    content_range="5000-",
                 )
             ],
         )
         raw_audio_range_result = await raw_audio_range_poller.result()
 
         raw_audio_content = cast(AudioVisualContent, raw_audio_range_result.contents[0])
         print(
-            f"Raw ContentRange audio analysis:"
+            f"Raw '5000-' audio analysis:"
             f" {raw_audio_content.start_time_ms} ms onward"
         )
         # [END analyze_audio_url_with_raw_content_range]

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/sample_analyze_binary.py

@@ -128,22 +128,47 @@ def main() -> None:
     # [END analyze_binary_with_combined_content_range]
 
     # [START analyze_binary_with_raw_content_range]
-    # You can also pass a range string directly to the ContentRange constructor.
-    # This is equivalent to using the factory methods and is useful for dynamically
-    # constructed or user-supplied ranges.
-    # Analyze pages 1-3, page 5, and pages 9 onward using a raw range string.
-    # This is equivalent to: ContentRange.combine(ContentRange.pages(1, 3), ContentRange.page(5), ContentRange.pages_from(9))
-    print("\nAnalyzing with raw ContentRange string '1-3,5,9-'...")
-    raw_range_poller = client.begin_analyze_binary(
+    # You can also pass content range as a plain string directly, without using
+    # ContentRange factory methods. The wire format is the same as what the factory methods produce.
+
+    # "1-3" — pages 1 through 3 (equivalent to ContentRange.pages(1, 3))
+    print("\nAnalyzing pages 1-3 with raw string '1-3'...")
+    raw_pages_poller = client.begin_analyze_binary(
+        analyzer_id="prebuilt-documentSearch",
+        binary_input=multi_page_bytes,
+        content_range="1-3",
+    )
+    raw_pages_result: AnalysisResult = raw_pages_poller.result()
+
+    if isinstance(raw_pages_result.contents[0], DocumentContent):
+        raw_pages_doc = raw_pages_result.contents[0]
+        print(f"Raw '1-3' returned pages {raw_pages_doc.start_page_number} - {raw_pages_doc.end_page_number}")
+
+    # "9-" — pages 9 onward (equivalent to ContentRange.pages_from(9))
+    print("\nAnalyzing pages 9 onward with raw string '9-'...")
+    raw_from_poller = client.begin_analyze_binary(
+        analyzer_id="prebuilt-documentSearch",
+        binary_input=multi_page_bytes,
+        content_range="9-",
+    )
+    raw_from_result: AnalysisResult = raw_from_poller.result()
+
+    if isinstance(raw_from_result.contents[0], DocumentContent):
+        raw_from_doc = raw_from_result.contents[0]
+        print(f"Raw '9-' returned pages {raw_from_doc.start_page_number} - {raw_from_doc.end_page_number}")
+
+    # "1-3,5,9-" — combined ranges (equivalent to ContentRange.combine(pages(1,3), page(5), pages_from(9)))
+    print("\nAnalyzing combined pages (1-3, 5, 9-) with raw string '1-3,5,9-'...")
+    raw_combine_poller = client.begin_analyze_binary(
         analyzer_id="prebuilt-documentSearch",
         binary_input=multi_page_bytes,
-        content_range=ContentRange("1-3,5,9-"),
+        content_range="1-3,5,9-",
     )
-    raw_range_result: AnalysisResult = raw_range_poller.result()
+    raw_combine_result: AnalysisResult = raw_combine_poller.result()
 
-    if isinstance(raw_range_result.contents[0], DocumentContent):
-        raw_doc = raw_range_result.contents[0]
-        print(f"Raw ContentRange analysis returned pages {raw_doc.start_page_number} - {raw_doc.end_page_number}")
+    if isinstance(raw_combine_result.contents[0], DocumentContent):
+        raw_combine_doc = raw_combine_result.contents[0]
+        print(f"Raw '1-3,5,9-' returned pages {raw_combine_doc.start_page_number} - {raw_combine_doc.end_page_number}")
     # [END analyze_binary_with_raw_content_range]
 
     # [START extract_markdown]

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/sample_analyze_url.py

@@ -258,18 +258,16 @@ def main() -> None:
     # [END analyze_video_url_with_additional_content_ranges]
 
     # [START analyze_video_url_with_raw_content_range]
-    # You can also pass a range string directly to the ContentRange constructor.
-    # Time ranges use milliseconds on the wire. This is useful for dynamically
-    # constructed or user-supplied ranges.
-    # Analyze the first 5 seconds using a raw range string (milliseconds).
-    # This is equivalent to: ContentRange.time_range(timedelta(0), timedelta(seconds=5))
-    print("\nAnalyzing first 5 seconds of video with raw ContentRange string '0-5000'...")
+    # You can also pass content range as a plain string directly for video time ranges.
+    # Time ranges use milliseconds. This is useful for dynamically constructed or user-supplied ranges.
+    # "0-5000" — analyze the first 5 seconds (equivalent to ContentRange.time_range(timedelta(0), timedelta(seconds=5)))
+    print("\nAnalyzing first 5 seconds of video with raw string '0-5000'...")
     raw_video_range_poller = client.begin_analyze(
         analyzer_id="prebuilt-videoSearch",
         inputs=[
             AnalysisInput(
                 url=video_url,
-                content_range=str(ContentRange("0-5000")),
+                content_range="0-5000",
             )
         ],
     )
@@ -278,7 +276,7 @@ def main() -> None:
     for raw_media in raw_video_range_result.contents:
         raw_video_content = cast(AudioVisualContent, raw_media)
         print(
-            f"Raw ContentRange segment:"
+            f"Raw '0-5000' segment:"
             f" {raw_video_content.start_time_ms} ms - {raw_video_content.end_time_ms} ms"
         )
     # [END analyze_video_url_with_raw_content_range]
@@ -391,24 +389,24 @@ def main() -> None:
     # [END analyze_audio_url_with_additional_content_ranges]
 
     # [START analyze_audio_url_with_raw_content_range]
-    # You can also pass a range string directly for audio time ranges.
-    # Analyze audio from 5 seconds onward using a raw range string (milliseconds).
-    # This is equivalent to: ContentRange.time_range_from(timedelta(seconds=5))
-    print("\nAnalyzing audio from 5 seconds onward with raw ContentRange string '5000-'...")
+    # You can also pass content range as a plain string directly for audio time ranges.
+    # Time ranges use milliseconds. This is useful for dynamically constructed or user-supplied ranges.
+    # "5000-" — analyze from 5 seconds onward (equivalent to ContentRange.time_range_from(timedelta(seconds=5)))
+    print("\nAnalyzing audio from 5 seconds onward with raw string '5000-'...")
     raw_audio_range_poller = client.begin_analyze(
         analyzer_id="prebuilt-audioSearch",
         inputs=[
             AnalysisInput(
                 url=audio_url,
-                content_range=str(ContentRange("5000-")),
+                content_range="5000-",
             )
         ],
     )
     raw_audio_range_result = raw_audio_range_poller.result()
 
     raw_audio_content = cast(AudioVisualContent, raw_audio_range_result.contents[0])
     print(
-        f"Raw ContentRange audio analysis:"
+        f"Raw '5000-' audio analysis:"
         f" {raw_audio_content.start_time_ms} ms onward"
     )
     # [END analyze_audio_url_with_raw_content_range]