lazr.restful 2.0.2

WSGI 示例网络服务

在 src/lazr/restful/example/wsgi/ 中的示例网络服务是理解 lazr.restful 的最佳起点。它是一个非常简单的网络服务，使用 lazr.restful 的子集功能，可以作为独立的 WSGI 应用程序运行。代码解释可以在 src/lazr/restful/example/wsgi/README.txt 中找到。

完整示例网络服务

要理解 lazr.restful 的全部内容，您应该查看 src/lazr/restful/example/base/ 中定义的网络服务。它定义了一个简单的应用程序，提供有关烹饪书和食谱的信息。接口（interfaces.py）使用 lazr.restful 装饰器进行注释，说明从 IRecipe、ICookbook 等对象中发布哪些字段和方法。这些接口的实现位于 root.py 中。

lazr.restful 的机制使用 interfaces.py 中的装饰器，生成一个接口，将传入的 HTTP 请求映射到 root.py 中定义的实际对象的操作。您不需要进行任何 HTTP 服务器编程即可使其工作（尽管目前您确实需要了解很多关于 Zope 的知识）。

您可以通过运行 bin/test 来测试示例网络服务。src/lazr/restful/example/base/tests 中的 doctests 使用模拟的 httplib2 连接来模拟对网络服务的 HTTP 请求。您可以看到测试如何向网络服务发出 GET、PUT、POST、PATCH 和 DELETE 请求。从 root.txt 开始。

其他代码

在您开始时，可能有其他两个代码片段值得关注。

• declarations.py 包含所有 Python 装饰器。docs/webservice-declarations.txt 展示了如何使用它们。

• docs/webservice.txt 展示了一个示例网络服务，它直接创建 Entry 和 Collection 类，而不是使用 declarations 生成。如果您想在不需要 zope.schema 的情况下使用 lazr.restful，请查看此测试。

2.0.2 (2023-10-17)

• 不要在 304 响应中发送多余的 HTTP 标头（错误 2039251）。

2.0.1 (2022-06-28)

• 删除 simplejson 依赖。

• 通过 lazr.restful.testing.webservice.pformat_value 修复 OrderedDict 对象列表的渲染错误。

2.0.0 (2022-06-01)

• 停止支持 Python 2。

• 添加对 Python 3.9 和 3.10 的支持。

• 添加基本的 pre-commit 配置。

• 在 Read the Docs 上发布文档。

• 通过 woke pre-commit 钩子应用包容性命名。以下 API 变更已执行：lazr.restful.metazcml.webservice_sanity_checks => lazr.restful.metazcml.webservice_coherence_checks、lazr.restful.testing.webservice.DummyURL => lazr.restful.testing.webservice.StubAbsoluteURL、lazr.restful.testing.webservice.DummyAbsoluteURL => lazr.restful.testing.webservice.StubAbsoluteURL、lazr.restful.testing.webservice.DummyRootResourceURL => lazr.restful.testing.webservice.StubRootResourceURL

• 通过 pre-commit 应用 black 代码格式化器。

• 删除 export_as_webservice_entry 和 export_as_webservice_collection；这些在 0.22.0 版本中已弃用，且在 Python 3 中无法工作。请改用类装饰器 @exported_as_webservice_entry 和 @exported_as_webservice_collection。

• 弃用 lazr.restful.utils.safe_hasattr，因为 Python 的内置 hasattr 自 Python 3.2 以来已修复。

• 集合序列化器（列表、集合、元组）现在将正确地将 None 反序列化为 None。

1.1.0 (2021-10-07)

• 向 lazr.restful.declarations 中添加一个新的 @scoped 装饰器，允许应用程序使用作用域名称标记方法，并颁发仅能调用具有特定作用域的方法的认证令牌。目前，作用域请求无法使用属性、访问器或修改器；这可能在将来改变。

1.0.4 (2021-09-13)

• 调整版本策略，以避免在大型环境中导入 pkg_resources，因为它的速度很慢。

1.0.3 (2021-05-20)

为 DateTimeFieldMarshaller 提供一个 unmarshall 方法，而不是在其他地方进行特殊处理。

