From 3fc1def58e2bb4f0a2961fbc1d17082c4c584044 Mon Sep 17 00:00:00 2001 From: Angel M De Miguel Date: Mon, 31 Jul 2023 13:35:29 +0200 Subject: [PATCH 1/3] docs: add example and docs about using Python libraries in a project --- docs/docs/languages/python.md | 77 +++++++++++++++++++++++++++ examples/python-libs/.wws.toml | 44 +++++++++++++++ examples/python-libs/README.md | 36 +++++++++++++ examples/python-libs/_libs/.gitignore | 2 + examples/python-libs/index.py | 25 +++++++++ examples/python-libs/index.toml | 9 ++++ examples/python-libs/requirements.txt | 1 + 7 files changed, 194 insertions(+) create mode 100644 examples/python-libs/.wws.toml create mode 100644 examples/python-libs/README.md create mode 100644 examples/python-libs/_libs/.gitignore create mode 100644 examples/python-libs/index.py create mode 100644 examples/python-libs/index.toml create mode 100644 examples/python-libs/requirements.txt diff --git a/docs/docs/languages/python.md b/docs/docs/languages/python.md index 89e5b582..dda8c2cd 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). +## Use a Python library + +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 a 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 a HTML document and return 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 a `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 available 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..6ca88293 --- /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)). Be 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 From 9cf4c69a7ab8ec98f87751af6cd8befab7fb3430 Mon Sep 17 00:00:00 2001 From: Angel M De Miguel Date: Mon, 31 Jul 2023 13:40:48 +0200 Subject: [PATCH 2/3] docs: fix the Python libraries title --- docs/docs/languages/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/languages/python.md b/docs/docs/languages/python.md index dda8c2cd..fb5335dd 100644 --- a/docs/docs/languages/python.md +++ b/docs/docs/languages/python.md @@ -202,7 +202,7 @@ 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). -## Use a Python library +## 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 a 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. From ee23d6d031b4b0ad813efe89476972ac68b610fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81ngel=20M?= Date: Mon, 31 Jul 2023 15:09:59 +0200 Subject: [PATCH 3/3] docs: apply suggestions, fixes and wording improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rafael Fernández López --- docs/docs/languages/python.md | 8 ++++---- examples/python-libs/README.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/languages/python.md b/docs/docs/languages/python.md index fb5335dd..757ee532 100644 --- a/docs/docs/languages/python.md +++ b/docs/docs/languages/python.md @@ -204,11 +204,11 @@ If you prefer, you can configure the environment variable value dynamically by f ## 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 a 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. +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 a HTML document and return the text using the `bs4` library: +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 @@ -239,7 +239,7 @@ To add a new Python library to your project, follow these steps: pip3 install -t ./_libs beautifulsoup4 ``` -1. Create a `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: +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" @@ -277,7 +277,7 @@ To add a new Python library to your project, follow these steps: ### Limitations -Currently, Wasm Workers Server only supports pure Python libraries like Beautiful Soup. Libraries that requires to compile native extensions are not available yet. +Currently, Wasm Workers Server only supports pure Python libraries like Beautiful Soup. Libraries that requires to compile native extensions are not supported yet. ## Examples diff --git a/examples/python-libs/README.md b/examples/python-libs/README.md index 6ca88293..b0a55f12 100644 --- a/examples/python-libs/README.md +++ b/examples/python-libs/README.md @@ -25,7 +25,7 @@ Run a Python worker that uses a Python library in Wasm Workers Server. ## Run -This example runs from the previously cloned repository (See [Prerequisites](#prerequisites)). Be sure you followed all the steps and you're in the `examples/python-libs` folder: +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 .