Shell Support

Warning

The current page still doesn't have a translation for this language.

But you can help translating it: Contributing.

This is a simple support for an interactive shell with Esmerald. This directive simply loads some of the defaults such as Gateway, Router, Include, OpenAPIResponse, settings and some others by default (like Pydantic BaseModel, FieldInfo...) saving you time every time you need to use an interactive shell to test some ad-hoc processes.

Esmerald gives you that possibility completely out of the box and ready to use with your application.

Important

Before reading this section, you should get familiar with the ways Esmerald handles the discovery of the applications.

The following examples and explanations will be using the auto discovery but --app and environment variables approach but the is equally valid and works in the same way.

How does it work

Esmerald ecosystem is complex internally but simpler to the user. Esmerald will use the application discovery to understand some of your defaults and events and start the shell.

Requirements

To run any of the available shells you will need ipython or ptpython or both installed.

IPython

$ pip install ipython

or

$ pip install esmerald[ipython]

PTPython

$ pip install ptpython

or

$ pip install esmerald[ptpyton]

How to call it

With auto discovery

Default shell

$ esmerald shell

PTPython shell

$ esmerald shell --kernel ptpython

With --app and environment variables

--app

$ esmerald --app myproject.main:app shell

Environment variables

$ export ESMERALD_DEFAULT_APP=--app myproject.main:app
$ esmerald shell --kernel ptpython

If you want to use your custom EsmeraldSettings

Sometimes you want to use your application settings as well while loading the shell. You can see more details about the settings and how to use them.

MacOS & LinuxWindows

$ export ESMERALD_SETTINGS_MODULE=MyCustomSettings
$ export ESMERALD_DEFAULT_APP=--app myproject.main:app
$ esmerald shell # default
$ esmerald shell --kernel ptpython # start with ptpython

$ $env:ESMERALD_SETTINGS_MODULE=="MyCustomSettings"
$ $env:ESMERALD_DEFAULT_APP=--app myproject.main:app
$ esmerald shell # default
$ esmerald shell --kernel ptpython # start with ptpython

How does it look like

Esmerald doesn't want to load all python globals and locals for you. Instead loads all the essentials and some python packages automatically for you but you can still import others.

It looks like this:

Of course the ESMERALD-VERSION, YOUR-APPLICATION-TITLE and YOUR-APPLICATION-VERSION are replaced automatically by the version you are using.

Pretty cool, right? Then it is a normal python shell where you can import whatever you want and need as per normal python shell interaction.