template
timezone(时区支持)

upload(文件上传及显示处理)

使用werkzeug进行处理

在Uliweb中对上传有一定的封装处理，下面先介绍一下，不使用Uliweb提供的功能，如何 使用底层的werkzeug来处理文件上传。

当用户在前端通过 <input type="file"> 来上传一个文件时，在request对象中的request.files中可以得到相应的上传文件。其中是一个类dict的对象，存放多个文件对象属性，例如， <input type="file" name="docfile"> 定义了一个docfile字段，当上传后，可以通过:

filename = request.files['docfile'].filename
file_obj = request.files['docfile'].stream

来分别处理上传的文件名和文件对象。后续你要保存到哪个目录，同时考虑到中文的问题， 你可能需要将上传的unicode文件名转为与操作系统对应的本身编码。因此，为了解决这些 问题，Uliweb提供了upload app来处理上传文件。同时upload app还提供上传后文件的访 问处理，包括X-Sendfile的支持。

upload 的安装与配置

在apps/settings.ini中的INSTALLED_APPS中添加:

'uliweb.contrib.upload'

upload缺省提供以下配置:

[UPLOAD]
TO_PATH = './uploads'
BUFFER_SIZE = 4096
FILENAME_CONVERTER =
BACKEND =

#X-Sendfile type: nginx, apache
X_SENDFILE = None

#if not set, then will be set a default value that according to X_SENDFILE
#nginx will be 'X-Accel-Redirect'
#apache will be 'X-Sendfile'
X_HEADER_NAME = ''
X_FILE_PREFIX = '/files'

[EXPOSES]
file_serving = '/uploads/<path:filename>', 'uliweb.contrib.upload.file_serving'

其中：

TO_PATH

为文件要保存的目录。缺省为当前路径下的uploads子目录。一般，当前路径就是你的项目目录。

BUFFER_SIZE

保存文件时的块大小。

FILENAME_CONVERTER

文件名转換类，它用来处理当文件上传后，在保存文件时使用的文件名。没有给出此配置时缺省是使用UUID来生成文件名，以保证文件名不重复。同时upload还定义了其它的几种转換类，可以根据需要来使用。更详细的说明参见下面具体的说明。

BACKEND

upload中文件上传和下载的类定义。如果没有给出，则缺省使用 FileServing 类来处理。

目前upload还支持X-Sendfile的处理方式，这是目前apache, nginx中都有的一种方法，不过细节上有所差异。关于X-Sendfile这里有一篇 文章 可以参考。简单地说就是在下载文件时可以对下载的过程进行控制，详情可参加下面的Nginx配置示例。

X_SENDFILE

X-Sendfile处理类型，目前只支持Nginx和Apache。根据需要可以输入'nginx'或'apache'。缺省为None，则表示不启动，则文件读取及下载是由Uliweb本身提供的。

X_HEADER_NAME

当X_SENDFILE生效时，此选项用于指明将返回web server的头。目前已经知道Nginx和Apache要使用的头标识，其它的web server可以在这里指定。当保持为空时，则根据X_SENDFILE的值自动使用相应的头标识，对于Nginx则为 X-Accel-Redirect ，对于Apache则为 X-Sendfile。

X_FILE_PREFIX

传给web server的头中新的URL的前缀。因为这个URL与原始的URL将不一样，所以利用这个前缀可以方便生成新的URL。这个前缀需要与web server中的内部URL相对应。不过对于Nginx和Apache的处理机制不完全相同，对于Nginx的方式，是通过返回一个新的URL，而对于Apache来说，则需要返回一个文件路径，不是一个URL。所以这个项的设置要根据所使用的web server而有所不同。对于Apache则可以认为是目录的前缀。对于Nginx则可以认为是新的URL的前缀。

EXPOSES/file_serving

用于定义一个缺省的View函数，以处理上传后的文件的下载。

其实这个配置中，真正与上传有关的就是前两项。后几项都是和下载有关的。在upload中，不仅处理了上传还为了方便处理了下载。只不过，它与静态文件的下载不同，它的下载是可以在非static目录下，并且可以有view的控制参与的。而静态文件是不需要进行控制处理的。