为字典字段生成稳定的 ETags。

在条目表示中为字段使用稳定的排序。

稳定 Python 2 和 3 之间包含字符串集合的条目的 ETags（问题编号 1928474）。

为 date 和 datetime 添加一个 IJSONPublishable 适配器。

1.0.2 (2021-05-14)

避免在 ReadWriteResource.__call__ 中的回溯引用循环。

1.0.1 (2021-02-18)

在 export_factory_operation 和 BaseResourceOperationAdapter 中保留指定的参数排序。这可以在创建对象时发挥作用，确保验证器以正确的顺序被调用。

1.0.0 (2021-01-21)

重做 lazr.restful.testing.webservice.WebServiceCaller，使其将命名的 POST 作为 multipart/form-data 请求发送。如果参数是 io.BufferedIOBase 的实例，则将其原样发送，而不是将其编码为 JSON，允许在 Python 2 和 3 中稳健地使用二进制参数（问题编号 1116954）。

将来自请求的文本字段中打包的换行符标准化为 Unix 风格的 LF，因为 multipart/form-data 编码需要 CRLF。

使 lazr.restful.testing.webservice.pprint_entry 和 lazr.restful.testing.webservice.pprint_collection 递归到列表中，以便以 Python 3 风格打印文本字符串表示形式。

在 Python 3 上要求 zope.publisher >= 6.0.0。

使 lazr.restful.testing.helpers.encode_unicode 在 Python 3 上返回 str。

按名称对条目的 HTML 视图中的字段进行排序。

不要尝试对从请求中读取的 Bytes 字段进行 JSON 解码，因为无法通过不进行额外编码（我们不进行此操作）来通过 JSON 打包二进制数据，并且 lazr.restfulclient 不对二进制字段进行 JSON 编码。

声明支持 Python 3。

0.23.0 (2020-09-28)

将 lazr.restful.testing.webservice.pprint_entry 和 lazr.restful.testing.webservice.pprint_collection 改为在 Python 2 和 3 上以 Python 3 风格打印文本字符串表示形式（'text' 而不是 u'text'）。这使得编写双语 doctests 更容易，尽管现有的调用者需要更改。

停止 lazr.restful.utils.make_identifier_safe 有地域依赖的行为。

删除 lazr.restful.utils.safe_js_escape。Launchpad 自 2012 年以来就没有使用它，而且它的接口很混乱，因为它结合了 JavaScript 和 HTML 转义。如果任何代码仍在使用此功能，则应使用 cgi.escape/html.escape（如果需要）和 json.dumps 直接替代。

一些 Python 3 移植工作，但尚未完成。

0.22.2 (2020-09-02)

修复 HTTPS 请求中重定向的 URL 的引用。

一些 Python 3 移植工作，但尚未完成。

0.22.1 (2020-07-08)

修复 zope.interface >= 5.0.0 时的测试失败。

使 ObjectLookupFieldMarshaller 能够接受重定向的 URL，前提是重定向到的资源具有一个 context 属性，该属性评估为适当的模型对象。

0.22.0 (2020-06-12)

在提供不同版本 web 服务的 WADL 时设置不同的 ETag（问题编号 1875917）。

从 lazr.restful.declarations 中弃用“class advice” API： export_as_webservice_entry 和 export_as_webservice_collection。取而代之，首选等效的类装饰器： @exported_as_webservice_entry 和 @exported_as_webservice_collection。基于类建议的功能在 Python 3 上将无法工作。

0.21.1 (2020-02-19)

仅在 Python 2 上需要单独的 wsgiref 包。

移除 epydoc 依赖，直接合并相关代码。

允许使用 grokcore.component 和 martian 的新版本，而不是固定（且过时）的版本。

一些 Python 3 移植工作，尚未完成。

0.21.0 (2019-12-17)

修复 IDjangoLocation，以与 zope.traversing >= 3.13 兼容，该版本仅适配没有 __parent__ 属性的对象为 ILocation。实现 IDjangoLocation 的对象现在必须具有 __parent_object__ 属性而不是 __parent__。

修复自定义操作编码结果时双闭合花括号的问题，其中结果具有 ICollection 的适配器。

