lazr.restful 2.0.1

WSGI 示例 Web 服务

src/lazr/restful/example/wsgi/ 中的示例 Web 服务是了解 lazr.restful 的最佳起点。这是一个非常简单的 Web 服务，它使用了 lazr.restful 的一部分功能，并且可以作为独立的 WSGI 应用程序运行。代码的解释可以在 src/lazr/restful/example/wsgi/README.txt

完整的示例 Web 服务

要了解所有 lazr.restful，您应该查看 src/lazr/restful/example/base/ 中定义的 Web 服务。它定义了一个简单的应用程序，提供有关食谱和食谱的信息。接口 (interfaces.py) 使用 lazr.restful 装饰器进行注释，说明要从 IRecipe、ICookbook 等发布哪些字段和方法。这些接口的实现在 root.py 中。

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

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

其他代码

当您刚开始时，可​​能会对另外两段代码感兴趣。

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

• docs/webservice.txt 显示了一个 web 服务的示例，它直接创建 Entry 和 Collection 类，而不是使用声明生成它们。如果你想在不使用 zope.schema 的情况下使用 lazr.restful，这是要查看的测试。

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 的支持。

• 添加基本​​的预提交配置。

• 在阅读文档上发布文档。

• 通过唤醒预提交挂钩应用包容性命名。执行了以下 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

• 通过预提交应用黑色代码格式化程序。

• 删除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 起已修复。

• 集合编组器 (list, set, tuple) 现在可以正确地将 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方法，而不是在其他地方特例化它。

为 dict 字段生成稳定的 ETag。

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

稳定包含 Python 2 和 3 之间的字符串集合的条目的 ETag（错误 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 作为多部分/表单数据请求发送。作为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 视图中的字段进行排序。

不要尝试对从请求中读取的字节字段进行 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' ）打印文本字符串表示形式。这使得尽管现有的调用者需要更改，但编写双语文档测试更容易。

停止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，前提是重定向到的资源具有评估为适当模型对象的上下文属性。

0.22.0 (2020-06-12)

为不同版本的 Web 服务提供 WADL 时设置不同的 ETag（错误 1875917）。

弃用lazr.restful.declarations中的“类建议”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 子接口。

修复了错误 1803564：现在可以正确解释来自仅包含空格的请求的值。

删除在 Web 服务版本中立即恢复与 mutator 同名的命名操作的限制，该版本摆脱了 mutator 方法的命名操作。（这在以前只是在任何情况下都不可靠地执行，因为它取决于 zope.interface.Interface.namesAndDescriptions 返回的方法的顺序。）

使用 zope.configuration >= 4.3.0 修复测试失败。

使用 Python >= 2.7.17（或 CVE-2019-9740 的反向移植修复）修复测试失败。

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

从增建切换到毒性。

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

0.20.1 (2018-02-21)

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

0.20.0 (2017-06-29)

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

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

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

0.19.10 (2012-12-06)

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

0.19.9 (2012-10-23)

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

0.19.8 (2012-10-02)

修复了错误 1020439：dict marshaller 现在将正确解组 None。

0.19.7 (2012-09-26)

修复了错误 1056666：导致资源 URL 更改的命名操作发出包含新位置的 301 响应。

0.19.6 (2012-03-15)

修复了错误 955668：使编组器在未指定键和/或值类型的集合字段（Set、List、Dict）上正常工作。在这种情况下，默认编组器用于集合元素。

0.19.5 (2012-03-13)

修复了错误 953587：添加 dict marshaller，以便导出的方法参数可以是 dict 类型。

0.19.4 (2011-10-11)

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

0.19.3 (2011-09-20)

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

0.19.2 (2011-09-08)

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

0.19.1 (2011-09-08)

修复了错误 832136：重新引发异常时，原始回溯被掩盖。

0.19.0 (2011-07-27)

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

0.18.1 (2011-04-01)

修复了轻微的测试失败。

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

Web 服务可以定义一个适配器，在对资源进行操作之后，该适配器用于提供由命名元组（级别、消息）组成的通知。任何通知都使用 'X-Lazr-Notification' 键进行 json 编码并插入到响应标头中。然后，调用者可以使用它们向用户提供有关已完成请求的额外信息。

webservice:json TALES 函数现在返回可以在 HTML 转义后继续存在的 JSON。

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)

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

0.16.1 (2011-02-16)

修复了一个错误，该错误阻止了写操作被提升为一个 mutator 操作。

0.16.0（未正式发布）

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

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

命名操作的验证错误将被正确发送到客户端，即使它们包含 Unicode 字符。（启动板错误 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 会提供更有用的错误消息。（启动板错误 539070）

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

0.15.1 (2011-01-19)

修复了 Web 浏览器请求 JSON 以外的表示时的重定向错误。

删除了导致 Chromium 等浏览器出现问题的过度错误检查。（启动板错误 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 中无效字符的 Location 标头时避免了错误。（错误可能仍然会发生，但在 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)

当 'total_size' 易于计算时，优化 lazr.restful 以发送 '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 错误 39727 得到修复时，将提供更好的解决方案。

特别说明：此版本删除了配置元素“set_hop_to_hop_headers”。您仍然可以在配置中定义此元素，但它不会产生任何影响。

删除了通过跳到跳标头处理压缩的代码。我们从未遇到过这些标头有用的实际情况。压缩可以而且应该由 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”。

重构了使用版本信息标记请求对象的代码，以便标记会始终如一地发生。

By default, mutator methods are no longer separately published as named operations. To maintain backwards compatibility (or if you just want this feature back), put the name of the most recent version of your web service in the “last_version_with_mutator_named_operations” field of your IWebServiceConfiguration implementation.

0.9.21 (2010-02-23)

Fixed a family of bugs that were treating a request originated by a web browser as though it had been originated by a web service client.

0.9.20 (2010-02-16)

Fixed a bug that broke multi-versioned named operations that take the request user as a fixed argument.

0.9.19 (2010-02-15)

A few minor bugfixes to help with Launchpad integration.

0.9.18 (2010-02-11)

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

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

此版本_replaces_ IWebServiceConfiguration 中的字段之一。字符串 'service_version_uri'_prefix 已成为列表 'active_versions'。处理这个问题的最简单方法是将你的“service_version_uri_prefix”放到一个列表中，并称之为“active_versions”。我们建议您还在“active_versions”的末尾添加一个浮动的“开发”版本，将其称为“开发”或“主干”。这将为您的用户提供“最新版本的网络服务”的永久别名。

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 方法的 id 应该是 HostedFile-delete，而不是 HostedFile-put。

0.9.12 (2009-10-14)

使用 Transfer-Encoding 的透明压缩现在是可选的，并且默认情况下对于 WSGI 应用程序是禁用的。（真正的 WSGI 服务器不允许应用程序设置像 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)

添加了 WSGI 中间件类，用于使用 HTTP Basic Auth 或 OAuth 保护资源。

0.9.7 (2009-09-24)

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

0.9.6 (2009-09-16)

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

0.9.5 (2009-08-26)

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

为简单的 ServiceRootResource 添加了 AbsoluteURL 实现。

从 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 实用程序的 Web 服务创建简化的 IServiceRootResource 实现。

对规范位置在另一个条目下方的条目进行遍历。

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

0.9.2 (2009-08-05)

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

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

错误 387487；允许在通常会有字段的资源下使用从属条目资源。将支持从属 IObject 的导航添加到发布者。

0.9.1 (2009-07-13)

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

0.9 (2009-04-29)

• 首次公开发布