文件上传的处理

其实在Uliweb有不同级别的文件上传处理，比如最原始的就是手工处理、然后就是利用upload来处理、再有就是通过generic.py来处理。在处理时，有使用Form来处理的，也可以不使用Form来处理，而是使用request，它们之间有一些差异。generic.py会专门在generic.py的文档进行讲解，这里将根据几种情景进行说明。

上传Form的定义

其实使用手工HTML或利用Uliweb提供的Form类来生成Form代码都没有太大关系，基本上是一样的。 简单的话，就是使用Form类了，例如:

from uliweb.form import *

class F(Form):
    file = FileField(label='file')

@expose('/show_upload')
def show_upload():
    form = F(action='/upload')
    return {'form':form}

上面定义了一个Form类，然后我们在show_upload()中将返回一个dict，用于模板的渲染。这个view方法只处理了显示，上传还没有处理。在F创建时，我们传入action的值用于指定上传文件后的处理URL。

不使用upload app进行上传处理

当用户选择了文件，并提交上传后，信息将提交到/upload来。则对应的处理代码示例为:

import os

@expose('/upload')
def upload():

    form = F(action='/upload')
    if form.validate(request.params, request.files):
        filename = request.files['file'].filename
        target = os.path.join('./uploads', filename)
        with open(target, 'wb') as f:
            f.write(request.files['file'].stream.read())
        return redirect('/ok')
    else:
        #指定将要使用的模板文件名
        response.template = 'show_upload.html'
        #如果校验失败，则再次返回Form，将带有错误信息
        return {'form':form}

先生成保存目标的文件名，然后手工将上传的内容进行保存。不过，这里如果文件名有中文有可能会报错。request中得到的文件名是unicode，你需要将其转为与操作系统相匹配的编码。在Uliweb的全局配置项中提供了一个:

[GLOBAL]
FILESYSTEM_ENCODING = None

你可以考虑先对其进行配置，然后使用它来处理文件的编码。因此，你需要做的处理主要就是:

  1. 生成目标文件名（可能要处理文件名编码的问题）
  2. 保存文件

下面再看一看使用upload app的做法

使用upload app进行上传处理

首先安装upload app。

然后设置配置项，比如TO_PATH的值，缺省是./uploads。

将上面的代码修改一下:

import os

@expose('/upload')
def upload():
    from uliweb import functions

    form = F(action='/upload')
    if form.validate(request.params, request.files):
        functions.save_file(form.file.data.filename, form.file.data.file)
        return redirect('/ok')
    else:
        #指定将要使用的模板文件名
        response.template = 'show_upload.html'
        #如果校验失败，则再次返回Form，将带有错误信息
        return {'form':form}

这里使用了upload中提供的save_file函数，它的原型为:

save_file(filename, fobj, replace=False, convert=True)

这里只提供了两个参数，一个是文件名，一个是文件对象。第三个没有提供，因此如果存在 同名的文件，将不会覆盖，而是自动添加象(1), (2)这样的内容。在save_file中会自动根 据相关的配置项：文件系统编码、保存目录信息来自动生成目标文件名并转換成合适的编码， 然后保存。第4个参数用来控制是否自动进行文件名转換，缺省会转換。其目的是为了让文件 名不重复，没有乱码。

这里save_file是通过functions对象来引用的。在upload中还定义了其它类似的通用方法， 后面我们会看到。

为了方便处理Form字段，upload app还提供了save_file_field函数，具体使用参见下面的 函数说明。

放在一起的处理方式

我们可以考虑把显示和上传后的处理放在一起，也可以象这个例子一样，分开不同的URL。如果放在一起，逻辑可以是:

def upload():
    from uliweb import functions

    form = F()
    #GET是显示用，POST是提交用
    if request.method == 'GET':
        return {'form':form}
    else:
        #如果提交，则先进行校验，这里是使用Form的方式
        #form有一个validate方法，可以传入多个值，这里将request.files传入
        #以便形成完整的数据集，如果validate返回True，表示校验成功，并且
        #上传的数据将按照Form字段定义的类型已经做了转換
        if form.validate(request.params, request.files):
            functions.save_file(form.file.data.filename, form.file.data.file)
            return redirect('/ok')
        else:
            #如果校验失败，则再次返回Form，将带有错误信息
            return {'form':form}

