API Reference

Launcher

pyppeteer.launcher.launch(options: dict = None, **kwargs) → pyppeteer.browser.Browser[source]

Start chrome process and return Browser.

This function is a shotcut to Launcher(options, **kwargs).launch().

Available options are:

  • ignoreHTTPSErrors (bool): Whether to ignore HTTPS errors. Defaults to False.
  • headless (bool): Whether to run browser in headless mode. Defaults to True unless appMode or devtools options is True.
  • executablePath (str): Path to a Chromium or Chrome executable to run instead of default bundled Chromium.
  • slowMo (int|float): Sles down pyppeteer operations by the specified amount of milliseconds.
  • args (List[str]): Additional arguments (flags) to pass to the browser process.
  • ignoreDefaultArgs (bool): Do not use pyppeteer’s default args. This is dangerous option; use with care.
  • handleSIGINT (bool): Close the browser process on Ctrl+C. Defaults to True.
  • handleSIGTERM (bool): Close the browser process on SIGTERM. Defaults to True.
  • handleSIGHUP (bool): Close the browser process on SIGHUP. Defaults to True.
  • userDataDir (str): Path to a user data directory.
  • env (dict): Specify environment variables that will be visible to the browser. Defaults to same as python process.
  • devtools (bool): Whether to auto-open a DevTools panel for each tab. If this option is True, the headless option will be set False.
  • appMode (bool): Deprecated.

Note

Pyppeteer can also be used to control the Chrome browser, but it works best with the version of Chromium it is bundled with. There is no guarantee it will work with any other version. Use executablePath option with extreme caution.

pyppeteer.launcher.connect(options: dict = None, **kwargs) → pyppeteer.browser.Browser[source]

Connect to the existing chrome.

browserWSEndpoint option is necessary to connect to the chrome. The format is ws://${host}:${port}/devtools/browser/<id>. This value can get by wsEndpoint.

Available options are:

  • browserWSEndpoint (str): A browser websocket endpoint to connect to. (required)
  • ignoreHTTPSErrors (bool): Whether to ignore HTTPS errors. Defaults to False.
  • slowMo (int|float): Slow down pyppeteer’s by the specified amount of milliseconds.
pyppeteer.launcher.executablePath() → str[source]

Get executable path of default chrome.

Browser Class

class pyppeteer.browser.Browser(connection: pyppeteer.connection.Connection, options: Dict = None, process: Union[subprocess.Popen, NoneType] = None, closeCallback: Callable[Awaitable[NoneType]] = None, **kwargs) → None[source]

Bases: pyee.EventEmitter

Browser class.

A Broser object is created when pyppeteer connects to chrome, either through launch() or connect().

coroutine close() → None[source]

Close connections and terminate browser process.

coroutine disconnect() → None[source]

Disconnect browser.

coroutine newPage() → pyppeteer.page.Page[source]

Make new page on this browser and return its object.

coroutine pages() → List[pyppeteer.page.Page][source]

Get all pages of this browser.

process

Return process of this browser.

If browser instance is created by pyppeteer.launcer.connect(), return None.

targets() → List[_ForwardRef(‘Target’)][source]

Get all targets of this browser.

coroutine userAgent() → str[source]

Return browser’s original user agent.

Note

Pages can override browser user agent with pyppeteer.page.Page.setUserAgent().

coroutine version() → str[source]

Get version of the browser.

wsEndpoint

Retrun websocket end point url.

Page Class

class pyppeteer.page.Page(client: pyppeteer.connection.CDPSession, target: Target, frameTree: Dict, ignoreHTTPSErrors: bool = False, screenshotTaskQueue: list = None) → None[source]

Bases: pyee.EventEmitter

Page class.

This class provides methods to interact with a single tab of chrome. One Browser object might have multiple Page object.

The Page class emits various Events which can be handled by using on or once method, which is inherited from pyee’s EventEmitter class.

Events = namespace(Console=’console’, Dialog=’dialog’, Error=’error’, FrameAttached=’frameattached’, FrameDetached=’framedetached’, FrameNavigated=’framenavigated’, Load=’load’, Metrics=’metrics’, PageError=’pageerror’, Request=’request’, RequestFailed=’requestfailed’, RequestFinished=’requestfinished’, Response=’response’)

Available events.

coroutine J(selector: str) → Union[_ForwardRef(‘ElementHandle’), NoneType]

alias to querySelector()

coroutine JJ(selector: str) → List[_ForwardRef(‘ElementHandle’)]

alias to querySelectorAll()

coroutine JJeval(selector: str, pageFunction: str, *args) → Union[typing.Any, NoneType]

alias to querySelectorAllEval()

coroutine Jeval(selector: str, pageFunction: str, *args) → Union[typing.Any, NoneType]

alias to querySelectorEval()

coroutine Jx(expression: str) → List[pyppeteer.element_handle.ElementHandle]

alias to xpath()

coroutine addScriptTag(options: Dict = None, **kwargs) → pyppeteer.element_handle.ElementHandle[source]

Add script tag to this page.

