Help users with new project layout

[tomchristie]

Pulling this issue out from a seperate thread here... #704 (comment)

How do we best guide users around project layouts?

• starlette init.
• Pointers towards how to clone existing layouts.
• Something else?

[tomchristie]

FWIW I do think that we want to help guide users down the happy path here.

I'm not sure how much of that responsibility lives with the starlette package itself, and how much should be documentation etc.

Also there's probably valid use cases for both single-file and multi-file layouts, so we might want to have templates for both cases?

[rmorison]

Pulling this issue out from a seperate thread here... #704 (comment)

How do we best guide users around project layouts?

• starlette init.
• Pointers towards how to clone existing layouts.
• Something else?

I'm a big fan of the cookiecutter approach popular with a lot of Django veterans. That would, of course, live another place (or places).

That "external" aside, a factory recommended "semi-manual" project layout via tutorial and/or sample project with best practice routes, settings, handlers, etc. would really help adoption by users from other platforms, especially Django. Django little blog tutorial is "just right" for newbs and is a meaningful part of its success.

$.02

[raiderrobert]

@tomchristie and @rmorison not to be self-serving, but I started a cookiecutter a few weeks ago for starlette: https://github.com/raiderrobert/cookiecutter-starlette

So I'm of the strong opinion that you let my or other cookiecutters sort of figure out best practices for a while. Later on if there's still strong demand for starlette init, you'll have a broader array of options to choose between on what people kind of seem to like and you wouldn't have built that into docs in Starlette.

[espositofulvio]

I'm a fan of "your project layout should tell something about the domain of your app" (I think Robert Martin said that) which in turns I take it means different projects needs different layouts and, in my opinion, shouldn't be Starlette responsibility to provide one. The code to quickly have something running is less than 10 lines long and that includes uvicorn import and run. Due to the low-level nature of Starlette I, also, have a hard time to see what a starlette init should actually do. Maybe if someone come up with the right example I can change my mind :)

[mbeacom]

While I agree with a cookiecutter style approach, I can't help but argue the fact that similar frameworks (like previously mentioned django) do offer an extremely slim starting point to begin a project via django-admin startproject mysite.

The starlette init concept seems like a proper approach as a generator of a minimal base. Cookiecutter projects (or GH templates and the like) can fill the void of opinionated project construction.

[jordaneremieff]

I agree with @mbeacom. I think a starlette init command would be valuable. I've found Django's startapp and startproject commands quite useful as starting points in several projects, and I think there could be a similar benefit here.

[jugaadi]

For us, Starlette is the quintessential async web toolkit just like encode/databases. The fact that frameworks are being built over Starlette(like FastAPI, Responder, etc) proves it. I hope it becomes the Python equivalent of go-kit or spring boot.

So the question whether project layout falls under the scope of Starlette depends on the future path that the maintainers wish to take i.e toolkit vs framework approach. Whatever it is, I hope the decision is taken before v1.0

If its a framework, then it makes sense to dictate the project layout and other conventions. Else it is best left to the community to figure out the best way to utilize starlette for their usecase.

[sandys]

All frameworks go through this crisis of scope - especially the starter vs complex ...and dictate vs assist conundrum. I think these tweets by Dan Abramov (creator of React) is very interesting in that context.

"React is harder, because it cares". I think it sums up the most important variable - care for for the end user.
/fin

[alex-oleshkevich]

The Phoenix framework has a very good directory layout:
https://github.com/phoenix-examples/hello_phoenix

It separates web application part (web dir) from the application (lib dir).
Another directories like api, cli, etc may live next to web.

[erichaus]

ember-cli also has a top-notch project layout/template https://ember-cli.com/

[tomchristie]

Closing this as out of scope right now.

[sheecegardezi]

@tomchristie now that we have evidence... every single framework ships with a scaffolding CLI!

Can we open this ticket up?

Happy to work on it ... I am in the process of migrating from FastAPI to Starlette... The documentation is very limited... I could create a CLI that allows users to select what features they want, like lifespan, webhooks, background tasks, middleware, routes, etc... and create a layout with generic examples??? ... There needs to be something out for people to use and give feedback on, to give direction on the kind of features that will be useful ???

[Kludex]

Opening for discussion. I may close it.

What functionalities should it have?

[alex-oleshkevich]

After years, I made an opinion that Starlette needs a higher-level framework that can incorporate layout as a feature.

I can't see any valuable layout for vanilla Starlette. Because it would just include few files: config.py, app.py, may be routes.py and .env. It just takes less than 5 minutes to set up it by hand.

[Kludex]

Should we think about a CLI that you can add plugins and then make it easier for higher-level frameworks?

[tool.scripts]
starlette11 = "potato_api.plugin"

---

Those are random thoughts.

[alex-oleshkevich]

Should we think about a CLI that you can add plugins and then make it easier for higher-level frameworks?

Yes, this is a cool solution, I use this approach. It can be a separate package like startlette-cli with a well-defined scope.
What I like about it is that we provide a plugin interface to users under a common namespace. This makes things more clear and discoverable. No more custom CLI per framework. Instead, devs have a unified interface and community plugins which may work in any Starlette-based project.

[Kludex]

It can be a separate package like startlette-cli with a well-defined scope.

Or maybe a starlette[cli] extra.

---

What commands would be there by default?

[alex-oleshkevich]

Probably none. Starlette is very low level, so any command will make it opinionated.
It may make sense to include only the plugin interface and CLI binary with Starlette and delegate any commands to plugins.

Some plugins could be official-like (eg. a simple scaffold project), and some more advanced (like boilerplates with tons of features).

The closest thing I see is Flask CLI. This is an output from flask command (no plugins installed):

Usage: flask [OPTIONS] COMMAND [ARGS]...

  A general utility script for Flask applications.

  An application to load must be given with the '--app' option, 'FLASK_APP'
  environment variable, or with a 'wsgi.py' or 'app.py' file in the current
  directory.

Options:
  -e, --env-file FILE   Load environment variables from this file, taking
                        precedence over those set by '.env' and '.flaskenv'.
                        Variables set directly in the environment take highest
                        precedence. python-dotenv must be installed.
  -A, --app IMPORT      The Flask application or factory function to load, in
                        the form 'module:name'. Module can be a dotted import
                        or file path. Name is not required if it is 'app',
                        'application', 'create_app', or 'make_app', and can be
                        'name(args)' to pass arguments.
  --debug / --no-debug  Set debug mode.
  --version             Show the Flask version.
  --help                Show this message and exit.

Commands:
  routes  Show the routes for the app.
  run     Run a development server.
  shell   Run a shell in the app context.```