生成与原始接口中字段排序匹配的 IEntry 子接口。

修复了 bug 1803564：现在正确解释只包含空白的请求值。

移除在 webservice 版本中取消命名操作的方法中，具有相同名称的命名操作立即恢复的限制。 （这以前在任何情况下都不可靠地执行，因为它依赖于 zope.interface.Interface.namesAndDescriptions 返回的方法顺序。）

修复了 zope.configuration >= 4.3.0 时的测试失败。

修复了 Python >= 2.7.17（或 CVE-2019-9740 的回滚修复）时的测试失败。

从 zope.component.interfaces 而不是 zope.interface.interfaces 导入 ComponentLookupError，修复了一个弃用警告。

从 buildout 切换到 tox。

移除对 zope.app.pagetemplate 的依赖，显式依赖于 zope.datetime，它之前只是间接引入。

0.20.1 (2018-02-21)

调整 docstring 渲染以避免在运行“zope.testrunner –subunit”时关闭 sys.stdout（docutils >= 0.8）。

0.20.0 (2017-06-29)

修复了 bug 1294543：contributes_to 现在可以引用其他模块中的接口和 webservice:register 指令。

将 zope.interface、zope.component 和 lazr.delegates 的用户从类建议切换到类装饰器。

限制 find_exported_interfaces 到通常被认为是模块导出的名称。

0.19.10 (2012-12-06)

修复了 bug 809863：WebServicePublicationMixin.getResource() 将 ComponentLookupErrors 转换为 NotFound。

0.19.9 (2012-10-23)

修复了 bug 924291：FixedVocabularyFieldMarshaller 现在将正确地返回整个词汇表，如果传入的值是 None。

0.19.8 (2012-10-02)

修复了 bug 1020439：dict marshaller 现在将正确地反序列化 None。

0.19.7 (2012-09-26)

修复了 bug 1056666：导致资源 URL 发生变化的命名操作将发出包含新位置的 301 响应。

0.19.6 (2012-03-15)

修复了 bug 955668：对于未指定键和/或值的集合字段（Set、List、Dict），使 marshaller 正确工作。在这种情况下，使用默认 marshaller 为集合元素。

0.19.5 (2012-03-13)

修复了 bug 953587：添加字典 marshaller，以便导出方法参数可以是字典类型。

0.19.4 (2011-10-11)

修复了 bug 871944：使用 If-Match 成功写入有时会返回过时的值。

0.19.3 (2011-09-20)

修复了 bug 854695：没有 __traceback__ 属性的异常会导致 AttributeError。

0.19.2 (2011-09-08)

修复了 bug 842917：请求中的 ws.op 的多个值会生成 TypeError。

0.19.1 (2011-09-08)

修复了 bug 832136：当重新抛出异常时，原始跟踪回溯会被遮蔽。

0.19.0 (2011-07-27)

在 lazr.restful.declarations 中添加了一个新的装饰器，@accessor_for。这使得将带有绑定变量的方法导出为属性的访问器成为可能。

0.18.1 (2011-04-01)

修复了小的测试失败。

如果客户端通过 PATCH 发送空更改集，则不会触发对象修改事件。

Web服务可能定义一个适配器，在资源操作之后使用，以提供包含命名元组（level，message）的通知。任何通知都将被JSON编码，并使用“X-Lazr-Notification”键插入到响应头中。然后调用者可以使用它们向用户提供有关完成请求的额外信息。

Web服务：json TALES函数现在返回的JSON将能够承受HTML转义。

0.18.0 (2011-03-23)

如果配置变量require_explicit_versions被设置，lazr.restful将不会加载一个Web服务，除非每个字段、条目和命名操作都明确声明它首次出现的Web服务版本。

0.17.5 (2011-03-15)

当为异常注册了一个视图，但该视图不包含对lazr.restful有用的信息时，将重新抛出异常，而不是尝试渲染视图。

0.17.4 (2011-03-08)

将客户端缓存表示重置为仅JSON。调用站点需要转义JSON_PLUS_XHTML_TYPE表示，可能需要JSONEncoderForHTML或声明脚本为CDATA。