One of url, path or content option is necessary.
  • url (string): URL of a script to add.
  • path (string): Path to the local JavaScript file to add.
  • content (string): JavaScript string to add.
Return ElementHandle:
 ElementHandle of added tag.
coroutine addStyleTag(options: Dict = None, **kwargs) → pyppeteer.element_handle.ElementHandle[source]

Add style or link tag to this page.

One of url, path or content option is necessary.
  • url (string): URL of the link tag to add.
  • path (string): Path to the local CSS file to add.
  • content (string): CSS string to add.
Return ElementHandle:
 ElementHandle of added tag.
coroutine authenticate(credentials: Dict[str, str]) → Any[source]

Provide credentials for http authentication.

credentials should be None or dict which has username and password field.

coroutine bringToFront() → None[source]

Bring page to front (activate tab).

coroutine click(selector: str, options: dict = None, **kwargs) → None[source]

Click element which matches selector.

This method fetches an element with selector, scrolls it into view if needed, and then uses mouse to click in the center of the element. If there’s no element matching selector, the method raises PageError.

Available options are:

  • button (str): left, right, or middle, defaults to left.
  • clickCount (int): defaults to 1.
  • delay (int|float): Time to wait between mousedown and mouseup in milliseconds. defaults to 0.

Note

If this method triggers a navigation event and there’s a separate waitForNavigation(), you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following:

await asyncio.wait([
    page.waitForNavigation(waitOptions),
    page.click(selector, clickOptions),
])
coroutine close() → None[source]

Close connection.

coroutine content() → str[source]

Get the whole HTML contents of the page.

coroutine cookies(*urls) → dict[source]

Get cookies.

coverage

Return Coverage.

coroutine deleteCookie(*cookies) → None[source]

Delete cookie.

coroutine emulate(options: dict = None, **kwargs) → None[source]

Emulate viewport and user agent.

coroutine emulateMedia(mediaType: str = None) → None[source]

Emulate css media type of the page.

coroutine evaluate(pageFunction: str, *args, force_expr: bool = False) → Any[source]

Execute js-function or js-expression on browser and get result.

Parameters:
  • pageFunction (str) – String of js-function/expression to be executed on the browser.
  • force_expr (bool) – If True, evaluate pageFunction as expression. If False (default), try to automatically detect function or expression.

note: force_expr option is a keyword only argument.

coroutine evaluateHandle(pageFunction: str, *args) → pyppeteer.execution_context.JSHandle[source]

Execute function on this page.

Difference between evaluate() and evaluateHandle() is that evaluateHandle returns JSHandle object (not value).

Parameters:pageFunction (str) – JavaScript function to be executed.
coroutine evaluateOnNewDocument(pageFunction: str, *args) → None[source]

Add a JavaScript function to the document.

This function would be invoked in one of the following scenarios:

  • whenever the page is navigated
  • whenever the child frame is attached or navigated. Inthis case, the function is invoked in the context of the newly attached frame.
coroutine exposeFunction(name: str, pyppeteerFunction: Callable) → None[source]

Add python function to the browser’s window object as name.

Registered function can be called from chrome process.

Parameters:
  • name (string) – Name of the function on the window object.
  • pyppeteerFunction (Callable) – Function which will be called on python process.
coroutine focus(selector: str) → None[source]

Focus the element which matches selector.

If no element matched the selector, raise PageError.

frames

Get all frames of this page.

coroutine goBack(options: dict = None, **kwargs) → Union[pyppeteer.network_manager.Response, NoneType][source]

Navigate to the previous page in history.

Available options are same as goto() method.

coroutine goForward(options: dict = None, **kwargs) → Union[pyppeteer.network_manager.Response, NoneType][source]

Navigate to the next page in history.

Available options are same as goto() method.

coroutine goto(url: str, options: dict = None, **kwargs) → Union[pyppeteer.network_manager.Response, NoneType][source]

Go to the url.

Parameters:url (string) – URL to navigate page to. The url should include scheme, e.g. https://.

Available options are:

  • timeout (int): Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to desable timeout. The default value can be changed by using the setDefaultNavigationTimeout() method.
  • waitUntil (str|List[str]): When to consider navigation succeeded, defaults to load. Given a list of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
    • load: when load event is fired.
    • documentloaded: when the DOMContentLoaded event is fired.
    • networkidle0: when there are no more than 0 network connections for at least 500 ms.
    • networkidle2: when there are no more than 2 network connections for at least 500 ms.
coroutine hover(selector: str) → None[source]

Mouse hover the element which matches selector.

If no element matched the selector, raise PageError.

coroutine injectFile(filePath: str) → str[source]

[Deprecated] Inject file to this page.

This method is deprecated. Use addScriptTag() instead.

keyboard

Get Keyboard object.

mainFrame

Get main Frame of this page.

coroutine metrics() → Dict[str, Any][source]

Get metrics.

mouse

Get Mouse object.

coroutine pdf(options: dict = None, **kwargs) → bytes[source]

Generate a pdf of the page.

