Usage

Static HTML

Use cold_soup for pages that do not require JavaScript rendering.

from souppot import cold_soup

soup = cold_soup("https://example.com")

if soup:
    print(soup.title.string)

cold_soup returns a BeautifulSoup object for HTML responses, a raw requests.Response for other successful response types, and None for missing URLs or non-200 responses.

JavaScript-Rendered HTML

Use hot_soup when a page needs Playwright Chromium to render JavaScript before parsing.

from souppot import hot_soup

soup = hot_soup("https://example.com", wait_selector=".loaded")

if soup:
    print(soup.select_one(".loaded").get_text(strip=True))

If wait_selector times out, hot_soup logs the timeout and parses whatever DOM is available.

Downloads

Use hot_pot when a file should be downloaded through Playwright’s request context.

from souppot import hot_pot

path = hot_pot(
    "https://example.com/file.zip",
    "downloads/file.zip",
    referer="https://example.com",
)

print(path)

Parent directories for the destination path are created automatically.