0.17.3 (2011-03-08)

修复了当相关响应代码在4xx系列时异常处理中的错误。

0.17.2 (2011-03-03)

关联异常与HTTP响应代码的几种技术根本不起作用。已修复。

0.17.1 (2011-02-23)

向测试套件添加了一个新测试。

0.17.0 (2011-02-17)

添加了获取具有自定义HTML字段表示的条目的组合JSON/HTML表示的能力。

0.16.1 (2011-02-16)

修复了一个阻止写操作升级为修改器操作的错误。

0.16.0（非官方版本）

如果Web服务中的每个条目对应于网站上的某个对象，并且存在将Web服务请求转换为网站请求的方法，则Web服务现在将为每个条目提供网站链接。

可以通过将publish_web_link=False传递给export_as_webservice_entry()来禁用特定条目类的网站链接。

即使包含Unicode字符，命名操作的有效性错误也将被正确发送到客户端。（Launchpad错误619180。）

0.15.4 (2011-01-26)

修复了自定义HTML字段渲染的不一致处理。现在IFieldHTMLRenderer可以返回Unicode或UTF-8。

0.15.3 (2011-01-21)

如果尝试导出IObject，lazr.restful现在会报错，因为这会在字段验证期间导致无限递归。我们有一些代码可以解决无限递归问题，但它们不可靠，我们已将其删除以简化。在您使用IObject的地方始终使用IReference。

0.15.2 (2011-01-20)

当发布接口包含对未发布接口的引用时，lazr.restful现在会提供更有用的错误消息。（Launchpad错误539070）

lazr.restful的测试现在在Python 2.7中通过。（Launchpad错误691841）

0.15.1 (2011-01-19)

修复了当Web浏览器请求除JSON之外的其他表示时的重定向错误。

删除了导致Chromium等浏览器出现问题的过度错误检查。（Launchpad错误423149。）

0.15.0 (2010-11-30)

在WADL文档字符串处理中添加了优化，使大型文件的WADL生成时间减少了30%。

0.14.1 (2010-10-24)

修复了一个Unicode编码错误，该错误阻止了报告包含非ASCII字符的异常。

0.14.0 (2010-10-05)

重新设计ETag生成以更保守（优化）。

0.13.3 (2010-09-29)

将作为参数接受URL的命名操作现在将接受相对于版本化服务根的相对URL。之前它们只能接受绝对URL。PUT和PATCH请求也将接受相对URL。这修复了错误497602。

0.13.2 (2010-09-27)

避免了在查看包含在URI中无效字符的位置头时的错误。（错误可能仍然会发生，但在lazr.restful中发生时会让人们感到困惑。）

0.13.1 (2010-09-23)

删除了Python 2.6-ism以恢复与Python 2.5的兼容性。

0.13.0 (2010-09-06)

添加了注释异常的能力，以便将异常消息作为响应的HTTP正文提供给客户端。

0.12.1 (2010-09-02)

使WADL生成更确定。

0.12.0 (2010-08-26)

添加了将可读写字段作为只读通过Web服务发布的能力。

0.11.2 (2010-08-23)

优化了lazr.restful，以便在“total_size”容易计算时发送“total_size”而不是“total_size_link”，可能节省了客户端发送另一个HTTP请求。

0.11.1 (2010-08-13)

修复了一个在多版本环境中阻止 first_version_with_total_size_link 正确工作的错误。

0.11.0 (2010-08-10)

对 total_size 进行了优化，使其尽可能通过链接获取。新的配置选项 first_version_with_total_size_link 指定了哪个版本应该首先展示此行为。默认情况下，它将对所有版本启用，因此请设置此选项以保留之前发布 Web 服务的行为。

0.10.0 (2010-08-05)

增加了将接口 A 标记为接口 B 的贡献者的能力，这样我们就可以将 A 的所有字段和操作添加到 B 的发布版本中，而不是单独发布 A。实现 B 的对象必须能够适应 A 才能使其工作，但 lazr.restful 将负责在访问对象未直接提供的字段/操作之前执行实际的适配。

0.9.29 (2010-06-14)