Options:

  • path (str): The file path to save the PDF.
  • scale (float): Scale of the webpage rendering, defaults to 1.
  • displayHeaderFooter (bool): Display header and footer. Defaults to False.
  • headerTemplate (str): HTML template for the print header. Should be valid HTML markup with following classes.
    • data: formatted print date
    • title: document title
    • url: document location
    • pageNumber: current page number
    • totalPages: total pages in the document
  • footerTemplate (str): HTML template for the print footer. Should use the same template as headerTemplate.
  • printBackground (bool): Print background graphics. Defaults to False.
  • landscape (bool): Paper orientation. Defaults to False.
  • pageRanges (string): Paper ranges to print, e.g., ‘1-5,8,11-13’. Defaults to empty string, which means all pages.
  • foramt (str): Paper format. If set, takes prioprity over width or height. Defaults to Letter.
  • width (str): Paper width, accepts values labeled with units.
  • height (str): Paper height, accepts values labeled with units.
  • margin (dict): Paper margins, defaults to None.
    • top (str): Top margin, accepts values labeled with units.
    • right (str): Right margin, accepts values labeled with units.
    • bottom (str): Bottom margin, accepts values labeled with units.
    • left (str): Left margin, accepts values labeled with units.
Return bytes:Return generated PDF bytes object.
coroutine plainText() → str[source]

[Deprecated] Get page content as plain text.

coroutine queryObjects(prototypeHandle: pyppeteer.execution_context.JSHandle) → pyppeteer.execution_context.JSHandle[source]

Iterate js heap and finds all the objects with the handle.

Parameters:prototypeHandle (JSHandle) – JSHandle of prototype object.
coroutine querySelector(selector: str) → Union[_ForwardRef(‘ElementHandle’), NoneType][source]

Get an Element which matches selector.

Parameters:selector (str) – A selector to search element.
Return Optional[ElementHandle]:
 If element which matches the selector is found, return its ElementHandle. If not found, returns None.
coroutine querySelectorAll(selector: str) → List[_ForwardRef(‘ElementHandle’)][source]

Get all element which matches selector as a list.

Parameters:selector (str) – A selector to search element.
Return List[ElementHandle]:
 List of ElementHandle which matches the selector. If no element is matched to the selector, return empty list.
coroutine querySelectorAllEval(selector: str, pageFunction: str, *args) → Union[typing.Any, NoneType][source]

Execute function with all elements which matches selector.

Parameters:
  • selector (str) – A selector to query page for.
  • pageFunction (str) – String of JavaScript function to be evaluated on browser. This function takes Array of the matched elements as the first argument.
  • args (Any) – Arguments to pass to pageFunction.
coroutine querySelectorEval(selector: str, pageFunction: str, *args) → Union[typing.Any, NoneType][source]

Execute function with an element which matches selector.

Parameters:
  • selector (str) – A selector to query page for.
  • pageFunction (str) – String of JavaScript function to be evaluated on browser. This function takes an element which matches the selector as a first argument.
  • args (Any) – Arguments to pass to pageFunction.

This method raises error if no element matched the selector.

coroutine reload(options: dict = None, **kwargs) → Union[pyppeteer.network_manager.Response, NoneType][source]

Reload this page.

Available options are same as goto() method.

coroutine screenshot(options: dict = None, **kwargs) → bytes[source]

Take a screen shot.

The following options are available:

  • path (str): The file path to save the image to. The screenshot type will be inferred from the file extension.
  • type (str): Specify screenshot type, can be either jpeg or png. Defaults to png.
  • quality (int): The quality of the image, between 0-100. Not applicable to png image.
  • fullPage (bool): When true, take a screenshot of the full scrollable page. Defaults to False.
  • clip (dict): An object which specifies clipping region of the page. This option should have the following fields:
    • x (int): x-coordinate of top-left corner of clip area.
    • y (int): y-coordinate of top-left corner of clip area.
    • width (int): width of clipping area.
    • height (int): height of clipping area.
  • omitBackground (bool): Hide default white background and allow capturing screenshot with transparency.
coroutine select(selector: str, *values) → List[str][source]

Select options and return selected values.

If no element matched the selector, raise ElementHandleError.

coroutine setContent(html: str) → None[source]

Set content to this page.

coroutine setCookie(*cookies) → None[source]

Set cookies.

setDefaultNavigationTimeout(timeout: int) → None[source]

Change the default maximum navigation timeout.

This method changes the default timeout of 30 seconds for the following methods:

Parameters:timeout (int) – Maximum navigation time in milliseconds.
coroutine setExtraHTTPHeaders(headers: Dict[str, str]) → None[source]

Set extra http headers.

coroutine setJavaScriptEnabled(enabled: bool) → None[source]

Set JavaScript enable/disable.

coroutine setOfflineMode(enabled: bool) → None[source]

Set offline mode enable/disable.

coroutine setRequestInterception(value: bool) → None[source]

Enable/disable request interception.

coroutine setUserAgent(userAgent: str) → None[source]

Set user agent to use in this page.

