Merge pull request #1751 from plotly/dev-aliases

`app.run` instead of `run_server`

Author: alexcjohnson

CHANGELOG.md

@@ -26,6 +26,9 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 - [#2016](https://github.com/plotly/dash/pull/2016) Drop the 375px width from default percy_snapshot calls, keep only 1280px
 
+- [#1751](https://github.com/plotly/dash/pull/1751) Rename `app.run_server` to `app.run` while preserving `app.run_server` for backwards compatibility.
+
+
 ### Updated
 - [#2016](https://github.com/plotly/dash/pull/2016) Widespread dependency upgrades
   - Upgrade Plotly.js to v2.11.1 (from v2.11.0). Patch release [2.11.1](https://github.com/plotly/plotly.js/releases/tag/v2.11.1) fixes regl-based traces in strict CSP mode, however you must manually switch to the strict bundle to use this.

MAKE_A_NEW_BACK_END.md

@@ -80,7 +80,7 @@ Any new back end needs to provide all of that functionality, one way or another.
 
 The `Dash()` constructor has lots of options. They’re all listed and documented [here]( https://github.com/plotly/dash/blob/357f22167d40ef00c92ff165aa6df23c622799f6/dash/dash.py#L113-L253) - some are Python-specific (`name`, `server`, `plugins`), others should eventually be replicated but many can be left out of the first proof-of-concept implementation.
 
-Similarly the `app.run_server` method has a lot of options, listed [here](https://github.com/plotly/dash/blob/357f22167d40ef00c92ff165aa6df23c622799f6/dash/dash.py#L1596-L1671) - again some are Python-specific (`flask_run_options`) and others can be added over time. Notice that many of these are simply passed on to `self.enable_dev_tools` - that’s because in Python the flask `server.run` command (called at the end of `app.run_server`) is normally only used in development, in production a more powerful server such as gunicorn is used, but a user may still want to enable devtools using a production server. You’re the expert on the new back end language, only you know if such a split makes sense. We don't want to write our own web server framework, you should be able to choose an existing one. Ideally this server should be easy to install on all major operating systems / platforms where your language is used, and for production scalability it should be able to run multiple workers or otherwise make full use of a multi-core machine. If it has the ability in development mode to create friendly error messages with stack traces to help debugging, that's a plus, but if not we can probably build that ourselves. 
+Similarly the `app.run` (previously `app.run_server`) method has a lot of options, listed [here](https://github.com/plotly/dash/blob/357f22167d40ef00c92ff165aa6df23c622799f6/dash/dash.py#L1596-L1671) - again some are Python-specific (`flask_run_options`) and others can be added over time. Notice that many of these are simply passed on to `self.enable_dev_tools` - that’s because in Python the flask `server.run` command (called at the end of `app.run_server`) is normally only used in development, in production a more powerful server such as gunicorn is used, but a user may still want to enable devtools using a production server. You’re the expert on the new back end language, only you know if such a split makes sense. We don't want to write our own web server framework, you should be able to choose an existing one. Ideally this server should be easy to install on all major operating systems / platforms where your language is used, and for production scalability it should be able to run multiple workers or otherwise make full use of a multi-core machine. If it has the ability in development mode to create friendly error messages with stack traces to help debugging, that's a plus, but if not we can probably build that ourselves. 
 
 ## Contributing your own backends
 

dash/__init__.py

@@ -26,4 +26,5 @@
     get_relative_path,
     strip_relative_path,
 )
+
 ctx = callback_context

dash/dash.py

@@ -1630,7 +1630,7 @@ def enable_dev_tools(
         dev_tools_silence_routes_logging=None,
         dev_tools_prune_errors=None,
     ):
-        """Activate the dev tools, called by `run_server`. If your application
+        """Activate the dev tools, called by `run`. If your application
         is served by wsgi and you want to activate the dev tools, you can call
         this method out of `__main__`.
 
@@ -1653,7 +1653,7 @@ def enable_dev_tools(
         :param debug: Enable/disable all the dev tools unless overridden by the
             arguments or environment variables. Default is ``True`` when
             ``enable_dev_tools`` is called directly, and ``False`` when called
-            via ``run_server``. env: ``DASH_DEBUG``
+            via ``run``. env: ``DASH_DEBUG``
         :type debug: bool
 
         :param dev_tools_ui: Show the dev tools UI. env: ``DASH_UI``
@@ -1891,7 +1891,7 @@ def delete_resource(resources):
                         # pylint: disable=protected-access
                         delete_resource(self.css._resources._resources)
 
-    def run_server(
+    def run(
         self,
         host=os.getenv("HOST", "127.0.0.1"),
         port=os.getenv("PORT", "8050"),
@@ -1937,7 +1937,7 @@ def run_server(
         :param debug: Enable/disable all the dev tools unless overridden by the
             arguments or environment variables. Default is ``True`` when
             ``enable_dev_tools`` is called directly, and ``False`` when called
-            via ``run_server``. env: ``DASH_DEBUG``
+            via ``run``. env: ``DASH_DEBUG``
         :type debug: bool
 
         :param dev_tools_ui: Show the dev tools UI. env: ``DASH_UI``
@@ -2055,3 +2055,11 @@ def verify_url_part(served_part, url_part, part_name):
                     extra_files.append(path)
 
         self.server.run(host=host, port=port, debug=debug, **flask_run_options)
+
+    def run_server(self, *args, **kwargs):
+        """`run_server` is a deprecated alias of `run` and may be removed in a
+        future version. We recommend using `app.run` instead.
+
+        See `app.run` for usage information.
+        """
+        self.run(*args, **kwargs)

dash/testing/application_runners.py

@@ -167,7 +167,7 @@ def run():
                 self.port = options["port"]
 
             try:
-                app.run_server(threaded=True, **options)
+                app.run(threaded=True, **options)
             except SystemExit:
                 logger.info("Server stopped")
 

tests/unit/test_configs.py

@@ -320,7 +320,7 @@ def test_invalid_strip_relative_path(prefix, partial_path):
 def test_port_env_fail_str(empty_environ):
     app = Dash()
     with pytest.raises(Exception) as excinfo:
-        app.run_server(port="garbage")
+        app.run(port="garbage")
     assert (
         excinfo.exconly()
         == "ValueError: Expecting an integer from 1 to 65535, found port='garbage'"
@@ -330,14 +330,14 @@ def test_port_env_fail_str(empty_environ):
 def test_port_env_fail_range(empty_environ):
     app = Dash()
     with pytest.raises(Exception) as excinfo:
-        app.run_server(port="0")
+        app.run(port="0")
     assert (
         excinfo.exconly()
         == "AssertionError: Expecting an integer from 1 to 65535, found port=0"
     )
 
     with pytest.raises(Exception) as excinfo:
-        app.run_server(port="65536")
+        app.run(port="65536")
     assert (
         excinfo.exconly()
         == "AssertionError: Expecting an integer from 1 to 65535, found port=65536"
@@ -357,7 +357,7 @@ def test_no_proxy_success(mocker, caplog, empty_environ, setlevel_warning):
     # mock out the run method so we don't actually start listening forever
     mocker.patch.object(app.server, "run")
 
-    app.run_server(port=8787)
+    app.run(port=8787)
 
     STARTUP_MESSAGE = "Dash is running on http://127.0.0.1:8787/\n"
     if setlevel_warning:
@@ -381,7 +381,7 @@ def test_proxy_success(mocker, caplog, empty_environ, proxy, host, port, path):
     app = Dash(url_base_pathname=path)
     mocker.patch.object(app.server, "run")
 
-    app.run_server(proxy=proxystr, host=host, port=port)
+    app.run(proxy=proxystr, host=host, port=port)
 
     assert "Dash is running on {}{}\n".format(proxy, path) in caplog.text
 
@@ -394,23 +394,21 @@ def test_proxy_failure(mocker, empty_environ):
     mocker.patch.object(app.server, "run")
 
     with pytest.raises(_exc.ProxyError) as excinfo:
-        app.run_server(
+        app.run(
             proxy="https://127.0.0.1:8055::http://plot.ly", host="127.0.0.1", port=8055
         )
     assert "protocol: http is incompatible with the proxy" in excinfo.exconly()
     assert "you must use protocol: https" in excinfo.exconly()
 
     with pytest.raises(_exc.ProxyError) as excinfo:
-        app.run_server(
+        app.run(
             proxy="http://0.0.0.0:8055::http://plot.ly", host="127.0.0.1", port=8055
         )
     assert "host: 127.0.0.1 is incompatible with the proxy" in excinfo.exconly()
     assert "you must use host: 0.0.0.0" in excinfo.exconly()
 
     with pytest.raises(_exc.ProxyError) as excinfo:
-        app.run_server(
-            proxy="http://0.0.0.0:8155::http://plot.ly", host="0.0.0.0", port=8055
-        )
+        app.run(proxy="http://0.0.0.0:8155::http://plot.ly", host="0.0.0.0", port=8055)
     assert "port: 8055 is incompatible with the proxy" in excinfo.exconly()
     assert "you must use port: 8155" in excinfo.exconly()