Update command line instructions and invocation (#1110)

* Initial README.rst improvements. * Rework docs. * Unify install.rst and installation section in README.rst. * Remove flower as individual command. Celery now requires subcommands to be invoked with celery <subcommand>. * Update docs - mainly remove old usage of just flower as a command. * Update docs - mainly remove old usage of just flower as a command. Also add missing args in their list. * Update docs. * Add warning for users when they specify celery args in the flower args part of the invokation. * Naming changes and log only if incorrect args found. * Add test for warning about incorrect args for flower. * change -A to proj as in other places. * Fix test.
mher · May 29, 2021 · af9ae38 · af9ae38
1 parent 2674b22
commit af9ae38
Show file tree

Hide file tree

Showing 7 changed files with 158 additions and 33 deletions.
diff --git a/README.rst b/README.rst
@@ -46,36 +46,60 @@ Features
 Installation
 ------------
 
-PyPI version: ::
+Installing `flower` with `pip <http://www.pip-installer.org/>`_ is simple ::
 
     $ pip install flower
 
-Development version: ::
+Development version can be installed with ::
 
-    $ pip install https://github.com/mher/flower/zipball/master
+    $ pip install https://github.com/mher/flower/zipball/master#egg=flower
 
 Usage
 -----
 
-Launch the server and open http://localhost:5555: ::
+**Important** Please note that from version 1.0.1 Flower uses Celery 5 and has to be invoked in the same style as celery
+commands do.
 
-    $ flower --port=5555
+The key takeaway here is that the Celery app's arguments have to be specified after the `celery` command and Flower's
+arguments have to be specified after the `flower` sub-command.
 
-Launch from celery: ::
+This is the template to follow::
 
-    $ celery flower -A proj --address=127.0.0.1 --port=5555
+    celery [celery args] flower [flower args]
+
+Core Celery args that you may want to set::
+
+    -A, --app
+    -b, --broker
+    --result-backend
+
+More info on available `Celery command args <https://docs.celeryproject.org/en/stable/reference/cli.html#celery>`_.
+
+For Flower command args `see here <https://flower.readthedocs.io/en/latest/config.html#options>`_.
+
+Usage Examples
+--------------
+
+Launch the Flower server at specified port other than default 5555 (open the UI at http://localhost:5566): ::
+
+    $ celery flower --port=5566
+
+Specify Celery application path with address and port for Flower: ::
+
+    $ celery -A proj flower --address=127.0.0.6 --port=5566
 
 Launch using docker: ::
 
     $ docker run -p 5555:5555 mher/flower
 
 Launch with unix socket file: ::
 
-    $ flower --unix-socket=/tmp/flower.sock
+    $ celery flower --unix-socket=/tmp/flower.sock
 
-Broker URL and other configuration options can be passed through the standard Celery options: ::
+Broker URL and other configuration options can be passed through the standard Celery options (notice that they are after
+Celery command and before Flower sub-command): ::
 
-    $ celery flower -A proj --broker=amqp://guest:guest@localhost:5672//
+    $ celery -A proj --broker=amqp://guest:guest@localhost:5672// flower
 
 API
 ---

diff --git a/docs/config.rst b/docs/config.rst
@@ -5,7 +5,7 @@ Configuration
 
 Flower can be configured from the command line: ::
 
-    $ flower --auto_refresh=False
+    $ celery flower --auto_refresh=False
 
 Using :file:`flowerconfig.py` configuration file:
 
@@ -26,7 +26,7 @@ Options passed through the command line have precedence over the options
 defined in the configuration file. The configuration file name and path
 can be changed with `conf`_ option. ::
 
-    $ flower --conf=celeryconfig.py
+    $ celery flower --conf=celeryconfig.py
 
 Options
 -------
@@ -40,7 +40,7 @@ the available settings, and their default values.
 Celery command line options also can be passed to Flower. For example
 the `--broker` sets the default broker URL: ::
 
-    $ flower -A proj --broker=amqp://guest:guest@localhost:5672//
+    $ celery -A proj --broker=amqp://guest:guest@localhost:5672// flower
 
 For a full list of options see: ::
 
@@ -90,7 +90,7 @@ broker_api
 Flower uses `RabbitMQ Management Plugin`_ to get info about queues.
 `broker_api` is a URL of RabbitMQ HTTP API including user credentials. ::
 
-    $ flower -A proj --broker_api=http://username:password@rabbitmq-server-name:15672/api/
+    $ celery -A proj flower --broker_api=http://username:password@rabbitmq-server-name:15672/api/
 
 .. Note:: By default the management plugin is not enabled. To enable it run::
 
@@ -276,7 +276,7 @@ Enables deploying Flower on non-root URL
 
 For example to access Flower on http://example.com/flower run it with: ::
 
-    $ flower --url_prefix=flower
+    $ celery flower --url_prefix=flower
 
 NOTE: The old `nginx` rewrite is no longer needed
 

diff --git a/docs/install.rst b/docs/install.rst
@@ -12,15 +12,47 @@ Development version can be installed with ::
 Usage
 -----
 
-Launch the server and open http://localhost:5555 ::
+**Important** Please note that from version 1.0.1 Flower uses Celery 5 and has to be invoked in the same style as celery
+commands do.
 
-    $ flower -A proj --port=5555
+The key takeaway here is that the Celery app's arguments have to be specified after the `celery` command and Flower's
+arguments have to be specified after the `flower` sub-command.
 
-Or, launch from Celery ::
+This is the template to follow::
 
-    $ celery -A proj flower --address=127.0.0.1 --port=5555
+    celery [celery args] flower [flower args]
 
-Broker URL and other configuration options can be passed through the standard Celery options ::
+Core Celery args that you may want to set::
 
-    $ celery -A proj flower --broker=amqp://guest:guest@localhost:5672// --broker_api=http://guest:guest@localhost:15672/api/
+    -A, --app
+    -b, --broker
+    --result-backend
+
+More info on available `Celery command args <https://docs.celeryproject.org/en/stable/reference/cli.html#celery>`_.
+
+For Flower command args `see here <https://flower.readthedocs.io/en/latest/config.html#options>`_.
+
+Usage Examples
+--------------
+
+Launch the Flower server at specified port other than default 5555 (open the UI at http://localhost:5566): ::
+
+    $ celery flower --port=5566
+
+Specify Celery application path with address and port for Flower: ::
+
+    $ celery -A proj flower  --address=127.0.0.6 --port=5566
+
+Launch using docker: ::
+
+    $ docker run -p 5555:5555 mher/flower
+
+Launch with unix socket file: ::
+
+    $ celery flower --unix-socket=/tmp/flower.sock
+
+Broker URL and other configuration options can be passed through the standard Celery options (notice that they are after
+Celery command and before Flower sub-command): ::
+
+    $ celery --broker=amqp://guest:guest@localhost:5672// flower
 
diff --git a/docs/man.rst b/docs/man.rst
@@ -47,24 +47,38 @@ OPTIONS
 
   --address                        run on the given address
   --auth                           regexp  of emails to grant access
+  --auth_provider                  sets authentication provider class
+  --auto_refresh                   refresh dashboard automatically (default *True*)
   --basic_auth                     colon separated user-password to enable
                                    basic auth
   --broker_api                     inspect broker e.g.
                                    http://guest:guest@localhost:15672/api/
+  --ca_certs                       path to SSL certificate authority (CA) file
   --certfile                       path to SSL certificate file
+  --conf                           flower configuration file path (default *flowerconfig.py*)
+  --cookie_secret                  secure cookie secret
   --db                             flower database file (default *flower.db*)
   --debug                          run in debug mode (default *False*)
+  --enable_events                  periodically enable Celery events (default *True*)
+  --format_task                    use custom task formatter
   --help                           show this help information
   --inspect                        inspect workers (default *True*)
   --inspect_timeout                inspect timeout (in milliseconds) (default
                                    *1000*)
   --keyfile                        path to SSL key file
-  --max_workrs                     maximum number of workers to keep in memory
+  --max_workers                     maximum number of workers to keep in memory
                                    (default *5000*)
   --max_tasks                      maximum number of tasks to keep in memory
                                    (default *10000*)
+  --natural_time                   show time in relative format (default *False*)
   --persistent                     enable persistent mode (default *False*)
   --port                           run on the given port (default *5555*)
+  --purge_offline_workers          time (in seconds) after which offline workers are purged
+                                   from dashboard
+  --state_save_interval            state save interval (in milliseconds) (default *0*)
+  --tasks_columns                  slugs of columns on /tasks/ page, delimited by comma
+                                   (default *name,uuid,state,args,kwargs,result,received,started,runtime,worker*)
+  --unix_socket                    path to unix socket to bind flower server to
   --url_prefix                     base url prefix
   --xheaders                       enable support for the 'X-Real-Ip' and
                                    'X-Scheme' headers. (default *False*)
@@ -91,14 +105,15 @@ TORNADO OPTIONS
 USAGE
 =====
 
-Launch the server and open http://localhost:5555: ::
+Launch the Flower server at specified port other than default 5555 (open the UI at http://localhost:5566): ::
 
-    $ flower -A proj --port=5555
+    $ celery flower --port=5566
 
-Or, launch from Celery: ::
+Specify Celery application path with address and port for Flower: ::
 
-    $ celery flower -A proj --address=127.0.0.1 --port=5555
+    $ celery -A proj flower --address=127.0.0.6 --port=5566
 
-Broker URL and other configuration options can be passed through the standard Celery options: ::
+Broker URL and other configuration options can be passed through the standard Celery options (notice that they are after
+Celery command and before Flower sub-command): ::
 
-    $ celery flower -A proj --broker=amqp://guest:guest@localhost:5672//
+    $ celery -A proj --broker=amqp://guest:guest@localhost:5672// flower
diff --git a/flower/command.py b/flower/command.py
@@ -14,7 +14,6 @@
 from tornado.log import enable_pretty_logging
 from celery.bin.base import CeleryCommand
 
-from . import __version__
 from .app import Flower
 from .urls import settings
 from .utils import abs_path, prepend_url
@@ -32,6 +31,7 @@
 @click.pass_context
 def flower(ctx, tornado_argv):
     """Web based tool for monitoring and administrating Celery clusters."""
+    warn_about_celery_args_used_in_flower_command(ctx, tornado_argv)
     apply_env_options()
     apply_options(sys.argv[0], tornado_argv)
 
@@ -85,6 +85,24 @@ def apply_options(prog_name, argv):
             raise
 
 
+def warn_about_celery_args_used_in_flower_command(ctx, flower_args):
+    celery_options = [option for param in ctx.parent.command.params for option in param.opts]
+
+    incorrectly_used_args = []
+    for arg in flower_args:
+        arg_name, _, _ = arg.partition("=")
+        if arg_name in celery_options:
+            incorrectly_used_args.append(arg_name)
+
+    if incorrectly_used_args:
+        logger.warning(
+            f'You have incorrectly specified the following celery arguments after flower command:'
+            f' {incorrectly_used_args}. '
+            f'Please specify them after celery command instead following this template: '
+            f'celery [celery args] flower [flower args].'
+        )
+
+
 def setup_logging():
     if options.debug and options.logging == 'info':
         options.logging = 'debug'

diff --git a/setup.py b/setup.py
@@ -59,9 +59,6 @@ def get_requirements(filename):
     package_data={'flower': ['templates/*', 'static/*.*',
                              'static/**/*.*', 'static/**/**/*.*']},
     entry_points={
-        'console_scripts': [
-            'flower = flower.__main__:main',
-        ],
         'celery.commands': [
             'flower = flower.command:flower',
         ],

diff --git a/tests/unit/test_command.py b/tests/unit/test_command.py
@@ -3,8 +3,9 @@
 import tempfile
 import unittest
 import subprocess
+from unittest.mock import Mock, patch
 
-from flower.command import apply_options
+from flower.command import apply_options, warn_about_celery_args_used_in_flower_command
 from tornado.options import options
 from tests.unit import AsyncHTTPTestCase
 
@@ -21,6 +22,44 @@ def test_address(self):
             self.assertEqual('foo', options.address)
 
 
+class TestWarnAboutCeleryArgsUsedInFlowerCommand(AsyncHTTPTestCase):
+    @patch('flower.command.logger.warning')
+    def test_does_not_log_warning(self, mock_warning):
+        mock_app_param = Mock(name='app_param', opts=('-A', '--app'))
+        mock_broker_param = Mock(name='broker_param', opts=('-b', '--broker'))
+
+        class FakeContext:
+            parent = Mock(command=Mock(params=[mock_app_param, mock_broker_param]))
+
+        ctx = FakeContext()
+
+        warn_about_celery_args_used_in_flower_command(
+            ctx=ctx, flower_args=('--port=5678', '--address=0.0.0.0')
+        )
+
+        mock_warning.assert_not_called()
+
+    @patch('flower.command.logger.warning')
+    def test_logs_warning(self, mock_warning):
+        mock_app_param = Mock(name='app_param', opts=('-A', '--app'))
+        mock_broker_param = Mock(name='broker_param', opts=('-b', '--broker'))
+
+        class FakeContext:
+            parent = Mock(command=Mock(params=[mock_app_param, mock_broker_param]))
+
+        ctx = FakeContext()
+
+        warn_about_celery_args_used_in_flower_command(
+            ctx=ctx, flower_args=('--app=proj', '-b', 'redis://localhost:6379/0')
+        )
+
+        mock_warning.assert_called_once_with(
+            "You have incorrectly specified the following celery arguments after flower command: "
+            "[\'--app\', \'-b\']. Please specify them after celery command instead following"
+            " this template: celery [celery args] flower [flower args]."
+        )
+
+
 class TestConfOption(AsyncHTTPTestCase):
     def test_error_conf(self):
         with self.mock_option('conf', None):