FileServing 类

upload 把文件和下载的管理组织成了类的形式。这个类就是FileServing，你可以根据需要 从这个类进行派生。在缺省情况下，upload app会自动创建一个default_fileserving，而 前面所看到的UPLOAD的配置项就是这个缺省的文件服务类。同时，基于这个缺省的实例，提 供了下面的一些方法。在简单的情况下，你可以只使用缺省的文件服务对象就够了。

FileServing的说明:

class FileServing(object):
    default_config = 'UPLOAD'
    options = {
        'x_sendfile' : ('X_SENDFILE', None),
        'x_header_name': ('X_HEADER_NAME', ''),
        'x_file_prefix': ('X_FILE_PREFIX', '/files'),
        'to_path': ('TO_PATH', './uploads'),
        'buffer_size': ('BUFFER_SIZE', 4096),
        '_filename_converter': ('FILENAME_CONVERTER', None),
    }

    #每个FileServing类有相应的settings配置项。因此FileServing的所有方法
    #都是根据这些配置项计算来的
    #options中的每个值后面都可以使用 obj.xxx 来访问
    #
    #default_config表示会从哪里读配置信息。它会和下面的配置项合成，如，可以
    #和TO_PATH合成为 UPLOAD/TO_PATH 。如果配置项中间有 '/' ，则认为不要进行合成。

    def __init__(self, default_filename_converter_cls=UUIDFilenameConverter, config=None):
        """
        初始化函数。第一个参数表示文件名转換类，缺省使用UUID方式生成文件名
        第二个参数表示读取配置项的名字，与Settings.ini中的section对应
        """
        
    def filename_convert(self, filename):
        """
        对文件名进行转換
        """

    def get_filename(self, filename, filesystem=False, convert=False)
        """
        用于获得一个文件的实际路径。它是根据to_path计算得到的。如果
        filesystem为True，则会将生成的文件名按settings中配置的文件
        系统编码来进行转換。convert参数用于处理是否要进行文件名的转換。
        因此根据参数的不同，它有几种用法:

        1. 根据传入的filename得到对应的实际路径，但文件名不转換为文件系统
           的编码:

           get_filename(filename)

        2. 根据传入的filename得到对应的实际路径，但是文件名转換为文件系统
           的编码:

           get_filename(filename, filestystem=True)

        3. 得到filiename的实际路径，同时进行文件名转換，这样得到的文件名将
           不是原来的文件名:

           get_filename(filename, convert=True)

        前两种主要是用在上传文件后的显示上，这时一般使用的是转換后的文件名。
        第三种是用在上传后保存文件时，先对文件名进行转換。
        """

    def download(self, filename, action='download', x_filename='', real_filename='')
        """
        提供下载处理，支持X-Sendfile的处理。action取值为'download'或
        'inline'，它们分别对应不同的应答头:

        download
            Content-Disposition:attachment; filename=<filename>
        inline
            Content-Disposition:inline; filename=<filename>

        如果action为None，则不显示上面的头信息。

        在这里，我们看到有三个文件名，都有什么用？

        filename一般是从数据库中取出来的文件名，比如我们将文件名保存到
        FileProperty中，当取出来时是Unicode格式的，并且是相对于上传路径
        的相对路径，所以我们要进行转換。

        如果不考虑X-Sendfile的情况，一般我们只提供filename就足够了，因
        为可以自动根据to_path来计算出实际文件路径。不过当文件名并不存在
        于to_path所指定的目录下时，我们还可以提供real_filename参数来指
        明文件实际的路径。

        对于使用了X-Sendfile的情况，又复杂了一些。我们可能还需要指出
        x_filename参数，比如在nginx下，它用来指明X-Accel-Redirect中的
        文件名，而这个文件路径是一个URL，提供Nginx可以找到真正的文件。
        所以x_sendfile其实是一个中间路径。

        所以x_sendfile和real_filename其实不会同时使用。在更底层的filedown
        函数中会进行确实的处理。对于用户来说，如果想实现根据配置不同，
        使用不同的下载方式，则么这些参数最好都提供。
        """

    def save_file(self, filename, fobj, replace=False, convert=True)
        """
        将文件保存在to_path路径下。

        使用convert可以设置要不要转換文件名。
        """

    def save_file_field(self, field, replace=False, filename=None, convert=True)
        """
        根据文件字段来保存。路径处理同save_file
        """

    def save_image_field(self, field, resize_to=None, replace=False, filename=None, convert=True)
        """
        根据图片字段来保存。路径处理同save_file
        """

    def delete_filename(self, filename)
        """
        删除保存在to_path下的文件。
        """

    def get_href(self, filename)
        """
        获取filename对应的URL地址，不是真正的URL信息
        """

    def get_url(self, filename, query_para=None, **url_args)
        """
        获取filename对应的URL。注意，这是一个真正的URL，如果只是想得到URL的
        地址，要使用get_href(filename)

        如果url_args中传入了 title 和 text，则生成的URL形式为

        <a href='xxx' title='title'>text</a>

        如果没有传入，则使用filename代替title和text。

        如果传入了query_para，则它的值将写在href对应的链接后面。query_para
        是一个dict值，如： ``query_para={'alt':'filename.txt'}``

        那么生成的URL可能为:

        <a href='xxx?alt=filename.txt' title='title'>text</a>

        它有什么用，在后面的download你会看到
        """

