安装 ReportLab

在生� PDF 文件之�，需�安装 ReportLab 库。这通常是个很简�的过程：从 http://www.reportlab.org/downloads.html 下载并且安装这个库��。

使用手册（原始的�有 PDF 格�）�以从 http://www.reportlab.org/rsrc/userguide.pdf 下载，其中包�有一些其它的安装指�。

注�

如果使用的是一些新的 Linux �行版，则在安装��以先检查包管�软件。多数软件包仓库中都加入了 ReportLab 。

比如，如果使用（�出的） Ubuntu �行版，�需�简�的 apt-get install python-reportlab 一行命令��完�安装。

在 Python 交互环境中导入这个软件包以检查安装是��功。

>>> import reportlab

如果刚�那�命令没有出现任何错误，则表明安装�功。

编写视图

和 CSV 类似，由 Django 动�生� PDF 文件很简�，因为 ReportLab API �样�以使用类似文件对象。

下�是一个 Hello World 的示例：

from reportlab.pdfgen import canvas
from django.http import HttpResponse

def hello_pdf(request):
    # Create the HttpResponse object with the appropriate PDF headers.
    response = HttpResponse(mimetype='application/pdf')
    response['Content-Disposition'] = 'attachment; filename=hello.pdf'

    # Create the PDF object, using the response object as its "file."
    p = canvas.Canvas(response)

    # Draw things on the PDF. Here's where the PDF generation happens.
    # See the ReportLab documentation for the full list of functionality.
    p.drawString(100, 100, "Hello world.")

    # Close the PDF object cleanly, and we're done.
    p.showPage()
    p.save()
    return response

需�注�以下几点：

• 这里我们使用的 MIME 类型是 application/pdf 。这会告诉æµ�览器这个文档是一个 PDF 文档，而ä¸�是 HTML 文档。如果忽略了这个å�‚数，æµ�览器å�¯èƒ½ä¼šæŠŠè¿™ä¸ªæ–‡ä»¶çœ‹æˆ� HTML 文档，这会使æµ�览器的窗å�£ä¸­å‡ºçŽ°å¾ˆå¥‡æ€ªçš„文字。

• 使用 ReportLab çš„ API 很简å�•ï¼šå�ªéœ€è¦�å°† response 对象作为 canvas.Canvas 的第一个å�‚数传入。 Canvas 类需è¦�一个类似文件的对象， HttpResponse 对象å�¯ä»¥æ»¡è¶³è¿™ä¸ªè¦�求。

• 所有å�Žç»­çš„ PDF 生æˆ�方法需è¦�ç”± PDF 对象调用（在本例中是 p ），而ä¸�是 response 对象。

• 最å�Žéœ€è¦�对 PDF 文件调用 showPage() å’Œ save() 方法（å�¦åˆ™ä½ ä¼šå¾—到一个æ�Ÿå��çš„ PDF 文件）。

��的 PDF 文件

如果您在创建一个��的 PDF 文档（或者任何较大的数��），请使用 cStringIO 库存放临时生�的 PDF 文件。 cStringIO �供了一个用 C 编写的类似文件对象的接�，从而�以使系统的效率最高。

下�是使用 cStringIO �写的 Hello World 例�：

from cStringIO import StringIO
from reportlab.pdfgen import canvas
from django.http import HttpResponse

def hello_pdf(request):
    # Create the HttpResponse object with the appropriate PDF headers.
    response = HttpResponse(mimetype='application/pdf')
    response['Content-Disposition'] = 'attachment; filename=hello.pdf'

    temp = StringIO()

    # Create the PDF object, using the StringIO object as its "file."
    p = canvas.Canvas(temp)

    # Draw things on the PDF. Here's where the PDF generation happens.
    # See the ReportLab documentation for the full list of functionality.
    p.drawString(100, 100, "Hello world.")

    # Close the PDF object cleanly.
    p.showPage()
    p.save()

    # Get the value of the StringIO buffer and write it to the response.
    response.write(temp.getvalue())
    return response

�始化

为了在您的Django站点中激活syndication feeds, 添加如下的 URLconf:

(r'^feeds/(?P<url>.*)/$',
 'django.contrib.syndication.views.feed',
 {'feed_dict': feeds}
),

这一行告诉Django使用RSS框架处�所有的以 "feeds/" 开头的URL. ( 你�以修改 "feeds/" �缀以满足您自己的�求. )

