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

Revise foreword and Becoming Big docs, #484.

Browse source
This commit is contained in:
Ron DuPlain 2012-04-23 23:42:58 -04:00
parent ff5ee034b8
commit 7c79ce6e41
4 changed files with 118 additions and 102 deletions
Download patch file Download diff file Expand all files Collapse all files

66
docs/foreword.rst
View file

@ -8,48 +8,50 @@ 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.
“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 extensions add such functionality to your
application as if it was implemented in Flask itself. Numerous extensions
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 the
possibilities are endless.
authentication technologies, and more. Flask may be "micro", but it's ready for
production use on a variety of needs.
Convention over Configuration
Configuration and Conventions
-----------------------------
Flask is based on convention over configuration, which means that many things
are preconfigured. For example, by convention templates and static files are
stored in subdirectories within the application's Python source tree. While
this can be changed you usually don't have to. We want to minimize the time
you need to spend in order to get up and running, without assuming things
about your needs.
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 `templates` and `static` respectively. While this can be changed you
usually don't have to, especially when getting started.
Growing Up
----------
Growing with Flask
------------------
Since Flask is based on a very solid foundation there is not a lot of code in
Flask itself. As such it's easy to adapt even for large applications and we
are making sure that you can either configure it as much as possible by
subclassing things or by forking the entire codebase. If you are interested
in that, check out the :ref:`becomingbig` chapter.
Once you have Flask up and running, you'll find a variety of extensions
available in the community to integrate your project for production. The Flask
core team reviews extensions and ensures approved extensions do not break with
future releases.
If you are curious about the Flask design principles, head over to the section
about :ref:`design`.
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.
For the Stalwart and Wizened...
-------------------------------
Flask includes many hooks to customize its behavior. Should you need more
customization, the Flask class is built for subclassing. If you are interested
in that, check out the :ref:`becomingbig` chapter. If you are curious about
the Flask design principles, head over to the section about :ref:`design`.
If you're more curious about the minutiae of Flask's implementation, and
whether its structure is right for your needs, read the
Continue to :ref:`installation`, the :ref:`quickstart`, or the
:ref:`advanced_foreword`.