Pyramid Web框架1.9.2开发文档详解

需积分: 12 10 浏览量更新于2024-07-18 收藏 3.95MB PDF 举报

Pyramid文档是关于Pyramid Web Framework的开发指南，该框架在早期的Web开发中曾非常流行。Pyramid是基于Python编写的轻量级且灵活的Web框架，由Chris McDonough创建并维护。该版本为1.9.2，出版于2011年，遵循Creative Commons Attribution-Noncommercial-ShareAlike 3.0 United States License（CC BY-NC-SA 3.0 US），这意味着用户可以在非商业用途下自由复制、修改和分享文档内容，但必须保留原始作者署名，并且对于修改后的作品也需遵循类似或相似的许可。文档内容分为四个主要部分： 1. **教程(Tutorials)**: 这部分为初学者提供了入门指导，包括安装、配置以及基础架构的设置。它可能涵盖了如何构建简单的Web应用，如路由、模板引擎、请求处理和响应生成等内容。 2. **叙事性文档(Narrative Documentation)**: 这是更深入的文档，讲解了Pyramid框架的核心概念和技术细节，包括如何设计和实现复杂的应用架构，如视图层、URL管理、中间件和配置选项等。这部分有助于开发者理解和掌握框架的最佳实践。 3. **API文档(API Documentation)**: 对Pyramid的公共接口进行了详尽的描述，包括类、函数、模块的详细说明和用法示例。开发者可以查阅这部分来查找特定功能的使用方法和参数说明。 4. **脚本文档(p*Scripts Documentation)**: 提供与Pyramid框架相关的实用脚本和工具，这些脚本可以帮助开发人员进行项目管理和自动化任务，例如构建工具、部署脚本等。此外，文档还包括了**变更历史(Change History)**，记录了每个版本的主要更新和改进；以及**术语表(Glossary and Index)**，方便读者查找专业术语和索引文档内容。 Pyramid文档是一个全面的学习资源，不仅适合希望使用Pyramid框架的开发人员，也是框架开发者和社区成员了解其设计哲学和实现细节的重要参考。通过阅读和理解这份文档，用户能够熟练地构建高效、可扩展的Web应用。

the two systems was an exercise in frustration for an otherwise non-partisan developer. It was also strange

for the Pylons and BFG development communities to be in competition for the same set of users, given

how similar the two frameworks were. So the Pylons and BFG teams began to work together to form a

plan to merge. The features missing from BFG (notably view handler classes, ﬂash messaging, and other

minor missing bits), were added to provide familiarity to ex-Pylons users. The result is Pyramid.

The Python web framework space is currently notoriously balkanized. We’re truly hoping that the amal-

gamation of components in Pyramid will appeal to at least two currently very distinct sets of users: Pylons

and BFG users. By unifying the best concepts from Pylons and BFG into a single codebase, and leaving

the bad concepts from their ancestors behind, we’ll be able to consolidate our efforts better, share more

code, and promote our efforts as a unit rather than competing pointlessly. We hope to be able to shortcut

the pack mentality which results in a much larger duplication of effort, represented by competing but

incredibly similar applications and libraries, each built upon a speciﬁc low level stack that is incompatible

with the other. We’ll also shrink the choice of credible Python web frameworks down by at least one.

We’re also hoping to attract users from other communities (such as Zope’s and TurboGears’) by provid-

ing the features they require, while allowing enough ﬂexibility to do things in a familiar fashion. Some

overlap of functionality to achieve these goals is expected and unavoidable, at least if we aim to prevent

pointless duplication at higher levels. If we’ve done our job well enough, the various audiences will be

able to coexist and cooperate rather than ﬁring at each other across some imaginary web framework DMZ.

Pyramid Uses a Zope Component Architecture ("ZCA") Registry

Pyramid uses a Zope Component Architecture (ZCA) "component registry" as its application registry

under the hood. This is a point of some contention. Pyramid is of a Zope pedigree, so it was natural for

its developers to use a ZCA registry at its inception. However, we understand that using a ZCA registry

has issues and consequences, which we’ve attempted to address as best we can. Here’s an introspection

about Pyramid use of a ZCA registry, and the trade-offs its usage involves.

Problems

The global API that may be used to access data in a ZCA component registry is not particularly pretty

or intuitive, and sometimes it’s just plain obtuse. Likewise, the conceptual load on a casual source code

reader of code that uses the ZCA global API is somewhat high. Consider a ZCA neophyte reading the

code that performs a typical "unnamed utility" lookup using the zope.component.getUtility()

global API:

1 from pyramid.interfaces import ISettings

2 from zope.component import getUtility

3 settings = getUtility(ISettings)