coroutine setViewport(viewport: dict) → None[source]

Set viewport.

Available options are:
  • width (int): page width in pixel.
  • height (int): page height in pixel.
  • deviceScaleFactor (float): Default to 1.0.
  • isMobile (bool): Default to False.
  • hasTouch (bool): Default to False.
  • isLandscape (bool): Default to False.
coroutine tap(selector: str) → None[source]

Tap the element which matches the selector.

Parameters:selector (str) – A selector to search element to touch.
target

Return a target this page created from.

coroutine title() → str[source]

Get page title.

touchscreen

Get Touchscreen object.

tracing

Get tracing object.

coroutine type(selector: str, text: str, options: dict = None, **kwargs) → None[source]

Type text on the element which matches selector.

If no element matched the selector, raise PageError.

Details see pyppeteer.input.Keyboard.type().

url

Get url of this page.

viewport

Get viewport dict.

Field of returned dict is same as setViewport().

waitFor(selectorOrFunctionOrTimeout: Union[str, int, float], options: dict = None, *args, **kwargs) → Awaitable[source]

Wait for function, timeout, or element which matches on page.

This method behaves differently with respect to the first argument:

  • If selectorOrFunctionOrTimeout is number (int or float), then it is treated as a timeout in milliseconds and this returns future which will be done after the timeout.
  • If selectorOrFunctionOrTimeout is a string of JavaScript function, this method is a shortcut to waitForFunction().
  • If selectorOrFunctionOrTimeout is a selector string, this method is a shortcut to waitForSelector().

Pyppeteer tries to automatically detect function or selector, but sometimes miss-detects. If not work as you expected, use waitForFunction() or waitForSelector() dilectly.

Parameters:
  • selectorOrFunctionOrTimeout – A selector or function string, or timeout (milliseconds).
  • args (Any) – Arguments to pass the function.
Returns:

Return awaitable object which resolves to a JSHandle of the success value.

Available options: see waitForFunction() or waitForSelector()

waitForFunction(pageFunction: str, options: dict = None, *args, **kwargs) → Awaitable[source]

Wait until the function completes and returns a truethy value.

Parameters:args (Any) – Arguments to pass to pageFunction.
Returns:Return awaitable object which resolves when the pageFunction returns a truethy value. It resolves to a JSHandle of the truethy value.

This method accepts the following options:

  • polling (str|number): An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values:
    • raf: to constantly execute pageFunction in requestAnimationFrame callback. This is the tightest polling mode which is suitable to observe styling changes.
    • mutation: to execute pageFunction on every DOM mutation.
  • timeout (int|float): maximum time to wait for in milliseconds.
coroutine waitForNavigation(options: dict = None, **kwargs) → Union[pyppeteer.network_manager.Response, NoneType][source]

Wait for navigation.

Available options are same as goto() method.

waitForSelector(selector: str, options: dict = None, **kwargs) → Awaitable[source]

Wait until element which matches selector appears on page.

Wait for the selector to appear in page. If at the moment of callingthe method the selector already exists, the method will return immediately. If the selector doesn’t appear after the timeout milliseconds of waiting, the function will raise error.

Parameters:selector (str) – A selector of an element to wait for.
Returns:Return awaitable object which resolves when element specified by selector string is added to DOM.

This method accepts the following options:

  • visible (bool): Wait for element to be present in DOM and to be visible; i.e. to not have display: none or visibility: hidden CSS properties. Defaults to False.
  • hidden (bool): Wait for eleemnt to not be found in the DOM or to be hidden, i.e. have display: none or visibility: hidden CSS properties. Defaults to False.
  • timeout (int|float): Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds).
coroutine xpath(expression: str) → List[pyppeteer.element_handle.ElementHandle][source]

Evaluate XPath expression.

If there is no such element in this page, return None.

Parameters:expression (str) – XPath string to be evaluated.

Keyboard Class

class pyppeteer.input.Keyboard(client: pyppeteer.connection.CDPSession) → None[source]

Bases: object

Keyboard class.

coroutine down(key: str, options: dict = None, **kwargs) → None[source]

Dispatches a keydown event with key.

If key is a single character and no modifier keys besides shift are being held down, and a keyparess/input event will also generated. The text option can be specified to force an input event to be generated.

If key is a modifier key, like Shift, Meta, or Alt, subsequent key presses will be sent with that modifier active. To release the modifier key, use up() method.

Parameters:
  • key (str) – Name of key to press, such as ArrowLeft.
  • options (dict) – Option can have text field, and if this option spedified, generate an input event with this text.
coroutine press(key: str, options: Dict = None, **kwargs) → None[source]

Press key.

If key is a single character and no modifier keys besides Shift are being held down, a keypress/input event will also generated. The text option can be specified to force an input event to be generated.

Parameters:key (str) – Name of key to press, such as ArrowLeft.

This method accepts the following options:

  • text (str): If specified, generates an input event with this text.
  • delay (int|float): Time to wait between keydown and keyup. Defaults to 0.
coroutine sendCharacter(char: str) → None[source]

