From 3a15204ae3876f19edfbe99b9d2e78a9c3ac006b Mon Sep 17 00:00:00 2001 From: thomas chaton Date: Tue, 30 Aug 2022 17:07:34 +0200 Subject: [PATCH 01/15] update --- .../api/lightning_app.core.LightningApp.rst | 5 +- .../api/lightning_app.core.LightningFlow.rst | 5 +- .../api/lightning_app.core.LightningWork.rst | 5 +- .../glossary/command_lines/command_lines.rst | 76 +++++++++++++++ .../glossary/restful_api/restful_api.rst | 53 +++++++++++ docs/source-app/index.rst | 4 + .../build_command_line_interface/app.py | 36 ++++++++ .../build_command_line_interface/cli.rst | 68 ++++++++++++++ .../cli_client.rst | 92 +++++++++++++++++++ .../commands/__init__.py | 0 .../commands/notebook/__init__.py | 0 .../commands/notebook/run.py | 32 +++++++ .../example_command.py | 24 +++++ .../build_command_line_interface/index.rst | 55 +++++++++++ .../index_content.rst | 51 ++++++++++ .../post_example.py | 27 ++++++ .../workflows/build_rest_api/add_api.rst | 83 +++++++++++++++++ .../workflows/build_rest_api/index.rst | 32 +++++++ .../build_rest_api/index_content.rst | 50 ++++++++++ .../workflows/build_rest_api/models.py | 6 ++ .../workflows/build_rest_api/post_example.py | 26 ++++++ .../build_rest_api/post_example_pydantic.py | 30 ++++++ .../build_rest_api/request_validation.rst | 67 ++++++++++++++ src/lightning_app/cli/lightning_cli.py | 2 +- 24 files changed, 816 insertions(+), 13 deletions(-) create mode 100644 docs/source-app/glossary/command_lines/command_lines.rst create mode 100644 docs/source-app/glossary/restful_api/restful_api.rst create mode 100644 docs/source-app/workflows/build_command_line_interface/app.py create mode 100644 docs/source-app/workflows/build_command_line_interface/cli.rst create mode 100644 docs/source-app/workflows/build_command_line_interface/cli_client.rst create mode 100644 docs/source-app/workflows/build_command_line_interface/commands/__init__.py create mode 100644 docs/source-app/workflows/build_command_line_interface/commands/notebook/__init__.py create mode 100644 docs/source-app/workflows/build_command_line_interface/commands/notebook/run.py create mode 100644 docs/source-app/workflows/build_command_line_interface/example_command.py create mode 100644 docs/source-app/workflows/build_command_line_interface/index.rst create mode 100644 docs/source-app/workflows/build_command_line_interface/index_content.rst create mode 100644 docs/source-app/workflows/build_command_line_interface/post_example.py create mode 100644 docs/source-app/workflows/build_rest_api/add_api.rst create mode 100644 docs/source-app/workflows/build_rest_api/index.rst create mode 100644 docs/source-app/workflows/build_rest_api/index_content.rst create mode 100644 docs/source-app/workflows/build_rest_api/models.py create mode 100644 docs/source-app/workflows/build_rest_api/post_example.py create mode 100644 docs/source-app/workflows/build_rest_api/post_example_pydantic.py create mode 100644 docs/source-app/workflows/build_rest_api/request_validation.rst diff --git a/docs/source-app/api_reference/api/lightning_app.core.LightningApp.rst b/docs/source-app/api_reference/api/lightning_app.core.LightningApp.rst index 269a4e8f1143a..8f0a39b44d535 100644 --- a/docs/source-app/api_reference/api/lightning_app.core.LightningApp.rst +++ b/docs/source-app/api_reference/api/lightning_app.core.LightningApp.rst @@ -1,6 +1,4 @@ -:orphan: - -.. role:: hidden +.. role:: hidden :class: hidden-section .. currentmodule:: lightning_app.core @@ -10,4 +8,3 @@ LightningApp .. autoclass:: LightningApp :members: - :noindex: diff --git a/docs/source-app/api_reference/api/lightning_app.core.LightningFlow.rst b/docs/source-app/api_reference/api/lightning_app.core.LightningFlow.rst index 336efd4d7165b..d305b42d6fc38 100644 --- a/docs/source-app/api_reference/api/lightning_app.core.LightningFlow.rst +++ b/docs/source-app/api_reference/api/lightning_app.core.LightningFlow.rst @@ -1,6 +1,4 @@ -:orphan: - -.. role:: hidden +.. role:: hidden :class: hidden-section .. currentmodule:: lightning_app.core @@ -10,4 +8,3 @@ LightningFlow .. autoclass:: LightningFlow :members: - :noindex: diff --git a/docs/source-app/api_reference/api/lightning_app.core.LightningWork.rst b/docs/source-app/api_reference/api/lightning_app.core.LightningWork.rst index db80b79e41d8b..77965e2146757 100644 --- a/docs/source-app/api_reference/api/lightning_app.core.LightningWork.rst +++ b/docs/source-app/api_reference/api/lightning_app.core.LightningWork.rst @@ -1,6 +1,4 @@ -:orphan: - -.. role:: hidden +.. role:: hidden :class: hidden-section .. currentmodule:: lightning_app.core @@ -10,4 +8,3 @@ LightningWork .. autoclass:: LightningWork :members: - :noindex: diff --git a/docs/source-app/glossary/command_lines/command_lines.rst b/docs/source-app/glossary/command_lines/command_lines.rst new file mode 100644 index 0000000000000..d064ea00894ee --- /dev/null +++ b/docs/source-app/glossary/command_lines/command_lines.rst @@ -0,0 +1,76 @@ +:orphan: + +############################ +Command Line Interface (CLI) +############################ + +**Audience:** Users looking to create a command line interface for their application. + +---- + +**************************************** +What is a command line interface (CLI) ? +**************************************** + +A command-line interface (CLI) is a text-based user interface (UI) used to run programs, manage computer files and interact with the computer. Command-line interfaces are also called command-line user interfaces, console user interfaces and character user interfaces. + +As an example, Lightning provides a CLI to interact with your Lightning Apps and the `lightning.ai `_ platform as follows: + +.. code-block:: bash + + main + ├── create - Create Lightning AI self-managed resources (clusters, etc…) + │ └── cluster - Create a Lightning AI BYOC compute cluster with your cloud provider credentials. + ├── delete - Delete Lightning AI self-managed resources (clusters, etc…) + │ └── cluster - Delete a Lightning AI BYOC compute cluster and all associated cloud provider resources. + ├── fork - Fork an application. + ├── init - Init a Lightning App and/or component. + │ ├── app + │ ├── component + │ ├── pl-app - Create an app from your PyTorch Lightning source files. + │ └── react-ui - Create a react UI to give a Lightning component a React.js web user interface (UI) + ├── install - Install a Lightning App and/or component. + │ ├── app + │ └── component + ├── list - List Lightning AI self-managed resources (clusters, etc…) + │ ├── apps - List your Lightning AI apps. + │ └── clusters - List your Lightning AI BYOC compute clusters. + ├── login - Log in to your lightning.ai account. + ├── logout - Log out of your lightning.ai account. + ├── run - Run a Lightning application locally or on the cloud. + │ └── app - Run an app from a file. + ├── show - Show given resource. + │ ├── cluster - Groups cluster commands inside show. + │ │ └── logs - Show cluster logs. + │ └── logs - Show cloud application logs. By default prints logs for all currently available components. + ├── stop - Stop your application. + └── tree - show the command tree of your CLI + +Learn more with `Command-line interface `_. + +.. note:: + + The Lightning guideline to build CLI is lightning ... or ... + +---- + +********** +Learn more +********** + +.. raw:: html + +
+
+ +.. displayitem:: + :header: Develop a Command Line Interface + :description: Learn how to develop an CLI for your application. + :col_css: col-md-6 + :button_link: ../../workflows/build_command_line_interface/index_content.html + :height: 150 + +.. raw:: html + +
+
diff --git a/docs/source-app/glossary/restful_api/restful_api.rst b/docs/source-app/glossary/restful_api/restful_api.rst new file mode 100644 index 0000000000000..00d0d62958053 --- /dev/null +++ b/docs/source-app/glossary/restful_api/restful_api.rst @@ -0,0 +1,53 @@ +:orphan: + +########### +RESTful API +########### + +**Audience:** Users looking to create an API in their application to let users activate functionalities from external sources. + +---- + +*********************** +What is a RESTful API ? +*********************** + +A RESTful API is a set of external url routes exposed by a server that enables clients to trigger some functionalities such as getting or putting some data, uploading files, etc.. + +This provides great flexibility for clients as they can easily discover functionalities made available by the App Builders. + +The Lightning App framework supports the 4 traditional http methods. + +They are guidelines to organize your RESTful Services and help clients understand your functionalities. + +* **Get** is used to read data from the server. +* **Post** is used to create new resources. +* **Put** is used to update/replace existing resources. +* **Delete** is used to delete resources. + +Learn more with `HTTP Methods for RESTful Services `_. + +The Lightning App framework uses the popular `FastAPI `_ and `Pydantic `_ frameworks under the hood e.g you can use all their features while building your application. + +---- + +********** +Learn more +********** + +.. raw:: html + +
+
+ +.. displayitem:: + :header: Develop a RESTful API + :description: Learn how to develop an API for your application. + :col_css: col-md-6 + :button_link: ../../workflows/build_rest_api/index_content.html + :height: 150 + +.. raw:: html + +
+
diff --git a/docs/source-app/index.rst b/docs/source-app/index.rst index 6c701ffd574d9..af0e7eb350827 100644 --- a/docs/source-app/index.rst +++ b/docs/source-app/index.rst @@ -220,8 +220,10 @@ Keep Learning Add a web user interface (UI) Add a web link Arrange app tabs + Develop a Command Line Interface (CLI) Develop a Lightning App Develop a Lightning Component + Develop a REST API Cache Work run calls Customize your cloud compute Extend an existing app @@ -264,10 +266,12 @@ Keep Learning App Components Tree Build Configuration + Command Line Interface (CLI) DAG Event Loop Environment Variables Frontend + REST API Sharing Components Scheduling Storage diff --git a/docs/source-app/workflows/build_command_line_interface/app.py b/docs/source-app/workflows/build_command_line_interface/app.py new file mode 100644 index 0000000000000..d5d949ea51304 --- /dev/null +++ b/docs/source-app/workflows/build_command_line_interface/app.py @@ -0,0 +1,36 @@ +from commands.notebook.run import RunNotebook, RunNotebookConfig +from lit_jupyter import JupyterLab + +import lightning as L +from lightning.app.structures import Dict + + +class Flow(L.LightningFlow): + + def __init__(self): + super().__init__() + self.notebooks = Dict() + + # 1. Annotate the handler input with the notebook config. + def run_notebook(self, config: RunNotebookConfig): + if config.name in self.notebooks: + return f"The notebook {config.name} is already created." + else: + # 2. Create dynamically the notebook if it doesn't exist and run it. + self.notebooks[config.name] = JupyterLab( + cloud_compute=L.CloudCompute(config.cloud_compute) + ) + self.notebooks[config.name].run() + return f"The notebook {config.name} was created." + + def configure_commands(self): + # 3. Returns a list of dictionaries with the format: + # {"command_name": CustomClientCommand(method=self.custom_server_handler)} + return [{"run-notebook": RunNotebook(method=self.run_notebook)}] + + def configure_layout(self): + # 4. Dynamically display the notebooks in the Lightning App View. + return [{"name": n, "content": w} for n, w in self.notebooks.items()] + + +app = L.LightningApp(Flow()) diff --git a/docs/source-app/workflows/build_command_line_interface/cli.rst b/docs/source-app/workflows/build_command_line_interface/cli.rst new file mode 100644 index 0000000000000..7f1596476729d --- /dev/null +++ b/docs/source-app/workflows/build_command_line_interface/cli.rst @@ -0,0 +1,68 @@ +************************************** +Develop a CLI without client side code +************************************** + +In order to create your first CLI, you need to override the :class:`~lightning_app.core.flow.LightningFlow.configure_commands` hook and return a list of dictionaries where the keys are the commands and the values are the server-side handlers. + +.. literalinclude:: example_command.py + +After copy-pasting the code above to a file ``app.py``, execute the following command in your terminal in your first terminal. + +.. code-block:: bash + + lightning run app app.py + +And you find the following: + +.. code-block:: bash + + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + [] + +In another terminal, you can trigger the command line exposed by your application. + +.. code-block:: bash + + lightning add --name=my_name + WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. + +In your first terminal, **Received name: my_name** and **["my_name"]** are printed. + +.. code-block:: bash + + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + [] + Received name: my_name + ["my_name] + +---- + +********** +Learn more +********** + +.. raw:: html + +
+
+ +.. displayitem:: + :header: Develop a CLI with server and client code execution + :description: Learn how to develop a complex API for your application + :col_css: col-md-6 + :button_link: cli_client.html + :height: 150 + +.. displayitem:: + :header: Develop a RESTful API + :description: Learn how to develop an API for your application. + :col_css: col-md-6 + :button_link: ../build_rest_api/index.html + :height: 150 + +.. raw:: html + +
+
diff --git a/docs/source-app/workflows/build_command_line_interface/cli_client.rst b/docs/source-app/workflows/build_command_line_interface/cli_client.rst new file mode 100644 index 0000000000000..c9289f1c550a2 --- /dev/null +++ b/docs/source-app/workflows/build_command_line_interface/cli_client.rst @@ -0,0 +1,92 @@ +*********************************** +Develop a CLI with client side code +*********************************** + +In the previous section, we learned how to create a simple command line interface. In more realistic use-cases, an app builder wants to provide more complex functionalities where trusted code is executed on the client side. + +Lightning provides a flexible way to create complex CLI without effort. + +In the example below, we create a CLI to dynamically run notebooks with the following structures. + +.. code-block:: bash + + app_folder/ + commands/ + notebook/ + run.py + app.py + +Furthermore, we are using the `Jupyter-Component `_. Follow the installation steps on the repo. + +In the ``commands/notebook/run.py``, add the following code: + +.. literalinclude:: commands/notebook/run.py + +And in the ``app.py``, add the following code: + +.. literalinclude:: app.py + +In your first terminal, run the following command and open the ``http://127.0.0.1:7501/view`` in browser. + +.. code-block:: bash + + lightning run app app.py + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + +And a second terminal, run a first notebook + +.. code-block:: bash + + lightning run-notebook --name="my_notebook" + WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. + The notebook my_notebook was created. + +And run a second notebook. + +.. code-block:: bash + + lightning run-notebook --name="my_notebook_2" + WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. + The notebook my_notebook_2 was created. + +Here is a recording of the Lightning App described above. + +.. raw:: html + +
+ +
+
+ +---- + +********** +Learn more +********** + +.. raw:: html + +
+
+ +.. displayitem:: + :header: Develop a CLI with server side code only + :description: Learn how to develop a simple API for your application + :col_css: col-md-6 + :button_link: cli.html + :height: 150 + +.. displayitem:: + :header: Develop a RESTful API + :description: Learn how to develop an API for your application. + :col_css: col-md-6 + :button_link: ../build_rest_api/index.html + :height: 150 + +.. raw:: html + +
+
diff --git a/docs/source-app/workflows/build_command_line_interface/commands/__init__.py b/docs/source-app/workflows/build_command_line_interface/commands/__init__.py new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/docs/source-app/workflows/build_command_line_interface/commands/notebook/__init__.py b/docs/source-app/workflows/build_command_line_interface/commands/notebook/__init__.py new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/docs/source-app/workflows/build_command_line_interface/commands/notebook/run.py b/docs/source-app/workflows/build_command_line_interface/commands/notebook/run.py new file mode 100644 index 0000000000000..dd7081f31f753 --- /dev/null +++ b/docs/source-app/workflows/build_command_line_interface/commands/notebook/run.py @@ -0,0 +1,32 @@ +from argparse import ArgumentParser +from uuid import uuid4 + +from pydantic import BaseModel + +from lightning.app.utilities.commands import ClientCommand + + +class RunNotebookConfig(BaseModel): + name: str + cloud_compute: str + + +class RunNotebook(ClientCommand): + + def run(self): + # 1. Define your own argument parser. You can use argparse, click, etc... + parser = ArgumentParser(description='Run Notebook Parser') + parser.add_argument("--name", type=str, default=None) + parser.add_argument("--cloud_compute", type=str, default="cpu") + hparams = parser.parse_args() + + # 2. Invoke the server-side handler by sending a payload. + response = self.invoke_handler( + config=RunNotebookConfig( + name=hparams.name or str(uuid4()), + cloud_compute=hparams.cloud_compute, + ), + ) + + # 3. Print the server response. + print(response) diff --git a/docs/source-app/workflows/build_command_line_interface/example_command.py b/docs/source-app/workflows/build_command_line_interface/example_command.py new file mode 100644 index 0000000000000..3c013548af0a3 --- /dev/null +++ b/docs/source-app/workflows/build_command_line_interface/example_command.py @@ -0,0 +1,24 @@ +from lightning import LightningApp, LightningFlow + + +class Flow(LightningFlow): + def __init__(self): + super().__init__() + self.names = [] + + def run(self): + print(self.names) + + def add_name(self, name: str): + print(f"Received name: {name}") + self.names.append(name) + + def configure_commands(self): + # This can be invoked with `lightning add --name=my_name` + commands = [ + {"add": self.add_name}, + ] + return commands + + +app = LightningApp(Flow()) diff --git a/docs/source-app/workflows/build_command_line_interface/index.rst b/docs/source-app/workflows/build_command_line_interface/index.rst new file mode 100644 index 0000000000000..81bfac572efe1 --- /dev/null +++ b/docs/source-app/workflows/build_command_line_interface/index.rst @@ -0,0 +1,55 @@ +###################################### +Develop a Command Line Interface (CLI) +###################################### + +**Audience:** Users looking to create a command line interface for their application. + +---- + +**************************************** +What is a command line interface (CLI) ? +**************************************** + +A command-line interface (CLI) is a text-based user interface (UI) used to run programs, manage computer files and interact with the computer. Command-line interfaces are also called command-line user interfaces, console user interfaces and character user interfaces. + +As an example, Lightning provides a CLI to interact with your Lightning Apps and the `lightning.ai `_ platform as follows: + +.. code-block:: bash + + main + ├── create - Create Lightning AI self-managed resources (clusters, etc…) + │ └── cluster - Create a Lightning AI BYOC compute cluster with your cloud provider credentials. + ├── delete - Delete Lightning AI self-managed resources (clusters, etc…) + │ └── cluster - Delete a Lightning AI BYOC compute cluster and all associated cloud provider resources. + ├── fork - Fork an application. + ├── init - Init a Lightning App and/or component. + │ ├── app + │ ├── component + │ ├── pl-app - Create an app from your PyTorch Lightning source files. + │ └── react-ui - Create a react UI to give a Lightning component a React.js web user interface (UI) + ├── install - Install a Lightning App and/or component. + │ ├── app + │ └── component + ├── list - List Lightning AI self-managed resources (clusters, etc…) + │ ├── apps - List your Lightning AI apps. + │ └── clusters - List your Lightning AI BYOC compute clusters. + ├── login - Log in to your lightning.ai account. + ├── logout - Log out of your lightning.ai account. + ├── run - Run a Lightning application locally or on the cloud. + │ └── app - Run an app from a file. + ├── show - Show given resource. + │ ├── cluster - Groups cluster commands inside show. + │ │ └── logs - Show cluster logs. + │ └── logs - Show cloud application logs. By default prints logs for all currently available components. + ├── stop - Stop your application. + └── tree - show the command tree of your CLI + +Learn more with `Command-line interface `_. + +.. note:: + + The Lightning guideline to build CLI is lightning ... or ... + +---- + +.. include:: index_content.rst diff --git a/docs/source-app/workflows/build_command_line_interface/index_content.rst b/docs/source-app/workflows/build_command_line_interface/index_content.rst new file mode 100644 index 0000000000000..e7ed5cbd94143 --- /dev/null +++ b/docs/source-app/workflows/build_command_line_interface/index_content.rst @@ -0,0 +1,51 @@ +************************************** +Develop a command line interface (CLI) +************************************** + +.. raw:: html + +
+
+ +.. displayitem:: + :header: Develop a CLI with server side code only + :description: Learn how to develop a simple CLI for your application + :col_css: col-md-6 + :button_link: cli.html + :height: 150 + +.. displayitem:: + :header: Develop a CLI with server and client code execution + :description: Learn how to develop a complex CLI for your application + :col_css: col-md-6 + :button_link: cli_client.html + :height: 150 + +.. raw:: html + +
+
+ + +---- + +********** +Learn more +********** + +.. raw:: html + +
+
+ +.. displayitem:: + :header: Develop a RESTful API + :description: Learn how to develop an API for your application. + :col_css: col-md-6 + :button_link: ../build_rest_api/index.html + :height: 150 + +.. raw:: html + +
+
diff --git a/docs/source-app/workflows/build_command_line_interface/post_example.py b/docs/source-app/workflows/build_command_line_interface/post_example.py new file mode 100644 index 0000000000000..de1800530c8c4 --- /dev/null +++ b/docs/source-app/workflows/build_command_line_interface/post_example.py @@ -0,0 +1,27 @@ +import lightning as L +from lightning.app.api import Post + + +class Flow(L.LightningFlow): + + # 1. Define the state + def __init__(self): + super().__init__() + self.names = [] + + # 2. Optional, but used to validate names is modified + def run(self): + print(self.names) + + # 3. Method executed when a request is received. + def handle_post(self, name: str): + self.names.append(name) + return f'The name {name} was registered' + + # 4. Defines this component Restful API. You can have several routes. + def configure_api(self): + # Your own defined route and handler + return [Post(route="/name", method=self.handle_post)] + + +app = L.LightningApp(Flow()) diff --git a/docs/source-app/workflows/build_rest_api/add_api.rst b/docs/source-app/workflows/build_rest_api/add_api.rst new file mode 100644 index 0000000000000..9ec3677b72219 --- /dev/null +++ b/docs/source-app/workflows/build_rest_api/add_api.rst @@ -0,0 +1,83 @@ +**************************** +Add an API Route to your App +**************************** + +In order to add a new route, you need to override the :class:`~lightning_app.core.flow.LightningFlow.configure_api` hook and return a list of :class:`~lightning_app.api.:class:`~lightning_app.api.http_methods.HttpMethod` such as :class:`~lightning_app.api.:class:`~lightning_app.api.http_methods.Get`, :class:`~lightning_app.api.:class:`~lightning_app.api.http_methods.Post`, :class:`~lightning_app.api.:class:`~lightning_app.api.http_methods.Put`, :class:`~lightning_app.api.:class:`~lightning_app.api.http_methods.Delete`. + +Below, we create a single route ``/name`` that takes a string input ``name`` and stores the value within the ``names`` attribute of the flow state. + +.. literalinclude:: post_example.py + +After copy-pasting the code above to a file ``app.py``, execute the following command in your terminal: + +.. code-block:: bash + + lightning run app app.py + +And you find the following: + +.. code-block:: bash + + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + +The Lightning App framework automatically generates an API documentation from your application traditionally a `Swagger UI `_. + +You can access it by accessing the following url: ``http://127.0.0.1:7501/docs`` in your browser and validate your API with the route ``/name`` directly from the documentation page as showed below. + +.. raw:: html + +
+ +
+
+ +Alternatively, you can invoke the route directly from a second terminal using `curl `_. + +.. code-block:: bash + + curl -X 'POST' \ + 'http://127.0.0.1:7501/name?name=my_name' \ + -H 'accept: application/json' \ + -d '' + + "The name my_name was registered" + +And you will observe the following your first terminal running your application. + +.. code-block:: bash + + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + [] + ["my_name"] + +************************************** +Develop a command line interface (CLI) +************************************** + +.. raw:: html + +
+
+ +.. displayitem:: + :header: Add Requests Validation + :description: Learn how to use pydantic with your API. + :col_css: col-md-6 + :button_link: request_validation.html + :height: 150 + +.. displayitem:: + :header: Develop a Command Line Interface (CLI) + :description: Learn how to develop an CLI for your application. + :col_css: col-md-6 + :button_link: ../build_command_line_interface/index.html + :height: 150 + +.. raw:: html + +
+
diff --git a/docs/source-app/workflows/build_rest_api/index.rst b/docs/source-app/workflows/build_rest_api/index.rst new file mode 100644 index 0000000000000..cea577f04e6fe --- /dev/null +++ b/docs/source-app/workflows/build_rest_api/index.rst @@ -0,0 +1,32 @@ +##################### +Develop a RESTful API +##################### + +**Audience:** Users looking to create an API in their application to let users activate functionalities from external sources. + +---- + +*********************** +What is a RESTful API ? +*********************** + +A RESTful API is a set of external url routes exposed by a server that enables clients to trigger some functionalities such as getting or putting some data, uploading files, etc.. + +This provides great flexibility for clients as they can easily discover functionalities made available by the App Builders. + +The Lightning App framework supports the 4 traditional http methods. + +They are guidelines to organize your RESTful Services and help clients understand your functionalities. + +* **Get** is used to read data from the server. +* **Post** is used to create new resources. +* **Put** is used to update/replace existing resources. +* **Delete** is used to delete resources. + +Learn more with `HTTP Methods for RESTful Services `_. + +The Lightning App framework uses the popular `FastAPI `_ and `Pydantic `_ frameworks under the hood e.g you can use all their features while building your application. + +---- + +.. include:: index_content.rst diff --git a/docs/source-app/workflows/build_rest_api/index_content.rst b/docs/source-app/workflows/build_rest_api/index_content.rst new file mode 100644 index 0000000000000..34b269e306a16 --- /dev/null +++ b/docs/source-app/workflows/build_rest_api/index_content.rst @@ -0,0 +1,50 @@ +************************************** +Develop a command line interface (CLI) +************************************** + +.. raw:: html + +
+
+ +.. displayitem:: + :header: Add an API Route to your App + :description: Learn how to develop a simple API for your application + :col_css: col-md-6 + :button_link: add_api.html + :height: 150 + +.. displayitem:: + :header: Add Requests Validation + :description: Learn how to use pydantic with your API. + :col_css: col-md-6 + :button_link: cli_client.html + :height: 150 + +.. raw:: html + +
+
+ +---- + +********** +Learn more +********** + +.. raw:: html + +
+
+ +.. displayitem:: + :header: Develop a Command Line Interface + :description: Learn how to develop an CLI for your application. + :col_css: col-md-6 + :button_link: ../build_command_line_interface/index.html + :height: 150 + +.. raw:: html + +
+
diff --git a/docs/source-app/workflows/build_rest_api/models.py b/docs/source-app/workflows/build_rest_api/models.py new file mode 100644 index 0000000000000..7ebb3ac8c8c17 --- /dev/null +++ b/docs/source-app/workflows/build_rest_api/models.py @@ -0,0 +1,6 @@ +from pydantic import BaseModel + + +# 1. Subclass the BaseModel and defines your payload format. +class NamePostConfig(BaseModel): + name: str diff --git a/docs/source-app/workflows/build_rest_api/post_example.py b/docs/source-app/workflows/build_rest_api/post_example.py new file mode 100644 index 0000000000000..03d033704fff0 --- /dev/null +++ b/docs/source-app/workflows/build_rest_api/post_example.py @@ -0,0 +1,26 @@ +import lightning as L +from lightning.app.api import Post + + +class Flow(L.LightningFlow): + + # 1. Define the state + def __init__(self): + super().__init__() + self.names = [] + + # 2. Optional, but used to validate names is modified + def run(self): + print(self.names) + + # 3. Method executed when a request is received. + def handle_post(self, name: str): + self.names.append(name) + return f'The name {name} was registered' + + # 4. Defines this component Restful API. You can have several routes. + def configure_api(self): + return [Post(route="/name", method=self.handle_post)] + + +app = L.LightningApp(Flow()) diff --git a/docs/source-app/workflows/build_rest_api/post_example_pydantic.py b/docs/source-app/workflows/build_rest_api/post_example_pydantic.py new file mode 100644 index 0000000000000..28b2c682803a3 --- /dev/null +++ b/docs/source-app/workflows/build_rest_api/post_example_pydantic.py @@ -0,0 +1,30 @@ +from models import NamePostConfig # 2. Import your custom model. + +import lightning as L +from lightning.app.api import Post + + +class Flow(L.LightningFlow): + + def __init__(self): + super().__init__() + self.names = [] + + def run(self): + print(self.names) + + # 3. Annotate your input with your custom pydantic model. + def handle_post(self, config: NamePostConfig): + self.names.append(config.name) + return f'The name {config} was registered' + + def configure_api(self): + return [ + Post( + route="/name", + method=self.handle_post, + ) + ] + + +app = L.LightningApp(Flow()) diff --git a/docs/source-app/workflows/build_rest_api/request_validation.rst b/docs/source-app/workflows/build_rest_api/request_validation.rst new file mode 100644 index 0000000000000..1bd47b5a05075 --- /dev/null +++ b/docs/source-app/workflows/build_rest_api/request_validation.rst @@ -0,0 +1,67 @@ +*********************** +Add Requests Validation +*********************** + +The Lightning App framework uses the popular `FastAPI `_ and `Pydantic `_ frameworks under the hood e.g you can use all their features while building your application. + +Pydantic enables fast data validation and settings management using python type annotations and FastAPI is a modern, fast (high-performance), web framework for building APIs. + +You can easily use pydantic by defining your own payload format. + +.. literalinclude:: models.py + +Then, type your handler input with your custom model. + +.. literalinclude:: post_example_pydantic.py + +After running the updated application, the application documentation ``/name`` has changed and takes a JSON with ``{"name": ...}`` as input. + +.. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/rest_post_pydantic.png + :alt: Rest API with Pydantic + :width: 100 % + +You can invoke the RESTful API route ``/name`` with the following command + +.. code-block:: bash + + curl -X 'POST' \ + 'http://127.0.0.1:7501/name' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "name": "my_name" + }' + +.. note:: + + Using curl, you can pass a JSON payload using the ``-d`` argument. + +---- + +********** +Learn more +********** + +.. raw:: html + +
+
+ +.. displayitem:: + :header: Add an API Route to your App + :description: Learn how to develop a simple API for your application + :col_css: col-md-6 + :button_link: add_api.html + :height: 150 + +.. displayitem:: + :header: Develop a Command Line Interface (CLI) + :description: Learn how to develop an CLI for your application. + :col_css: col-md-6 + :button_link: ../build_command_line_interface/index.html + :height: 150 + +.. raw:: html + +
+
diff --git a/src/lightning_app/cli/lightning_cli.py b/src/lightning_app/cli/lightning_cli.py index d590cbc667f8a..c33d0de1d654d 100644 --- a/src/lightning_app/cli/lightning_cli.py +++ b/src/lightning_app/cli/lightning_cli.py @@ -345,7 +345,7 @@ def app_command(): """Execute a function in a running application from its name.""" from lightning_app.utilities.commands.base import _download_command - logger.warn("Lightning Commands are a beta feature and APIs aren't stable yet.") + logger.warn("Lightning Command Line Interface is an experimental feature and unannounced changes are likely.") debug_mode = bool(int(os.getenv("DEBUG", "0"))) From a79bdfbf8d62fe862efc068ed3f05b48af96b921 Mon Sep 17 00:00:00 2001 From: thomas chaton Date: Tue, 30 Aug 2022 17:22:18 +0200 Subject: [PATCH 02/15] update --- .../api_reference/api/lightning_app.core.LightningApp.rst | 5 ++++- .../api_reference/api/lightning_app.core.LightningFlow.rst | 5 ++++- .../api_reference/api/lightning_app.core.LightningWork.rst | 5 ++++- 3 files changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/source-app/api_reference/api/lightning_app.core.LightningApp.rst b/docs/source-app/api_reference/api/lightning_app.core.LightningApp.rst index 8f0a39b44d535..269a4e8f1143a 100644 --- a/docs/source-app/api_reference/api/lightning_app.core.LightningApp.rst +++ b/docs/source-app/api_reference/api/lightning_app.core.LightningApp.rst @@ -1,4 +1,6 @@ -.. role:: hidden +:orphan: + +.. role:: hidden :class: hidden-section .. currentmodule:: lightning_app.core @@ -8,3 +10,4 @@ LightningApp .. autoclass:: LightningApp :members: + :noindex: diff --git a/docs/source-app/api_reference/api/lightning_app.core.LightningFlow.rst b/docs/source-app/api_reference/api/lightning_app.core.LightningFlow.rst index d305b42d6fc38..336efd4d7165b 100644 --- a/docs/source-app/api_reference/api/lightning_app.core.LightningFlow.rst +++ b/docs/source-app/api_reference/api/lightning_app.core.LightningFlow.rst @@ -1,4 +1,6 @@ -.. role:: hidden +:orphan: + +.. role:: hidden :class: hidden-section .. currentmodule:: lightning_app.core @@ -8,3 +10,4 @@ LightningFlow .. autoclass:: LightningFlow :members: + :noindex: diff --git a/docs/source-app/api_reference/api/lightning_app.core.LightningWork.rst b/docs/source-app/api_reference/api/lightning_app.core.LightningWork.rst index 77965e2146757..db80b79e41d8b 100644 --- a/docs/source-app/api_reference/api/lightning_app.core.LightningWork.rst +++ b/docs/source-app/api_reference/api/lightning_app.core.LightningWork.rst @@ -1,4 +1,6 @@ -.. role:: hidden +:orphan: + +.. role:: hidden :class: hidden-section .. currentmodule:: lightning_app.core @@ -8,3 +10,4 @@ LightningWork .. autoclass:: LightningWork :members: + :noindex: From 68348cec719533753823e5ac083dad950abd0475 Mon Sep 17 00:00:00 2001 From: thomas chaton Date: Tue, 30 Aug 2022 19:48:59 +0200 Subject: [PATCH 03/15] update --- .../workflows/build_command_line_interface/cli.rst | 10 ++++++---- .../build_command_line_interface/cli_client.rst | 10 ++++++---- docs/source-app/workflows/build_rest_api/add_api.rst | 2 ++ .../workflows/build_rest_api/request_validation.rst | 2 ++ 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/source-app/workflows/build_command_line_interface/cli.rst b/docs/source-app/workflows/build_command_line_interface/cli.rst index 7f1596476729d..63e9224c5b0cf 100644 --- a/docs/source-app/workflows/build_command_line_interface/cli.rst +++ b/docs/source-app/workflows/build_command_line_interface/cli.rst @@ -1,3 +1,5 @@ +:orphan: + ************************************** Develop a CLI without client side code ************************************** @@ -8,13 +10,13 @@ In order to create your first CLI, you need to override the :class:`~lightning_a After copy-pasting the code above to a file ``app.py``, execute the following command in your terminal in your first terminal. -.. code-block:: bash +.. code-block:: lightning run app app.py And you find the following: -.. code-block:: bash +.. code-block:: Your Lightning App is starting. This won't take long. INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view @@ -22,14 +24,14 @@ And you find the following: In another terminal, you can trigger the command line exposed by your application. -.. code-block:: bash +.. code-block:: lightning add --name=my_name WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. In your first terminal, **Received name: my_name** and **["my_name"]** are printed. -.. code-block:: bash +.. code-block:: Your Lightning App is starting. This won't take long. INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view diff --git a/docs/source-app/workflows/build_command_line_interface/cli_client.rst b/docs/source-app/workflows/build_command_line_interface/cli_client.rst index c9289f1c550a2..6488328618deb 100644 --- a/docs/source-app/workflows/build_command_line_interface/cli_client.rst +++ b/docs/source-app/workflows/build_command_line_interface/cli_client.rst @@ -1,3 +1,5 @@ +:orphan: + *********************************** Develop a CLI with client side code *********************************** @@ -8,7 +10,7 @@ Lightning provides a flexible way to create complex CLI without effort. In the example below, we create a CLI to dynamically run notebooks with the following structures. -.. code-block:: bash +.. code-block:: python app_folder/ commands/ @@ -28,7 +30,7 @@ And in the ``app.py``, add the following code: In your first terminal, run the following command and open the ``http://127.0.0.1:7501/view`` in browser. -.. code-block:: bash +.. code-block:: python lightning run app app.py Your Lightning App is starting. This won't take long. @@ -36,7 +38,7 @@ In your first terminal, run the following command and open the ``http://127.0.0. And a second terminal, run a first notebook -.. code-block:: bash +.. code-block:: python lightning run-notebook --name="my_notebook" WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. @@ -44,7 +46,7 @@ And a second terminal, run a first notebook And run a second notebook. -.. code-block:: bash +.. code-block:: python lightning run-notebook --name="my_notebook_2" WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. diff --git a/docs/source-app/workflows/build_rest_api/add_api.rst b/docs/source-app/workflows/build_rest_api/add_api.rst index 9ec3677b72219..ed68b93a3bef7 100644 --- a/docs/source-app/workflows/build_rest_api/add_api.rst +++ b/docs/source-app/workflows/build_rest_api/add_api.rst @@ -1,3 +1,5 @@ +:orphan: + **************************** Add an API Route to your App **************************** diff --git a/docs/source-app/workflows/build_rest_api/request_validation.rst b/docs/source-app/workflows/build_rest_api/request_validation.rst index 1bd47b5a05075..37d4e0f022f61 100644 --- a/docs/source-app/workflows/build_rest_api/request_validation.rst +++ b/docs/source-app/workflows/build_rest_api/request_validation.rst @@ -1,3 +1,5 @@ +:orphan: + *********************** Add Requests Validation *********************** From 8c438ac4979f2ac437a504b2ee14b0a77437ae43 Mon Sep 17 00:00:00 2001 From: thomas chaton Date: Tue, 30 Aug 2022 20:46:18 +0200 Subject: [PATCH 04/15] update --- tests/tests_app_examples/idle_timeout/app.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/tests_app_examples/idle_timeout/app.py b/tests/tests_app_examples/idle_timeout/app.py index ff45f5332bcaa..218c9e0174d08 100644 --- a/tests/tests_app_examples/idle_timeout/app.py +++ b/tests/tests_app_examples/idle_timeout/app.py @@ -49,7 +49,7 @@ def run(self): assert stopped_status_sigterm.stage == WorkStageStatus.STOPPED assert stopped_status_sigterm.reason == WorkStopReasons.SIGTERM_SIGNAL_HANDLER # Note: Account for the controlplane, k8s, SIGTERM handler delays. - assert (stopped_status_pending.timestamp - succeeded_status.timestamp) < 10 + assert (stopped_status_pending.timestamp - succeeded_status.timestamp) < 20 assert (stopped_status_sigterm.timestamp - stopped_status_pending.timestamp) < 120 fs = filesystem() destination_path = artifacts_path(self.work) / pathlib.Path(*self.work.path.resolve().parts[1:]) From 74c2f42393a347cc91e02ed817792871b427a5f8 Mon Sep 17 00:00:00 2001 From: Felonious-Spellfire Date: Tue, 30 Aug 2022 14:07:02 -0700 Subject: [PATCH 05/15] Review of content --- .../glossary/command_lines/command_lines.rst | 66 +++++++++--------- .../glossary/restful_api/restful_api.rst | 30 ++++---- .../build_command_line_interface/app.py | 10 +-- .../build_command_line_interface/cli.rst | 50 +++++++------- .../cli_client.rst | 60 ++++++++-------- .../commands/notebook/run.py | 2 +- .../build_command_line_interface/index.rst | 68 +++++++++---------- .../post_example.py | 4 +- .../workflows/build_rest_api/add_api.rst | 68 ++++++++++--------- .../workflows/build_rest_api/index.rst | 34 +++++----- .../build_rest_api/index_content.rst | 12 ++-- .../workflows/build_rest_api/post_example.py | 4 +- .../build_rest_api/post_example_pydantic.py | 3 + .../build_rest_api/request_validation.rst | 14 ++-- 14 files changed, 220 insertions(+), 205 deletions(-) diff --git a/docs/source-app/glossary/command_lines/command_lines.rst b/docs/source-app/glossary/command_lines/command_lines.rst index d064ea00894ee..6b0c29f6ffe69 100644 --- a/docs/source-app/glossary/command_lines/command_lines.rst +++ b/docs/source-app/glossary/command_lines/command_lines.rst @@ -1,56 +1,56 @@ :orphan: ############################ -Command Line Interface (CLI) +Command-line Interface (CLI) ############################ -**Audience:** Users looking to create a command line interface for their application. +**Audience:** Users looking to create a command line interface (CLI) for their application. ---- -**************************************** -What is a command line interface (CLI) ? -**************************************** +************** +What is a CLI? +************** -A command-line interface (CLI) is a text-based user interface (UI) used to run programs, manage computer files and interact with the computer. Command-line interfaces are also called command-line user interfaces, console user interfaces and character user interfaces. +A CLI is a text-based user interface (UI) used to run programs, manage computer files and interact with the computer. CLIs are also called command-line user interfaces, console user interfaces and character user interfaces. + +.. note:: + + The Lightning guideline to build CLI is `lightning ...` or ` ...`. As an example, Lightning provides a CLI to interact with your Lightning Apps and the `lightning.ai `_ platform as follows: .. code-block:: bash main - ├── create - Create Lightning AI self-managed resources (clusters, etc…) - │ └── cluster - Create a Lightning AI BYOC compute cluster with your cloud provider credentials. - ├── delete - Delete Lightning AI self-managed resources (clusters, etc…) - │ └── cluster - Delete a Lightning AI BYOC compute cluster and all associated cloud provider resources. - ├── fork - Fork an application. - ├── init - Init a Lightning App and/or component. + ├── create - Creates Lightning AI self-managed resources (clusters, etc…) + │ └── cluster - Creates a Lightning AI BYOC compute cluster with your cloud provider credentials. + ├── delete - Deletes Lightning AI self-managed resources (clusters, etc…) + │ └── cluster - Deletes a Lightning AI BYOC compute cluster and all associated cloud provider resources. + ├── fork - Forks an App. + ├── init - Initializes a Lightning App and/or Component. │ ├── app │ ├── component - │ ├── pl-app - Create an app from your PyTorch Lightning source files. - │ └── react-ui - Create a react UI to give a Lightning component a React.js web user interface (UI) - ├── install - Install a Lightning App and/or component. + │ ├── pl-app - Creates an App from your PyTorch Lightning source files. + │ └── react-ui - Creates a React UI to give a Lightning Component a React.js web UI + ├── install - Installs a Lightning App and/or Component. │ ├── app │ └── component - ├── list - List Lightning AI self-managed resources (clusters, etc…) - │ ├── apps - List your Lightning AI apps. - │ └── clusters - List your Lightning AI BYOC compute clusters. - ├── login - Log in to your lightning.ai account. - ├── logout - Log out of your lightning.ai account. - ├── run - Run a Lightning application locally or on the cloud. - │ └── app - Run an app from a file. - ├── show - Show given resource. + ├── list - Lists Lightning AI self-managed resources (clusters, etc…) + │ ├── apps - Lists your Lightning AI Apps. + │ └── clusters - Lists your Lightning AI BYOC compute clusters. + ├── login - Logs in to your lightning.ai account. + ├── logout - Logs out of your lightning.ai account. + ├── run - Runs a Lightning App locally or on the cloud. + │ └── app - Runs an App from a file. + ├── show - Shows given resource. │ ├── cluster - Groups cluster commands inside show. - │ │ └── logs - Show cluster logs. - │ └── logs - Show cloud application logs. By default prints logs for all currently available components. - ├── stop - Stop your application. - └── tree - show the command tree of your CLI - -Learn more with `Command-line interface `_. - -.. note:: + │ │ └── logs - Shows cluster logs. + │ └── logs - Shows cloud application logs. By default prints logs for all currently available Components. + ├── stop - Stops your App. + └── tree - Shows the command tree of your CLI. - The Lightning guideline to build CLI is lightning ... or ... +Learn more about `Command-line interfaces here `_. ---- @@ -65,7 +65,7 @@ Learn more .. displayitem:: :header: Develop a Command Line Interface - :description: Learn how to develop an CLI for your application. + :description: Learn how to develop a CLI for your App. :col_css: col-md-6 :button_link: ../../workflows/build_command_line_interface/index_content.html :height: 150 diff --git a/docs/source-app/glossary/restful_api/restful_api.rst b/docs/source-app/glossary/restful_api/restful_api.rst index 00d0d62958053..a1128f2234558 100644 --- a/docs/source-app/glossary/restful_api/restful_api.rst +++ b/docs/source-app/glossary/restful_api/restful_api.rst @@ -4,30 +4,30 @@ RESTful API ########### -**Audience:** Users looking to create an API in their application to let users activate functionalities from external sources. +**Audience:** Users looking to create an API in their App to allow users to activate functionalities from external sources. ---- -*********************** -What is a RESTful API ? -*********************** +********************** +What is a RESTful API? +********************** -A RESTful API is a set of external url routes exposed by a server that enables clients to trigger some functionalities such as getting or putting some data, uploading files, etc.. +A RESTful API is a set of external URL routes exposed by a server that enables clients to trigger some functionalities, such as getting or putting some data, uploading files, etc.. -This provides great flexibility for clients as they can easily discover functionalities made available by the App Builders. +This provides great flexibility for users as they can easily discover functionalities made available by the App Builders. -The Lightning App framework supports the 4 traditional http methods. +The Lightning App framework supports the four primary HTTP methods: `GET`, `POST`, `PUT`, `DELETE`. -They are guidelines to organize your RESTful Services and help clients understand your functionalities. +These methods are guidelines to organize your RESTful Services and help users understand your functionalities. -* **Get** is used to read data from the server. -* **Post** is used to create new resources. -* **Put** is used to update/replace existing resources. -* **Delete** is used to delete resources. +* **`GET`:** Reads data from the server. +* **`POST`:** Creates new resources. +* **`PUT`:** Updates/replaces existing resources. +* **`DELETE`:** Deletes resources. -Learn more with `HTTP Methods for RESTful Services `_. +Learn more about `HTTP Methods for RESTful Services here `_. -The Lightning App framework uses the popular `FastAPI `_ and `Pydantic `_ frameworks under the hood e.g you can use all their features while building your application. +The Lightning App framework uses the popular `FastAPI `_ and `Pydantic `_ frameworks under the hood. This means you can use all their features while building your App. ---- @@ -42,7 +42,7 @@ Learn more .. displayitem:: :header: Develop a RESTful API - :description: Learn how to develop an API for your application. + :description: Learn how to develop an API for your App. :col_css: col-md-6 :button_link: ../../workflows/build_rest_api/index_content.html :height: 150 diff --git a/docs/source-app/workflows/build_command_line_interface/app.py b/docs/source-app/workflows/build_command_line_interface/app.py index d5d949ea51304..818f2f1616db6 100644 --- a/docs/source-app/workflows/build_command_line_interface/app.py +++ b/docs/source-app/workflows/build_command_line_interface/app.py @@ -11,17 +11,17 @@ def __init__(self): super().__init__() self.notebooks = Dict() - # 1. Annotate the handler input with the notebook config. + # 1. Annotates the handler input with the Notebook config. def run_notebook(self, config: RunNotebookConfig): if config.name in self.notebooks: - return f"The notebook {config.name} is already created." + return f"The Notebook {config.name} already exists." else: - # 2. Create dynamically the notebook if it doesn't exist and run it. + # 2. Dynamically creates the Notebook if it doesn't exist and runs it. self.notebooks[config.name] = JupyterLab( cloud_compute=L.CloudCompute(config.cloud_compute) ) self.notebooks[config.name].run() - return f"The notebook {config.name} was created." + return f"The Notebook {config.name} was created." def configure_commands(self): # 3. Returns a list of dictionaries with the format: @@ -29,7 +29,7 @@ def configure_commands(self): return [{"run-notebook": RunNotebook(method=self.run_notebook)}] def configure_layout(self): - # 4. Dynamically display the notebooks in the Lightning App View. + # 4. Dynamically displays the Notebooks in the Lightning App View. return [{"name": n, "content": w} for n, w in self.notebooks.items()] diff --git a/docs/source-app/workflows/build_command_line_interface/cli.rst b/docs/source-app/workflows/build_command_line_interface/cli.rst index 7f1596476729d..67e9cf9a16605 100644 --- a/docs/source-app/workflows/build_command_line_interface/cli.rst +++ b/docs/source-app/workflows/build_command_line_interface/cli.rst @@ -2,40 +2,44 @@ Develop a CLI without client side code ************************************** -In order to create your first CLI, you need to override the :class:`~lightning_app.core.flow.LightningFlow.configure_commands` hook and return a list of dictionaries where the keys are the commands and the values are the server-side handlers. +In order to create your first CLI, you need to override the :class:`~lightning_app.core.flow.LightningFlow.configure_commands` hook and return a list of dictionaries where the keys are the commands and the values are the server side handlers. -.. literalinclude:: example_command.py +Here's an example: -After copy-pasting the code above to a file ``app.py``, execute the following command in your terminal in your first terminal. +#. Create a file called ``app.py`` and copy-paste the following code in to the file: -.. code-block:: bash + .. literalinclude:: example_command.py - lightning run app app.py +#. Execute the following command in a terminal: -And you find the following: + .. code-block:: bash -.. code-block:: bash + lightning run app app.py - Your Lightning App is starting. This won't take long. - INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view - [] + The following appears: -In another terminal, you can trigger the command line exposed by your application. + .. code-block:: bash -.. code-block:: bash + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + [] - lightning add --name=my_name - WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. +#. In another terminal, trigger the command line exposed by your App: -In your first terminal, **Received name: my_name** and **["my_name"]** are printed. + .. code-block:: bash -.. code-block:: bash + lightning add --name=my_name + WARNING: Lightning Command-line Interface is an experimental feature and unannounced changes are likely. - Your Lightning App is starting. This won't take long. - INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view - [] - Received name: my_name - ["my_name] +#. In your first terminal, **Received name: my_name** and **["my_name"]** are printed. + + .. code-block:: bash + + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + [] + Received name: my_name + ["my_name] ---- @@ -50,14 +54,14 @@ Learn more .. displayitem:: :header: Develop a CLI with server and client code execution - :description: Learn how to develop a complex API for your application + :description: Learn how to develop a complex API for your App. :col_css: col-md-6 :button_link: cli_client.html :height: 150 .. displayitem:: :header: Develop a RESTful API - :description: Learn how to develop an API for your application. + :description: Learn how to develop an API for your App. :col_css: col-md-6 :button_link: ../build_rest_api/index.html :height: 150 diff --git a/docs/source-app/workflows/build_command_line_interface/cli_client.rst b/docs/source-app/workflows/build_command_line_interface/cli_client.rst index c9289f1c550a2..87956c57e009d 100644 --- a/docs/source-app/workflows/build_command_line_interface/cli_client.rst +++ b/docs/source-app/workflows/build_command_line_interface/cli_client.rst @@ -2,11 +2,13 @@ Develop a CLI with client side code *********************************** -In the previous section, we learned how to create a simple command line interface. In more realistic use-cases, an app builder wants to provide more complex functionalities where trusted code is executed on the client side. +We've learned how to create a simple command-line interface. But in real-world use-cases, an App Builder wants to provide more complex functionalities where trusted code is executed on the client side. -Lightning provides a flexible way to create complex CLI without effort. +Lightning provides a flexible way to create complex CLI without much effort. -In the example below, we create a CLI to dynamically run notebooks with the following structures. +Here's an example: + +We're going to create a CLI to dynamically run Notebooks using the following: .. code-block:: bash @@ -16,41 +18,43 @@ In the example below, we create a CLI to dynamically run notebooks with the foll run.py app.py -Furthermore, we are using the `Jupyter-Component `_. Follow the installation steps on the repo. +We're also going to use the `Lightning Jupyter-Component `_. Follow the installation steps on the repo to install the Component. -In the ``commands/notebook/run.py``, add the following code: +#. In the ``commands/notebook/run.py`` file, add the following code: -.. literalinclude:: commands/notebook/run.py + .. literalinclude:: commands/notebook/run.py -And in the ``app.py``, add the following code: +#. In the ``app.py`` file, add the following code: -.. literalinclude:: app.py + .. literalinclude:: app.py -In your first terminal, run the following command and open the ``http://127.0.0.1:7501/view`` in browser. +#. Open a terminal and run the following command: -.. code-block:: bash + .. code-block:: bash - lightning run app app.py - Your Lightning App is starting. This won't take long. - INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + lightning run app app.py + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view -And a second terminal, run a first notebook +#. Open this link ``http://127.0.0.1:7501/view`` in a web browser. -.. code-block:: bash +#. Open a second terminal, and run this notebook: - lightning run-notebook --name="my_notebook" - WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. - The notebook my_notebook was created. + .. code-block:: bash -And run a second notebook. + lightning run-notebook --name="my_notebook" + WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. + The notebook my_notebook was created. -.. code-block:: bash +#. Now run a second notebook: + + .. code-block:: bash - lightning run-notebook --name="my_notebook_2" - WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. - The notebook my_notebook_2 was created. + lightning run-notebook --name="my_notebook_2" + WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. + The notebook my_notebook_2 was created. -Here is a recording of the Lightning App described above. +This is what the App is going to look like: .. raw:: html @@ -73,15 +77,15 @@ Learn more
.. displayitem:: - :header: Develop a CLI with server side code only - :description: Learn how to develop a simple API for your application + :header: Develop a CLI with server side code only. + :description: Learn how to develop a simple CLI for your App. :col_css: col-md-6 :button_link: cli.html :height: 150 .. displayitem:: - :header: Develop a RESTful API - :description: Learn how to develop an API for your application. + :header: Develop a RESTful API. + :description: Learn how to develop an API for your App. :col_css: col-md-6 :button_link: ../build_rest_api/index.html :height: 150 diff --git a/docs/source-app/workflows/build_command_line_interface/commands/notebook/run.py b/docs/source-app/workflows/build_command_line_interface/commands/notebook/run.py index dd7081f31f753..4e3bc67d9e538 100644 --- a/docs/source-app/workflows/build_command_line_interface/commands/notebook/run.py +++ b/docs/source-app/workflows/build_command_line_interface/commands/notebook/run.py @@ -20,7 +20,7 @@ def run(self): parser.add_argument("--cloud_compute", type=str, default="cpu") hparams = parser.parse_args() - # 2. Invoke the server-side handler by sending a payload. + # 2. Invoke the server side handler by sending a payload. response = self.invoke_handler( config=RunNotebookConfig( name=hparams.name or str(uuid4()), diff --git a/docs/source-app/workflows/build_command_line_interface/index.rst b/docs/source-app/workflows/build_command_line_interface/index.rst index 81bfac572efe1..86839da13c354 100644 --- a/docs/source-app/workflows/build_command_line_interface/index.rst +++ b/docs/source-app/workflows/build_command_line_interface/index.rst @@ -1,54 +1,54 @@ -###################################### -Develop a Command Line Interface (CLI) -###################################### +############################ +Command-line Interface (CLI) +############################ -**Audience:** Users looking to create a command line interface for their application. +**Audience:** Users looking to create a command line interface (CLI) for their application. ---- -**************************************** -What is a command line interface (CLI) ? -**************************************** +************** +What is a CLI? +************** -A command-line interface (CLI) is a text-based user interface (UI) used to run programs, manage computer files and interact with the computer. Command-line interfaces are also called command-line user interfaces, console user interfaces and character user interfaces. +A CLI is a text-based user interface (UI) used to run programs, manage computer files and interact with the computer. CLIs are also called command-line user interfaces, console user interfaces and character user interfaces. + +.. note:: + + The Lightning guideline to build CLI is `lightning ...` or ` ...`. As an example, Lightning provides a CLI to interact with your Lightning Apps and the `lightning.ai `_ platform as follows: .. code-block:: bash main - ├── create - Create Lightning AI self-managed resources (clusters, etc…) - │ └── cluster - Create a Lightning AI BYOC compute cluster with your cloud provider credentials. - ├── delete - Delete Lightning AI self-managed resources (clusters, etc…) - │ └── cluster - Delete a Lightning AI BYOC compute cluster and all associated cloud provider resources. - ├── fork - Fork an application. - ├── init - Init a Lightning App and/or component. + ├── create - Creates Lightning AI self-managed resources (clusters, etc…) + │ └── cluster - Creates a Lightning AI BYOC compute cluster with your cloud provider credentials. + ├── delete - Deletes Lightning AI self-managed resources (clusters, etc…) + │ └── cluster - Deletes a Lightning AI BYOC compute cluster and all associated cloud provider resources. + ├── fork - Forks an App. + ├── init - Initializes a Lightning App and/or Component. │ ├── app │ ├── component - │ ├── pl-app - Create an app from your PyTorch Lightning source files. - │ └── react-ui - Create a react UI to give a Lightning component a React.js web user interface (UI) - ├── install - Install a Lightning App and/or component. + │ ├── pl-app - Creates an App from your PyTorch Lightning source files. + │ └── react-ui - Creates a React UI to give a Lightning Component a React.js web UI + ├── install - Installs a Lightning App and/or Component. │ ├── app │ └── component - ├── list - List Lightning AI self-managed resources (clusters, etc…) - │ ├── apps - List your Lightning AI apps. - │ └── clusters - List your Lightning AI BYOC compute clusters. - ├── login - Log in to your lightning.ai account. - ├── logout - Log out of your lightning.ai account. - ├── run - Run a Lightning application locally or on the cloud. - │ └── app - Run an app from a file. - ├── show - Show given resource. + ├── list - Lists Lightning AI self-managed resources (clusters, etc…) + │ ├── apps - Lists your Lightning AI Apps. + │ └── clusters - Lists your Lightning AI BYOC compute clusters. + ├── login - Logs in to your lightning.ai account. + ├── logout - Logs out of your lightning.ai account. + ├── run - Runs a Lightning App locally or on the cloud. + │ └── app - Runs an App from a file. + ├── show - Shows given resource. │ ├── cluster - Groups cluster commands inside show. - │ │ └── logs - Show cluster logs. - │ └── logs - Show cloud application logs. By default prints logs for all currently available components. - ├── stop - Stop your application. - └── tree - show the command tree of your CLI - -Learn more with `Command-line interface `_. - -.. note:: + │ │ └── logs - Shows cluster logs. + │ └── logs - Shows cloud application logs. By default prints logs for all currently available Components. + ├── stop - Stops your App. + └── tree - Shows the command tree of your CLI. - The Lightning guideline to build CLI is lightning ... or ... +Learn more about `Command-line interfaces here `_. ---- diff --git a/docs/source-app/workflows/build_command_line_interface/post_example.py b/docs/source-app/workflows/build_command_line_interface/post_example.py index de1800530c8c4..c7f87f1cffdf7 100644 --- a/docs/source-app/workflows/build_command_line_interface/post_example.py +++ b/docs/source-app/workflows/build_command_line_interface/post_example.py @@ -9,7 +9,7 @@ def __init__(self): super().__init__() self.names = [] - # 2. Optional, but used to validate names is modified + # 2. Optional, but used to validate names def run(self): print(self.names) @@ -18,7 +18,7 @@ def handle_post(self, name: str): self.names.append(name) return f'The name {name} was registered' - # 4. Defines this component Restful API. You can have several routes. + # 4. Defines this Component's Restful API. You can have several routes. def configure_api(self): # Your own defined route and handler return [Post(route="/name", method=self.handle_post)] diff --git a/docs/source-app/workflows/build_rest_api/add_api.rst b/docs/source-app/workflows/build_rest_api/add_api.rst index 9ec3677b72219..473e5e4982215 100644 --- a/docs/source-app/workflows/build_rest_api/add_api.rst +++ b/docs/source-app/workflows/build_rest_api/add_api.rst @@ -4,55 +4,59 @@ Add an API Route to your App In order to add a new route, you need to override the :class:`~lightning_app.core.flow.LightningFlow.configure_api` hook and return a list of :class:`~lightning_app.api.:class:`~lightning_app.api.http_methods.HttpMethod` such as :class:`~lightning_app.api.:class:`~lightning_app.api.http_methods.Get`, :class:`~lightning_app.api.:class:`~lightning_app.api.http_methods.Post`, :class:`~lightning_app.api.:class:`~lightning_app.api.http_methods.Put`, :class:`~lightning_app.api.:class:`~lightning_app.api.http_methods.Delete`. -Below, we create a single route ``/name`` that takes a string input ``name`` and stores the value within the ``names`` attribute of the flow state. +Here's an example: -.. literalinclude:: post_example.py +We're going to create a single route ``/name`` that takes a string input ``name`` and stores the value within the ``names`` attribute of the flow state. -After copy-pasting the code above to a file ``app.py``, execute the following command in your terminal: +#. Create a file called ``app.py`` and copy-paste the following code in to the file: -.. code-block:: bash + .. literalinclude:: post_example.py - lightning run app app.py +#. Execute the following command in a terminal: -And you find the following: + .. code-block:: bash -.. code-block:: bash + lightning run app app.py - Your Lightning App is starting. This won't take long. - INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + The following appears: -The Lightning App framework automatically generates an API documentation from your application traditionally a `Swagger UI `_. + .. code-block:: bash -You can access it by accessing the following url: ``http://127.0.0.1:7501/docs`` in your browser and validate your API with the route ``/name`` directly from the documentation page as showed below. + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view -.. raw:: html + The Lightning App framework automatically generates API documentation from your App using `Swagger UI `_. + + You can access it by accessing the following URL: ``http://127.0.0.1:7501/docs`` in your browser and validate your API with the route ``/name`` directly from the documentation page as shown below. + + .. raw:: html -
- -
-
+
+ +
+
-Alternatively, you can invoke the route directly from a second terminal using `curl `_. + Alternatively, you can invoke the route directly from a second terminal using `curl `_. -.. code-block:: bash + .. code-block:: bash - curl -X 'POST' \ - 'http://127.0.0.1:7501/name?name=my_name' \ - -H 'accept: application/json' \ - -d '' + curl -X 'POST' \ + 'http://127.0.0.1:7501/name?name=my_name' \ + -H 'accept: application/json' \ + -d '' - "The name my_name was registered" + "The name my_name was registered" -And you will observe the following your first terminal running your application. + And you can see the following in your first terminal running your App. -.. code-block:: bash + .. code-block:: bash - Your Lightning App is starting. This won't take long. - INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view - [] - ["my_name"] + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + [] + ["my_name"] ************************************** Develop a command line interface (CLI) @@ -72,7 +76,7 @@ Develop a command line interface (CLI) .. displayitem:: :header: Develop a Command Line Interface (CLI) - :description: Learn how to develop an CLI for your application. + :description: Learn how to develop an CLI for your App. :col_css: col-md-6 :button_link: ../build_command_line_interface/index.html :height: 150 diff --git a/docs/source-app/workflows/build_rest_api/index.rst b/docs/source-app/workflows/build_rest_api/index.rst index cea577f04e6fe..269b810ec6442 100644 --- a/docs/source-app/workflows/build_rest_api/index.rst +++ b/docs/source-app/workflows/build_rest_api/index.rst @@ -1,31 +1,31 @@ -##################### -Develop a RESTful API -##################### +########### +RESTful API +########### -**Audience:** Users looking to create an API in their application to let users activate functionalities from external sources. +**Audience:** Users looking to create an API in their App to allow users to activate functionalities from external sources. ---- -*********************** -What is a RESTful API ? -*********************** +********************** +What is a RESTful API? +********************** -A RESTful API is a set of external url routes exposed by a server that enables clients to trigger some functionalities such as getting or putting some data, uploading files, etc.. +A RESTful API is a set of external URL routes exposed by a server that enables clients to trigger some functionalities, such as getting or putting some data, uploading files, etc.. -This provides great flexibility for clients as they can easily discover functionalities made available by the App Builders. +This provides great flexibility for users as they can easily discover functionalities made available by the App Builders. -The Lightning App framework supports the 4 traditional http methods. +The Lightning App framework supports the four primary HTTP methods: `GET`, `POST`, `PUT`, `DELETE`. -They are guidelines to organize your RESTful Services and help clients understand your functionalities. +These methods are guidelines to organize your RESTful Services and help users understand your functionalities. -* **Get** is used to read data from the server. -* **Post** is used to create new resources. -* **Put** is used to update/replace existing resources. -* **Delete** is used to delete resources. +* **`GET`:** Reads data from the server. +* **`POST`:** Creates new resources. +* **`PUT`:** Updates/replaces existing resources. +* **`DELETE`:** Deletes resources. -Learn more with `HTTP Methods for RESTful Services `_. +Learn more about `HTTP Methods for RESTful Services here `_. -The Lightning App framework uses the popular `FastAPI `_ and `Pydantic `_ frameworks under the hood e.g you can use all their features while building your application. +The Lightning App framework uses the popular `FastAPI `_ and `Pydantic `_ frameworks under the hood. This means you can use all their features while building your App. ---- diff --git a/docs/source-app/workflows/build_rest_api/index_content.rst b/docs/source-app/workflows/build_rest_api/index_content.rst index 34b269e306a16..9f77225f24f59 100644 --- a/docs/source-app/workflows/build_rest_api/index_content.rst +++ b/docs/source-app/workflows/build_rest_api/index_content.rst @@ -1,6 +1,6 @@ -************************************** -Develop a command line interface (CLI) -************************************** +************** +Develop an API +************** .. raw:: html @@ -9,7 +9,7 @@ Develop a command line interface (CLI) .. displayitem:: :header: Add an API Route to your App - :description: Learn how to develop a simple API for your application + :description: Learn how to develop a simple API for your App. :col_css: col-md-6 :button_link: add_api.html :height: 150 @@ -38,8 +38,8 @@ Learn more
.. displayitem:: - :header: Develop a Command Line Interface - :description: Learn how to develop an CLI for your application. + :header: Develop a Command-line Interface + :description: Learn how to develop an CLI for your App. :col_css: col-md-6 :button_link: ../build_command_line_interface/index.html :height: 150 diff --git a/docs/source-app/workflows/build_rest_api/post_example.py b/docs/source-app/workflows/build_rest_api/post_example.py index 03d033704fff0..4a306f176e4b0 100644 --- a/docs/source-app/workflows/build_rest_api/post_example.py +++ b/docs/source-app/workflows/build_rest_api/post_example.py @@ -9,7 +9,7 @@ def __init__(self): super().__init__() self.names = [] - # 2. Optional, but used to validate names is modified + # 2. Optional, but used to validate names def run(self): print(self.names) @@ -18,7 +18,7 @@ def handle_post(self, name: str): self.names.append(name) return f'The name {name} was registered' - # 4. Defines this component Restful API. You can have several routes. + # 4. Defines this Component's Restful API. You can have several routes. def configure_api(self): return [Post(route="/name", method=self.handle_post)] diff --git a/docs/source-app/workflows/build_rest_api/post_example_pydantic.py b/docs/source-app/workflows/build_rest_api/post_example_pydantic.py index 28b2c682803a3..e3c16ca35de48 100644 --- a/docs/source-app/workflows/build_rest_api/post_example_pydantic.py +++ b/docs/source-app/workflows/build_rest_api/post_example_pydantic.py @@ -6,10 +6,12 @@ class Flow(L.LightningFlow): + # 1. Define the state def __init__(self): super().__init__() self.names = [] + # 2. Optional, but used to validate names def run(self): print(self.names) @@ -18,6 +20,7 @@ def handle_post(self, config: NamePostConfig): self.names.append(config.name) return f'The name {config} was registered' + # 4. Defines this Component's Restful API. You can have several routes. def configure_api(self): return [ Post( diff --git a/docs/source-app/workflows/build_rest_api/request_validation.rst b/docs/source-app/workflows/build_rest_api/request_validation.rst index 1bd47b5a05075..122b0f4092bab 100644 --- a/docs/source-app/workflows/build_rest_api/request_validation.rst +++ b/docs/source-app/workflows/build_rest_api/request_validation.rst @@ -2,9 +2,9 @@ Add Requests Validation *********************** -The Lightning App framework uses the popular `FastAPI `_ and `Pydantic `_ frameworks under the hood e.g you can use all their features while building your application. +The Lightning App framework uses the popular `FastAPI `_ and `Pydantic `_ frameworks under the hood. This means you can use all their features while building your App. -Pydantic enables fast data validation and settings management using python type annotations and FastAPI is a modern, fast (high-performance), web framework for building APIs. +pydantic enables fast data validation and settings management using Python type annotations and FastAPI is a modern, fast (high-performance), web framework for building APIs. You can easily use pydantic by defining your own payload format. @@ -14,13 +14,13 @@ Then, type your handler input with your custom model. .. literalinclude:: post_example_pydantic.py -After running the updated application, the application documentation ``/name`` has changed and takes a JSON with ``{"name": ...}`` as input. +After running the updated App, the App documentation ``/name`` has changed and takes JSON with ``{"name": ...}`` as input. .. figure:: https://pl-flash-data.s3.amazonaws.com/assets_lightning/rest_post_pydantic.png - :alt: Rest API with Pydantic + :alt: Rest API with pydantic :width: 100 % -You can invoke the RESTful API route ``/name`` with the following command +You can invoke the RESTful API route ``/name`` with the following command: .. code-block:: bash @@ -49,14 +49,14 @@ Learn more .. displayitem:: :header: Add an API Route to your App - :description: Learn how to develop a simple API for your application + :description: Learn how to develop a simple API for your App. :col_css: col-md-6 :button_link: add_api.html :height: 150 .. displayitem:: :header: Develop a Command Line Interface (CLI) - :description: Learn how to develop an CLI for your application. + :description: Learn how to develop an CLI for your App. :col_css: col-md-6 :button_link: ../build_command_line_interface/index.html :height: 150 From ed01a4294110487a749a23defad4df06cc28da7f Mon Sep 17 00:00:00 2001 From: Felonious-Spellfire Date: Tue, 30 Aug 2022 15:35:25 -0700 Subject: [PATCH 06/15] Formatting updates --- .../build_command_line_interface/cli.rst | 42 ++++++------- .../cli_client.rst | 28 ++++----- .../workflows/build_rest_api/add_api.rst | 62 +++++++++---------- 3 files changed, 65 insertions(+), 67 deletions(-) diff --git a/docs/source-app/workflows/build_command_line_interface/cli.rst b/docs/source-app/workflows/build_command_line_interface/cli.rst index 853534079f53f..a3925ea0725bb 100644 --- a/docs/source-app/workflows/build_command_line_interface/cli.rst +++ b/docs/source-app/workflows/build_command_line_interface/cli.rst @@ -1,49 +1,47 @@ :orphan: -************************************** +###################################### Develop a CLI without client side code -************************************** +###################################### In order to create your first CLI, you need to override the :class:`~lightning_app.core.flow.LightningFlow.configure_commands` hook and return a list of dictionaries where the keys are the commands and the values are the server side handlers. Here's an example: -#. Create a file called ``app.py`` and copy-paste the following code in to the file: +**Step 1:** Create a file called ``app.py`` and copy-paste the following code in to the file: - .. literalinclude:: example_command.py +.. literalinclude:: example_command.py -#. Execute the following command in a terminal: +**Step 2:** Execute the following command in a terminal: - .. code-block:: python +.. code-block:: python - lightning run app app.py + lightning run app app.py - The following appears: +The following appears: - .. code-block:: python +.. code-block:: python Your Lightning App is starting. This won't take long. INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view [] -#. In another terminal, trigger the command line exposed by your App: +**Step 3:** In another terminal, trigger the command line exposed by your App: - .. code-block:: python +.. code-block:: python - lightning add --name=my_name - WARNING: Lightning Command-line Interface is an experimental feature and unannounced changes are likely. + lightning add --name=my_name + WARNING: Lightning Command-line Interface is an experimental feature and unannounced changes are likely. -#. In your first terminal, **Received name: my_name** and **["my_name"]** are printed. +In your first terminal, **Received name: my_name** and **["my_name"]** are printed. - .. code-block:: python +.. code-block:: python - Your Lightning App is starting. This won't take long. - INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view - [] - Received name: my_name - ["my_name] - ----- + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + [] + Received name: my_name + ["my_name] ********** Learn more diff --git a/docs/source-app/workflows/build_command_line_interface/cli_client.rst b/docs/source-app/workflows/build_command_line_interface/cli_client.rst index a0635a832aff0..7d697938f1607 100644 --- a/docs/source-app/workflows/build_command_line_interface/cli_client.rst +++ b/docs/source-app/workflows/build_command_line_interface/cli_client.rst @@ -1,8 +1,8 @@ :orphan: -*********************************** +################################### Develop a CLI with client side code -*********************************** +################################### We've learned how to create a simple command-line interface. But in real-world use-cases, an App Builder wants to provide more complex functionalities where trusted code is executed on the client side. @@ -22,25 +22,25 @@ We're going to create a CLI to dynamically run Notebooks using the following: We're also going to use the `Lightning Jupyter-Component `_. Follow the installation steps on the repo to install the Component. -#. In the ``commands/notebook/run.py`` file, add the following code: +**Step 1:** In the ``commands/notebook/run.py`` file, add the following code: - .. literalinclude:: commands/notebook/run.py +.. literalinclude:: commands/notebook/run.py -#. In the ``app.py`` file, add the following code: +**Step 2:** In the ``app.py`` file, add the following code: - .. literalinclude:: app.py +.. literalinclude:: app.py -#. Open a terminal and run the following command: +**Step 3:** Open a terminal and run the following command: - .. code-block:: python +.. code-block:: python - lightning run app app.py - Your Lightning App is starting. This won't take long. - INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + lightning run app app.py + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view -#. Open this link ``http://127.0.0.1:7501/view`` in a web browser. +**Step 4:** Open this link ``http://127.0.0.1:7501/view`` in a web browser. -#. Open a second terminal, and run this notebook: +**Step 5:** Open a second terminal, and run this notebook: .. code-block:: python @@ -48,7 +48,7 @@ We're also going to use the `Lightning Jupyter-Component `_. +The Lightning App framework automatically generates API documentation from your App using `Swagger UI `_. - You can access it by accessing the following URL: ``http://127.0.0.1:7501/docs`` in your browser and validate your API with the route ``/name`` directly from the documentation page as shown below. +You can access it by accessing the following URL: ``http://127.0.0.1:7501/docs`` in your browser and validate your API with the route ``/name`` directly from the documentation page as shown below. - .. raw:: html +.. raw:: html -
- -
-
+
+ +
+
- Alternatively, you can invoke the route directly from a second terminal using `curl `_. +Alternatively, you can invoke the route directly from a second terminal using `curl `_. - .. code-block:: bash +.. code-block:: bash - curl -X 'POST' \ - 'http://127.0.0.1:7501/name?name=my_name' \ - -H 'accept: application/json' \ - -d '' + curl -X 'POST' \ + 'http://127.0.0.1:7501/name?name=my_name' \ + -H 'accept: application/json' \ + -d '' - "The name my_name was registered" + "The name my_name was registered" - And you can see the following in your first terminal running your App. +And you can see the following in your first terminal running your App. - .. code-block:: bash +.. code-block:: bash - Your Lightning App is starting. This won't take long. - INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view - [] - ["my_name"] + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + [] + ["my_name"] ************************************** Develop a command line interface (CLI) From 53af1a22bde19742826a09bc20b2f44aa9ca7d8b Mon Sep 17 00:00:00 2001 From: Felonious-Spellfire Date: Tue, 30 Aug 2022 15:53:53 -0700 Subject: [PATCH 07/15] Fomatting updates --- docs/source-app/workflows/build_rest_api/add_api.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/source-app/workflows/build_rest_api/add_api.rst b/docs/source-app/workflows/build_rest_api/add_api.rst index e469df2277d2f..6f0efb1ded150 100644 --- a/docs/source-app/workflows/build_rest_api/add_api.rst +++ b/docs/source-app/workflows/build_rest_api/add_api.rst @@ -22,7 +22,7 @@ lightning run app app.py The following appears: -.. code-block:: bash +.. code-block:: Your Lightning App is starting. This won't take long. INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view @@ -33,16 +33,13 @@ You can access it by accessing the following URL: ``http://127.0.0.1:7501/docs`` .. raw:: html -
-
-
Alternatively, you can invoke the route directly from a second terminal using `curl `_. -.. code-block:: bash +.. code-block:: curl curl -X 'POST' \ 'http://127.0.0.1:7501/name?name=my_name' \ @@ -53,7 +50,7 @@ Alternatively, you can invoke the route directly from a second terminal using `c And you can see the following in your first terminal running your App. -.. code-block:: bash +.. code-block:: Your Lightning App is starting. This won't take long. INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view From ca6fd22bf672eebe4a44430cd885aed2ee97cd6b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 30 Aug 2022 22:55:38 +0000 Subject: [PATCH 08/15] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/source-app/workflows/build_rest_api/add_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source-app/workflows/build_rest_api/add_api.rst b/docs/source-app/workflows/build_rest_api/add_api.rst index 6f0efb1ded150..59c9c01e456ec 100644 --- a/docs/source-app/workflows/build_rest_api/add_api.rst +++ b/docs/source-app/workflows/build_rest_api/add_api.rst @@ -50,7 +50,7 @@ Alternatively, you can invoke the route directly from a second terminal using `c And you can see the following in your first terminal running your App. -.. code-block:: +.. code-block:: Your Lightning App is starting. This won't take long. INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view From fb54f9889b00de5234ad6c24dd9d5232de863761 Mon Sep 17 00:00:00 2001 From: Felonious-Spellfire Date: Tue, 30 Aug 2022 18:43:36 -0700 Subject: [PATCH 09/15] Updates based on new commits --- .../build_command_line_interface/cli.rst | 116 ++++++++++++---- .../cli_client.rst | 126 ++++++++++++++---- .../workflows/build_rest_api/add_api.rst | 28 +++- 3 files changed, 214 insertions(+), 56 deletions(-) diff --git a/docs/source-app/workflows/build_command_line_interface/cli.rst b/docs/source-app/workflows/build_command_line_interface/cli.rst index a3925ea0725bb..1e11f98795e24 100644 --- a/docs/source-app/workflows/build_command_line_interface/cli.rst +++ b/docs/source-app/workflows/build_command_line_interface/cli.rst @@ -4,44 +4,112 @@ Develop a CLI without client side code ###################################### -In order to create your first CLI, you need to override the :class:`~lightning_app.core.flow.LightningFlow.configure_commands` hook and return a list of dictionaries where the keys are the commands and the values are the server side handlers. +---- -Here's an example: +************************* +1. Implement a simple CLI +************************* -**Step 1:** Create a file called ``app.py`` and copy-paste the following code in to the file: +To create your first CLI, you need to override the :class:`~lightning_app.core.flow.LightningFlow.configure_commands` hook and return a list of dictionaries where the keys are the commands and the values are the server side handlers. + +First, create a file ``app.py`` and copy-paste the following code in to the file: .. literalinclude:: example_command.py -**Step 2:** Execute the following command in a terminal: +---- + +************** +2. Run the App +************** + +Execute the following command in a terminal: + +.. code-block:: + + lightning run app app.py + +The following appears the terminal: + +.. code-block:: + + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + [] + +---- + +*************************** +3. Connect to a running App +*************************** + +In another terminal, connect to the running App. +When you connect to an App, the Lightning CLI is replaced by the App CLI. To exit the App CLI, you need to run ``lightning disconnect``. + +.. code-block:: + + lightning connect localhost -.. code-block:: python +To see a list of available commands: - lightning run app app.py +.. code-block:: -The following appears: + lightning --help + You are connected to the cloud Lightning App: localhost. + Usage: lightning [OPTIONS] COMMAND [ARGS]... -.. code-block:: python + --help Show this message and exit. - Your Lightning App is starting. This won't take long. - INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view - [] + Lightning App Commands + add Description -**Step 3:** In another terminal, trigger the command line exposed by your App: +To find the arguments of the commands: -.. code-block:: python +.. code-block:: - lightning add --name=my_name - WARNING: Lightning Command-line Interface is an experimental feature and unannounced changes are likely. + lightning add --help + You are connected to the cloud Lightning App: localhost. + Usage: lightning add [ARGS]... + + Options + name: Add description + +---- + +******************** +4. Execute a command +******************** + +Trigger the command line exposed by your App: + +.. code-block:: + + lightning add --name=my_name + WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. In your first terminal, **Received name: my_name** and **["my_name"]** are printed. -.. code-block:: python +.. code-block:: + + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + [] + Received name: my_name + ["my_name] + +---- + +************************** +5. Disconnect from the App +************************** + +To exit the App CLI, you need to run ``lightning disconnect``. + +.. code-block:: + + lightning disconnect + You are disconnected from the local Lightning App. - Your Lightning App is starting. This won't take long. - INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view - [] - Received name: my_name - ["my_name] +---- ********** Learn more @@ -54,14 +122,14 @@ Learn more .. displayitem:: :header: Develop a CLI with server and client code execution - :description: Learn how to develop a complex API for your App. + :description: Learn how to develop a complex API for your application :col_css: col-md-6 :button_link: cli_client.html :height: 150 .. displayitem:: :header: Develop a RESTful API - :description: Learn how to develop an API for your App. + :description: Learn how to develop an API for your application. :col_css: col-md-6 :button_link: ../build_rest_api/index.html :height: 150 @@ -69,4 +137,4 @@ Learn more .. raw:: html
- + \ No newline at end of file diff --git a/docs/source-app/workflows/build_command_line_interface/cli_client.rst b/docs/source-app/workflows/build_command_line_interface/cli_client.rst index 7d697938f1607..673f1d3bee231 100644 --- a/docs/source-app/workflows/build_command_line_interface/cli_client.rst +++ b/docs/source-app/workflows/build_command_line_interface/cli_client.rst @@ -8,9 +8,13 @@ We've learned how to create a simple command-line interface. But in real-world u Lightning provides a flexible way to create complex CLI without much effort. -Here's an example: +---- + +************************** +1. Implement a complex CLI +************************** -We're going to create a CLI to dynamically run Notebooks using the following: +In this example, we'll create a CLI to dynamically run Notebooks using the following structures: .. code-block:: python @@ -20,53 +24,123 @@ We're going to create a CLI to dynamically run Notebooks using the following: run.py app.py -We're also going to use the `Lightning Jupyter-Component `_. Follow the installation steps on the repo to install the Component. +We'll use the `Jupyter-Component `_. Follow the installation steps on the repo to install the Component. -**Step 1:** In the ``commands/notebook/run.py`` file, add the following code: +Add the following code to ``commands/notebook/run.py``: .. literalinclude:: commands/notebook/run.py -**Step 2:** In the ``app.py`` file, add the following code: +Add the following code to ``app.py``: .. literalinclude:: app.py -**Step 3:** Open a terminal and run the following command: +---- + +********************************************** +2. Run the App and check the API documentation +********************************************** + +In a terminal, run the following command and open ``http://127.0.0.1:7501/view`` in a browser. .. code-block:: python - lightning run app app.py - Your Lightning App is starting. This won't take long. - INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + lightning run app app.py + Your Lightning App is starting. This won't take long. + INFO: Your app has started. View it in your browser: http://127.0.0.1:7501/view + +---- + +*************************** +3. Connect to a running App +*************************** + +In another terminal, connect to the running App. +When you connect to an App, the Lightning CLI is replaced by the App CLI. To exit the App CLI, you need to run ``lightning disconnect``. + +.. code-block:: + + lightning connect localhost + + Storing `run_notebook` under /Users/thomas/.lightning/lightning_connection/commands/run_notebook.py + You can review all the downloaded commands under /Users/thomas/.lightning/lightning_connection/commands folder. + You are connected to the local Lightning App. + +To see a list of available commands: + +.. code-block:: + + lightning --help + + You are connected to the cloud Lightning App: localhost. + Usage: lightning [OPTIONS] COMMAND [ARGS]... + + --help Show this message and exit. -**Step 4:** Open this link ``http://127.0.0.1:7501/view`` in a web browser. + Lightning App Commands + run notebook Description -**Step 5:** Open a second terminal, and run this notebook: - .. code-block:: python +To find the arguments of the commands: - lightning run-notebook --name="my_notebook" - WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. - The notebook my_notebook was created. +.. code-block:: -**Step 6:** Now run a second notebook: + lightning run notebook --help - .. code-block:: python + You are connected to the cloud Lightning App: localhost. + usage: notebook [-h] [--name NAME] [--cloud_compute CLOUD_COMPUTE] - lightning run-notebook --name="my_notebook_2" - WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. - The notebook my_notebook_2 was created. + Run Notebook Parser -This is what the App is going to look like: + optional arguments: + -h, --help show this help message and exit + --name NAME + --cloud_compute CLOUD_COMPUTE + +---- + +******************** +4. Execute a command +******************** + +And then you can trigger the command-line exposed by your App. + +Run the first Notebook with the following command: + +.. code-block:: python + + lightning run notebook --name="my_notebook" + WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. + The notebook my_notebook was created. + +And run a second Notebook by changing its name: + +.. code-block:: python + + lightning run notebook --name="my_notebook_2" + WARNING: Lightning Command Line Interface is an experimental feature and unannounced changes are likely. + The notebook my_notebook_2 was created. + +Here is a recording of the Lightning App: .. raw:: html
-