From f4bf400f050d9c7db27b4d65e207d3b85c4bb0f7 Mon Sep 17 00:00:00 2001
From: Max Schmitt <max@schmitt.mx>
Date: Mon, 21 Jun 2021 19:57:56 +0200
Subject: [PATCH] docs(python): enhance intro (#7234)

---
 docs/src/intro-python.md | 52 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/docs/src/intro-python.md b/docs/src/intro-python.md
index 0a8a001783..b6c482d417 100644
--- a/docs/src/intro-python.md
+++ b/docs/src/intro-python.md
@@ -12,6 +12,8 @@ See [system requirements](#system-requirements).
 
 ### Pip
 
+[![PyPI version](https://badge.fury.io/py/playwright.svg)](https://pypi.python.org/pypi/playwright/)
+
 ```bash
 pip install playwright
 playwright install
@@ -19,6 +21,8 @@ playwright install
 
 ### Conda
 
+[![Anaconda version](https://img.shields.io/conda/v/microsoft/playwright)](https://anaconda.org/Microsoft/playwright)
+
 ```bash
 conda config --add channels conda-forge
 conda config --add channels microsoft
@@ -89,6 +93,54 @@ Command Line Interface [CLI](./cli.md) can be used to record user interactions a
 playwright codegen wikipedia.org
 ```
 
+## With Pytest
+
+See [here](./test-runners.md) for Pytest instructions and examples.
+
+## Interactive mode (REPL)
+
+Blocking REPL, as in CLI via Python directly:
+
+```bash
+python
+```
+
+```py
+>>> from playwright.sync_api import sync_playwright
+>>> playwright = sync_playwright().start()
+# Use playwright.chromium, playwright.firefox or playwright.webkit
+# Pass headless=False to launch() to see the browser UI
+>>> browser = playwright.chromium.launch()
+>>> page = browser.new_page()
+>>> page.goto("http://whatsmyuseragent.org/")
+>>> page.screenshot(path="example.png")
+>>> browser.close()
+>>> playwright.stop()
+```
+
+Async REPL such as `asyncio` REPL:
+
+```bash
+python -m asyncio
+```
+
+```py
+>>> from playwright.async_api import async_playwright
+>>> playwright = await async_playwright().start()
+>>> browser = await playwright.chromium.launch()
+>>> page = await browser.new_page()
+>>> await page.goto("http://whatsmyuseragent.org/")
+>>> await page.screenshot(path="example.png")
+>>> await browser.close()
+>>> await playwright.stop()
+```
+
+## Known issues
+
+### `time.sleep()` leads to outdated state
+
+You should use `page.wait_for_timeout(5000)` instead of `time.sleep(5)` and it is better to not wait for a timeout at all, but sometimes it is useful for debugging. In these cases, use our wait method instead of the `time` module. This is because we internally rely on asynchronous operations and when using `time.sleep(5)` they can't get processed correctly.
+
 ## System requirements
 
 Playwright requires Python 3.7 or above. The browser binaries for Chromium,