Dispatches a keypress and input event.

This does not send a keydown or keyup event.

coroutine type(text: str, options: Dict = None, **kwargs) → None[source]

Type characters.

This method sends keydown, keypress/input, and keyup event for each character in the text.

To press a special key, like Control or ArrowDown, use press() method.

Parameters:
  • text (str) – Text to type into this element.
  • options (dict) – Options can have delay (int|float) field, which specifies time to wait between key presses in milliseconds. Defaults to 0.
coroutine up(key: str) → None[source]

Dispatches a keyup event of the key.

Parameters:key (str) – Name of key to release, such as ArrowLeft.

Mouse Class

class pyppeteer.input.Mouse(client: pyppeteer.connection.CDPSession, keyboard: pyppeteer.input.Keyboard) → None[source]

Bases: object

Mouse class.

coroutine click(x: float, y: float, options: dict = None, **kwargs) → None[source]

Click button at (x, y).

Shortcut to move(), down(), and up().

This method accepts the following options:

  • button (str): left, right, or middle, defaults to left.
  • clickCount (int): defaults to 1.
  • delay (int|float): Time to wait between mousedown and mouseup in milliseconds. Defaults to 0.
coroutine down(options: dict = None, **kwargs) → None[source]

Press down button (dispatches mousedown event).

This method accepts the following options:

  • button (str): left, right, or middle, defaults to left.
  • clickCount (int): defaults to 1.
coroutine move(x: float, y: float, options: dict = None, **kwargs) → None[source]

Move mouse cursor (dispatches a mousemove event).

Options can accepts steps (int) field. If this steps option specified, Sends intermediate mousemove events. Defaults to 1.

coroutine up(options: dict = None, **kwargs) → None[source]

Release pressed button (dispatches mouseup event).

This method accepts the following options:

  • button (str): left, right, or middle, defaults to left.
  • clickCount (int): defaults to 1.

Tracing Class

class pyppeteer.tracing.Tracing(client: pyppeteer.connection.CDPSession) → None[source]

Bases: object

Tracing class.

coroutine start(options: dict = None, **kwargs) → None[source]

Start tracing.

Only one trace can be active at a time per browser.

This method accepts the following options:

  • path (str): A path to write the trace file to. required
  • screenshots (bool): Capture screenshots in the trace.
  • categories (List[str]): Specify custom categories to use instead of default.
coroutine stop() → Awaitable[source]

Stop tracing.

Dialog Class

class pyppeteer.dialog.Dialog(client: pyppeteer.connection.CDPSession, type: str, message: str, defaultValue: str = ‘’) → None[source]

Bases: object

Dialog class.

Dialog objects are dispatched by page via the dialog event.

coroutine accept(promptText: str = ‘’) → None[source]

Accept the dialog.

  • promptText (str): A text to enter in prompt. If the dialog’s type is not prompt, this does not cause any effect.
defaultValue

If dialog is prompt, get default prompt value.

If dialog is not prompt, return empty string ('').

coroutine dismiss() → None[source]

Dismiss the dialog.

message

Get dialog message.

type

Get dialog type.

One of alert, beforeunload, confirm, or prompt.

ConsoleMessage Class

class pyppeteer.page.ConsoleMessage(type: str, text: str, args: List[pyppeteer.execution_context.JSHandle]) → None[source]

Bases: object

Console message class.

ConsoleMessage objects are dispatched by page via the console event.

args

Return list of args (JSHandle) of this message.

text

Return text representation of this message.

type

Return type of this message.

Frame Class

class pyppeteer.frame_manager.Frame(client: pyppeteer.connection.CDPSession, page: Any, parentFrame: Union[_ForwardRef(‘Frame’), NoneType], frameId: str) → None[source]

Bases: object

Frame class.

Frame objects can be obtained via pyppeteer.page.Page.mainFrame.

coroutine J(selector: str) → Union[pyppeteer.element_handle.ElementHandle, NoneType]

Alias to querySelector()

coroutine JJ(selector: str) → List[pyppeteer.element_handle.ElementHandle]

Alias to querySelectorAll()

coroutine JJeval(selector: str, pageFunction: str, *args) → Union[typing.Dict, NoneType]

Alias to querySelectorAllEval()

coroutine Jeval(selector: str, pageFunction: str, *args) → Union[typing.Any, NoneType]

Alias to querySelectorEval()

coroutine Jx(expression: str) → List[pyppeteer.element_handle.ElementHandle]

Alias to xpath()

coroutine addScriptTag(options: Dict) → pyppeteer.element_handle.ElementHandle[source]

Add script tag to this frame.

Details see pyppeteer.page.Page.addScriptTag().

coroutine addStyleTag(options: Dict) → pyppeteer.element_handle.ElementHandle[source]

Add style tag to this frame.

Details see pyppeteer.page.Page.addStyleTag().

childFrames

Get child frames.

coroutine content() → str[source]

Get the whole HTML contents of the page.

coroutine evaluate(pageFunction: str, *args, force_expr: bool = False) → Any[source]