自定义FileServing类

如果需要自定义FileServing类，可以从这个类派生。如果没有新増的配置项，只要定义 default_config 即可。它表示一个完整的section，用来定义options中所有的值。因此 我们需要在settings.ini中定义完整的配置信息，可以直接拷贝UPLOAD的定义。如果有些值 想采用UPLOAD的值，并且希望和UPLOAD值一起变化，那么可以在定义值的时候引用UPLOAD的值，如：

[UPLOAD_TEST]
TO_PATH = UPLOAD.TO_PATH
BUFFER_SIZE = UPLOAD.BUFFER_SIZE
FILENAME_CONVERTER =
BACKEND =
X_SENDFILE = None
X_HEADER_NAME = ''
X_FILE_PREFIX = '/files'

上面前两项使用了UPLOAD中的定义值。

简单示例:

class FileServingTest(FileServing):
    default_config = 'UPLOAD_TEST'

如何获取FileServing对象

想要获得FileServing实例，可以先导入这个类，然后创建它的实例。创建时可以传入对应的 配置section的名字，以获得完整的配置，否则使用类中定义的配置。

另一种方法是使用 get_fileserving(config) 函数。它会使用FileServing作为BACKEND类，但 是配置项使用你指定的section的名字。这样不会创建新的类，但是实例的参数是可以不同。

upload app提供方法说明

以下方法都是基于缺省的default_fileserving对象来处理的。

get_fileserving(config)

获得缺省的文件上传下载对象。缺省使用UPLOAD的配置。如果传入其它的配置名，将 使用这个配置来创建FileServing对象。

file_serving(filename)

缺省的文件下载函数。它是通过在 settings.ini 中配置了:

[EXPOSES]
file_serving = '/uploads/<path:filename>', 'uliweb.contrib.upload.file_serving'

这样所有以 /uploads 开头的 URL都会被 file_serving 处理，从而提供服务。

在这里还有特殊的扩展处理。在缺省情况下，上传后的文件为了保证唯一性会自动 对文件名进行转換，具体用什么要看使用哪个文件名生成器处理的。详见下面 FilenameConverter 的有关说明。因此，当下载文件名还是使用转換后的文件 名会非常不方便。所以这里有一个扩展，就是在传入的URL上添加一个特殊的 query_string，如:

xxxxxxxxx.txt?alt=中文.txt

这样alt对应的就是想另存为的文件名。这样只要 <a> 标签加上 alt 信息就可以 以想要的文件名来保存。

get_filename(filename, filesystem=False, convert=False)

用于获得目标文件，即将TO_PATH与filename进行连接。同时，如果给出filesystem为 True，则将文件名转为文件系统的编码。否则返回的将是unicode。 convert=False 表示不对文件名进行转換

save_file(filename, fobj, replace=False, convert=True)

