diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/narr/introduction.rst | 371 |
1 files changed, 166 insertions, 205 deletions
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 47638579b..40d9c14a8 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -9,54 +9,47 @@ :app:`Pyramid` Introduction =========================== -:app:`Pyramid` is a general, open source, Python web application development -*framework*. Its primary goal is to make it easier for a Python developer to -create web applications. - -.. sidebar:: Frameworks vs. Libraries - - A *framework* differs from a *library* in one very important way: library - code is always *called* by code that you write, while a framework always - *calls* code that you write. Using a set of libraries to create an - application is usually easier than using a framework initially, because you - can choose to cede control to library code you have not authored very - selectively. But when you use a framework, you are required to cede a - greater portion of control to code you have not authored: code that resides - in the framework itself. You needn't use a framework at all to create a web - application using Python. A rich set of libraries already exists for the - platform. In practice, however, using a framework to create an application - is often more practical than rolling your own via a set of libraries if the - framework provides a set of facilities that fits your application - requirements. - -Pyramid attempts to follow these design and engineering principles: +:app:`Pyramid` is a Python web application *framework*. It is designed to make +creating web applications easier. It is open source. + +.. sidebar:: What Is a Framework? + + A *framework* provides capabilities that developers can enhance or extend. A + web application framework provides many of the common needs of building web + applications allowing developers to concentrate only on the parts that are + specific to their application. + + Every framework makes choices about how a particular problem should be + solved. When developers choose to use a framework, they cede control over + the portions of their application that are provided by the framework. It is + possible to write a complete web application without any framework, by using + Python libraries. In practice, however, it is often more practical to use a + framework, so long as your chosen framework fits the requirements of your + application. + +Pyramid follows these design and engineering principles: Simplicity - :app:`Pyramid` takes a *"pay only for what you eat"* approach. You can get - results even if you have only a partial understanding of :app:`Pyramid`. It - doesn't force you to use any particular technology to produce an application, - and we try to keep the core set of concepts that you need to understand to a - minimum. + :app:`Pyramid` is designed to be easy to use. You can get started even if you + don't understand it all. And when you're ready to do more, :app:`Pyramid` + will be there for you. Minimalism - :app:`Pyramid` tries to solve only the fundamental problems of creating a web - application: the mapping of URLs to code, templating, security, and serving - static assets. We consider these to be the core activities that are common to - nearly all web applications. + Out of the box, :app:`Pyramid` provides only the core tools needed for nearly + all web applications: mapping URLs to code, security, and serving static + assets (files like JavaScript and CSS). Additional tools provide templating, + database integration and more. But with :app:`Pyramid` you can *"pay only for + what you eat"*. Documentation - Pyramid's minimalism means that it is easier for us to maintain complete and - up-to-date documentation. It is our goal that no aspect of Pyramid is - undocumented. + :app:`Pyramid` is committed to comprehensive and up-to-date documentation. Speed - :app:`Pyramid` is designed to provide noticeably fast execution for common - tasks such as templating and simple response generation. + :app:`Pyramid` is designed to be noticeably fast. Reliability - :app:`Pyramid` is developed conservatively and tested exhaustively. Where - Pyramid source code is concerned, our motto is: "If it ain't tested, it's - broke". + :app:`Pyramid` is developed conservatively and tested exhaustively. Our motto + is: "If it ain't tested, it's broke". Openness As with Python, the Pyramid software is distributed under a `permissive open @@ -67,54 +60,36 @@ Openness What makes Pyramid unique ------------------------- -Understandably, people don't usually want to hear about squishy engineering -principles; they want to hear about concrete stuff that solves their problems. -With that in mind, what would make someone want to use Pyramid instead of one -of the many other web frameworks available today? What makes Pyramid unique? - -This is a hard question to answer because there are lots of excellent choices, -and it's actually quite hard to make a wrong choice, particularly in the Python -web framework market. But one reasonable answer is this: you can write very -small applications in Pyramid without needing to know a lot. "What?" you say. -"That can't possibly be a unique feature. Lots of other web frameworks let you -do that!" Well, you're right. But unlike many other systems, you can also -write very large applications in Pyramid if you learn a little more about it. +There are many tools available for web development. What would make someone +want to use Pyramid instead? What makes Pyramid unique? + +With Pyramid you can write very small applications without needing to know a +lot. And by learning a bit more, you can write very large applications too. Pyramid will allow you to become productive quickly, and will grow with you. It won't hold you back when your application is small, and it won't get in your -way when your application becomes large. "Well that's fine," you say. "Lots of -other frameworks let me write large apps, too." Absolutely. But other Python -web frameworks don't seamlessly let you do both. They seem to fall into two -non-overlapping categories: frameworks for "small apps" and frameworks for "big -apps". The "small app" frameworks typically sacrifice "big app" features, and -vice versa. - -We don't think it's a universally reasonable suggestion to write "small apps" -in a "small framework" and "big apps" in a "big framework". You can't really -know to what size every application will eventually grow. We don't really want -to have to rewrite a previously small application in another framework when it -gets "too big". We believe the current binary distinction between frameworks -for small and large applications is just false. A well-designed framework -should be able to be good at both. Pyramid strives to be that kind of -framework. - -To this end, Pyramid provides a set of features that combined are unique -amongst Python web frameworks. Lots of other frameworks contain some -combination of these features. Pyramid of course actually stole many of them -from those other frameworks. But Pyramid is the only one that has all of them -in one place, documented appropriately, and useful *à la carte* without -necessarily paying for the entire banquet. These are detailed below. - -Single-file applications -~~~~~~~~~~~~~~~~~~~~~~~~ +way when your application becomes large. Other application frameworks seem to +fall into two non-overlapping categories: those that support "small apps" and +those designed for "big apps". + +We don't believe you should have to make this choice. You can't really know how +large your application will become. You certainly shouldn't have to rewrite a +small application in another framework when it gets "too big". A well-designed +framework should be able to be good at both. Pyramid is that kind of framework. -You can write a Pyramid application that lives entirely in one Python file, not -unlike existing Python microframeworks. This is beneficial for one-off -prototyping, bug reproduction, and very small applications. These applications -are easy to understand because all the information about the application lives -in a single place, and you can deploy them without needing to understand much -about Python distributions and packaging. Pyramid isn't really marketed as a -microframework, but it allows you to do almost everything that frameworks that -are marketed as "micro" offer in very similar ways. +Pyramid provides a set of features that are unique among Python web frameworks. +Others may provide some, but only Pyramid provides them all, in one place, +fully documented, and useful *à la carte* without needing to pay for the whole +banquet. + + +Build single-file applications +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can write a Pyramid application that lives entirely in one Python file. +Such an application is easy to understand since everything is in one place. It +is easy to deploy because you don't need to know much about Python packaging. +Pyramid allows you to do almost everything that so-called *microframeworks* can +in very similar ways. .. literalinclude:: helloworld.py @@ -122,13 +97,11 @@ are marketed as "micro" offer in very similar ways. See also :ref:`firstapp_chapter`. -Decorator-based configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Configure applications with decorators +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you like the idea of framework configuration statements living next to the -code it configures, so you don't have to constantly switch between files to -refer to framework configuration when adding new code, you can use Pyramid -decorators to localize the configuration. For example: +Pyramid allows you to keep your configuration right next to your code. That way +you don't have to switch files to see your configuration. For example: .. code-block:: python @@ -139,103 +112,90 @@ decorators to localize the configuration. For example: def fred_view(request): return Response('fred') -However, unlike some other systems, using decorators for Pyramid configuration -does not make your application difficult to extend, test, or reuse. The -:class:`~pyramid.view.view_config` decorator, for example, does not actually -*change* the input or output of the function it decorates, so testing it is a -"WYSIWYG" operation. You don't need to understand the framework to test your -own code. You just behave as if the decorator is not there. You can also -instruct Pyramid to ignore some decorators, or use completely imperative -configuration instead of decorators to add views. Pyramid decorators are inert -instead of eager. You detect and activate them with a :term:`scan`. +However, using Pyramid configuration decorators does not change your code. It +remains easy to extend, test or reuse. You can test your code as if the +decorators were not there. You can instruct the framework to ignore some +decorators. You can even use an imperative style to write your configuration, +skipping decorators entirely. Example: :ref:`mapping_views_using_a_decorator_section`. -URL generation -~~~~~~~~~~~~~~ +Generate application URLs +~~~~~~~~~~~~~~~~~~~~~~~~~ -Pyramid is capable of generating URLs for resources, routes, and static assets. -Its URL generation APIs are easy to use and flexible. If you use Pyramid's -various APIs for generating URLs, you can change your configuration around -arbitrarily without fear of breaking a link on one of your web pages. +Dynamic web applications produce URLs that can change depending on what you are +viewing. Pyramid provides flexible, consistent, easy to use tools for generating +URLs. When you use these tools to write your application, you can change your +configuration without fear of breaking links in your web pages. Example: :ref:`generating_route_urls`. -Static file serving +Serve static assets ~~~~~~~~~~~~~~~~~~~ -Pyramid is perfectly willing to serve static files itself. It won't make you -use some external web server to do that. You can even serve more than one set -of static files in a single Pyramid web application (e.g., ``/static`` and -``/static2``). You can optionally place your files on an external web server -and ask Pyramid to help you generate URLs to those files. This let's you use -Pyramid's internal file serving while doing development, and a faster static -file server in production, without changing any code. +Web applications often require JavaScript, CSS, images and other so-called +*static assets*. Pyramid provides flexible tools for serving these kinds of +files. You can serve them directly from Pyramid, or host them on an external +server or CDN (content delivery network). Either way, Pyramid can help you to +generate URLs so you can change where your files come from without changing any +code. Example: :ref:`static_assets_section`. -Fully interactive development -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Develop interactively +~~~~~~~~~~~~~~~~~~~~~ + +Pyramid can automatically detect changes you make to template files and code, +so your changes are immediately available in your browser. You can debug using +plain old ``print()`` calls, which will display to your console. -When developing a Pyramid application, several interactive features are -available. Pyramid can automatically utilize changed templates when rendering -pages and automatically restart the application to incorporate changed Python -code. Plain old ``print()`` calls used for debugging can display to a console. +Pyramid has a debug toolbar that allows you to see information about how your +application is working right in your browser. See configuration, installed +packages, SQL queries, logging statements and more. -Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to -render a project. This toolbar overlays your application in the browser, and -allows you access to framework data, such as the routes configured, the last -renderings performed, the current set of packages installed, SQLAlchemy queries -run, logging data, and various other facts. When an exception occurs, you can -use its interactive debugger to poke around right in your browser to try to -determine the cause of the exception. It's handy. +When your application has an error, an interactive debugger allows you to poke +around from your browser to find out what happened. Example: :ref:`debug_toolbar`. -Debugging settings -~~~~~~~~~~~~~~~~~~ +Debug with power +~~~~~~~~~~~~~~~~ -Pyramid has debugging settings that allow you to print Pyramid runtime -information to the console when things aren't behaving as you're expecting. For -example, you can turn on ``debug_notfound``, which prints an informative -message to the console every time a URL does not match any view. You can turn -on ``debug_authorization``, which lets you know why a view execution was -allowed or denied by printing a message to the console. These features are -useful for those WTF moments. +When things go wrong, Pyramid gives you powerful ways to fix the problem. -There are also a number of commands that you can invoke within a Pyramid -environment that allow you to introspect the configuration of your system. -``proutes`` shows all configured routes for an application in the order they'll -be evaluated for matching. ``pviews`` shows all configured views for any given -URL. These are also WTF-crushers in some circumstances. +You can configure Pyramid to print helpful information to the console. The +``debug_notfound`` setting shows information about URLs that aren't matched. +The ``debug_authorization`` setting provides helpful messages about why you +aren't allowed to do what you just tried. + +Pyramid also has command line tools to help you verify your configuration. You +can use ``proutes`` and ``pviews`` to inspect how URLs are connected to your +application code. Examples: :ref:`debug_authorization_section` and :ref:`command_line_chapter`. -Add-ons -~~~~~~~ +Extend your application +~~~~~~~~~~~~~~~~~~~~~~~ -Pyramid has an extensive set of add-ons held to the same quality standards as -the Pyramid core itself. Add-ons are packages which provide functionality that -the Pyramid core doesn't. Add-on packages already exist which let you easily -send email, let you use the Jinja2 templating system, let you use XML-RPC or -JSON-RPC, let you integrate with jQuery Mobile, etc. +Pyramid add-ons extend the core of the framework with useful abilities. There +are add-ons available for your favorite template language, SQL and NoSQL +databases, authentication services and much much more. + +Supported Pyramid add-ons are held to the same demanding standards as the +framework itself. You will find them to be fully tested and well documented. Examples: https://trypyramid.com/resources-extending-pyramid.html -Class-based and function-based views -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Write your views, *your* way +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Pyramid has a structured, unified concept of a :term:`view callable`. View -callables can be functions, methods of classes, or even instances. When you -add a new view callable, you can choose to make it a function or a method of a -class. In either case Pyramid treats it largely the same way. You can change -your mind later and move code between methods of classes and functions. A -collection of similar view callables can be attached to a single class as -methods, if that floats your boat, and they can share initialization code as -necessary. All kinds of views are easy to understand and use, and operate -similarly. There is no phony distinction between them. They can be used for -the same purposes. +A fundamental task for any framework is to map URLs to code. In Pyramid, that +code is called a :term:`view callable`. View callables can be functions, class +methods or even callable class instances. You are free to choose the approach +that best fits your use case. Regardless of your choice, Pyramid treats them +the same. You can change your mind at any time without any penalty. There are +no artificial distinctions between the various approaches. Here's a view callable defined as a function: @@ -275,54 +235,55 @@ Here's a few views defined as methods of a class instead: .. _intro_asset_specs: -Asset specifications -~~~~~~~~~~~~~~~~~~~~ +Find *your* static assets +~~~~~~~~~~~~~~~~~~~~~~~~~ + +In many web frameworks, the static assets required by an application are kept +in a globally shared location, "the *static* directory". Others use a lookup +scheme, like an ordered set of template directories. Both of these approaches +have problems when it comes to customization. -Asset specifications are strings that contain both a Python package name and a -file or directory name, e.g., ``MyPackage:static/index.html``. Use of these -specifications is omnipresent in Pyramid. An asset specification can refer to -a template, a translation directory, or any other package-bound static -resource. This makes a system built on Pyramid extensible because you don't -have to rely on globals ("*the* static directory") or lookup schemes ("*the* -ordered set of template directories") to address your files. You can move -files around as necessary, and include other packages that may not share your -system's templates or static files without encountering conflicts. - -Because asset specifications are used heavily in Pyramid, we've also provided a -way to allow users to override assets. Say you love a system that someone else -has created with Pyramid but you just need to change "that one template" to -make it all better. No need to fork the application. Just override the asset -specification for that template with your own inside a wrapper, and you're good -to go. +Pyramid takes a different approach. Static assets are located using *asset +specifications*, strings that contain reference both to a Python package name +and a file or directory name, e.g. ``MyPackage:static/index.html``. These +specifications are used for templates, JavaScript and CSS, translation files, +and any other package-bound static resource. By using asset specifications, +Pyramid makes it easy to extend your application with other packages without +worrying about conflicts. + +What happens if another Pyramid package you are using provides an asset you +need to customize? Maybe that page template needs better HTML, or you want to +update some CSS. With asset specifications you can override the assets from +other packages using simple wrappers. Examples: :ref:`asset_specifications` and :ref:`overriding_assets_section`. -Extensible templating -~~~~~~~~~~~~~~~~~~~~~ +Use *your* templates +~~~~~~~~~~~~~~~~~~~~ -Pyramid has a structured API that allows for pluggability of "renderers". -Templating systems such as Mako, Genshi, Chameleon, and Jinja2 can be treated -as renderers. Renderer bindings for all of these templating systems already -exist for use in Pyramid. But if you'd rather use another, it's not a big -deal. Just copy the code from an existing renderer package, and plug in your -favorite templating system. You'll then be able to use that templating system -from within Pyramid just as you'd use one of the "built-in" templating systems. +In Pyramid, the job of creating a ``Response`` belongs to a :term:`renderer`. +Any templating system--Mako, Genshi, Chameleon, Jinja2--can be a renderer. In +fact, packages exist for all of these systems. But if you'd rather use another, +a structured API exists allowing you to create a renderer using your favorite +templating system. You can use the templating system *you* understand, not one +required by the framework. -Pyramid does not make you use a single templating system exclusively. You can -use multiple templating systems, even in the same project. +What's more, Pyramid does not make you use a single templating system +exclusively. You can use multiple templating systems, even in the same +project. Example: :ref:`templates_used_directly`. -Rendered views can return dictionaries -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Write testable views +~~~~~~~~~~~~~~~~~~~~ -If you use a :term:`renderer`, you don't have to return a special kind of -"webby" ``Response`` object from a view. Instead you can return a dictionary, -and Pyramid will take care of converting that dictionary to a Response using a -template on your behalf. This makes the view easier to test, because you don't -have to parse HTML in your tests. Instead just make an assertion that the view -returns "the right stuff" in the dictionary. You can write "real" unit tests -instead of functionally testing all of your views. +When you use a :term:`renderer` with your view callable, you are freed from +needing to return a "webby" ``Response`` object. Instead, your views can return +a simple Python dictionary. Pyramid will take care of rendering the information +in that dictionary to a ``Response`` on your behalf. As a result, your views +are more easily tested, since you don't need to parse HTML to evaluate the +results. Pyramid makes it a snap to write unit tests for your views, instead of +requiring you to use functional tests. .. index:: pair: renderer; explicitly calling @@ -330,7 +291,7 @@ instead of functionally testing all of your views. .. _example_render_to_response_call: -For example, instead of returning a ``Response`` object from a +For example, a typical web framework might return a ``Response`` object from a ``render_to_response`` call: .. code-block:: python @@ -342,7 +303,7 @@ For example, instead of returning a ``Response`` object from a return render_to_response('myapp:templates/mytemplate.pt', {'a':1}, request=request) -You can return a Python dictionary: +While you *can* do this in Pyramid, you can also return a Python dictionary: .. code-block:: python :linenos: @@ -353,13 +314,13 @@ You can return a Python dictionary: def myview(request): return {'a':1} -When this view callable is called by Pyramid, the ``{'a':1}`` dictionary will -be rendered to a response on your behalf. The string passed as ``renderer=`` -above is an :term:`asset specification`. It is in the form -``packagename:directoryname/filename.ext``. In this case, it refers to the -``mytemplate.pt`` file in the ``templates`` directory within the ``myapp`` -Python package. Asset specifications are omnipresent in Pyramid. See -:ref:`intro_asset_specs` for more information. +By configuring your view to use a renderer, you tell Pyramid to use the +``{'a':1}`` dictionary and the specified template to render a response on your +behalf. + +The string passed as ``renderer=`` above is an :term:`asset specification`. +Asset specifications are omnipresent in Pyramid. They allow for more reliable +customization. See :ref:`intro_asset_specs` for more information. Example: :ref:`renderers_chapter`. |