After this code runs, settings will be a Python dictionary. But it’s unlikely that any civilian would

know that just by reading the code. There are a number of comprehension issues with the bit of code

above that are obvious.

First, what’s a "utility"? Well, for the purposes of this discussion, and for the purpose of the code above,

it’s just not very important. If you really want to know, you can read this. However, still, readers of such

code need to understand the concept in order to parse it. This is problem number one.

Second, what’s this ISettings thing? It’s an interface. Is that important here? Not really, we’re just

using it as a key for some lookup based on its identity as a marker: it represents an object that has the

dictionary API, but that’s not very important in this context. That’s problem number two.

Third of all, what does the getUtility function do? It’s performing a lookup for the ISettings

"utility" that should return... well, a utility. Note how we’ve already built up a dependency on the under-

standing of an interface and the concept of "utility" to answer this question: a bad sign so far. Note also

that the answer is circular, a really bad sign.

Fourth, where does getUtility look to get the data? Well, the "component registry" of course. What’s

a component registry? Problem number four.

Fifth, assuming you buy that there’s some magical registry hanging around, where is this registry? Hom-

ina homina... "around"? That’s sort of the best answer in this context (a more speciﬁc answer would

require knowledge of internals). Can there be more than one registry? Yes. So in which registry does

it ﬁnd the registration? Well, the "current" registry of course. In terms of Pyramid, the current registry

is a thread local variable. Using an API that consults a thread local makes understanding how it works

non-local.

You’ve now bought in to the fact that there’s a registry that is just hanging around. But how does the

registry get populated? Why, via code that calls directives like config.add_view. In this particular

case, however, the registration of ISettings is made by the framework itself under the hood: it’s not

present in any user conﬁguration. This is extremely hard to comprehend. Problem number six.

Clearly there’s some amount of cognitive load here that needs to be borne by a reader of code that extends

the Pyramid framework due to its use of the ZCA, even if they are already an expert Python programmer

and an expert in the domain of web applications. This is suboptimal.

Ameliorations

First, the primary amelioration: Pyramid does not expect application developers to understand ZCA con-

cepts or any of its APIs. If an application developer needs to understand a ZCA concept or API during

the creation of a Pyramid application, we’ve failed on some axis.

Instead the framework hides the presence of the ZCA registry behind special-purpose API functions that

do use ZCA APIs. Take for example the pyramid.security.authenticated_userid function,

which returns the userid present in the current request or None if no userid is present in the current

request. The application developer calls it like so:

1 from pyramid.security import authenticated_userid

2 userid = authenticated_userid(request)

They now have the current user id.

Under its hood however, the implementation of authenticated_userid is this:

1 def authenticated_userid(request):

2 """ Return the userid of the currently authenticated user or

3 ``None`` if there is no authentication policy in effect or there

4 is no currently authenticated user. """

6 registry = request.registry # the ZCA component registry

7 policy = registry.queryUtility(IAuthenticationPolicy)

8 if policy is None:

9 return None

10 return policy.authenticated_userid(request)

Using such wrappers, we strive to always hide the ZCA API from application developers. Application

developers should just never know about the ZCA API; they should call a Python function with some

object germane to the domain as an argument, and it should return a result. A corollary that follows is that

any reader of an application that has been written using Pyramid needn’t understand the ZCA API either.

Hiding the ZCA API from application developers and code readers is a form of enhancing domain speci-

ﬁcity. No application developer wants to need to understand the small, detailed mechanics of how a web

framework does its thing. People want to deal in concepts that are closer to the domain they’re working

in. For example, web developers want to know about users, not utilities. Pyramid uses the ZCA as an

implementation detail, not as a feature which is exposed to end users.

However, unlike application developers, framework developers, including people who want to override

Pyramid functionality via preordained framework plugpoints like traversal or view lookup, must under-

stand the ZCA registry API.

Pyramid framework developers were so concerned about conceptual load issues of the ZCA registry

API that a replacement registry implementation named repoze.component was actually developed.

Though this package has a registry implementation which is fully functional and well-tested, and its API

is much nicer than the ZCA registry API, work on it was largely abandoned, and it is not used in Pyramid.

We continued to use a ZCA registry within Pyramid because it ultimately proved a better ﬁt.

Note: We continued using ZCA registry rather than disusing it in favor of using the registry implemen-

tation in repoze.component largely because the ZCA concept of interfaces provides for use of an

interface hierarchy, which is useful in a lot of scenarios (such as context type inheritance). Coming up

with a marker type that was something like an interface that allowed for this functionality seemed like it

was just reinventing the wheel.

Making framework developers and extenders understand the ZCA registry API is a trade-off. We (the

Pyramid developers) like the features that the ZCA registry gives us, and we have long-ago borne the