URLConf里有一行å�‚数：``{‘feed_dict’: feeds}``，这个å�‚æ•°å�¯ä»¥æŠŠå¯¹åº”URL需è¦�å�‘布的feed内容传递给 syndication framework

特别的，feed_dict应该是一个映射feed的slug(简短URL标签)到它的Feed类的字典 你�以在URL�置本身里定义feed_dict，这里是一个完整的例�

from django.conf.urls.defaults import *
from myproject.feeds import LatestEntries, LatestEntriesByCategory

feeds = {
    'latest': LatestEntries,
    'categories': LatestEntriesByCategory,
}

urlpatterns = patterns('',
    # ...
    (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
        {'feed_dict': feeds}),
    # ...
)

��的例�注册了两个feed:

• LatestEntries``表示的内容将对应到``feeds/latest/ .

• LatestEntriesByCategory``的内容将对应到 ``feeds/categories/ .

以上的设定完�之�，接下�需�自己定义 Feed 类

一个 Feed 类是一个简�的python类，用�表示一个syndication feed. 一个feed�能是简�的 (例如一个站点新闻feed，或者最基本的，显示一个blog的最新�目)，也�能更加��(例如一个显示blog�一类别下所有�目的feed。这里类别 category 是个��).

Feed类必须继承django.contrib.syndication.feeds.Feed，它们�以在你的代�树的任何�置

一个简�的Feed

例��自于chicagocrime.org，�述最近5项新闻�目的feed:

from django.contrib.syndication.feeds import Feed
from chicagocrime.models import NewsItem

class LatestEntries(Feed):
    title = "Chicagocrime.org site news"
    link = "/sitenews/"
    description = "Updates on changes and additions to chicagocrime.org."

    def items(self):
        return NewsItem.objects.order_by('-pub_date')[:5]

�注�的��的事情如下所示:

�类 django.contrib.syndication.feeds.Feed .

title , link , 和 description 对应一个标准 RSS 里的 <title> , <link> , 和 <description> 标签.

items() 是一个方法，返回一个用以包�在包�在feed的 <item> 元素里的 list 虽然例�里用Djangos database API返回的 NewsItem 对象, items() �一定必须返回 model的实例

你�以利用 Django models�费实现一定功能，但是 items() �以返回你想�的任�类型的对象.

还有一个步骤，在一个RSS feed里，�个(item)有一个(title)，(link)和(description)，我们需�告诉框架 把数�放到这些元素中

如果�指定 <title> 和 <description> ，�以建立一个Django模�（�Chapter 4）�字� feeds/latest_title.html 和 feeds/latest_description.html ，�者是URLConf里为对应feed指定的 slug 。注� .html �缀是必须的。

RSS系统模�渲染�一个�目，需�给传递2个�数给模�上下文��：

• obj : 当å‰�对象 ( 返回到 items() ä»»æ„�对象之一 )。

• site : 一个表示当å‰�站点的 django.models.core.sites.Site 对象。 这对于 {{ site.domain }} 或者 {{ site.name }} 很有用。

如果你在创建模�的时候，没有指明标题或者�述信�，框架会默认使用 "{{ obj }}" ，对象的字符串表示。

你也�以通过修改 Feed 类中的两个属性 title_template 和 description_template �改�这两个模�的�字。

你有两�方法�指定 <link> 的内容。 Django 首先执行 items() 中�一项的 get_absolute_url() 方法。 如果该方法�存在，就会�试执行 Feed 类中的 item_link() 方法，并将自身作为 item �数传递进去。

get_absolute_url() 和 item_link() 都应该以Python字符串形�返回URL。

对于���到的 LatestEntries 例�，我们�以实现一个简�的feed模�。 latest_title.html 包括：

{{ obj.title }}

并且 latest_description.html 包�:

{{ obj.description }}

这真是 太 简�了�

一个更��的Feed

框架通过�数支�更加��的feeds。

举个例�，chicagocrime.org�供了一个RSS�以跟踪�一片区域的犯罪近况。如果为�一个�独的区域建立一个 Feed 类就显得很�明智。这样�就��了DRY原则了，程�逻辑也会和数�耦�在一起。

�而代之的方法是，使用��框架�产生一个通用的�，使其�以根�feeds URL返回相应的信�。

在chicagocrime这个例�中，区域信��以通过这样的URL方��访问:

• http://www.chicagocrime.org/rss/beats/0613/ ：返回0613å�·åœ°åŒºçš„犯罪数æ�®