Evaluate pageFunction on this frame.

Details see pyppeteer.page.Page.evaluate().

coroutine executionContext() → Union[pyppeteer.execution_context.ExecutionContext, NoneType][source]

Return execution context of this frame.

Return ExecutionContext associated to this frame.

coroutine injectFile(filePath: str) → str[source]

[Deprecated] Inject file to the frame.

isDetached() → bool[source]

Return True if this frame is detached.

Otherwise return False.

name

Get frame name.

parentFrame

Get parent frame.

If this frame is main frame or detached frame, return None.

coroutine querySelector(selector: str) → Union[pyppeteer.element_handle.ElementHandle, NoneType][source]

Get element which matches selector string.

Details see pyppeteer.page.Page.querySelector().

coroutine querySelectorAll(selector: str) → List[pyppeteer.element_handle.ElementHandle][source]

Get all elelments which matches selector.

Details see pyppeteer.page.Page.querySelectorAll().

coroutine querySelectorAllEval(selector: str, pageFunction: str, *args) → Union[typing.Dict, NoneType][source]

Execute function on all elements which matches selector.

Details see pyppeteer.page.Page.querySelectorAllEval().

coroutine querySelectorEval(selector: str, pageFunction: str, *args) → Union[typing.Any, NoneType][source]

Execute function on element which matches selector.

Details see pyppeteer.page.Page.querySelectorEval().

coroutine select(selector: str, *values) → List[str][source]

Select options and return selected values.

Details see pyppeteer.page.Page.select().

coroutine setContent(html: str) → None[source]

Set content to this page.

coroutine title() → str[source]

Get title of the frame.

url

Get url of the frame.

waitFor(selectorOrFunctionOrTimeout: Union[str, int, float], options: dict = None, *args, **kwargs) → Union[typing.Awaitable, _ForwardRef(‘WaitTask’)][source]

Wait until selectorOrFunctionOrTimeout.

Details see pyppeteer.page.Page.waitFor().

waitForFunction(pageFunction: str, options: dict = None, *args, **kwargs) → pyppeteer.frame_manager.WaitTask[source]

Wait until the function completes.

Details see pyppeteer.page.Page.waitForFunction().

waitForSelector(selector: str, options: dict = None, **kwargs) → pyppeteer.frame_manager.WaitTask[source]

Wait until element which matches selector appears on page.

Details see pyppeteer.page.Page.waitForSelector().

coroutine xpath(expression: str) → List[pyppeteer.element_handle.ElementHandle][source]

Evaluate XPath expression.

If there is no such element in this frame, return None.

Parameters:expression (str) – XPath string to be evaluated.

ExecutionContext Class

class pyppeteer.execution_context.ExecutionContext(client: pyppeteer.connection.CDPSession, contextPayload: Dict, objectHandleFactory: Any) → None[source]

Bases: object

Execution Context class.

coroutine evaluate(pageFunction: str, *args, force_expr: bool = False) → Any[source]

Execute pageFunction on this context.

Details see pyppeteer.page.Page.evaluate().

coroutine evaluateHandle(pageFunction: str, *args, force_expr: bool = False) → pyppeteer.execution_context.JSHandle[source]

Execute pageFunction on this context.

Details see pyppeteer.page.Page.evaluateHandle().

coroutine queryObjects(prototypeHandle: pyppeteer.execution_context.JSHandle) → pyppeteer.execution_context.JSHandle[source]

Send query.

Details see pyppeteer.page.Page.queryObjects().

JSHandle Class

class pyppeteer.execution_context.JSHandle(context: pyppeteer.execution_context.ExecutionContext, client: pyppeteer.connection.CDPSession, remoteObject: Dict) → None[source]

Bases: object

JSHandle class.

JSHandle represents an in-page JavaScript object. JSHandle can be created with the evaluateHandle() method.

asElement() → Union[_ForwardRef(‘ElementHandle’), NoneType][source]

Return either null or the object handle itself.

coroutine dispose() → None[source]

Stop referencing the handle.

executionContext

Get execution context of this handle.

coroutine getProperties() → Dict[str, _ForwardRef(‘JSHandle’)][source]

Get all properties of this handle.

coroutine getProperty(propertyName: str) → pyppeteer.execution_context.JSHandle[source]

Get property value of propertyName.

coroutine jsonValue() → Dict[source]

Get Jsonized value of this object.

toString() → str[source]

Get string representation.

ElementHandle Class

class pyppeteer.element_handle.ElementHandle(context: pyppeteer.execution_context.ExecutionContext, client: pyppeteer.connection.CDPSession, remoteObject: dict, page: Any) → None[source]

Bases: pyppeteer.execution_context.JSHandle

ElementHandle class.

This class represents an in-page DOM element. ElementHandle can be created by the pyppeteer.page.Page.querySelector() method.

ElementHandle prevents DOM element from garbage collection unless the handle is disposed. ElementHandles are automatically disposed when their origin frame gets navigated.

