From 7ba62d77dc7021417599d9a594eee264b28a46a5 Mon Sep 17 00:00:00 2001
From: laund <me@laund.moe>
Date: Mon, 28 Oct 2024 04:39:31 +0100
Subject: [PATCH] Allow py4web to be run using "python -m py4web" (#935)

* Allow py4web to be run using python -m py4web

* update debugging docs for __main__.py usage

* update vscode HTTPS launch.json for __main__.py usage

---------

Co-authored-by: Laurin Schmidt <l.schmidt@geosens.de>
---
 docs/chapter-02.rst | 24 +++++++++---------------
 docs/chapter-03.rst |  7 ++++---
 py4web/__main__.py  |  5 +++++
 3 files changed, 18 insertions(+), 18 deletions(-)
 create mode 100644 py4web/__main__.py

diff --git a/docs/chapter-02.rst b/docs/chapter-02.rst
index 54509b7e1..3f6987a01 100644
--- a/docs/chapter-02.rst
+++ b/docs/chapter-02.rst
@@ -103,25 +103,19 @@ to the vscode ``launch.json`` configuration file. Note that if you're using Wind
 forward slash only, like
 "C:/Users/your_name/py4web/py4web.py".
 
-If you have instead **installed py4web from pip,** you need to:
-
-- open the ``apps`` folder with VScode 
-- copy the standard `py4web.py launcher <https://github.com/web2py/py4web/blob/master/py4web.py>`__ inside it, but rename it to ``py4web-start.py`` in
-  order to avoid import errors later:
-
-.. code:: python
-
-  #!/usr/bin/env python3
-  from py4web.core import cli
-  cli()
-
-- create / change the vscode ``launch.json`` configuration file:
+If you have instead **installed py4web from pip,** you need to set the launch.json file to run py4web as a module
 
 ::
 
-  "args": ["run", "."],
-  "program": "your_full_path_to_py4web-start.py",
+  {
+    "name": "py4web apps",
+    "type": "debugpy",
+    "request": "launch",
+    "module": "py4web",
+    "args": ["run", "apps", "-D", "--watch", "lazy"]
+  }
 
+Adjust the `args` to match your apps folder. For example, replace `apps` with `.` if you opened the apps folder itself in VSCode.
 
 .. tip::
 
diff --git a/docs/chapter-03.rst b/docs/chapter-03.rst
index 117d61f69..fd04649e8 100644
--- a/docs/chapter-03.rst
+++ b/docs/chapter-03.rst
@@ -586,14 +586,15 @@ To use https with the build-in web server (Rocket3) these are the steps:
 
 If you use VSCode to run py4web you may want to update the py4web launch.json file to contain:
 
-.. code:: json   
+.. code:: json
 
     "configurations": [
             {
                 "name": "py4web",
-                "type": "python",
+                "type": "debugpy",
                 "request": "launch",
-                "program": "${workspaceFolder}/py4web.py",
+                "module": "py4web",
+                // or "program": "${workspaceFolder}/py4web.py", if you didn't install py4web as a package
                 "args": [
                     "run",
                     "apps",
diff --git a/py4web/__main__.py b/py4web/__main__.py
new file mode 100644
index 000000000..71d237e2a
--- /dev/null
+++ b/py4web/__main__.py
@@ -0,0 +1,5 @@
+# allow py4web to be run as a module
+# this file is called when running "python -m py4web"
+from py4web.core import cli
+
+cli()