为 lazr.restful 自身生成的事件添加了表示缓存失效代码。使缓存更健壮，并修复了一个问题，即它会完全删除被禁止的表示，而不是简单地拒绝提供服务。现在可以允许缓存出于任何原因拒绝缓存对象。

0.9.28 (2010-06-03)

特别说明：此版本添加了一个新的配置元素，‘enable_server_side_representation_cache’。这允许您在运行时打开或关闭表示缓存，而无需注销缓存实用程序。

修复了一些测试失败。

0.9.27 (2010-06-01)

增加了定义用于存储条目资源的 JSON 表示的表示缓存的能力，而不是每次都从头构建。尽管缓存有失效钩子，但 lazr.restful 永远不会自行使缓存的部分失效。您需要将 lazr.restful 的失效代码连接到您的 ORM 或其他数据存储。

0.9.26 (2010-05-18)

特别说明：此版本添加了一个新的配置元素，‘compensate_for_mod_compress_etag_modification’。如果您在 Apache 服务器后面运行 lazr.restful，设置此配置元素将使 mod_compress 能够与 lazr.restful 正确工作。这不是一个永久性的解决方案：当 Apache bug 39727 被修复时，将有一个更好的解决方案。

特别说明：此版本删除了配置元素 ‘set_hop_to_hop_headers’。您仍然可以在配置中定义此元素，但它将没有任何效果。

删除了处理 hop-to-hop 标头的压缩代码。我们从未遇到过这些标头真正有用的实际场景。压缩应该由 mod_compress 等中间件处理。（不幸的是，mod_compress 有它自己的问题，此版本试图解决这个问题。）

0.9.25 (2010-04-14)

特别说明：此版本引入了一个新的配置元素，‘caching_policy’。此元素最初很简单，但可能在未来的版本中变得更复杂。有关更多详细信息，请参阅 IWebServiceConfiguration 接口。

服务根资源现在可以在客户端缓存一定时间，这取决于服务器配置和请求的 Web 服务版本。要获得全部好处，客户端需要升级到 lazr.restfulclient 0.9.14。

当 PATCH 或 PUT 请求同时更改多个字段时，更改将按确定性的顺序应用，以最大限度地减少可能的冲突。

0.9.24 (2010-03-17)

即使资源的一个只读字段最近在后台更改了，条目资源现在也将接受条件 PATCH 请求。

0.9.23 (2010-03-11)

Web 服务配置有两个新属性，“service_description” 和 “version_descriptions”。两者都是可选的，但它们对于向用户概述您的 Web 服务以及不同版本之间的差异非常有用。

0.9.22 (2010-03-05)

特别说明：除非您采取特殊步骤，否则此版本将破坏您的 Web 服务的向后兼容性。请参阅下面的“last_version_with_named_mutator_operations”。

重构了标记带有版本信息的请求对象的代码，以便始终进行标记。

默认情况下，mutator 方法不再作为命名操作单独发布。为了保持向后兼容性（或者如果您只是想恢复此功能），请将您的 Web 服务的最新版本名称放入 IWebServiceConfiguration 实现的“last_version_with_mutator_named_operations”字段中。

0.9.21 (2010-02-23)

修复了一组错误，这些错误将浏览器发起的请求当作是来自Web服务客户端发起的。

0.9.20 (2010-02-16)

修复了一个错误，该错误破坏了接受固定参数的请求用户的多版本命名操作。

0.9.19 (2010-02-15)

针对Launchpad集成进行了一些小的错误修复。

0.9.18 (2010-02-11)

特别说明：此版本包含向后不兼容的更改。您必须更改配置对象才能使代码在此版本中运行！请参阅下文“active_versions”。

为Web服务添加了版本控制系统。客户端现在可以请求任意数量的不同版本以及一个浮动的“trunk”，它始终是最新版本。通过使用版本感知的注解，开发者可以在不同时间以不同的方式发布相同的数据模型。请参阅example/multiversion/中的示例Web服务以了解注解的工作方式。

