docs(openapi): unify regex wording and shorten sourcePreference descriptions (#2051)

Stainless-Generated-From: bf62369f078eaf1f89353aeea1847af0bd4c0474

Author: stlc-bot

src/context/dev/resources/web.py

@@ -285,8 +285,8 @@ def map_urls(
         Args:
           domain: Domain to map, e.g. `stripe.com`.
 
-          exclude_url_regex: Optional RE2-compatible regex pattern. URLs matching this pattern are not
-              returned, even when they match urlRegex.
+          exclude_url_regex: Regex pattern. URLs matching this pattern are not returned, even when they match
+              urlRegex.
 
           headers: HTTP headers for the target origin. Non-empty headers bypass caching.
 
@@ -303,8 +303,8 @@ def map_urls(
 
           timeout_opts: Request deadline and what to return when it passes.
 
-          url_regex: Optional RE2-compatible regex pattern. Only URLs matching this pattern are
-              returned and counted against maxLinks.
+          url_regex: Regex pattern. Only URLs matching this pattern are returned and counted against
+              maxLinks.
 
           zdr: `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless
               your organization has ZDR.
@@ -1456,8 +1456,8 @@ def web_crawl_md(
 
           exclude_selectors: Remove matching elements after inclusions. Exclusions take precedence.
 
-          exclude_url_regex: RE2 regex pattern. URLs matching this pattern are never followed or scraped,
-              even when they match urlRegex. The starting URL is always scraped.
+          exclude_url_regex: Regex pattern. URLs matching this pattern are never followed or scraped, even
+              when they match urlRegex. The starting URL is always scraped.
 
           follow_subdomains: When true, follow links on subdomains of the starting URL's domain (e.g.
               docs.example.com when starting from example.com). www and apex are always
@@ -1466,11 +1466,9 @@ def web_crawl_md(
           include_frames: When true, the contents of iframes are rendered to Markdown for each crawled
               page.
 
-          include_images: Include image references in the Markdown output Only applies to
-              `html-conversion` extractions.
+          include_images: Include image references in the Markdown output (`html-conversion` only).
 
-          include_links: Preserve hyperlinks in the Markdown output Only applies to `html-conversion`
-              extractions.
+          include_links: Preserve hyperlinks in the Markdown output (`html-conversion` only).
 
           include_selectors: Keep matching HTML subtrees before converting each page to Markdown.
 
@@ -1485,18 +1483,11 @@ def web_crawl_md(
           settle_animations: Wait briefly for CSS animations and transitions to settle before reading each
               page.
 
-          shorten_base64_images: Truncate base64-encoded image data in the Markdown output Only applies to
-              `html-conversion` extractions.
+          shorten_base64_images: Truncate base64-encoded image data in the Markdown output (`html-conversion`
+              only).
 
-          source_preference: Where the Markdown should come from, in order of preference; the first usable
-              source wins. `html-conversion` converts the page HTML, and counts as unusable
-              when the conversion has almost no content (under 200 characters).
-              `markdown-direct` uses the official Markdown version the page publishes through,
-              returned as the site serves it. Defaults to
-              `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page
-              that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed.
-              Requests with include or exclude selectors never use `markdown-direct`, so they
-              must include `html-conversion`.
+          source_preference: Markdown sources in order of preference: `html-conversion` converts the page
+              HTML, `markdown-direct` uses Markdown the site publishes.
 
           stop_after_ms: Soft crawl deadline in milliseconds. Returns pages collected before the next
               deadline check.
@@ -1808,8 +1799,8 @@ async def map_urls(
         Args:
           domain: Domain to map, e.g. `stripe.com`.
 
-          exclude_url_regex: Optional RE2-compatible regex pattern. URLs matching this pattern are not
-              returned, even when they match urlRegex.
+          exclude_url_regex: Regex pattern. URLs matching this pattern are not returned, even when they match
+              urlRegex.
 
           headers: HTTP headers for the target origin. Non-empty headers bypass caching.
 
@@ -1826,8 +1817,8 @@ async def map_urls(
 
           timeout_opts: Request deadline and what to return when it passes.
 
-          url_regex: Optional RE2-compatible regex pattern. Only URLs matching this pattern are
-              returned and counted against maxLinks.
+          url_regex: Regex pattern. Only URLs matching this pattern are returned and counted against
+              maxLinks.
 
           zdr: `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless
               your organization has ZDR.
@@ -2979,8 +2970,8 @@ async def web_crawl_md(
 
           exclude_selectors: Remove matching elements after inclusions. Exclusions take precedence.
 
-          exclude_url_regex: RE2 regex pattern. URLs matching this pattern are never followed or scraped,
-              even when they match urlRegex. The starting URL is always scraped.
+          exclude_url_regex: Regex pattern. URLs matching this pattern are never followed or scraped, even
+              when they match urlRegex. The starting URL is always scraped.
 
           follow_subdomains: When true, follow links on subdomains of the starting URL's domain (e.g.
               docs.example.com when starting from example.com). www and apex are always
@@ -2989,11 +2980,9 @@ async def web_crawl_md(
           include_frames: When true, the contents of iframes are rendered to Markdown for each crawled
               page.
 
-          include_images: Include image references in the Markdown output Only applies to
-              `html-conversion` extractions.
+          include_images: Include image references in the Markdown output (`html-conversion` only).
 
-          include_links: Preserve hyperlinks in the Markdown output Only applies to `html-conversion`
-              extractions.
+          include_links: Preserve hyperlinks in the Markdown output (`html-conversion` only).
 
           include_selectors: Keep matching HTML subtrees before converting each page to Markdown.
 
@@ -3008,18 +2997,11 @@ async def web_crawl_md(
           settle_animations: Wait briefly for CSS animations and transitions to settle before reading each
               page.
 
-          shorten_base64_images: Truncate base64-encoded image data in the Markdown output Only applies to
-              `html-conversion` extractions.
-
-          source_preference: Where the Markdown should come from, in order of preference; the first usable
-              source wins. `html-conversion` converts the page HTML, and counts as unusable
-              when the conversion has almost no content (under 200 characters).
-              `markdown-direct` uses the official Markdown version the page publishes through,
-              returned as the site serves it. Defaults to
-              `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page
-              that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed.
-              Requests with include or exclude selectors never use `markdown-direct`, so they
-              must include `html-conversion`.
+          shorten_base64_images: Truncate base64-encoded image data in the Markdown output (`html-conversion`
+              only).
+
+          source_preference: Markdown sources in order of preference: `html-conversion` converts the page
+              HTML, `markdown-direct` uses Markdown the site publishes.
 
           stop_after_ms: Soft crawl deadline in milliseconds. Returns pages collected before the next
               deadline check.

src/context/dev/types/batch_submit_params.py

@@ -193,37 +193,20 @@ class InputScrapeDataMarkdownParams(TypedDict, total=False):
     """Markdown options. Requires `formats.markdown`."""
 
     include_images: Annotated[bool, PropertyInfo(alias="includeImages")]
-    """Include images in the Markdown using image syntax with URLs and alt text.
-
-    Only applies to `html-conversion` extractions.
-    """
+    """Include images in the Markdown (`html-conversion` only)."""
 
     include_links: Annotated[bool, PropertyInfo(alias="includeLinks")]
-    """Keep link URLs in the Markdown.
-
-    Set false to return link text without URLs. Only applies to `html-conversion`
-    extractions.
-    """
+    """Keep link URLs in the Markdown (`html-conversion` only)."""
 
     inline_images: Annotated[Literal["placeholder", "preserve"], PropertyInfo(alias="inlineImages")]
-    """How base64 images appear: `placeholder` (default) or `preserve`.
-
-    Requires `includeImages`. Only applies to `html-conversion` extractions.
-    """
+    """How base64 images appear when `includeImages` is set (`html-conversion` only)."""
 
     source_preference: Annotated[
         List[Literal["html-conversion", "markdown-direct"]], PropertyInfo(alias="sourcePreference")
     ]
     """
-    Where the Markdown should come from, in order of preference; the first usable
-    source wins. `html-conversion` converts the page HTML, and counts as unusable
-    when the conversion has almost no content (under 200 characters).
-    `markdown-direct` uses the official Markdown version the page publishes through,
-    returned as the site serves it. Defaults to
-    `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page
-    that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed.
-    Requests with include or exclude selectors never use `markdown-direct`, so they
-    must include `html-conversion`.
+    Markdown sources in order of preference: `html-conversion` converts the page
+    HTML, `markdown-direct` uses Markdown the site publishes.
     """
 
 
@@ -725,7 +708,7 @@ class InputCrawlDataSourceStartURLControls(TypedDict, total=False):
     """Limits and filters for page discovery."""
 
     exclude_regex: Annotated[str, PropertyInfo(alias="excludeRegex")]
-    """RE2 pattern for URLs to exclude, even when they match `regex`.
+    """Regex pattern for URLs to exclude, even when they match `regex`.
 
     The `start_url` itself is always included.
     """
@@ -814,11 +797,9 @@ class InputCrawlDataSourceStartURLControls(TypedDict, total=False):
             ]
         ],
     ]
-    """Languages whose pages are followed.
-
-    `same_as_start_url` follows only the start page's language; a list of language
-    codes such as `["en"]` follows those languages. Links whose language cannot be
-    determined are followed. When omitted all urls are crawled.
+    """
+    Only follow pages in these languages, or `same_as_start_url`; all languages when
+    omitted.
     """
 
     max_depth: Annotated[int, PropertyInfo(alias="maxDepth")]
@@ -828,7 +809,7 @@ class InputCrawlDataSourceStartURLControls(TypedDict, total=False):
     """Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000."""
 
     regex: str
-    """RE2 pattern for URLs to include. The `start_url` itself is always included."""
+    """Regex pattern for URLs to include. The `start_url` itself is always included."""
 
 
 class InputCrawlDataSourceStartURL(TypedDict, total=False):
@@ -852,15 +833,15 @@ class InputCrawlDataSourceSitemapControls(TypedDict, total=False):
 
     exclude_regex: Annotated[str, PropertyInfo(alias="excludeRegex")]
     """
-    RE2 pattern; sitemap URLs matching it are not scraped, even when they match
+    Regex pattern; sitemap URLs matching it are not scraped, even when they match
     `regex`.
     """
 
     max_urls: Annotated[int, PropertyInfo(alias="maxUrls")]
     """Maximum pages to fetch. Unused reserved credits are refunded. Maximum 100000."""
 
     regex: str
-    """RE2 pattern; only sitemap URLs matching it are scraped."""
+    """Regex pattern; only sitemap URLs matching it are scraped."""
 
 
 class InputCrawlDataSourceSitemap(TypedDict, total=False):
@@ -926,37 +907,20 @@ class InputCrawlDataMarkdownParams(TypedDict, total=False):
     """Markdown options. Requires `formats.markdown`."""
 
     include_images: Annotated[bool, PropertyInfo(alias="includeImages")]
-    """Include images in the Markdown using image syntax with URLs and alt text.
-
-    Only applies to `html-conversion` extractions.
-    """
+    """Include images in the Markdown (`html-conversion` only)."""
 
     include_links: Annotated[bool, PropertyInfo(alias="includeLinks")]
-    """Keep link URLs in the Markdown.
-
-    Set false to return link text without URLs. Only applies to `html-conversion`
-    extractions.
-    """
+    """Keep link URLs in the Markdown (`html-conversion` only)."""
 
     inline_images: Annotated[Literal["placeholder", "preserve"], PropertyInfo(alias="inlineImages")]
-    """How base64 images appear: `placeholder` (default) or `preserve`.
-
-    Requires `includeImages`. Only applies to `html-conversion` extractions.
-    """
+    """How base64 images appear when `includeImages` is set (`html-conversion` only)."""
 
     source_preference: Annotated[
         List[Literal["html-conversion", "markdown-direct"]], PropertyInfo(alias="sourcePreference")
     ]
     """
-    Where the Markdown should come from, in order of preference; the first usable
-    source wins. `html-conversion` converts the page HTML, and counts as unusable
-    when the conversion has almost no content (under 200 characters).
-    `markdown-direct` uses the official Markdown version the page publishes through,
-    returned as the site serves it. Defaults to
-    `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page
-    that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed.
-    Requests with include or exclude selectors never use `markdown-direct`, so they
-    must include `html-conversion`.
+    Markdown sources in order of preference: `html-conversion` converts the page
+    HTML, `markdown-direct` uses Markdown the site publishes.
     """
 
 

src/context/dev/types/crawl_controls.py

@@ -33,7 +33,7 @@ class CrawlControls(BaseModel):
     """Crawl settings as submitted."""
 
     exclude_url_pattern: Optional[str] = None
-    """RE2 pattern URLs must not match to be crawled. Null when the crawl set none."""
+    """Regex pattern URLs must not match to be crawled. Null when the crawl set none."""
 
     follow_subdomains: bool
     """Whether links to subdomains were followed. Always false for a sitemap crawl."""
@@ -120,11 +120,7 @@ class CrawlControls(BaseModel):
         ],
         None,
     ] = None
-    """
-    Languages whose pages were followed: `same_as_start_url` or a list of language
-    codes. Null when every language was followed, which is always the case for a
-    sitemap crawl.
-    """
+    """Languages whose pages were followed; null when all languages were."""
 
     max_depth: Optional[int] = None
     """Link depth limit.
@@ -144,4 +140,4 @@ class CrawlControls(BaseModel):
     """Where the crawl started."""
 
     url_pattern: Optional[str] = None
-    """RE2 pattern URLs had to match to be crawled. Null when the crawl set none."""
+    """Regex pattern URLs had to match to be crawled. Null when the crawl set none."""

src/context/dev/types/web_map_urls_params.py

@@ -16,7 +16,7 @@ class WebMapURLsParams(TypedDict, total=False):
     """Domain to map, e.g. `stripe.com`."""
 
     exclude_url_regex: Annotated[str, PropertyInfo(alias="excludeUrlRegex")]
-    """Optional RE2-compatible regex pattern.
+    """Regex pattern.
 
     URLs matching this pattern are not returned, even when they match urlRegex.
     """
@@ -46,7 +46,7 @@ class WebMapURLsParams(TypedDict, total=False):
     """Request deadline and what to return when it passes."""
 
     url_regex: Annotated[str, PropertyInfo(alias="urlRegex")]
-    """Optional RE2-compatible regex pattern.
+    """Regex pattern.
 
     Only URLs matching this pattern are returned and counted against maxLinks.
     """

src/context/dev/types/web_scrape_params.py

@@ -163,37 +163,20 @@ class MarkdownParams(TypedDict, total=False):
     """Markdown options. Requires `formats.markdown`."""
 
     include_images: Annotated[bool, PropertyInfo(alias="includeImages")]
-    """Include images in the Markdown using image syntax with URLs and alt text.
-
-    Only applies to `html-conversion` extractions.
-    """
+    """Include images in the Markdown (`html-conversion` only)."""
 
     include_links: Annotated[bool, PropertyInfo(alias="includeLinks")]
-    """Keep link URLs in the Markdown.
-
-    Set false to return link text without URLs. Only applies to `html-conversion`
-    extractions.
-    """
+    """Keep link URLs in the Markdown (`html-conversion` only)."""
 
     inline_images: Annotated[Literal["placeholder", "preserve"], PropertyInfo(alias="inlineImages")]
-    """How base64 images appear: `placeholder` (default) or `preserve`.
-
-    Requires `includeImages`. Only applies to `html-conversion` extractions.
-    """
+    """How base64 images appear when `includeImages` is set (`html-conversion` only)."""
 
     source_preference: Annotated[
         List[Literal["html-conversion", "markdown-direct"]], PropertyInfo(alias="sourcePreference")
     ]
     """
-    Where the Markdown should come from, in order of preference; the first usable
-    source wins. `html-conversion` converts the page HTML, and counts as unusable
-    when the conversion has almost no content (under 200 characters).
-    `markdown-direct` uses the official Markdown version the page publishes through,
-    returned as the site serves it. Defaults to
-    `["html-conversion", "markdown-direct"]`. With only `markdown-direct`, a page
-    that publishes no Markdown fails with `NO_PUBLISHED_MARKDOWN` and is not billed.
-    Requests with include or exclude selectors never use `markdown-direct`, so they
-    must include `html-conversion`.
+    Markdown sources in order of preference: `html-conversion` converts the page
+    HTML, `markdown-direct` uses Markdown the site publishes.
     """