• http://www.chicagocrime.org/rss/beats/1424/ ：返回1424å�·åœ°åŒºçš„犯罪数æ�®

固定的那一部分是 "beats" （区域）。��框架看到了��的��之处 0613 和 1424 ，它会�供给你一个钩�函数��述这些URL的�义，以�会对feed中的项产生的影�。

举个例�会澄清一切。下�是�个地区特定的feeds：

from django.core.exceptions import ObjectDoesNotExist

class BeatFeed(Feed):
    def get_object(self, bits):
        # In case of "/rss/beats/0613/foo/bar/baz/", or other such
        # clutter, check that bits has only one member.
        if len(bits) != 1:
            raise ObjectDoesNotExist
        return Beat.objects.get(beat__exact=bits[0])

    def title(self, obj):
        return "Chicagocrime.org: Crimes for beat %s" % obj.beat

    def link(self, obj):
        return obj.get_absolute_url()

    def description(self, obj):
        return "Crimes recently reported in police beat %s" % obj.beat

    def items(self, obj):
        crimes =  Crime.objects.filter(beat__id__exact=obj.id)
        return crimes.order_by('-crime_date')[:30]

以下是RSS框架的基本算法，我们�设通过URL /rss/beats/0613/ �访问这个类：

框架获得了URL /rss/beats/0613/ 并且注�到URL中的slug部分���有更多的信�。它将斜�("/" )作为分隔符，把剩余的字符串分割开作为�数，调用 Feed 类的 get_object() 方法。

在这个例�中，添加的信�是 ['0613'] 。对于 /rss/beats/0613/foo/bar/ 的一个URL请求， 这些信�就是 ['0613', 'foo', 'bar'] 。

get_object() 就根�给定的 bits 值�返回区域信�。

在这个例�中，它使用了Django的数�库API�获�信�。注�到如果给定的�数��法， get_object() 会抛出 django.core.exceptions.ObjectDoesNotExist 异常。在 Beat.objects.get() 调用中也没有出现 try /except 代��。函数在出错时抛出 Beat.DoesNotExist 异常，而 Beat.DoesNotExist 是 ObjectDoesNotExist 异常的一个�类型。 而在 get_object()

中抛出 ObjectDoesNotExist 异常�会使得Django引�404错误。

为产生 <title> ， <link> ， 和 <description> 的feeds， Django使用 title() , link() , 和 description() 方法。 在上�的例�中，它们都是简�的字符串类型的类属性，而这个例�表明，它们既�以是字符串， 也�以是 方法。对于�一个 title ， link 和 description 的组�，Django使用以下的算法：

1. 试图调用一个函数，并且以 get_object() 返回的对象作为�数传递给 obj �数。

2. 如果没有�功，则�带�数调用一个方法。

3. 还��功，则使用类属性。

最�，值得注�的是，这个例�中的 items() 使用 obj �数。对于 items 的算法就如�上�第一步所�述的那样，首先�试 items(obj) ， 然�是 items() ，最�是 items 类属性（必须是一个列表）。

