diff --git a/docs/docs/languages/python.md b/docs/docs/languages/python.md index 89e5b582..757ee532 100644 --- a/docs/docs/languages/python.md +++ b/docs/docs/languages/python.md @@ -202,6 +202,83 @@ def worker(req): If you prefer, you can configure the environment variable value dynamically by following [these instructions](../features/environment-variables.md#inject-existing-environment-variables). +## Python libraries + +The Python ecosystem has a huge number of packages. Developers like you usually rely on other libraries to accomplish different goals. In this example, you will use the [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/bs4/doc/#quick-start) to parse an HTML document and read its text. You have all the code available in the [examples/python-libs](https://github.com/vmware-labs/wasm-workers-server/tree/main/examples/python-libs) folder. + +To add a new Python library to your project, follow these steps: + +1. First, create an `index.py` file with the content below. This worker reads an HTML document and returns the text using the `bs4` library: + + ```python title="./index.py" + from bs4 import BeautifulSoup + + html_doc = """ + + Wasm Workers Server + + +
+

This page was generated by a Python file running in WebAssembly.

+
+ + """ + + def worker(req): + soup = BeautifulSoup(html_doc, 'html.parser') + + res = Response(soup.get_text(". ", True)) + res.headers["x-generated-by"] = "wasm-workers-server" + + return res + ``` + +1. Install the Beautiful Soup library with `pip` and save it in a new `_libs` folder: + + ```plain + pip3 install -t ./_libs beautifulsoup4 + ``` + +1. Create an `index.toml` file with the content below. Note the name of the TOML file must match the name of the worker (`index.py` and `index.toml`). The current configuration mounts the `_libs` folder and sets the `PYTHONPATH` environment variable to the mount path: + + ```toml title="./index.toml" + name = "libs" + version = "1" + + [vars] + PYTHONPATH = "/opt/python/libs" + + [[folders]] + from = "./_libs" + to = "/opt/python/libs" + ``` + +1. If you didn't download the `wws` server yet, check our [Getting Started](../get-started/quickstart.md) guide. You also need to install the Python runtime with the command below: + + ```plain + wws runtimes install python latest + ``` + +1. Run your worker with `wws`: + + ```bash + wws + + ⚙️ Preparing the project from: . + ⚙️ Loading routes from: . + ⏳ Loading workers from 1 routes... + ✅ Workers loaded in 524.804167ms. + - http://127.0.0.1:8080/ + => ./index.py + 🚀 Start serving requests at http://127.0.0.1:8080 + ``` + +1. Finally, open in your browser. + +### Limitations + +Currently, Wasm Workers Server only supports pure Python libraries like Beautiful Soup. Libraries that requires to compile native extensions are not supported yet. + ## Examples * [Basic](https://github.com/vmware-labs/wasm-workers-server/tree/main/examples/python-basic/) diff --git a/examples/python-libs/.wws.toml b/examples/python-libs/.wws.toml new file mode 100644 index 00000000..b9791233 --- /dev/null +++ b/examples/python-libs/.wws.toml @@ -0,0 +1,44 @@ +version = 1 + +[[repositories]] +name = "wasmlabs" +url = "https://workers.wasmlabs.dev/repository/v1/index.toml" + +[[repositories.runtimes]] +name = "python" +version = "3.11.1+20230217-1" +tags = [ + "latest", + "3.11", + "3.11.1", +] +status = "active" +extensions = ["py"] +args = [ + "--", + "/src/index.py", +] + +[repositories.runtimes.binary] +url = "https://github.com/vmware-labs/webassembly-language-runtimes/releases/download/python%2F3.11.1%2B20230217-15dfbed/python-3.11.1.wasm" +filename = "python.wasm" + +[repositories.runtimes.binary.checksum] +type = "sha256" +value = "66589b289f76bd716120f76f234e4dd663064ed5b6256c92d441d84e51d7585d" + +[repositories.runtimes.polyfill] +url = "https://workers.wasmlabs.dev/repository/v1/files/python/3-1/poly.py" +filename = "poly.py" + +[repositories.runtimes.polyfill.checksum] +type = "sha256" +value = "74d10132b0577a39e4ea30002d4605b7cdfb8f39abca327a45c8b313de7ea304" + +[repositories.runtimes.wrapper] +url = "https://workers.wasmlabs.dev/repository/v1/files/python/3-1/wrapper.txt" +filename = "wrapper.txt" + +[repositories.runtimes.wrapper.checksum] +type = "sha256" +value = "cf1edc5b1427180ec09d18f4d169580379f1b12001f30e330759f9a0f8745357" diff --git a/examples/python-libs/README.md b/examples/python-libs/README.md new file mode 100644 index 00000000..b0a55f12 --- /dev/null +++ b/examples/python-libs/README.md @@ -0,0 +1,36 @@ +# Python + libraries example + +Run a Python worker that uses a Python library in Wasm Workers Server. + +## Prerequisites + +* Wasm Workers Server (wws): + + ```shell-session + curl -fsSL https://workers.wasmlabs.dev/install | bash + ``` + +* Clone the repository: + + ```shell-session + git clone https://github.com/vmware-labs/wasm-workers-server.git && + cd ./wasm-workers-server/examples/python-libs + ``` + +* Install the Python libraries + + ```shell-session + pip3 install -r requirements.txt -t ./_libs + ``` + +## Run + +This example runs from the previously cloned repository (See [Prerequisites](#prerequisites)). Make sure you followed all the steps and you're in the `examples/python-libs` folder: + +```shell-session +wws . +``` + +## Resources + +* [Python documentation](https://workers.wasmlabs.dev/docs/languages/python) diff --git a/examples/python-libs/_libs/.gitignore b/examples/python-libs/_libs/.gitignore new file mode 100644 index 00000000..611b6fb7 --- /dev/null +++ b/examples/python-libs/_libs/.gitignore @@ -0,0 +1,2 @@ +!.gitignore +**/ diff --git a/examples/python-libs/index.py b/examples/python-libs/index.py new file mode 100644 index 00000000..b5e3b9a2 --- /dev/null +++ b/examples/python-libs/index.py @@ -0,0 +1,25 @@ +from bs4 import BeautifulSoup + +html_doc = """ + + Wasm Workers Server + + + + +
+

Hello from Wasm Workers Server

+

+ This page was generated by a Python file running in WebAssembly. +

+
+ +""" + +def worker(req): + soup = BeautifulSoup(html_doc, 'html.parser') + + res = Response(soup.get_text("

", True)) + res.headers["x-generated-by"] = "wasm-workers-server" + + return res diff --git a/examples/python-libs/index.toml b/examples/python-libs/index.toml new file mode 100644 index 00000000..4771b49d --- /dev/null +++ b/examples/python-libs/index.toml @@ -0,0 +1,9 @@ +name = "libs" +version = "1" + +[vars] +PYTHONPATH = "/opt/python/libs" + +[[folders]] +from = "./_libs" +to = "/opt/python/libs" diff --git a/examples/python-libs/requirements.txt b/examples/python-libs/requirements.txt new file mode 100644 index 00000000..c1f5f713 --- /dev/null +++ b/examples/python-libs/requirements.txt @@ -0,0 +1 @@ +beautifulsoup4