weight of understanding what it does and how it works. The authors of Pyramid understand the ZCA

deeply and can read code that uses it as easily as any other code.

But we recognize that developers who might want to extend the framework are not as comfortable with

the ZCA registry API as the original developers. So for the purpose of being kind to third-party Pyramid

framework developers, we’ve drawn some lines in the sand.

In all core code, we’ve made use of ZCA global API functions, such as zope.component.

getUtility and zope.component.getAdapter, the exception instead of the rule. So instead

of:

1 from pyramid.interfaces import IAuthenticationPolicy

2 from zope.component import getUtility

3 policy = getUtility(IAuthenticationPolicy)

Pyramid code will usually do:

1 from pyramid.interfaces import IAuthenticationPolicy

2 from pyramid.threadlocal import get_current_registry

3 registry = get_current_registry()

4 policy = registry.getUtility(IAuthenticationPolicy)

While the latter is more verbose, it also arguably makes it more obvious what’s going on. All of the

Pyramid core code uses this pattern rather than the ZCA global API.

Rationale

Here are the main rationales involved in the Pyramid decision to use the ZCA registry:

• History. A nontrivial part of the answer to this question is "history". Much of the design of Pyramid

is stolen directly from Zope. Zope uses the ZCA registry to do a number of tricks. Pyramid mimics

these tricks, and, because the ZCA registry works well for that set of tricks, Pyramid uses it for the

same purposes. For example, the way that Pyramid maps a request to a view callable using traversal

is lifted almost entirely from Zope. The ZCA registry plays an important role in the particulars of

how this request to view mapping is done.

• Features. The ZCA component registry essentially provides what can be considered something like

a superdictionary, which allows for more complex lookups than retrieving a value based on a single

key. Some of this lookup capability is very useful for end users, such as being able to register a

view that is only found when the context is some class of object, or when the context implements

some interface.

• Singularity. There’s only one place where "application conﬁguration" lives in a Pyramid appli-

cation: in a component registry. The component registry answers questions made to it by the

framework at runtime based on the conﬁguration of an application. Note: "an application" is not

the same as "a process"; multiple independently conﬁgured copies of the same Pyramid application

are capable of running in the same process space.

• Composability. A ZCA component registry can be populated imperatively, or there’s an existing

mechanism to populate a registry via the use of a conﬁguration ﬁle (ZCML, via the optional pyra-

mid_zcml package). We didn’t need to write a frontend from scratch to make use of conﬁguration-

ﬁle-driven registry population.

• Pluggability. Use of the ZCA registry allows for framework extensibility via a well-deﬁned and

widely understood plugin architecture. As long as framework developers and extenders understand

the ZCA registry, it’s possible to extend Pyramid almost arbitrarily. For example, it’s relatively

easy to build a directive that registers several views all at once, allowing app developers to use that

directive as a "macro" in code that they write. This is somewhat of a differentiating feature from

other (non-Zope) frameworks.

• Testability. Judicious use of the ZCA registry in framework code makes testing that code slightly

easier. Instead of using monkeypatching or other facilities to register mock objects for testing, we

inject dependencies via ZCA registrations, then use lookups in the code to ﬁnd our mock objects.

• Speed. The ZCA registry is very fast for a speciﬁc set of complex lookup scenarios that Pyramid

uses, having been optimized through the years for just these purposes. The ZCA registry contains

optional C code for this purpose which demonstrably has no (or very few) bugs.

• Ecosystem. Many existing Zope packages can be used in Pyramid with few (or no) changes due to

our use of the ZCA registry.

Conclusion

If you only develop applications using Pyramid, there’s not much to complain about here. You just should

never need to understand the ZCA registry API; use documented Pyramid APIs instead. However, you

may be an application developer who doesn’t read API documentation. Instead you read the raw source

code, and because you haven’t read the API documentation, you don’t know what functions, classes, and

methods even form the Pyramid API. As a result, you’ve now written code that uses internals, and you’ve

剩余1238页未读，继续阅读

华米

粉丝: 0
资源: 3

Pyramid Web框架1.9.2开发文档详解

基于FSD Pyramid的图像融合算法程序

Pyramid英文文档.pdf

pyramid-1.2.tar.gz

python pyramid中文文档

pyramid ultrasound elastography github

cannot import name 'UnencryptedCookieSessionFactoryConfig' from 'pyramid.session' (unknown

Could not find a version that satisfies the requirement pyramid.session (from versions: none)

python web开发手册

Python 做 web 项目 用什么框架实现

我想找一个Python写的轻量级web的教程

最新资源

Python 做 web 项目用什么框架实现