Merge pull request albertalexandrov#4 from albertalexandrov/commands-1

новый механизм работы с командами

Author: albertalexandrov

docs/assets/images/custom-command-under-name.png

@@ -1,59 +1,94 @@
+from fastapi_django.conf.global_settings import MANAGEMENT
+
 # Команды
 
 Работа с командами реализована в модуле [management](../fastapi_django/management). Работают команды на [Typer](https://typer.tiangolo.com)
 
-В модуле [management/commands](../fastapi_django/management/commands) реализованы дефолтные команды runserver и echo.
+## CLI
+
+Экземпляр Typer и команды созданы в модуле [management/cli.py](../fastapi_django/management/cli.py). Из-за особенностей работы с Typer необходимо, чтобы 
+интерпретатор Python при импорте экземпляра Typer проходил также команды, обернутые декоратором `command()`. 
+
+## Дефолтные команды
+
+Реализованы дефолтные команды `echo` и `runserver` (см. [management/cli.py](../fastapi_django/management/cli.py)). 
+
+## Директория management/commands
 
-По сути manage.py является прокси к приложению на Typer. 
+Дефолтные команды `echo` и `runserver` простые и вполне помещаются в функцию. Однако, если логика громоздкая, то возникает
+потребность поместить ее в класс. В таком случае, предлагается размещать в каждый свой файл как это например показано 
+по ссылке https://github.com/albertalexandrov/fastapi-django-example/blob/main/src/management/commands/calculator.py. 
+Осталось эту логику запустить. Для этого в https://github.com/albertalexandrov/fastapi-django-example/blob/main/src/management/cli.py создается команда, 
+которая запускает ее.
 
 ## Кастомные команды
 
-Команда - это callable объект, который может находится в любом месте проекта. Но чтобы команда разаработала, ее необходимо
-зарегистрировать. Предлагается регистрировать ее в том же модуле, в котором вызывается приложение Typer, то есть в модуле manage.py
-при помоши функции management.utils.register_command.
+Объект `typer` [management/cli.py](../fastapi_django/management/cli.py) является **корневым** CLI, в которому должны 
+добавляться кастомные команды. 
 
-Пример кастомной команды https://github.com/albertalexandrov/fastapi-django-example/tree/main/src/commands.
-Пример регистрации команды: https://github.com/albertalexandrov/fastapi-django-example/blob/main/src/manage.py#L10
+Вне зависимости от того, идет ли речь про код приложения FastAPI или некоторой библиотеки предлагается следующий алгоритм
+создания кастомных команд. 
 
-## Команда runserver
+1. В проекте/библиотеке создается структура папок и файлов:
 
-Данная команда запускает приложение FastAPI при помощи Uvicorn. Если взглянуть на ее реализацию, можно увидеть, 
-как она понимает, с какими параметрами необходимо запустить приложение:
+```python
+management
+├── commands (опционально)
+    ├── __init__.py 
+├── cli.py
+```
+
+2. в `cli.py` определяется, настраивается объект `Typer`, реализуются кастомные команды:
 
 ```python
-def runserver() -> None:
-    params = {}
-    uvicorn_settings = [setting for setting in dir(settings) if setting.startswith("UVICORN_")]
-    for setting in uvicorn_settings:
-        _, param = setting.split("_", 1)
-        params[param.lower()] = getattr(settings, setting)
-    uvicorn.run(**params)
+# cli.py
+
+from typer import Typer
+
+typer = Typer(help="Команды проекта/библиотеки")
+
+
+@typer.command()
+def info():
+    print("Вот информация о проекте/библиотеке")
+
 ```
 
-Параметры запуска Uvicorn задаются в settings. Названия параметров должны иметь префикс UVICORN_
-Далее идут названия параметров функции uvicorn.run в верхнем регистре. Таким образом, параметр,
-соответствующий параметру workers будет иметь название UVICORN_WORKERS, для port - UVICORN_PORT и тд
+3. Подключение к корневому CLI
 
-## Список команд
+Осталось подключить созданный объект typer, который содержит кастомные команды, к корневому CLI. 
+Для этого необходимо в настройку MANAGEMENT прописать:
 
-Здесь https://github.com/albertalexandrov/fastapi-django-example/blob/main/src/manage.py#L10 была зарегистрирована 
-кастомная команда. Убедится, команда была зарегистрирована можно введя в консоль список всех команд командой:
+```python
+# settings.py
 
-```shell
-python manage.py --help
+MANAGEMENT = [
+    {
+        "typer": "management.cli:typer",
+    }
+]
 ```
 
-![](assets/images/commands-list.png)
+4. Проверка 
 
-## Примечание
+Чтобы просмотреть список команд, необходимо выполнить команду `python manage.py --help`:
 
-Я рассчитывал, что объект [cli](../fastapi_django/management/__init__.py) будет импортироваться где нужно и 
-команды будут автоматически регистрироваться. Однако, недостаточно обернуть функцию в декоратор cli.command, 
-поэтому приходится делать так, что команда регистрируется аккурат перед тем, когда выполняется 
-cli() ([в файле manage.py](https://github.com/albertalexandrov/fastapi-django-example/blob/main/src/manage.py#L10))
+![](assets/images/custom-command.png)
 
-Поэтому сторонние библиотеки (не проект) не смогут просто оборачивать свои собственные команды - в проекте придется
-импортировать команды сторонних библиотек и регистрировать.
+Можно видеть, что отобразились как дефолтные команды, так и кастомная команд.
+
+Если в настройке MANAGEMENT определить name, то команды будут объединены в субкоманды, доступ к которым будет через
+name:
+
+```python
+# settings.py
+
+MANAGEMENT = [
+    {
+        "typer": "management.cli:typer",
+        "name": "custom-commands",
+    }
+]
+```
 
-**Возможно у кого нибудь возникнут идеи как реализовать автоматическую регистрацию команд. Автодисковеринг как в Celery 
-или типа того. Пишите.**
+![](assets/images/custom-command-under-name.png)

docs/assets/images/custom-command.png

@@ -27,3 +27,5 @@
 #         # другие параметры, которые будут переданы как kw в функцию create_async_engine()
 #     }
 # }
+
+MANAGEMENT: list[dict] = []

docs/Команды.md

@@ -1,12 +1,11 @@
-from collections.abc import Callable
-
 from typer import Typer
+from fastapi_django.conf import settings
+from uvicorn.importer import import_from_string
 
-from fastapi_django.management.commands.echo import echo
-from fastapi_django.management.commands.runserver import runserver
+typer = Typer(rich_markup_mode="markdown")
+management = [{"typer": "fastapi_django.management.cli:typer"}] + settings.MANAGEMENT
 
-cli = Typer()
-commands: list[Callable] = [echo, runserver]
+for item in management:
+    typer.add_typer(import_from_string(item["typer"]), name=item.get("name"))
 
-for command in commands:
-    cli.command()(command)
+__all__ = ["typer"]

fastapi_django/conf/global_settings.py

@@ -1,14 +1,18 @@
 import uvicorn
+from typer import Typer
 
 from fastapi_django.conf import settings
 
+typer = Typer(rich_markup_mode="markdown")
 
-def runserver() -> None:
+
+@typer.command()  # TODO: можно определить rich_help_panel, которые действуют объединяюще как теги в сваггере
+def runserver():
     """
     Запускает приложение при помощи Uvicorn.
 
-    Параметры запуска Uvicorn задаются в settings.  Названия параметров должны иметь префикс UVICORN_
-    Далее идут названия параметров функции uvicorn.run в верхнем регистре.  Таким образом, параметр,
+    Параметры запуска Uvicorn задаются в settings. Названия параметров должны иметь префикс UVICORN_
+    Далее идут названия параметров функции uvicorn.run в верхнем регистре. Таким образом, параметр,
     соответствующий параметру workers будет иметь название UVICORN_WORKERS, для port - UVICORN_PORT и тд
     """
     params = {}
@@ -17,3 +21,11 @@ def runserver() -> None:
         _, param = setting.split("_", 1)
         params[param.lower()] = getattr(settings, setting)
     uvicorn.run(**params)
+
+
+@typer.command()
+def echo(message: str):
+    """
+    Эхо-команда
+    """
+    print(f"Echo: {message}")

fastapi_django/management/__init__.py

@@ -7,7 +7,7 @@ check_untyped_defs = true
 
 [tool.poetry]
 name = "fastapi-django"
-version = "0.8.28"
+version = "0.9.12"
 description = ""
 authors = ["albertalexandrov <[email protected]>"]
 packages = [{include = "fastapi_django"}]