<commit_before>.. _quickstart:

Quickstart
==========

Eager to get started?  This page gives a good introduction in how to get
started with Flask.  This assumes you already have Flask installed.  If
you do not, head over to the :ref:`installation` section.


A Minimal Application
---------------------

A minimal Flask application looks something like that::

    from flask import Flask
    app = Flask(__name__)

    @app.route('/')
    def hello_world():
        return "Hello World!"

    if __name__ == '__main__':
        app.run()

Just save it as `hello.py` or something similar and run it with your
Python interpreter.  Make sure to not call your application `flask.py`
because this would conflict with Flask itself.

::

    $ python hello.py
     * Running on http://127.0.0.1:5000/

Head over to `http://127.0.0.1:5000/ <http://127.0.0.1:5000/>`_, you should
see your hello world greeting.

So what did that code do?

1. First we imported the :class:`~flask.Flask` class.  An instance of this
   class will be our WSGI application.  The first argument is the name of
   the application's module.  If you are using a single module (like here)
   you should use `__name__` because depending on if it's started as
   application or imported as module the name will be different
   (``'__main__'`` versus the actual import name).  For more information
   on that, have a look at the :class:`~flask.Flask` documentation.
2. Next we create an instance of it.  We pass it the name of the module /
   package.  This is needed so that Flask knows where it should look for
   templates, static files and so on.
3. Then we use the :meth:`~flask.Flask.route` decorator to tell Flask
   what URL should trigger our function.
4. The function then has a name which is also used to generate URLs to
   that particular function, and returns the message we want to display in
   the user's browser.
5. Finally we use the :meth:`~flask.Flask.run` function to run the
   local server with our application.  The ``if __name__ == '__main__':``
   makes sure the server only runs if the script is executed directly from
   the Python interpreter and not used as imported module.

To stop the server, hit control-C.

.. _public-server:

.. admonition:: Externally Visible Server

   If you run the server you will notice that the server is only available
   from your own computer, not from any other in the network.  This is the
   default because in debugging mode a user of the application can execute
   arbitrary Python code on your computer.  If you have `debug` disabled
   or trust the users on your network, you can make the server publicly
   available.

   Just change the call of the :meth:`~flask.Flask.run` method to look
   like this::

       app.run(host='0.0.0.0')

   This tells your operating system to listen on a public IP.


Debug Mode
----------

The :meth:`~flask.Flask.run` method is nice to start a local
development server, but you would have to restart it manually after each
change you do to code.  That is not very nice and Flask can do better.  If
you enable the debug support the server will reload itself on code changes
and also provide you with a helpful debugger if things go wrong.

There are two ways to enable debugging.  Either set that flag on the
application object::

    app.debug = True
    app.run()

Or pass it to run::

    app.run(debug=True)

Both will have exactly the same effect.

.. admonition:: Attention

   Even though the interactive debugger does not work in forking environments
   (which makes it nearly impossible to use on production servers), it still
   allows the execution of arbitrary code. That makes it a major security
   risk and therefore it **must never be used on production machines**.

Screenshot of the debugger in action:

.. image:: _static/debugger.png
   :align: center
   :class: screenshot
   :alt: screenshot of debugger in action


Routing
-------

Modern web applications have beautiful URLs.  This helps people remember
the URLs which is especially handy for applications that are used from
mobile devices with slower network connections.  If the user can directly
go to the desired page without having to hit the index page it is more<commit_msg>Note to use debug=False for third-party debuggers.<commit_after>.. _quickstart:

Quickstart
==========

Eager to get started?  This page gives a good introduction in how to get
started with Flask.  This assumes you already have Flask installed.  If
you do not, head over to the :ref:`installation` section.


A Minimal Application
---------------------

A minimal Flask application looks something like that::

    from flask import Flask
    app = Flask(__name__)

    @app.route('/')
    def hello_world():
        return "Hello World!"

    if __name__ == '__main__':
        app.run()

Just save it as `hello.py` or something similar and run it with your
Python interpreter.  Make sure to not call your application `flask.py`
because this would conflict with Flask itself.

::

    $ python hello.py
     * Running on http://127.0.0.1:5000/

Head over to `http://127.0.0.1:5000/ <http://127.0.0.1:5000/>`_, you should
see your hello world greeting.

So what did that code do?

1. First we imported the :class:`~flask.Flask` class.  An instance of this
   class will be our WSGI application.  The first argument is the name of
   the application's module.  If you are using a single module (like here)
   you should use `__name__` because depending on if it's started as
   application or imported as module the name will be different
   (``'__main__'`` versus the actual import name).  For more information
   on that, have a look at the :class:`~flask.Flask` documentation.
2. Next we create an instance of it.  We pass it the name of the module /
   package.  This is needed so that Flask knows where it should look for
   templates, static files and so on.
3. Then we use the :meth:`~flask.Flask.route` decorator to tell Flask
   what URL should trigger our function.
4. The function then has a name which is also used to generate URLs to
   that particular function, and returns the message we want to display in
   the user's browser.
5. Finally we use the :meth:`~flask.Flask.run` function to run the
   local server with our application.  The ``if __name__ == '__main__':``
   makes sure the server only runs if the script is executed directly from
   the Python interpreter and not used as imported module.

To stop the server, hit control-C.

.. _public-server:

.. admonition:: Externally Visible Server

   If you run the server you will notice that the server is only available
   from your own computer, not from any other in the network.  This is the
   default because in debugging mode a user of the application can execute
   arbitrary Python code on your computer.  If you have `debug` disabled
   or trust the users on your network, you can make the server publicly
   available.

   Just change the call of the :meth:`~flask.Flask.run` method to look
   like this::

       app.run(host='0.0.0.0')

   This tells your operating system to listen on a public IP.


Debug Mode
----------

The :meth:`~flask.Flask.run` method is nice to start a local
development server, but you would have to restart it manually after each
change you do to code.  That is not very nice and Flask can do better.  If
you enable the debug support the server will reload itself on code changes
and also provide you with a helpful debugger if things go wrong.

There are two ways to enable debugging.  Either set that flag on the
application object::

    app.debug = True
    app.run()

Or pass it to run::

    app.run(debug=True)

Both will have exactly the same effect.

.. admonition:: Attention

   Even though the interactive debugger does not work in forking environments
   (which makes it nearly impossible to use on production servers), it still
   allows the execution of arbitrary code. That makes it a major security
   risk and therefore it **must never be used on production machines**.

Screenshot of the debugger in action:

.. image:: _static/debugger.png
   :align: center
   :class: screenshot
   :alt: screenshot of debugger in action

.. admonition:: Working With Other Debuggers

   Some third-party debuggers, e.g. PyDev and IntelliJ, are interrupted when
   ``app`` reloads.  To use these debuggers, set ``app.debug = False``.


Routing
-------

Modern web applications have beautiful URLs.  This helps people remember
the URLs which is especially handy for applications that are used from
mobile devices with slower network connections.  If the user can directly
go to the desired page without having to hit the index page it is more
{'fraction_non_alphanumeric': 0.07081174438687392, 'fraction_numerical': 0.008981001727115717, 'mean_word_length': 3.3256972111553784, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1261133', 'n_tokens_mistral': 2416, 'n_tokens_neox': 2295, 'n_words': 1277}