1011 lines
38 KiB
Python
1011 lines
38 KiB
Python
"""
|
|
This type stub file was generated by pyright.
|
|
"""
|
|
|
|
from typing import Any, Awaitable, Callable, Dict, List, Optional, TYPE_CHECKING, Union
|
|
from pyee import EventEmitter
|
|
from pyppeteer.connection import CDPSession
|
|
from pyppeteer.coverage import Coverage
|
|
from pyppeteer.element_handle import ElementHandle
|
|
from pyppeteer.execution_context import JSHandle
|
|
from pyppeteer.frame_manager import Frame
|
|
from pyppeteer.input import Keyboard, Mouse, Touchscreen
|
|
from pyppeteer.network_manager import Request, Response
|
|
from pyppeteer.tracing import Tracing
|
|
from pyppeteer.worker import Worker
|
|
from pyppeteer.browser import Browser, Target
|
|
|
|
"""Page module."""
|
|
if TYPE_CHECKING:
|
|
...
|
|
logger = ...
|
|
class Page(EventEmitter):
|
|
"""Page class.
|
|
|
|
This class provides methods to interact with a single tab of chrome. One
|
|
:class:`~pyppeteer.browser.Browser` object might have multiple Page object.
|
|
|
|
The :class:`Page` class emits various :attr:`~Page.Events` which can be
|
|
handled by using ``on`` or ``once`` method, which is inherited from
|
|
`pyee <https://pyee.readthedocs.io/en/latest/>`_'s ``EventEmitter`` class.
|
|
"""
|
|
Events = ...
|
|
PaperFormats: Dict[str, Dict[str, float]] = ...
|
|
@staticmethod
|
|
async def create(client: CDPSession, target: Target, ignoreHTTPSErrors: bool, defaultViewport: Optional[Dict], screenshotTaskQueue: list = ...) -> Page:
|
|
"""Async function which makes new page object."""
|
|
...
|
|
|
|
def __init__(self, client: CDPSession, target: Target, frameTree: Dict, ignoreHTTPSErrors: bool, screenshotTaskQueue: list = ...) -> None:
|
|
...
|
|
|
|
@property
|
|
def target(self) -> Target:
|
|
"""Return a target this page created from."""
|
|
...
|
|
|
|
@property
|
|
def browser(self) -> Browser:
|
|
"""Get the browser the page belongs to."""
|
|
...
|
|
|
|
@property
|
|
def mainFrame(self) -> Optional[Frame]:
|
|
"""Get main :class:`~pyppeteer.frame_manager.Frame` of this page."""
|
|
...
|
|
|
|
@property
|
|
def keyboard(self) -> Keyboard:
|
|
"""Get :class:`~pyppeteer.input.Keyboard` object."""
|
|
...
|
|
|
|
@property
|
|
def touchscreen(self) -> Touchscreen:
|
|
"""Get :class:`~pyppeteer.input.Touchscreen` object."""
|
|
...
|
|
|
|
@property
|
|
def coverage(self) -> Coverage:
|
|
"""Return :class:`~pyppeteer.coverage.Coverage`."""
|
|
...
|
|
|
|
async def tap(self, selector: str) -> None:
|
|
"""Tap the element which matches the ``selector``.
|
|
|
|
:arg str selector: A selector to search element to touch.
|
|
"""
|
|
...
|
|
|
|
@property
|
|
def tracing(self) -> Tracing:
|
|
"""Get tracing object."""
|
|
...
|
|
|
|
@property
|
|
def frames(self) -> List[Frame]:
|
|
"""Get all frames of this page."""
|
|
...
|
|
|
|
@property
|
|
def workers(self) -> List[Worker]:
|
|
"""Get all workers of this page."""
|
|
...
|
|
|
|
async def setRequestInterception(self, value: bool) -> None:
|
|
"""Enable/disable request interception.
|
|
|
|
Activating request interception enables
|
|
:class:`~pyppeteer.network_manager.Request` class's
|
|
:meth:`~pyppeteer.network_manager.Request.abort`,
|
|
:meth:`~pyppeteer.network_manager.Request.continue_`, and
|
|
:meth:`~pyppeteer.network_manager.Request.response` methods.
|
|
This provides the capability to modify network requests that are made
|
|
by a page.
|
|
|
|
Once request interception is enabled, every request will stall unless
|
|
it's continued, responded or aborted.
|
|
|
|
An example of a native request interceptor that aborts all image
|
|
requests:
|
|
|
|
.. code:: python
|
|
|
|
browser = await launch()
|
|
page = await browser.newPage()
|
|
await page.setRequestInterception(True)
|
|
|
|
async def intercept(request):
|
|
if request.url.endswith('.png') or request.url.endswith('.jpg'):
|
|
await request.abort()
|
|
else:
|
|
await request.continue_()
|
|
|
|
page.on('request', lambda req: asyncio.ensure_future(intercept(req)))
|
|
await page.goto('https://example.com')
|
|
await browser.close()
|
|
"""
|
|
...
|
|
|
|
async def setOfflineMode(self, enabled: bool) -> None:
|
|
"""Set offline mode enable/disable."""
|
|
...
|
|
|
|
def setDefaultNavigationTimeout(self, timeout: int) -> None:
|
|
"""Change the default maximum navigation timeout.
|
|
|
|
This method changes the default timeout of 30 seconds for the following
|
|
methods:
|
|
|
|
* :meth:`goto`
|
|
* :meth:`goBack`
|
|
* :meth:`goForward`
|
|
* :meth:`reload`
|
|
* :meth:`waitForNavigation`
|
|
|
|
:arg int timeout: Maximum navigation time in milliseconds. Pass ``0``
|
|
to disable timeout.
|
|
"""
|
|
...
|
|
|
|
async def querySelector(self, selector: str) -> Optional[ElementHandle]:
|
|
"""Get an Element which matches ``selector``.
|
|
|
|
:arg str selector: A selector to search element.
|
|
:return Optional[ElementHandle]: If element which matches the
|
|
``selector`` is found, return its
|
|
:class:`~pyppeteer.element_handle.ElementHandle`. If not found,
|
|
returns ``None``.
|
|
"""
|
|
...
|
|
|
|
async def evaluateHandle(self, pageFunction: str, *args: Any) -> JSHandle:
|
|
"""Execute function on this page.
|
|
|
|
Difference between :meth:`~pyppeteer.page.Page.evaluate` and
|
|
:meth:`~pyppeteer.page.Page.evaluateHandle` is that
|
|
``evaluateHandle`` returns JSHandle object (not value).
|
|
|
|
:arg str pageFunction: JavaScript function to be executed.
|
|
"""
|
|
...
|
|
|
|
async def queryObjects(self, prototypeHandle: JSHandle) -> JSHandle:
|
|
"""Iterate js heap and finds all the objects with the handle.
|
|
|
|
:arg JSHandle prototypeHandle: JSHandle of prototype object.
|
|
"""
|
|
...
|
|
|
|
async def querySelectorEval(self, selector: str, pageFunction: str, *args: Any) -> Any:
|
|
"""Execute function with an element which matches ``selector``.
|
|
|
|
:arg str selector: A selector to query page for.
|
|
:arg str pageFunction: String of JavaScript function to be evaluated on
|
|
browser. This function takes an element which
|
|
matches the selector as a first argument.
|
|
:arg Any args: Arguments to pass to ``pageFunction``.
|
|
|
|
This method raises error if no element matched the ``selector``.
|
|
"""
|
|
...
|
|
|
|
async def querySelectorAllEval(self, selector: str, pageFunction: str, *args: Any) -> Any:
|
|
"""Execute function with all elements which matches ``selector``.
|
|
|
|
:arg str selector: A selector to query page for.
|
|
:arg str pageFunction: String of JavaScript function to be evaluated on
|
|
browser. This function takes Array of the
|
|
matched elements as the first argument.
|
|
:arg Any args: Arguments to pass to ``pageFunction``.
|
|
"""
|
|
...
|
|
|
|
async def querySelectorAll(self, selector: str) -> List[ElementHandle]:
|
|
"""Get all element which matches ``selector`` as a list.
|
|
|
|
:arg str selector: A selector to search element.
|
|
:return List[ElementHandle]: List of
|
|
:class:`~pyppeteer.element_handle.ElementHandle` which matches the
|
|
``selector``. If no element is matched to the ``selector``, return
|
|
empty list.
|
|
"""
|
|
...
|
|
|
|
async def xpath(self, expression: str) -> List[ElementHandle]:
|
|
"""Evaluate the XPath expression.
|
|
|
|
If there are no such elements in this page, return an empty list.
|
|
|
|
:arg str expression: XPath string to be evaluated.
|
|
"""
|
|
...
|
|
|
|
J = ...
|
|
Jeval = ...
|
|
JJ = ...
|
|
JJeval = ...
|
|
Jx = ...
|
|
async def cookies(self, *urls: str) -> List[Dict[str, Union[str, int, bool]]]:
|
|
"""Get cookies.
|
|
|
|
If no URLs are specified, this method returns cookies for the current
|
|
page URL. If URLs are specified, only cookies for those URLs are
|
|
returned.
|
|
|
|
Returned cookies are list of dictionaries which contain these fields:
|
|
|
|
* ``name`` (str)
|
|
* ``value`` (str)
|
|
* ``url`` (str)
|
|
* ``domain`` (str)
|
|
* ``path`` (str)
|
|
* ``expires`` (number): Unix time in seconds
|
|
* ``httpOnly`` (bool)
|
|
* ``secure`` (bool)
|
|
* ``session`` (bool)
|
|
* ``sameSite`` (str): ``'Strict'`` or ``'Lax'``
|
|
"""
|
|
...
|
|
|
|
async def deleteCookie(self, *cookies: dict) -> None:
|
|
"""Delete cookie.
|
|
|
|
``cookies`` should be dictionaries which contain these fields:
|
|
|
|
* ``name`` (str): **required**
|
|
* ``url`` (str)
|
|
* ``domain`` (str)
|
|
* ``path`` (str)
|
|
* ``secure`` (bool)
|
|
"""
|
|
...
|
|
|
|
async def setCookie(self, *cookies: dict) -> None:
|
|
"""Set cookies.
|
|
|
|
``cookies`` should be dictionaries which contain these fields:
|
|
|
|
* ``name`` (str): **required**
|
|
* ``value`` (str): **required**
|
|
* ``url`` (str)
|
|
* ``domain`` (str)
|
|
* ``path`` (str)
|
|
* ``expires`` (number): Unix time in seconds
|
|
* ``httpOnly`` (bool)
|
|
* ``secure`` (bool)
|
|
* ``sameSite`` (str): ``'Strict'`` or ``'Lax'``
|
|
"""
|
|
...
|
|
|
|
async def addScriptTag(self, options: Dict[str, Any] = ..., **kwargs: str) -> ElementHandle:
|
|
"""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.
|
|
* ``type`` (string): Script type. Use ``module`` in order to load a
|
|
JavaScript ES6 module.
|
|
|
|
:return ElementHandle: :class:`~pyppeteer.element_handle.ElementHandle`
|
|
of added tag.
|
|
"""
|
|
...
|
|
|
|
async def addStyleTag(self, options: Dict[str, Any] = ..., **kwargs: str) -> ElementHandle:
|
|
"""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: :class:`~pyppeteer.element_handle.ElementHandle`
|
|
of added tag.
|
|
"""
|
|
...
|
|
|
|
async def injectFile(self, filePath: str) -> str:
|
|
"""[Deprecated] Inject file to this page.
|
|
|
|
This method is deprecated. Use :meth:`addScriptTag` instead.
|
|
"""
|
|
...
|
|
|
|
async def exposeFunction(self, name: str, pyppeteerFunction: Callable[..., Any]) -> None:
|
|
"""Add python function to the browser's ``window`` object as ``name``.
|
|
|
|
Registered function can be called from chrome process.
|
|
|
|
:arg string name: Name of the function on the window object.
|
|
:arg Callable pyppeteerFunction: Function which will be called on
|
|
python process. This function should
|
|
not be asynchronous function.
|
|
"""
|
|
...
|
|
|
|
async def authenticate(self, credentials: Dict[str, str]) -> Any:
|
|
"""Provide credentials for http authentication.
|
|
|
|
``credentials`` should be ``None`` or dict which has ``username`` and
|
|
``password`` field.
|
|
"""
|
|
...
|
|
|
|
async def setExtraHTTPHeaders(self, headers: Dict[str, str]) -> None:
|
|
"""Set extra HTTP headers.
|
|
|
|
The extra HTTP headers will be sent with every request the page
|
|
initiates.
|
|
|
|
.. note::
|
|
``page.setExtraHTTPHeaders`` does not guarantee the order of
|
|
headers in the outgoing requests.
|
|
|
|
:arg Dict headers: A dictionary containing additional http headers to
|
|
be sent with every requests. All header values must
|
|
be string.
|
|
"""
|
|
...
|
|
|
|
async def setUserAgent(self, userAgent: str) -> None:
|
|
"""Set user agent to use in this page.
|
|
|
|
:arg str userAgent: Specific user agent to use in this page
|
|
"""
|
|
...
|
|
|
|
async def metrics(self) -> Dict[str, Any]:
|
|
"""Get metrics.
|
|
|
|
Returns dictionary containing metrics as key/value pairs:
|
|
|
|
* ``Timestamp`` (number): The timestamp when the metrics sample was
|
|
taken.
|
|
* ``Documents`` (int): Number of documents in the page.
|
|
* ``Frames`` (int): Number of frames in the page.
|
|
* ``JSEventListeners`` (int): Number of events in the page.
|
|
* ``Nodes`` (int): Number of DOM nodes in the page.
|
|
* ``LayoutCount`` (int): Total number of full partial page layout.
|
|
* ``RecalcStyleCount`` (int): Total number of page style
|
|
recalculations.
|
|
* ``LayoutDuration`` (int): Combined duration of page duration.
|
|
* ``RecalcStyleDuration`` (int): Combined duration of all page style
|
|
recalculations.
|
|
* ``ScriptDuration`` (int): Combined duration of JavaScript
|
|
execution.
|
|
* ``TaskDuration`` (int): Combined duration of all tasks performed by
|
|
the browser.
|
|
* ``JSHeapUsedSize`` (float): Used JavaScript heap size.
|
|
* ``JSHeapTotalSize`` (float): Total JavaScript heap size.
|
|
"""
|
|
...
|
|
|
|
@property
|
|
def url(self) -> str:
|
|
"""Get URL of this page."""
|
|
...
|
|
|
|
async def content(self) -> str:
|
|
"""Get the full HTML contents of the page.
|
|
|
|
Returns HTML including the doctype.
|
|
"""
|
|
...
|
|
|
|
async def setContent(self, html: str) -> None:
|
|
"""Set content to this page.
|
|
|
|
:arg str html: HTML markup to assign to the page.
|
|
"""
|
|
...
|
|
|
|
async def goto(self, url: str, options: Dict[str, Any] = ..., **kwargs: Any) -> Optional[Response]:
|
|
"""Go to the ``url``.
|
|
|
|
:arg string url: 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 disable timeout. The default value can
|
|
be changed by using the :meth:`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.
|
|
* ``domcontentloaded``: 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.
|
|
|
|
The ``Page.goto`` will raise errors if:
|
|
|
|
* there's an SSL error (e.g. in case of self-signed certificates)
|
|
* target URL is invalid
|
|
* the ``timeout`` is exceeded during navigation
|
|
* then main resource failed to load
|
|
|
|
.. note::
|
|
:meth:`goto` either raise error or return a main resource response.
|
|
The only exceptions are navigation to ``about:blank`` or navigation
|
|
to the same URL with a different hash, which would succeed and
|
|
return ``None``.
|
|
|
|
.. note::
|
|
Headless mode doesn't support navigation to a PDF document.
|
|
"""
|
|
...
|
|
|
|
async def reload(self, options: Dict[str, Any] = ..., **kwargs: Any) -> Optional[Response]:
|
|
"""Reload this page.
|
|
|
|
Available options are same as :meth:`goto` method.
|
|
"""
|
|
...
|
|
|
|
async def waitForNavigation(self, options: Dict[str, Any] = ..., **kwargs: Any) -> Optional[Response]:
|
|
"""Wait for navigation.
|
|
|
|
Available options are same as :meth:`goto` method.
|
|
|
|
This returns :class:`~pyppeteer.network_manager.Response` when the page
|
|
navigates to a new URL or reloads. It is useful for when you run code
|
|
which will indirectly cause the page to navigate. In case of navigation
|
|
to a different anchor or navigation due to
|
|
`History API <https://developer.mozilla.org/en-US/docs/Web/API/History_API>`_
|
|
usage, the navigation will return ``None``.
|
|
|
|
Consider this example:
|
|
|
|
.. code::
|
|
|
|
navigationPromise = async.ensure_future(page.waitForNavigation())
|
|
await page.click('a.my-link') # indirectly cause a navigation
|
|
await navigationPromise # wait until navigation finishes
|
|
|
|
or,
|
|
|
|
.. code::
|
|
|
|
await asyncio.wait([
|
|
page.click('a.my-link'),
|
|
page.waitForNavigation(),
|
|
])
|
|
|
|
.. note::
|
|
Usage of the History API to change the URL is considered a
|
|
navigation.
|
|
"""
|
|
...
|
|
|
|
async def waitForRequest(self, urlOrPredicate: Union[str, Callable[[Request], bool]], options: Dict[str, Any] = ..., **kwargs: Any) -> Request:
|
|
"""Wait for request.
|
|
|
|
:arg urlOrPredicate: A URL or function to wait for.
|
|
|
|
This method accepts below options:
|
|
|
|
* ``timeout`` (int|float): Maximum wait time in milliseconds, defaults
|
|
to 30 seconds, pass ``0`` to disable the timeout.
|
|
|
|
Example:
|
|
|
|
.. code::
|
|
|
|
firstRequest = await page.waitForRequest('http://example.com/resource')
|
|
finalRequest = await page.waitForRequest(lambda req: req.url == 'http://example.com' and req.method == 'GET')
|
|
return firstRequest.url
|
|
"""
|
|
...
|
|
|
|
async def waitForResponse(self, urlOrPredicate: Union[str, Callable[[Response], bool]], options: Dict[str, Any] = ..., **kwargs: Any) -> Response:
|
|
"""Wait for response.
|
|
|
|
:arg urlOrPredicate: A URL or function to wait for.
|
|
|
|
This method accepts below options:
|
|
|
|
* ``timeout`` (int|float): Maximum wait time in milliseconds, defaults
|
|
to 30 seconds, pass ``0`` to disable the timeout.
|
|
|
|
Example:
|
|
|
|
.. code::
|
|
|
|
firstResponse = await page.waitForResponse('http://example.com/resource')
|
|
finalResponse = await page.waitForResponse(lambda res: res.url == 'http://example.com' and res.status == 200)
|
|
return finalResponse.ok
|
|
"""
|
|
...
|
|
|
|
async def goBack(self, options: Dict[str, Any] = ..., **kwargs: Any) -> Optional[Response]:
|
|
"""Navigate to the previous page in history.
|
|
|
|
Available options are same as :meth:`goto` method.
|
|
|
|
If cannot go back, return ``None``.
|
|
"""
|
|
...
|
|
|
|
async def goForward(self, options: Dict[str, Any] = ..., **kwargs: Any) -> Optional[Response]:
|
|
"""Navigate to the next page in history.
|
|
|
|
Available options are same as :meth:`goto` method.
|
|
|
|
If cannot go forward, return ``None``.
|
|
"""
|
|
...
|
|
|
|
async def bringToFront(self) -> None:
|
|
"""Bring page to front (activate tab)."""
|
|
...
|
|
|
|
async def emulate(self, options: Dict[str, Any] = ..., **kwargs: Any) -> None:
|
|
"""Emulate given device metrics and user agent.
|
|
|
|
This method is a shortcut for calling two methods:
|
|
|
|
* :meth:`setUserAgent`
|
|
* :meth:`setViewport`
|
|
|
|
``options`` is a dictionary containing these fields:
|
|
|
|
* ``viewport`` (dict)
|
|
|
|
* ``width`` (int): page width in pixels.
|
|
* ``height`` (int): page width in pixels.
|
|
* ``deviceScaleFactor`` (float): Specify device scale factor (can be
|
|
thought as dpr). Defaults to 1.
|
|
* ``isMobile`` (bool): Whether the ``meta viewport`` tag is taken
|
|
into account. Defaults to ``False``.
|
|
* ``hasTouch`` (bool): Specifies if viewport supports touch events.
|
|
Defaults to ``False``.
|
|
* ``isLandscape`` (bool): Specifies if viewport is in landscape mode.
|
|
Defaults to ``False``.
|
|
|
|
* ``userAgent`` (str): user agent string.
|
|
"""
|
|
...
|
|
|
|
async def setJavaScriptEnabled(self, enabled: bool) -> None:
|
|
"""Set JavaScript enable/disable."""
|
|
...
|
|
|
|
async def setBypassCSP(self, enabled: bool) -> None:
|
|
"""Toggles bypassing page's Content-Security-Policy.
|
|
|
|
.. note::
|
|
CSP bypassing happens at the moment of CSP initialization rather
|
|
then evaluation. Usually this means that ``page.setBypassCSP``
|
|
should be called before navigating to the domain.
|
|
"""
|
|
...
|
|
|
|
async def emulateMedia(self, mediaType: str = ...) -> None:
|
|
"""Emulate css media type of the page.
|
|
|
|
:arg str mediaType: Changes the CSS media type of the page. The only
|
|
allowed values are ``'screen'``, ``'print'``, and
|
|
``None``. Passing ``None`` disables media
|
|
emulation.
|
|
"""
|
|
...
|
|
|
|
async def setViewport(self, viewport: dict) -> None:
|
|
"""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``.
|
|
"""
|
|
...
|
|
|
|
@property
|
|
def viewport(self) -> Optional[Dict]:
|
|
"""Get viewport as a dictionary or None.
|
|
|
|
Fields of returned dictionary is same as :meth:`setViewport`.
|
|
"""
|
|
...
|
|
|
|
async def evaluate(self, pageFunction: str, *args: Any, force_expr: bool = ...) -> Any:
|
|
"""Execute js-function or js-expression on browser and get result.
|
|
|
|
:arg str pageFunction: String of js-function/expression to be executed
|
|
on the browser.
|
|
:arg bool force_expr: 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.
|
|
"""
|
|
...
|
|
|
|
async def evaluateOnNewDocument(self, pageFunction: str, *args: str) -> None:
|
|
"""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. In this case, the
|
|
function is invoked in the context of the newly attached frame.
|
|
"""
|
|
...
|
|
|
|
async def setCacheEnabled(self, enabled: bool = ...) -> None:
|
|
"""Enable/Disable cache for each request.
|
|
|
|
By default, caching is enabled.
|
|
"""
|
|
...
|
|
|
|
async def screenshot(self, options: Dict[str, Any] = ..., **kwargs: Any) -> Union[bytes, str]:
|
|
"""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.
|
|
* ``encoding`` (str): The encoding of the image, can be either
|
|
``'base64'`` or ``'binary'``. Defaults to ``'binary'``.
|
|
"""
|
|
...
|
|
|
|
async def pdf(self, options: Dict[str, Any] = ..., **kwargs: Any) -> bytes:
|
|
"""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.
|
|
|
|
* ``date``: 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.
|
|
* ``format`` (str): Paper format. If set, takes priority 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.
|
|
|
|
* ``preferCSSPageSize``: Give any CSS ``@page`` size declared in the
|
|
page priority over what is declared in ``width`` and ``height`` or
|
|
``format`` options. Defaults to ``False``, which will scale the
|
|
content to fit the paper size.
|
|
|
|
:return: Return generated PDF ``bytes`` object.
|
|
|
|
.. note::
|
|
Generating a pdf is currently only supported in headless mode.
|
|
|
|
:meth:`pdf` generates a pdf of the page with ``print`` css media. To
|
|
generate a pdf with ``screen`` media, call
|
|
``page.emulateMedia('screen')`` before calling :meth:`pdf`.
|
|
|
|
.. note::
|
|
By default, :meth:`pdf` generates a pdf with modified colors for
|
|
printing. Use the ``--webkit-print-color-adjust`` property to force
|
|
rendering of exact colors.
|
|
|
|
.. code::
|
|
|
|
await page.emulateMedia('screen')
|
|
await page.pdf({'path': 'page.pdf'})
|
|
|
|
The ``width``, ``height``, and ``margin`` options accept values labeled
|
|
with units. Unlabeled values are treated as pixels.
|
|
|
|
A few examples:
|
|
|
|
- ``page.pdf({'width': 100})``: prints with width set to 100 pixels.
|
|
- ``page.pdf({'width': '100px'})``: prints with width set to 100 pixels.
|
|
- ``page.pdf({'width': '10cm'})``: prints with width set to 100 centimeters.
|
|
|
|
All available units are:
|
|
|
|
- ``px``: pixel
|
|
- ``in``: inch
|
|
- ``cm``: centimeter
|
|
- ``mm``: millimeter
|
|
|
|
The format options are:
|
|
|
|
- ``Letter``: 8.5in x 11in
|
|
- ``Legal``: 8.5in x 14in
|
|
- ``Tabloid``: 11in x 17in
|
|
- ``Ledger``: 17in x 11in
|
|
- ``A0``: 33.1in x 46.8in
|
|
- ``A1``: 23.4in x 33.1in
|
|
- ``A2``: 16.5in x 23.4in
|
|
- ``A3``: 11.7in x 16.5in
|
|
- ``A4``: 8.27in x 11.7in
|
|
- ``A5``: 5.83in x 8.27in
|
|
- ``A6``: 4.13in x 5.83in
|
|
|
|
.. note::
|
|
``headerTemplate`` and ``footerTemplate`` markup have the following
|
|
limitations:
|
|
|
|
1. Script tags inside templates are not evaluated.
|
|
2. Page styles are not visible inside templates.
|
|
"""
|
|
...
|
|
|
|
async def plainText(self) -> str:
|
|
"""[Deprecated] Get page content as plain text."""
|
|
...
|
|
|
|
async def title(self) -> str:
|
|
"""Get page's title."""
|
|
...
|
|
|
|
async def close(self, options: Dict[str, Any] = ..., **kwargs: Any) -> None:
|
|
"""Close this page.
|
|
|
|
Available options:
|
|
|
|
* ``runBeforeUnload`` (bool): Defaults to ``False``. Whether to run the
|
|
`before unload <https://developer.mozilla.org/en-US/docs/Web/Events/beforeunload>`_
|
|
page handlers.
|
|
|
|
By defaults, :meth:`close` **does not** run beforeunload handlers.
|
|
|
|
.. note::
|
|
If ``runBeforeUnload`` is passed as ``True``, a ``beforeunload``
|
|
dialog might be summoned and should be handled manually via page's
|
|
``dialog`` event.
|
|
"""
|
|
...
|
|
|
|
def isClosed(self) -> bool:
|
|
"""Indicate that the page has been closed."""
|
|
...
|
|
|
|
@property
|
|
def mouse(self) -> Mouse:
|
|
"""Get :class:`~pyppeteer.input.Mouse` object."""
|
|
...
|
|
|
|
async def click(self, selector: str, options: Dict[str, Any] = ..., **kwargs: Any) -> None:
|
|
"""Click element which matches ``selector``.
|
|
|
|
This method fetches an element with ``selector``, scrolls it into view
|
|
if needed, and then uses :attr:`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 :meth:`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.gather(
|
|
page.waitForNavigation(waitOptions),
|
|
page.click(selector, clickOptions),
|
|
)
|
|
"""
|
|
...
|
|
|
|
async def hover(self, selector: str) -> None:
|
|
"""Mouse hover the element which matches ``selector``.
|
|
|
|
If no element matched the ``selector``, raise ``PageError``.
|
|
"""
|
|
...
|
|
|
|
async def focus(self, selector: str) -> None:
|
|
"""Focus the element which matches ``selector``.
|
|
|
|
If no element matched the ``selector``, raise ``PageError``.
|
|
"""
|
|
...
|
|
|
|
async def select(self, selector: str, *values: str) -> List[str]:
|
|
"""Select options and return selected values.
|
|
|
|
If no element matched the ``selector``, raise ``ElementHandleError``.
|
|
"""
|
|
...
|
|
|
|
async def type(self, selector: str, text: str, options: Dict[str, Any] = ..., **kwargs: Any) -> None:
|
|
"""Type ``text`` on the element which matches ``selector``.
|
|
|
|
If no element matched the ``selector``, raise ``PageError``.
|
|
|
|
Details see :meth:`pyppeteer.input.Keyboard.type`.
|
|
"""
|
|
...
|
|
|
|
def waitFor(self, selectorOrFunctionOrTimeout: Union[str, int, float], options: Dict[str, Any] = ..., *args: Any, **kwargs: Any) -> Awaitable:
|
|
"""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 :meth:`waitForFunction`.
|
|
* If ``selectorOrFunctionOrTimeout`` is a selector string or xpath
|
|
string, this method is a shortcut to :meth:`waitForSelector` or
|
|
:meth:`waitForXPath`. If the string starts with ``//``, the string is
|
|
treated as xpath.
|
|
|
|
Pyppeteer tries to automatically detect function or selector, but
|
|
sometimes miss-detects. If not work as you expected, use
|
|
:meth:`waitForFunction` or :meth:`waitForSelector` directly.
|
|
|
|
:arg selectorOrFunctionOrTimeout: A selector, xpath, or function
|
|
string, or timeout (milliseconds).
|
|
:arg Any args: Arguments to pass the function.
|
|
:return: Return awaitable object which resolves to a JSHandle of the
|
|
success value.
|
|
|
|
Available options: see :meth:`waitForFunction` or
|
|
:meth:`waitForSelector`
|
|
"""
|
|
...
|
|
|
|
def waitForSelector(self, selector: str, options: Dict[str, Any] = ..., **kwargs: Any) -> Awaitable:
|
|
"""Wait until element which matches ``selector`` appears on page.
|
|
|
|
Wait for the ``selector`` to appear in page. If at the moment of
|
|
calling the 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.
|
|
|
|
:arg str selector: A selector of an element to wait for.
|
|
:return: 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 element 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). Pass ``0`` to disable timeout.
|
|
"""
|
|
...
|
|
|
|
def waitForXPath(self, xpath: str, options: Dict[str, Any] = ..., **kwargs: Any) -> Awaitable:
|
|
"""Wait until element which matches ``xpath`` appears on page.
|
|
|
|
Wait for the ``xpath`` to appear in page. If the moment of calling the
|
|
method the ``xpath`` already exists, the method will return
|
|
immediately. If the xpath doesn't appear after ``timeout`` milliseconds
|
|
of waiting, the function will raise exception.
|
|
|
|
|
|
:arg str xpath: A [xpath] of an element to wait for.
|
|
:return: Return awaitable object which resolves when element specified
|
|
by xpath string is added to DOM.
|
|
|
|
Available options are:
|
|
|
|
* ``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 element 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). Pass ``0`` to disable timeout.
|
|
"""
|
|
...
|
|
|
|
def waitForFunction(self, pageFunction: str, options: Dict[str, Any] = ..., *args: str, **kwargs: Any) -> Awaitable:
|
|
"""Wait until the function completes and returns a truthy value.
|
|
|
|
:arg Any args: Arguments to pass to ``pageFunction``.
|
|
:return: Return awaitable object which resolves when the
|
|
``pageFunction`` returns a truthy value. It resolves to a
|
|
:class:`~pyppeteer.execution_context.JSHandle` of the truthy
|
|
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.
|
|
Defaults to 30000 (30 seconds). Pass ``0`` to disable timeout.
|
|
"""
|
|
...
|
|
|
|
|
|
|
|
supportedMetrics = ...
|
|
unitToPixels = ...
|
|
def convertPrintParameterToInches(parameter: Union[None, int, float, str]) -> Optional[float]:
|
|
"""Convert print parameter to inches."""
|
|
...
|
|
|
|
class ConsoleMessage:
|
|
"""Console message class.
|
|
|
|
ConsoleMessage objects are dispatched by page via the ``console`` event.
|
|
"""
|
|
def __init__(self, type: str, text: str, args: List[JSHandle] = ...) -> None:
|
|
...
|
|
|
|
@property
|
|
def type(self) -> str:
|
|
"""Return type of this message."""
|
|
...
|
|
|
|
@property
|
|
def text(self) -> str:
|
|
"""Return text representation of this message."""
|
|
...
|
|
|
|
@property
|
|
def args(self) -> List[JSHandle]:
|
|
"""Return list of args (JSHandle) of this message."""
|
|
...
|
|
|
|
|
|
|