Feed 类所有方法和属性的完整文档，请�考官方的Django文档 (http://www.djangoproject.com/documentation/0.96/syndication_feeds/) 。

指定Feed的类型

默认情况下, ��框架生�RSS 2.0. �改�这样的情况, 在 Feed 类中添加一个 feed_type 属性.

from django.utils.feedgenerator import Atom1Feed

class MyFeed(Feed):
    feed_type = Atom1Feed

注�你把 feed_type 赋值�一个类对象，而�是类实例。目��法的Feed类型如表11-1所示。

闭包

为了指定闭包（例如，与feed项比方说MP3 feeds相关�的媒体资�信�），使用 item_enclosure_url ， item_enclosure_length ， 以� item_enclosure_mime_type ，比如

from myproject.models import Song

class MyFeedWithEnclosures(Feed):
    title = "Example feed with enclosures"
    link = "/feeds/example-with-enclosures/"

    def items(self):
        return Song.objects.all()[:30]

    def item_enclosure_url(self, item):
        return item.song_url

    def item_enclosure_length(self, item):
        return item.song_length

    item_enclosure_mime_type = "audio/mpeg"

当然，你首先�创建一个包�有 song_url 和 song_length （比如按照字节计算的长度）域的 Song 对象。

语言

��框架自动创建的Feed包�适当的 <language> 标签(RSS 2.0) 或 xml:lang 属性(Atom). 他直接�自于您的 LANGUAGE_CODE 设置.

URLs

link 方法/属性�以以�对URL的形�（例如， "/blog/" ）或者指定�议和域�的URL的形�返回（例如 "http://www.example.com/blog/" ）。如果 link 没有返回域�，��框架会根� SITE_ID 设置，自动的�入当�站点的域信�。

Atom feeds需� <link rel="self"> 指明feeds现在的�置。��框架根� SITE_ID 的设置，使用站点的域�自动完�这些功能。

�时�布Atom and RSS

一些开�人员想 �时 支�Atom和RSS。这在Django中很容易实现：�需创建一个你的 feed 类的�类，然�修改 feed_type ，并且更新URLconf内容。下�是一个完整的例�：

from django.contrib.syndication.feeds import Feed
from chicagocrime.models import NewsItem
from django.utils.feedgenerator import Atom1Feed

class RssSiteNewsFeed(Feed):
    title = "Chicagocrime.org site news"
    link = "/sitenews/"
    description = "Updates on changes and additions to chicagocrime.org."

    def items(self):
        return NewsItem.objects.order_by('-pub_date')[:5]

class AtomSiteNewsFeed(RssSiteNewsFeed):
    feed_type = Atom1Feed

这是与之相对应那个的URLconf：

from django.conf.urls.defaults import *
from myproject.feeds import RssSiteNewsFeed, AtomSiteNewsFeed

feeds = {
    'rss': RssSiteNewsFeed,
    'atom': AtomSiteNewsFeed,
}

urlpatterns = patterns('',
    # ...
    (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
        {'feed_dict': feeds}),
    # ...
)

安装

�安装 sitemap 应用程�, 按下�的步骤进行:

1. 将 'django.contrib.sitemaps' 添加到您的 INSTALLED_APPS 设置中.

2. 确� 'django.template.loaders.app_directories.load_template_source' 在您的 TEMPLATE_LOADERS 设置中。默认情况下它在那里, 所以, 如果你已�改�了那个设置的�, �需�改回���。

3. 确定您已�安装了 sites 框架 (��第14章).

备注

sitemap 应用程�没有安装任何数�库表. 它需�加入到 INSTALLED_APPS 中的唯一原因是: 这样 load_template_source 模�加载器�以找到默认的模�.

�始化

�在您的Django站点中激活sitemap生�, 请在您的 URLconf 中添加这一行:

(r'^sitemap.xml$', 'django.contrib.sitemaps.views.sitemap', {'sitemaps': sitemaps})

这一行告诉 Django, 当客户访问 /sitemap.xml 的时候, 构建一个 sitemap.

sitemap文件的�字无关紧�，但是它在�务器上的�置�很��。�索引擎�索引你的sitemap中当�URL级别�其以下级别的链接。用一个实例�说，如果 sitemap.xml �于你的根目录，那么它将引用任何的URL。然而，如果你的sitemap�于 /content/sitemap.xml ，那么它�引用以 /content/ 打头的URL。

sitemap视图需�一个�外的必须的�数： {'sitemaps': sitemaps} 。 sitemaps 应该是一个字典，它把一个短的�标签(例如, blog 或 news )映射到它的 Sitemap 类(例如， BlogSitemap 或 NewsSitemap )。它也�以映射到一个 Sitemap 类的实例(例如， BlogSitemap(some_var) )。

Sitemap ç±»

Sitemap 类展示了一个进入地图站点简�的Python类片断.例如,一个 Sitemap 类能展现所有日志入�，而�外一个能够调度所有的日历事件。

在最简�的例�中，所有部分�以全部包�在一个 sitemap.xml 中，也�以使用框架�产生一个站点地图，为�一个独立的部分产生一个�独的站点文件。

Sitemap 类必须是 django.contrib.sitemaps.Sitemap 的�类. 他们�以存在于您的代�树的任何地方。

例如�设你有一个blog系统，有一个 Entry 的model，并且你希望你的站点地图包�所有连到你的blog入�的超链接。你的 Sitemap 类很�能是这样的：

from django.contrib.sitemaps import Sitemap
from mysite.blog.models import Entry

class BlogSitemap(Sitemap):
    changefreq = "never"
    priority = 0.5

    def items(self):
        return Entry.objects.filter(is_draft=False)

    def lastmod(self, obj):
        return obj.pub_date

声明一个 Sitemap 和声明一个 Feed 看起�很类似；这都是预先设计好的。

如� Feed 类一样， Sitemap �员也既�以是方法，也�以是属性。想�知�更详细的内容，请��上文 《一个��的例�》章节。

一个 Sitemap 类�以定义如下 方法/属性:

items (必需 )：�供对象列表。框架并�关心对象的 类型 ；唯一关心的是这些对象会传递给 location() ， lastmod() ， changefreq() ，和 priority() 方法。

location （�选）：给定对象的�对URL。�对URL�包��议�称和域�。下�是一些例�：

• 好的: '/foo/bar/'

• 差的: 'example.com/foo/bar/'

• 差的: 'http://example.com/foo/bar/'

如果没有�供 location , 框架将会在�个 items() 返回的对象上调用 get_absolute_url() 方法.

lastmod (�选): 对象的最�修改日期, 作为一个Python datetime 对象.

changefreq （�选）：对象�更的频率。�选的值如下（详�Sitemaps文档）：

• 'always'

• 'hourly'

• 'daily'

• 'weekly'

• 'monthly'

• 'yearly'

• 'never'

priority （�选）：�值范围在 0.0 and 1.0 之间，用�表明优先级。默认值为 0.5 ；请详� http://sitemaps.org 文档。

快�方�

sitemap框架�供了一些常用的类。在下一部分中会看到。

from django.conf.urls.defaults import *
from django.contrib.sitemaps import FlatPageSitemap, GenericSitemap
from mysite.blog.models import Entry

info_dict = {
    'queryset': Entry.objects.all(),
    'date_field': 'pub_date',
}

sitemaps = {
    'flatpages': FlatPageSitemap,
    'blog': GenericSitemap(info_dict, priority=0.6),
}

urlpatterns = patterns('',
    # some generic view using info_dict
    # ...

    # the sitemap
    (r'^sitemap.xml$',
     'django.contrib.sitemaps.views.sitemap',
     {'sitemaps': sitemaps})
)

创建一个Sitemap索引

sitemap框架�样�以根� sitemaps 字典中定义的�独的sitemap文件�建立索引。用法区别如下：

• 您在您的URLconf 中使用了两个视图: django.contrib.sitemaps.views.index å’Œ django.contrib.sitemaps.views.sitemap .

• django.contrib.sitemaps.views.sitemap 视图需è¦�带一个 section 关键字å�‚æ•°.

这里是��的例�的相关的 URLconf 行看起�的样�:

(r'^sitemap.xml$',
 'django.contrib.sitemaps.views.index',
 {'sitemaps': sitemaps}),

(r'^sitemap-(?P<section>.+).xml$',
 'django.contrib.sitemaps.views.sitemap',
 {'sitemaps': sitemaps})

这将自动生�一个 sitemap.xml 文件, 它�时引用 sitemap-flatpages.xml 和 sitemap-blog.xml . Sitemap 类和 sitemaps 目录根本没有更改.

通知Google

当你的sitemap�化的时候，你会想通知Google，以便让它知�对你的站点进行�新索引。框架就�供了这样的一个函数： django.contrib.sitemaps.ping_google() 。

备注

在本书写�的时候, �有Google�以�应sitemap更新通知。然而，Yahoo和MSN�能很快也会支�这些通知。

到那个时候，把“ping_google()�这个�字改�“ping_search_engines()�会比较好。所以还是到http://www.djangoproject.com/documentation/0.96/sitemaps/ 去检查一下最新的站点地图文档。

ping_google() 有一个�选的�数 sitemap_url ，它应该是你的站点地图的URL�对地�（例如： /sitemap.xml ）。如果��供该�数， ping_google() 将�试通过�查你的URLconf�找到你的站点地图。

如果�能够确定你的sitemap URL, ping_google() 会引� django.contrib.sitemaps.SitemapNotFound 异常。

我们�以通过模型中的 save() 方法�调用 ping_google() ：

from django.contrib.sitemaps import ping_google

class Entry(models.Model):
    # ...
    def save(self):
        super(Entry, self).save()
        try:
            ping_google()
        except Exception:
            # Bare 'except' because we could get a variety
            # of HTTP-related exceptions.
            pass

一个更有效的解决方案是用 cron 脚本或任务调度表�调用 ping_google() ，该方法使用Http直接请求Google�务器，从而�少�次调用 save() 时�用的网络带宽。