✨ Add support for reading configuration from pyproject.toml

Author: patrick91

pyproject.toml

@@ -35,6 +35,7 @@ dependencies = [
     "typer >= 0.15.1",
     "uvicorn[standard] >= 0.15.0",
     "rich-toolkit >= 0.14.8",
+    "pydantic-settings",
 ]
 
 [project.optional-dependencies]

src/fastapi_cli/cli.py

@@ -3,10 +3,12 @@
 from typing import Any, List, Union
 
 import typer
+from pydantic import ValidationError
 from rich import print
 from rich.tree import Tree
 from typing_extensions import Annotated
 
+from fastapi_cli.config import FastAPIConfig
 from fastapi_cli.discover import get_import_data, get_import_data_from_import_string
 from fastapi_cli.exceptions import FastAPICLIException
 
@@ -111,11 +113,45 @@ def _run(
             "Searching for package file structure from directories with [blue]__init__.py[/blue] files"
         )
 
+        # Validate mutually exclusive options
+        if entrypoint and (path or app):
+            toolkit.print_line()
+            toolkit.print(
+                "[error]Cannot use --entrypoint together with path or --app arguments"
+            )
+            toolkit.print_line()
+            raise typer.Exit(code=1)
+
         try:
-            if entrypoint:
-                import_data = get_import_data_from_import_string(entrypoint)
-            else:
+            # Let pydantic merge CLI params with pyproject.toml (CLI takes priority)
+            # Filter out None values so pyproject.toml values are used as defaults
+            cli_params = {
+                k: v
+                for k, v in {"host": host, "port": port, "entrypoint": entrypoint}.items()
+                if v is not None
+            }
+            config = FastAPIConfig.model_validate(cli_params)
+        except ValidationError as e:
+            toolkit.print_line()
+            toolkit.print("[error]Invalid configuration in pyproject.toml:")
+            toolkit.print_line()
+
+            for error in e.errors():
+                field = ".".join(str(loc) for loc in error["loc"])
+                toolkit.print(f"  [red]•[/red] {field}: {error['msg']}")
+
+            toolkit.print_line()
+
+            raise typer.Exit(code=1) from None
+
+        try:
+            # Resolve import data with priority: CLI path/app > config entrypoint > auto-discovery
+            if path or app:
                 import_data = get_import_data(path=path, app_name=app)
+            elif config.entrypoint:
+                import_data = get_import_data_from_import_string(config.entrypoint)
+            else:
+                import_data = get_import_data()
         except FastAPICLIException as e:
             toolkit.print_line()
             toolkit.print(f"[error]{e}")
@@ -151,7 +187,7 @@ def _run(
             tag="app",
         )
 
-        url = f"http://{host}:{port}"
+        url = f"http://{config.host}:{config.port}"
         url_docs = f"{url}/docs"
 
         toolkit.print_line()