此版本替换了IWebServiceConfiguration中的一个字段。字符串‘service_version_uri’_prefix已变为列表‘active_versions’。处理这个问题的最简单方法是只需将您的‘service_version_uri_prefix’放入一个列表中，并命名为‘active_versions’。我们建议您还将一个浮动的“开发”版本添加到‘active_versions’的末尾，命名为“devel”或“trunk”。这将使用户有一个永久的别名指向“Web服务的最新版本”。

0.9.17 (2009-11-10)

修复了一个错误，当客户端尝试将URL字段设置为一个非字符串值时，会引发未处理的异常。

0.9.16 (2009-10-28)

修复了一个错误，该错误在导出对象包含非ASCII字符时渲染XHTML表示形式。

0.9.15 (2009-10-21)

更正了WADL媒体类型的拼写错误。

0.9.14 (2009-10-20)

lazr.restful现在在Python 2.6上运行时不再有弃用警告。

0.9.13 (2009-10-19)

修复了WADL模板：HostedFile DELETE方法应具有HostedFile-delete的id，而不是HostedFile-put。

0.9.12 (2009-10-14)

使用Transfer-Encoding的透明压缩现在是可选的，并且默认情况下对WSGI应用程序禁用。（真正的WSGI服务器不允许应用程序设置 hop-by-hop 标头，如Transfer-Encoding。）

此版本在IWebServiceConfiguration中引入了一个新字段：set_hop_by_hop_headers。如果您正在创建自己的IWebServiceConfiguration实现，而不是从BaseWebServiceConfiguration或其子类中继承，则需要为此设置一个值。基本上：如果您的应用程序正在WSGI服务器上运行，则将其设置为False，否则设置为True。

0.9.11 (2009-10-12)

修复了一个小的导入问题。

0.9.10 (2009-10-07)

lazr.restful再次在Python 2.4上运行。

0.9.9 (2009-10-07)

与身份验证相关的WSGI中间件类已被拆分为一个单独的项目，lazr.authentication。

修复了一个错误，该错误导致一些传入的字符串无法被simplejson加载。

0.9.8 (2009-10-06)

添加了用于保护HTTP基本认证或OAuth资源的WSGI中间件类。

0.9.7 (2009-09-24)

修复了一个错误，该错误使无法导航到字段资源，如果该字段是另一个对象的链接。

0.9.6 (2009-09-16)

使用grok指令简化了大多数Web服务配置。

0.9.5 (2009-08-26)

添加了一个函数，该函数根据服务根类、发布类和响应类生成一个基本的WSGI应用程序。

为具有多个URL路径的生成URL的对象添加了AbsoluteURL实现。

为使用Django的服务添加了从Django的Manager类到IFiniteSequence的适配器，这样使用Django的服务就可以在不使用特殊代码的情况下将数据库对象作为集合提供服务。

为提供多个URL路径的生成URL的对象添加了AbsoluteURL实现。

对于使用Django的服务，添加了从Django的ObjectDoesNotExist到lazr.restful的NotFoundView的适配器。

修复了lazr.restful.testing.webservice中的某些测试基础设施问题。

修复了一些关键的打包问题。

0.9.4 (2009-08-17)

修复了simple.py中的导入错误。

从example/wsgi/root.py中删除了Python 2.6ism。

0.9.3 (2009-08-17)

添加了一个lazr.restful.frameworks.django模块，以帮助通过lazr.restful Web服务发布Django模型对象。

TraverseWithGet实现现在将请求对象传递到get()中。

为未将顶级集合注册为Zope实用程序的服务创建了简化的IServiceRootResource实现。

使遍历工作于规范位置位于其他条目之下的条目。

当将数字日期传递给 DatetimeFieldMarshaller 时引发 ValueError。

0.9.2 (2009-08-05)

添加了一个作为独立 WSGI 应用程序工作的第二个示例 webservice。

错误 400170；在 setup.py 中停止篡改 sys.path。

错误 387487；允许在通常会有字段的资源下有一个子级条目资源。向发布者添加了支持子 IObjects 的导航。

0.9.1 (2009-07-13)

将 multipart/form-data 声明为包含二进制字段的命名操作的传入媒体类型。

0.9 (2009-04-29)

• 初始公共版本