ElementHandle isinstance can be used as arguments in pyppeteer.page.Page.querySelectorEval() and pyppeteer.page.Page.evaluate() methods.

coroutine J(selector: str) → Union[_ForwardRef(‘ElementHandle’), NoneType]

alias to querySelector()

coroutine JJ(selector: str) → List[_ForwardRef(‘ElementHandle’)]

alias to querySelectorAll()

coroutine Jx(expression: str) → List[_ForwardRef(‘ElementHandle’)]

alias to xpath()

asElement() → pyppeteer.element_handle.ElementHandle[source]

Return this ElementHandle.

coroutine boundingBox() → Union[typing.Dict[str, float], NoneType][source]

Return bounding box of this element.

If the element is not visible, return None.

This method returns dictionary of bounding box, which contains:

  • x (int): The X coordinate of the element in pixels.
  • y (int): The Y coordinate of the element in pixels.
  • width (int): The width of the element in pixels.
  • height (int): The height of the element in pixels.
coroutine click(options: dict = None, **kwargs) → None[source]

Click the center of this element.

If needed, this method scrolls element into view. If the element is detached from DOM, the method raises ElementHandleError.

options can contain the following fields:

  • button (str): left, right, of middle, defaults to left.
  • clickCount (int): Defaults to 1.
  • delay (int|float): Time to wait between mousedown and mouseup in milliseconds. Defaults to 0.
coroutine focus() → None[source]

Focus on this element.

coroutine hover() → None[source]

Move mouse over to center of this element.

If needed, this method scrolls eleemnt into view. If this element is detached from DOM tree, the method raises an ElementHandleError.

coroutine press(key: str, options: Dict = None, **kwargs) → None[source]

Press key onto the element.

This method focuses the element, and then uses pyppeteer.input.keyboard.down() and pyppeteer.input.keyboard.up().

Parameters:key (str) – Name of key to press, such as ArrowLeft.

This method accepts the following options:

  • text (str): If specified, generates an input event with this text.
  • delay (int|float): Time to wait between keydown and keyup. Defaults to 0.
coroutine querySelector(selector: str) → Union[_ForwardRef(‘ElementHandle’), NoneType][source]

Return first element which matches selector under this element.

If no element mathes the selector, returns None.

coroutine querySelectorAll(selector: str) → List[_ForwardRef(‘ElementHandle’)][source]

Return all elements which match selector under this element.

If no element matches the selector, returns empty list ([]).

coroutine screenshot(options: Dict = None, **kwargs) → bytes[source]

Take a screenshot of this element.

If the element is detached from DOM, this method raises an ElementHandleError.

Available options are same as pyppeteer.page.Page.screenshot().

coroutine tap() → None[source]

Tap the center of this element.

If needed, this method scrolls element into view. If the element is detached from DOM, the method raises ElementHandleError.

coroutine type(text: str, options: Dict = None, **kwargs) → None[source]

Focus the element and then type text.

Details see pyppeteer.input.Keyboard.type() method.

coroutine uploadFile(*filePaths) → dict[source]

Upload files.

coroutine xpath(expression: str) → List[_ForwardRef(‘ElementHandle’)][source]

Evaluate XPath expression relative to this elementHandle.

If there is no such element, return None.

Parameters:expression (str) – XPath string to be evaluated.

Request Class

class pyppeteer.network_manager.Request(client: pyppeteer.connection.CDPSession, requestId: Union[str, NoneType], interceptionId: str, allowInterception: bool, url: str, resourceType: str, payload: dict, frame: Union[pyppeteer.frame_manager.Frame, NoneType]) → None[source]

Bases: object

Request class.

coroutine abort(errorCode: str = ‘failed’) → None[source]

Abort request.

To use this, request interception should be enabled by pyppeteer.page.Page.setRequestInterception(). If request interception is not enabled, raise NetworkError.

errorCode is an optional error code string. Defaults to failed, could be one of the following: aborted, accesdenied, addressunreachable, connectionaborted, connectionclosed, connectionfailed, connnectionrefused, connectionreset, internetdisconnected, namenotresolved, timedout, failed

coroutine continue_(overrides: Dict = None) → None[source]

Continue request with optional request overrides.

To use this method, request interception should be enabled by pyppeteer.page.Page.setRequestInterception(). If request interception is not enabled, raise NetworkError.

overrides can have the following fields:

  • url (str): If set, the request url will be changed.
  • method (str): If set, change the request method (e.g. GET).
  • postData (str): If set, change the post data or request.
  • headers (dict): If set, change the request HTTP header.
failure() → Union[typing.Dict, NoneType][source]

Return error text.

Return None unless this request was failed, as reported by requestfailed event.

When request failed, this method return dictionary which has a errorText field, which contains human-readable error message, e.g. 'net::ERR_RAILED'.

frame

Return a matching frame object.

Return None if navigating to error page.

headers

Reurn a dictionary of HTTP headers of this request.

All header names are lower-case.

method

Return this request’s method (GET, POST, etc.).

postData

Return post body of this request.

resourceType

Resource type of this request perceived by the rendering engine.