用于保存一个文件。需要传入文件名和文件对象，这些都可以从request或form字段中 获得。如果replace设置为True，则表示当存在同名文件时自动覆盖，否则将自动添加 (1), (2)等内容，以保证文件不重名。save_file会把文件保存到指定的目录下，并根 据配置项进行相应的文件名编码的转換。

save_file_field(field, replace=False, filename=None, convert=True)

用于处理Form中的FileField字段。将自动从FileField中获得对应的文件名和文件对象。 也可以将文件保存为filename参数指定的文件名。

save_image_field(field, resize_to=None, replace=False, filename=None, convert=True)

和save_file_field类似，是用来处理ImageField(图像字段)的。不过，如果你设置了 resize_to参数的话，它还可以自动对图像进行缩放处理。

delete_filename(filename)

删除上传目录下的某个文件。

get_url(filename, query_para=None, **url_args)

获得上传目录下某个文件的URL，以便可以让浏览器进行访问。 query_para 将传入到href属性后面成为query_string.

get_href(filename, **kwargs)

获取filename对应的URL地址，不是真正的URL信息

如果上面的文件名使用的是相对路径，则会根据当前的FileServing对象来决定使用 什么配置信息，比如文件保存的路径。但是如果使用绝对路径，则将使用绝对路径进 行处理。

FilenameConverter类的说明

upload提供了几个用于文件名上传后转换的类，并且可以在settings.ini进行配置，分别说明如下:

  1. FilenameConverter:

    class FilenameConverter(object):
    @staticmethod
    def convert(filename):
        return filename

最基本的类，对文件名不作任何转換

  1. UUIDFilenameConverter 使用UUID方法生成文件名。文件名将保证唯一。

  2. MD5FilenameConverter 使用MD5算法生成文件名。具体算法:

    f = md5(
            md5("%f%s%f%s" % (time.time(), id({}), random.random(),
                              getpid())).hexdigest(),
        ).hexdigest()

BACKEND配置说明

upload在启动时会缺省按照 UPLOAD/BACKEND 的定义来生成缺省的fileserving类。如果 没给出，则使用FileServing。通过修改 BACKEND ，用户就可以定义自已缺省的文件上传处理类。

X-Sendfile Nginx配置说明

简单的处理流程可以表示为:

image

以上的处理可以理解为：

  1. 用户请求的url在后台经过处理后，由后台处理添加一个内部的头信息，头信息带有一个新的URL，并且返回内容为空，因此真正的内容将由Nginx完成，所以只要添加相应的头信息即可。同时你也可能会返回其它的头信息，如: 'Content-Disposition', 'Content-Type' 等。
  2. Nginx在发现 'X-Accel-Redirect' 头之后会自动删除，并且根据URL的信息去对应的目录下查找相应的文件，然后返回。
  3. 因此用户看到的文件路径有可能和真正存放文件的路径不同。并且，允许后台处理根据需要来决定返回 'X-Accel-Redirect' 还是其它的信息，从而可以控制是否真正进行文件下载。一方面可以进行下载控制，另一方面可以对后台文件进行保护。

Nginx的配置如下:

location /files {
    internal;
    alias /path/to/files;
}

在Nginx的conf文件中添加上面的内容，需要根据需要进行修改。其中:

/files

为你将在后台处理中要重新生成的URL的前缀。

internal

表示内部使用，用户将无法直接通过URL来访问这个路径。

alias

指明/files后对应的文件信息存放的路径。这里还可以考虑使用root，它们的区别就是:

例如URL为 /files/filename，如果配置为 alias /download，则将要读取的文件应该是 /download/filename，而如果配置为 root /download，则将要读取的文件将是 /download/files/filename

启用Nginx进行文件下载处理的配置项应设置为:

[UPLOAD]
X_SENDFILE = 'nginx'

functions定义说明

为了方便使用，在settings.ini中的FUNCTIONS中定义了一些全局函数，可以方便使用：

  • get_filename
  • save_file
  • save_file_field
  • save_image_field
  • delete_filename
  • get_url
  • get_href
  • download
  • filename_convert
  • get_fileserving
template
timezone(时区支持)