orbit-oss/flask
4
5
Fork 2
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

merge foreword into design

Browse source
This commit is contained in:
David Lord 2022-08-05 11:02:12 -07:00
parent e55e8a0f2f
commit b4dca6e24c
No known key found for this signature in database
GPG key ID: 7A1C87E3F5BC42A8
3 changed files with 28 additions and 60 deletions
Download patch file Download diff file Expand all files Collapse all files

25
docs/design.rst
View file

@ -130,9 +130,25 @@ being present. You can easily use your own templating language, but an
extension could still depend on Jinja itself.
Micro with Dependencies
What does "micro" mean?
-----------------------
“Micro” does not mean that your whole web application has to fit into a single
Python file (although it certainly can), nor does it mean that Flask is lacking
in functionality. The "micro" in microframework means Flask aims to keep the
core simple but extensible. Flask won't make many decisions for you, such as
what database to use. Those decisions that it does make, such as what
templating engine to use, are easy to change. Everything else is up to you, so
that Flask can be everything you need and nothing you don't.
By default, Flask does not include a database abstraction layer, form
validation or anything else where different libraries already exist that can
handle that. Instead, Flask supports extensions to add such functionality to
your application as if it was implemented in Flask itself. Numerous extensions
provide database integration, form validation, upload handling, various open
authentication technologies, and more. Flask may be "micro", but it's ready for
production use on a variety of needs.
Why does Flask call itself a microframework and yet it depends on two
libraries (namely Werkzeug and Jinja2). Why shouldn't it? If we look
over to the Ruby side of web development there we have a protocol very
@ -201,5 +217,12 @@ requirements and Flask could not meet those if it would force any of this
into the core. The majority of web applications will need a template
engine in some sort. However not every application needs a SQL database.
As your codebase grows, you are free to make the design decisions appropriate
for your project. Flask will continue to provide a very simple glue layer to
the best that Python has to offer. You can implement advanced patterns in
SQLAlchemy or another database tool, introduce non-relational data persistence
as appropriate, and take advantage of framework-agnostic tools built for WSGI,
the Python web interface.
The idea of Flask is to build a good foundation for all applications.
Everything else is up to you or extensions.

53
docs/foreword.rst
View file

@ -1,53 +0,0 @@
Foreword
========
Read this before you get started with Flask. This hopefully answers some
questions about the purpose and goals of the project, and when you
should or should not be using it.
What does "micro" mean?
-----------------------
“Micro” does not mean that your whole web application has to fit into a single
Python file (although it certainly can), nor does it mean that Flask is lacking
in functionality. The "micro" in microframework means Flask aims to keep the
core simple but extensible. Flask won't make many decisions for you, such as
what database to use. Those decisions that it does make, such as what
templating engine to use, are easy to change. Everything else is up to you, so
that Flask can be everything you need and nothing you don't.
By default, Flask does not include a database abstraction layer, form
validation or anything else where different libraries already exist that can
handle that. Instead, Flask supports extensions to add such functionality to
your application as if it was implemented in Flask itself. Numerous extensions
provide database integration, form validation, upload handling, various open
authentication technologies, and more. Flask may be "micro", but it's ready for
production use on a variety of needs.
Configuration and Conventions
-----------------------------
Flask has many configuration values, with sensible defaults, and a few
conventions when getting started. By convention, templates and static
files are stored in subdirectories within the application's Python
source tree, with the names :file:`templates` and :file:`static`
respectively. While this can be changed, you usually don't have to,
especially when getting started.
Growing with Flask
------------------
Once you have Flask up and running, you'll find a variety of extensions
available in the community to integrate your project for production.
As your codebase grows, you are free to make the design decisions appropriate
for your project. Flask will continue to provide a very simple glue layer to
the best that Python has to offer. You can implement advanced patterns in
SQLAlchemy or another database tool, introduce non-relational data persistence
as appropriate, and take advantage of framework-agnostic tools built for WSGI,
the Python web interface.
Flask includes many hooks to customize its behavior. Should you need
more customization, the Flask class is built for subclassing. If you are
curious about the Flask design principles, head over to the section
about :doc:`design`.

10
docs/index.rst
View file

@ -29,14 +29,14 @@ toolkit. The documentation for these libraries can be found at:
User's Guide
------------
This part of the documentation, which is mostly prose, begins with some
background information about Flask, then focuses on step-by-step
instructions for web development with Flask.
Flask provides configuration and conventions, with sensible defaults, to get started.
This section of the documentation explains the different parts of the Flask framework
and how they can be used, customized, and extended. Beyond Flask itself, look for
community-maintained extensions to add even more functionality.
.. toctree::
:maxdepth: 2
foreword
installation
quickstart
tutorial/index
@ -75,8 +75,6 @@ method, this part of the documentation is for you.
Additional Notes
----------------
Design notes, legal information and changelog are here for the interested.
.. toctree::
:maxdepth: 2