ResourceType will be one of the following: document, stylesheet, image, media, font, script, texttrack, xhr, fetch, eventsource, websocket, manifest, other.

coroutine respond(response: Dict) → None[source]

Fulfills request with given response.

To use this, request interception shuold by enabled by pyppeteer.page.Page.setRequestInterception(). Requst interception is not enabled, raise NetworkError.

response is a dictinary which can have the following fields:

  • status (int): Response status code, defaults to 200.
  • headers (dict): Optional response headers.
  • contentType (str): If set, euqals to setting Content-Type response header.
  • body (str|bytes): Optional response body.
response

Return matching Response object, or None.

If the response has not been recieved, return None.

url

URL of this request.

Response Class

class pyppeteer.network_manager.Response(client: pyppeteer.connection.CDPSession, request: pyppeteer.network_manager.Request, status: int, headers: Dict[str, str]) → None[source]

Bases: object

Response class represents responses which are recieved by Page.

buffer() → Awaitable[bytes][source]

Retrun awaitable which resolves to bytes with response body.

headers

Return dictionary of HTTP headers of this response.

All header names are lower-case.

coroutine json() → dict[source]

Get JSON representation of response body.

ok

Return bool whether this request is successfull (200-299) or not.

request

Get matching Request object.

status

Status code of the response.

coroutine text() → str[source]

Get text representation of response body.

url

URL of the response.

Target Class

class pyppeteer.browser.Target(browser: pyppeteer.browser.Browser, targetInfo: Dict) → None[source]

Bases: object

Browser’s target class.

coroutine createCDPSession() → pyppeteer.connection.CDPSession[source]

Create a Chrome Devtools Protocol session attached to the target.

coroutine page() → Union[pyppeteer.page.Page, NoneType][source]

Get page of this target.

type

Get type of this target.

url

Get url of this target.

CDPSession Class

class pyppeteer.connection.CDPSession(connection: pyppeteer.connection.Connection, targetId: str, sessionId: str) → None[source]

Bases: pyee.EventEmitter

Chrome Devtools Protocol Session.

The CDPSession instances are used to talk raw Chrome Devtools Protocol:

  • protocol methods can be called with send() method.
  • protocol events can be subscribed to with on() method.

Documentation on DevTools Protocol can be found here.

coroutine detach() → None[source]

Detach session from target.

Once detached, session won’t emit any events and can’t be used to send messages.

coroutine send(method: str, params: dict = None) → dict[source]

Send message to the connected session.

Parameters:
  • method (str) – Protocol method name.
  • params (dict) – Optional method parameters.

Coverage Class

class pyppeteer.coverage.Coverage(client: pyppeteer.connection.CDPSession) → None[source]

Bases: object

Coverage class.

Coverage gathers information about parts of JavaScript and CSS that were used by the page.

An example of using JavaScript and CSS coverage to get percentage of initially executed code:

# Enable both JavaScript and CSS coverage
await page.startJSCoverage()
await page.startCSSCoverage()

# Navigato to page
await page.goto('https://example.com')
# Disable JS and CSS coverage and get results
jsCoverage = await page.stopJSCoverage()
cssCoverage = await page.stopCSSCoverage()
totalBytes = 0
usedBytes = 0
coverage = jsCoverage + cssCoverage
for entry in coverage:
    totalBytes += len(entry['text'])
    for range in entry['ranges']:
        usedBytes += range['end'] - range['start'] - 1

print('Bytes used: {}%'.format(usedBytes / totalBytes * 100))
coroutine startCSSCoverage(options: Dict = None, **kwargs) → None[source]

Start CSS coverage measurement.

Available options are:

  • resetOnNavigation (bool): Whether to reset coverage on every navigation. Defaults to True.
coroutine startJSCoverage(options: Dict = None, **kwargs) → None[source]

Start JS coverage measurement.

Available options are:

  • resetOnNavigation (bool): Whether to reset coverage on every navigation. Defaults to True.
coroutine stopCSSCoverage() → List[source]

Stop CSS coverage measurement and get result.

Return list of coverage reports for all non-anonymous scripts. Each report includes:

  • url (str): StyleSheet url.
  • text (str): StyleSheet content.
  • ranges (List[Dict]): StyleSheet ranges that were executed. Ranges are sorted and non-overlapping.
    • start (int): A start offset in text, inclusive.
    • end (int): An end offset in text, exclusive.

Note

CSS coverage doesn’t include dynamically injected style tags without sourceURLs (but currently includs… to be fixed).

coroutine stopJSCoverage() → List[source]

Stop JS coverage measurement and get result.

Return list of coverage reports for all non-anonymous scripts. Each report includes:

  • url (str): Script url.
  • text (str): Script content.
  • ranges (List[Dict]): Script ranges that were executed. Ranges are sorted and non-overlapping.
    • start (int): A start offset in text, inclusive.
    • end (int): An end offset in text, exclusive.

Note

JavaScript coverage doesn’t include anonymous scripts; however, scripts with sourceURLs are reported.

.