- 论坛徽章:
- 0
|
snakelets 文档，我翻译了一部分。
Creating a Web Application
The web application that you will be making is essentially a lot of files in one or more directories. Static content files such as html files and images, dynamic content files such as Ypages, and web application code itself (python source code files). This chapter shows how they all fit together.
我们创建的web 应用程序基本上都是有很多文件或者文件夹组成的。静态页面包括html和图片，动态内容一般都是Ypage，还有web应用程序本身代码（python源代码文件）。这章将阐述它们之间是如何协调工作的。
FIrst you have to create and configure your web application, and then you must fill it with web pages.
首先您应该创建并配置您的web应用程序，之后添入我们需要的页面文件。
Setting up the web application
Put your stuff in a Python module in the "webapps" directory. The directory (module) name is also the name and URL context name of your web application. So when your webapp is in a directory called store, it will be accessible with the URL http://server.com/store/ There is one special reserved name: if you have a web app named "ROOT" that one will be used as the web application for the root context '/'. (When you are using Virtual Hosting settings, you can change this, it is only used when no vhosts are defined).
将您的源文件放到 webapps目录中。这个目录（模块）的名称跟您的web 应用程序的URL 名称相关。如果您的webapp被存储到文件夹 store中的时，您就可以通过http://server.com/store/ 来访问他，这里还有特殊的保留目录名：ROOT，相当于web 应用程序的根目录 ‘/’。（当您正在使用虚拟主机时，您可以对其进行修改，当没有定义vhosts的时候可以使用他。）
The module's __init__.py must contain the configuration settings for your web app:
模块 __init__.py 包括如下配置内容：
Attribute属性 Description描述
name The descriptive name for this webapp
webapp的描述名称
docroot The (relative) directory where files are served from, usually "." (which means the directory of the webapp itself). Many webapps also choose to use "docroot" or something similar, and then put all files into a docroot/ subdirectory. This is a bit more secure because it is not possible to access files outside this directory, so you can place code or other data in the webapp directory without worrying about this.
文件服务目录（相对目录），一般为 ‘.’（webapp的目录从属关系）。一般的webapp都使用 “docroot” 或者类似的名称，并将所有文件放到docroot/ 的子目录中。这是比较安全的，因为外部不能访问此目录中的文件，所以您可以比较放心得将您的代码或者是数据存放到此目录中。
assetLocation The (relative or absolute) url location where static assets are to be found. If you use a relative location ("static/img/" for instance), the assets are located inside the webapp's docroot (use "." to use the docroot directory itself, instead of a directory inside it). If you use an absolute location ("/static/" for instance), the assets are located in another web app or path entirely (but still on the same web server). It is also possible to put a totally different url here such as "http://images.server.com/img/" to be able to serve static assets (images, files) from an entirely different server. This setting is used by the asset Ypage function and the mkAssetUrl Webapp function.
可以访问到静态文件的url路径（相对 或 绝对）。如果您使用相对路径（比如 “static/img/”），所有文件都被放置到 webapp的docroot中（可以通过 ‘.’来使用docroot目录）。如果使用绝对路径（”/static/”），所有文件将被放到其他的 web app或者路径中（但是仍然使用同一个 web server）。也可以将文件（图片，文件）放到完全不同web server的url中，比如 http://images.server.com/img/ 。设置此项可以通过 asset Ypage函数 和 mkAssetUrl Webapp函数。
snakelets a dict that maps (relative) URL patterns to snakelet classes. With this you define the snakelets in your web application, and on what URLs they are 'listening'. Don't forget to import the required modules/classes. You can use 'fnmatch'-style patterns here, for instance: docs/*.pdf would let the snakelet listen on any URL that matches this pattern, such as http://.../docs/report.pdf (the full URL must match the pattern). If you don't use a pattern, any URL that starts with the string matches. Note that if you use fnmatch-patterns, you cannot use path info arguments anymore (only query args): http://.../docs/report.pdf/path/info?foo=bar doesn't work, but http://.../docs/report.pdf?foo=bar still does. See below how you can use Snakelets as virtual index pages.
映射（相对） URL 式样到 snakelet classes（这句话如何翻译？）。您可以在您正在使用的web应用程序中定义snakelets，让它通过URL来监听您的web 应用程序。不要忘了 import 需要的 模块/类 。在这里您可以使用 ‘fnmatch-style 式样。比如：docs/*.pdf 它可以让snakelet任何URL上与之相匹配的式样。像 http://…/docs/report.pdf(完整的URL必须匹配式样)。如果不是用式样，URL将使用 字符串 匹配。请注意如果您使用 fnmatch-pattens ，您将不能使用 path info 参数（只是query参数）：http://…/docs/report.pdf/path/info?foo=bar 是不能工作的，但是http://…/docs/report.pdf?foo=bar 仍然工作。详细请见下文 如何真正的使用Snakelets.
configItems a dict that you can fill with any config items you want to be available in the web app trough the getConfigItem() method.
通过getConfigItem()方法在web app中设置您想使用的配置项目。
sessionTimeoutSecs the inactivity period it takes for a user session to be deleted automatically. Default=600 seconds (10 minutes).
用户session自动被删除的得默认时间是 600秒。
sharedSession boolean that says if this webapp should use the global shared session. Every webapp that has this on True will not use its own session, but instead share a single global session. This can be used for single signon, for instance, because the logged in user object is also shared. For more info see authorization. (The default value is False: use a unique, private session) Note: shared session does NOT mean that different users share a session. Every user ofcourse has her own private session!
boolean值，它将告诉webapp是拥有公共的否共享session。一般每个webapp都打开此项，来代替单一的共享session。也可以使用单一标记，因为 logged in user对象也是共享的。更多信息见 authorization。（默认值是 False:使用唯一的，私有的session）注解：共享session并不是不同用户共享同一个session。每个用户当然有他们自己的私有session。
defaultOutputEncoding Specify the output character encoding of dynamic pages (Ypages, snakelets) that don't specify an encoding themselves (or obtain one from a template page). If they set an encoding themselves, that one is used. Default=None; no encoding.
指定动态页面的输出字符编码（Ypages,snakelets），如果页面自己没有指定字符编码，就会按此参数进行字符编码（或者从页面模版获得）。默认是 Default=None;没有编码。
defaultContentType Specify the content type of dynamic pages (Ypages, snakelets) that don't specify a content type themselves (or obtain one from a template page). If they set a content type themselves, that one is used.
Default=text/html指定动态页面的内容类型，默认 text/html。
defaultPageTemplate Specify the default page template file to use for formatting dynamic pages without an explicit page template declaration. Default=None; no page template. Doesn't work on snakelets, only Ypages
指定默认模版页面文件用于格式化动态页面，不通过直接模版声明。Default=None；默认没有页面模版。只在Ypage工作。
defaultErrorPage Specify the default errorpage to use for formatting server error pages. This saves you from having to specify an errorpage in every Ypage file. Works for snakelets and Ypages.
指定默认错误页面文件来格式化server错误页面。避免您重复进行错误页面设置。在snakelets和Ypage都可以使用。
indexPages Setting this value allows you to use a custom 'index pages' list on a site-by-site basis. It will override the default list of index pages that Snakelets looks for. If you don't specify it, the default list is used. The built-in default list is index.y, index.html, index.htm (in this order). Only real files can be mentioned in this list. It is possible to use Snakelets as 'virtual' index pages but that is configured elsewhere.
允许设置自定义的 ‘index 页面’列表。他将替代默认的index页面列表。如果你没有指定他，默认内置列表为 index.y . index.html . index.htm 。只有真实文件可以在列表中出现。您也可以使用虚拟页面，但这需要另外的配置。
def dirListAllower(path): ... define this function to allow directory listings for the path (regardless of user authorization). Return True if allowed. By default, directory listing is not allowed. Path is relative for the web app, for instance "img/picture.gif"
通过定义此函数来实现对某些目录的列表访问（忽略用户授权）。如果可以访问返回True 。默认情况下目录列表不允许访问。使用相对路径，比如： ‘img/picture.gif’。
def documentAllower(path): ... define this function to allow serving the given document (regardless of user authorization). Return True if allowed. By default, all documents are allowed except Python source files (.py suffix). Path is relative for the web app, for instance "img/picture.gif"
定义此函数来提供文档服务（忽略用户授权）。如果允许返回True。默认情况除了python源文件(.py后缀)以外所有文档都可以访问。采用相对路径。比如： ‘img/picture.gif’。
authorizationPatterns a dict that maps (relative) URL patterns to lists of privilege names that are allowed to access those URLs. Note that the full URL must match the pattern before authorization is required, so Snakelets automatically appends the *-wildcard to the end of your pattern to avoid security holes. (Also: the server-wide url prefix is automatically prepended to your patterns) See authorization. Default: all URLs are allowed (no privilege checks).
允许访问特有名称列表的映射URL标记。注意 在授权请求之前完整URL必须匹配标记，Snakelets自动在您的标记后面添加*-wildcard来避免安全漏洞。（同样：server-wide url前缀将被预先自动添加到你的标记前）见 authorization 。默认：所有URL都是允许的（没有特权检测）。
authenticationMethod tuple (method, argument) that defines the user authentication method to use for the whole webapp. See authorization. Default: not specified. This setting can be overruled by a corresponding page declaration or snakelet method.
为整个webapp定义用户验证。见 authorization 。 默认：无指定。这个设置可以被相应的页面或者snakelet 方法修改。
def authorizeUser(method, url, user, passwd, request): ... You must implement this method yourself if you let Snakelets do the user authentication. It must do the actual user/password checking, see authorization.
如果您让Snakelets进行用户验证，您必须自己实现该方法。必须有 user/password 检测，见 authorization 。
def init(webapp): ... You may define this function to do your webapp's initialization. Parameter is the current webapp. Note: when you are deploying your webapp on multiple vhosts, the init is called once for each vhost! Be prepared for this, especially when you are doing system-global initialisation code such as registering server plugins... (you should trap possible errors, or add some code that makes sure that such things are only done once)
您可能定义这个函数用来初始化您的webapp。参数值为当前的得webapp。 注意：如果您正在使用多重vhost 进行开发，init函数将在每一个vhost中被执行一次！请注意这一点，尤其是当您正在使用 system-global（系统全局）初始化代码的时候，比如注册系统插件…（您应该捕捉可能出现的错误，或者添加一些代码来确定这些注册操作只进行一次）。
def close(webapp): ... You may define this function to do your webapp's cleanup when it is removed. Parameter is the current webapp. Note: when you are deploying your webapp on multiple vhosts, the init is called once for each vhost!
当您的webapp被移除的时候自动执行此函数。参数是当前的webapp。
vhost config: To make your web application appear on the server, you have to add it to the virtual host configuration file. See Starting the Server.
vhost 配置:如果想在server中运行您的webapp，您需要在虚拟主机中添加相应的配置文件。见Starting the Server。
Python module/package names: There is a big catch concerning the naming of your packages and modules in the web apps (for instance, the package where your snakelets are in, or the name(s) of the modules that contain your snakelets). They are not unique over all web applications (because every webapp's directory is placed in Python's module search path)! This means that you cannot have a module or package called "snakelets" in one webapp and also a module or package with that name in another web application. This also means that your code is not protected from (ab)use by another web application. This wil very likely not be fixed, so keep this in mind!
Python module/package 名称：您的 package 和 module 的名称在整个web应用程序中并不是唯一的（因为所有的webapp目录都在搜索路径范围之内）！这就意味着您不能有名为 “snakelets”的webapp，当然在其他web应用程序中的module或 package也不能用这个名字。也就是说使用同名的module/package您想要使用的module/package将不能保证在其他web应用程序中被运行。
Shared modules/libraries: place modules and packages that you want to easily share between webapps in the "userlibs" directory, as described in Starting and Configuring.
共享的 modules/libraries:将您想要共享的 module/packages 放到该目录下，Starting and Configuring中有比较详细的描述。
Create pages for the web application
Let's say that you have created a web application "testapp" and that it has a "docroot" directory where you will put your page files, so you must point the docroot attribute to it in the webapp's init file, as described above. The files in that directory will now be accessible in your browser by using the url base: http://server.com/testapp/
加入您创建了一个web应用程序”testapp”，在此目录中有一个 “docroot”目录用来仿制您的页面文件，您必须在webapp的 init文件中指定docroot属性，就像我们先前描述的。该文件将不能通过url访问：http://server.com/testapp/
Snakelets maps the rest of the URL to the filesystem (=the contents of the docroot directory) in a rather straightforward way, much the same as a normal web server such as Apache does this. A path component in the url maps to a directory on disk, and a file component usually maps to a file on disk. So that means that when the url http://server.com/testapp/office/page.html is requested, Snakelets will return the "page.html" file from the "office" directory in the docroot location. For Ypages it is the same, http://server.com/testapp/office/login.y will cause Snakelets to load and run the "login.y" ypage in the given location.
Snakelets 直接将URL映射到系统文件（=docroot 目录的内容），跟Apache一样。每一个路径组成部分都映射到硬盘上的某一个文件夹，文件映射到硬盘上的文件。所以，当 http://server.com/testapp/office/page.html被请求的时候，Snakelets将从docroot的office目录返回 ‘page.html’文件。对于Ypage也是同样。
It is impossible to request files outside the docroot location this way. That is nice, because you can protect your other files (web app source code and such) very easily just by placing them in a different directory as your web pages. You could fool around with the documentAllower function but this is more convenient and faster.
这种方式不可能请求到docroot区域以外的文件。这样你可以很容易的保护其他文件（比如 webapp的源文件代码），只要你把他们放到其他目录。您可能会随意的使用 documentAllower函数，但它确实方便，快速。
There is a big exception to the simple URL-to-filesystem mapping: Snakelets. Dynamic content created by a snakelet page is not found on disk in the regular way. Instead, there is a snakelet object defined in your Python source code that is called by the server when a URL is requested that triggers the snakelet. Which URLs trigger which snakelets, is configured in the "snakelets" attribute in your webapp init file (see above). Because you can use simple wildcard patterns there, a lot of URLs may be mapped onto a single snakelet object.
在URL到系统文件的映射问题上有一个例外：Snakelets。被snakelet 创建的动态内容在硬盘上是着不到的。他是定义在你的python源文件中的对象，当URL被请求的时候server会调用他从而触发snakelet。哪一个URL触发哪一个snakelets，这都定义在您的web app 的 init（初始化）文件中（见前面文章）。因为您可以使用通配符号，所以大部分的URL可以映射到单一的snakelet对象。
The server uses the following order to determine what is returned for a requested URL:
server 返回下面几种URL请求：
1. Snakelet url/patterns
2. Dynamic page (Ypage)
3. Static page/file (.html etc)
Index pages
When you leave out a specific page name from an url (example: http://server.com/app/info/) the server will try to fetch the index page for that directory. If there is a file index.html (or index.y) in that location, Snakelets will load that one. It is as if you typed the url http://server.com/app/info/index.y.
See above at the indexPages variable what the default list of files is that are searched for, and how you can change this.
当您没有对url指定页面名称的时候（如：http://server.com/app/info/）server就会自动尝试此目录中的 index 页面（或 index.y）。和使用url http://server.com/app/info/index.y。如何设置默认页请见前面文章。
Snakelet as index page: if no other suitable page is found, the server will also try to use a Snakelet as index page. You have to configure a snakelet with a suitable URL pattern to make this work. The server looks for index.sn Snakelet in the requested URL path, so when the URL "http://server.com/test/dir/" is requested and you have configured a snakelet in the "test" webapp on the pattern dir/index.sn or */index.sn it will be used as index page. You can also use a Snakelet as 'root' index page in your webapp, but you will have to add it explicitly to the Snakelet list (because of the way the fnmatch urlpatterns work): use the pattern index.sn (no pre- or suffixes).
To avoid conflicts with other snakelets, it is required that the url pattern for your index snakelet(s) explicitly ends in 'index.sn'.
Note that you can create 'fake' directories using index Snakelets; the directory that you use in the snakelet url path pattern doesn't have to exist on disk - in contrast to regular index pages.
Snakelet 作为index page:如果没有找到匹配的页面，server就会尝试使用snakelet 作为索引页面。您必须对snakelet的url标记进行设置才能正常使用此功能。 Server会自动在请求路径中寻找 index.sn ，但是这需要您明确的指出：使用标记 index.sn 。为了避免冲突，url标记必须以 ‘index.sn’结尾。注意 您可以使用index Snakelets创建一个“冒牌”的目录；这个目录并不一定在硬盘上存在 --- 同正规页面有鲜明的对比。
Smart Suffix Search
Snakelets also uses a 'smart suffix search'. This means that it is not strictly required to have the correct file suffix in the URL. This allows for 'cleaner' URLs. If a page is not found, Snakelets will try again by -internally- appending the .y, .html and .htm suffixes (in that order). For instance, http://server.com/testapp/office/login.y will load the "login.y" Ypage, but so will http://server.com/testapp/office/login (the same url but without the .y suffix). Notice that dynamic content has higher priority than static content, so if "login.y" and "login.html" both exist, the server will use "login.y". This mechanism is rather useful when you are setting up a website: you can start with all static .html pages, and replace them later on with dynamic .y pages - without changing any of your URLs.
Snakelets 使用了 ‘ smart suffix search ‘。就是说在URL中的文件后缀不一定严格准确。这允许使用 ‘cleaner’ URL。如果页面没有找到，Snakelets将逐个搜索 .y, .html 和 .htm 后缀。比如 http://server.com/testapp/office/login.y 将载入 ‘login.y’页面，同样将搜索除 .y 后缀以外的 http://server.com/testapp/office/login文件。注意动态内容比静态内容有更高的优先级，当 ‘login.y’ 和 ‘login.html’同时存在时，server将优先使用 ‘login.y’。这种机制是很有用的：您可以先使用静态.html页面，之后用动态 .y 页面代替 --- 而不用修改任何URL连接。
There is one small issue: the 'smart suffix search' does not work if you are using path components in the URL query parameters. For instance, http://server.com/testapp/office/login.y/floor1 will work (it will call login.y with "/floor1" pathinfo on the request), but http://server.com/testapp/office/login/floor1 will not work. (If you want something like this to work, use a Snakelet with a suitable URL pattern). Note that regular query parameters do work: http://server.com/testapp/office/login?floor=1 works fine (it will call login.y with correct query parameters).
这又一个小小的问题： 在您使用路径作为参数的时候‘smart suffix search’是不工作的。比如： http://server.com/testapp/office/login.y/floor1 工作（这将传递给login.y ‘/floor1’路径信息，而 http://server.com/testapp/office/login/floor1不工作。（如果您想使这样的方式正常工作，需要适当的设置URL标记）。注意：http://server.com/testapp/office/login?floor=1 也是可以很好工作的（这将传递给login.y正确的参数）。
Smart suffixes and authorization patterns: when checking authorization patterns, Snakelets takes smart suffixes into account. For more info see authorization.
后缀 和 认证标记：当验证认证标记的时候，Snakelets将后缀考虑在内。更多信息参考 authorization.
Automatic reloading
For fast development, Snakelets supports automatic page reloading. This means that when you update an Ypage source file, or a Snakelets module source file, the server will detect that it has been updated and it will reload and recompile the new version. This happens on-the-fly so you will directly see the changes you have made in your browser.
为了实现快速的开发，Snakelets 提供自动页面重载。当您更新了您的 Ypage 文件，或者 Snakelets 模块文件的时候，server会自动监测您的更新，并且自动载入新版本的文件。所以您可以很方便的直接看到您修改的结果。
To avoid problems and performance issues, the automatic reloading is limited to the Ypage source file (and templates, if any) and the snakelet module file. Imported modules are not reloaded.
为了避免错误，自动重载功能只对 Ypage 源代码文件和 snakelet module文件有效，被import 的 module文件不会被重新载入。
Page Creation Tutorial
Please refer to Effective Ypages and Snakelets for a tutorial on creating good, maintainable web pages.
Snakelets manual - Back to index |
|
免费注册
发表于 2005-06-16 17:50
.
, and optionally set the input encoding too (if your source file is written in a special character encoding), and Snakelets takes care of all the rest. Don't encode stuff yourself, just write those unicode strings to the page output! If you are careful about the way you add FORMs to your pages (see below), the input of special characters is painless too. Snakelets handles everything and you get to deal with Python strings (or unicode objects) only. All symbols are supported. The suggested character encoding is UTF-8 (it can contain all symbols, is widely supported, and works efficiently for most western languages). You can define a character encoding in every page or define one global setting for all pages using the webapp's defaultOutputEncoding config variable.
OST"