@@ -179,8 +215,8 @@ def _run(
 
         uvicorn.run(
             app=import_string,
-            host=host,
-            port=port,
+            host=config.host,
+            port=config.port,
             reload=reload,
             workers=workers,
             root_path=root_path,

src/fastapi_cli/config.py

@@ -0,0 +1,35 @@
+import logging
+from typing import Optional
+
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    PyprojectTomlConfigSettingsSource,
+    SettingsConfigDict,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class FastAPIConfig(BaseSettings):
+    entrypoint: Optional[str] = None
+    host: Optional[str] = None
+    port: Optional[int] = None
+
+    model_config = SettingsConfigDict(
+        pyproject_toml_table_header=("tool", "fastapi"),
+    )
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (
+            init_settings,
+            PyprojectTomlConfigSettingsSource(settings_cls),
+        )

tests/assets/pyproject_config/mymodule.py

@@ -0,0 +1,8 @@
+from fastapi import FastAPI
+
+app = FastAPI()
+
+
+@app.get("/")
+def read_root():
+    return {"Hello": "World"}

tests/assets/pyproject_config/pyproject.toml

@@ -0,0 +1,2 @@
+[tool.fastapi]
+entrypoint = "mymodule:app"

tests/test_cli_pyproject.py

@@ -0,0 +1,163 @@
+from pathlib import Path
+from unittest.mock import patch
+
+import uvicorn
+from typer.testing import CliRunner
+
+from fastapi_cli.cli import app
+from fastapi_cli.utils.cli import get_uvicorn_log_config
+from tests.utils import changing_dir
+
+runner = CliRunner()
+
+assets_path = Path(__file__).parent / "assets"
+
+
+def test_dev_with_pyproject_app_config() -> None:
+    with changing_dir(assets_path / "pyproject_config"), patch.object(
+        uvicorn, "run"
+    ) as mock_run:
+        result = runner.invoke(app, ["dev"])
+        assert result.exit_code == 0, result.output
+        assert mock_run.called
+        assert mock_run.call_args
+        assert mock_run.call_args.kwargs == {
+            "app": "mymodule:app",
+            "host": "127.0.0.1",
+            "port": 8000,
+            "reload": True,
+            "workers": None,
+            "root_path": "",
+            "proxy_headers": True,
+            "forwarded_allow_ips": None,
+            "log_config": get_uvicorn_log_config(),
+        }
+        assert "Using import string: mymodule:app" in result.output
+
+
+def test_run_with_pyproject_app_config() -> None:
+    with changing_dir(assets_path / "pyproject_config"), patch.object(
+        uvicorn, "run"
+    ) as mock_run:
+        result = runner.invoke(app, ["run"])
+        assert result.exit_code == 0, result.output
+        assert mock_run.called
+        assert mock_run.call_args
+        assert mock_run.call_args.kwargs["app"] == "mymodule:app"
+        assert mock_run.call_args.kwargs["host"] == "0.0.0.0"
+        assert mock_run.call_args.kwargs["port"] == 8000
+        assert mock_run.call_args.kwargs["reload"] is False
+
+
+def test_cli_arg_overrides_pyproject_config() -> None:
+    """Test that CLI arguments override pyproject.toml configuration"""
+    with changing_dir(assets_path / "pyproject_config"):
+        # Create another file to test override
+        other_app = assets_path / "pyproject_config" / "other.py"
+        other_app.write_text("""
+from fastapi import FastAPI
+
+api = FastAPI()
+
+@api.get("/")
+def read_root():
+    return {"source": "other"}
+""")
+
+        try:
+            with patch.object(uvicorn, "run") as mock_run:
+                result = runner.invoke(app, ["dev", "other.py", "--app", "api"])
+                assert result.exit_code == 0, result.output
+                assert mock_run.called
+                assert mock_run.call_args
+                assert mock_run.call_args.kwargs["app"] == "other:api"
+        finally:
+            other_app.unlink()
+
+
+def test_pyproject_app_config_invalid_format() -> None:
+    """Test error handling for invalid app format in pyproject.toml"""
+
+    # Create a test directory with invalid config
+    test_dir = assets_path / "pyproject_invalid_config"
+    test_dir.mkdir(exist_ok=True)
+
+    pyproject_file = test_dir / "pyproject.toml"
+    pyproject_file.write_text("""
+[tool.fastapi]
+entrypoint = "invalid_format_without_colon"
+""")
+
+    try:
+        with changing_dir(test_dir):
+            result = runner.invoke(app, ["dev"])
+            assert result.exit_code == 1
+            assert (
+                "Import string must be in the format module.submodule:app_name"
+                in result.output
+            )
+    finally:
+        pyproject_file.unlink()
+        test_dir.rmdir()
+
+
+def test_dev_without_pyproject_toml() -> None:
+    """Test that dev command works without pyproject.toml file"""
+    # Use an existing test directory that has a main.py but no pyproject.toml
+    test_dir = assets_path / "default_files" / "default_main"
+
+    with changing_dir(test_dir):
+        with patch.object(uvicorn, "run") as mock_run:
+            result = runner.invoke(app, ["dev"])
+            assert result.exit_code == 0, result.output
+            assert mock_run.called
+            assert mock_run.call_args
+            # Should use defaults since no config file
+            assert mock_run.call_args.kwargs["host"] == "127.0.0.1"
+            assert mock_run.call_args.kwargs["port"] == 8000
+            assert mock_run.call_args.kwargs["app"] == "main:app"
+
+
+def test_pyproject_validation_error() -> None:
+    """Test error handling for validation errors in pyproject.toml"""
+    # Create a test directory with invalid config (invalid entrypoint type)
+    test_dir = assets_path / "pyproject_validation_error"
+    test_dir.mkdir(exist_ok=True)
+
+    pyproject_file = test_dir / "pyproject.toml"
+    pyproject_file.write_text("""
+[tool.fastapi]
+entrypoint = 123
+""")
+
+    try:
+        with changing_dir(test_dir):
+            result = runner.invoke(app, ["dev"])
+            assert result.exit_code == 1
+            assert "Invalid configuration in pyproject.toml:" in result.output
+            assert "entrypoint" in result.output.lower()
+    finally:
+        pyproject_file.unlink()
+        test_dir.rmdir()
+
+
+def test_entrypoint_mutually_exclusive_with_path() -> None:
+    """Test that --entrypoint cannot be used with path argument"""
+    with changing_dir(assets_path / "pyproject_config"):
+        result = runner.invoke(app, ["dev", "mymodule.py", "--entrypoint", "other:app"])
+        assert result.exit_code == 1
+        assert (
+            "Cannot use --entrypoint together with path or --app arguments"
+            in result.output
+        )
+
+
+def test_entrypoint_mutually_exclusive_with_app() -> None:
+    """Test that --entrypoint cannot be used with --app flag"""
+    with changing_dir(assets_path / "pyproject_config"):
+        result = runner.invoke(app, ["dev", "--app", "myapp", "--entrypoint", "other:app"])
+        assert result.exit_code == 1
+        assert (
+            "Cannot use --entrypoint together with path or --app arguments"
+            in result.output
+        )