node 1.2.2

概述

Node是一个用于创建嵌套数据模型和结构的库。

这些数据模型被描述为带有可选属性和模式定义的节点树。

它们使用

• Python的映射和序列API来访问节点成员。

• 关于层次信息的 zope.location.interfaces.ILocation 合同。

此包的一个目的是为不同的后端存储提供统一的 API。具体的存储相关实现例如：

• node.ext.fs

• node.ext.ldap

• node.ext.yaml

• node.ext.zodb

另一个用途是为特定应用领域提供接口。

例如，对于用户和组管理，node.ext.ugm 定义了接口。此外，它实现了一个基于文件的默认实现。然后，在 node.ext.ldap 和 cone.sql 中实现了这些接口的具体实现，以便访问 LDAP 和 SQL 数据库中的用户和组。

此包还用于构建各种内存模型。

例如，yafowil 是一个 HTML 表单处理和渲染库。它使用节点树来声明性地描述表单模型。

另一个要提到的是 cone.app，这是一个基于 Pyramid 的 Web 应用程序开发环境，它使用节点树来描述应用程序模型。

基本用法

有两种基本节点类型。映射节点和序列节点。此包提供了一些基本节点作为起点。

from node.base import BaseNode

root = BaseNode(name='root')
root['child'] = BaseNode()

from node.base import OrderedNode

root = OrderedNode(name='orderedroot')
root['foo'] = OrderedNode()
root['bar'] = OrderedNode()

>>> root.printtree()
<class 'node.base.OrderedNode'>: orderedroot
  <class 'node.base.OrderedNode'>: foo
  <class 'node.base.OrderedNode'>: bar

from node.base import BaseNode
from node.base import ListNode

root = ListNode(name='listroot')
root.insert(0, BaseNode())
root.insert(1, BaseNode())

>>> root.printtree()
<class 'node.base.ListNode'>: listnode
  <class 'node.base.BaseNode'>: 0
  <class 'node.base.BaseNode'>: 1

from node.behaviors import DefaultInit
from node.behaviors import MappingNode
from node.behaviors import OdictStorage
from plumber import plumbing

@plumbing(
    DefaultInit,
    MappingNode,
    OdictStorage)
class CustomNode:
    pass

>>> dir(CustomNode)
['__bool__', '__class__', '__contains__', '__delattr__', '__delitem__',
'__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__',
'__getattribute__', '__getitem__', '__gt__', '__hash__', '__implemented__',
'__init__', '__init_subclass__', '__iter__', '__le__', '__len__', '__lt__',
'__module__', '__name__', '__ne__', '__new__', '__nonzero__', '__parent__',
'__plumbing__', '__plumbing_stacks__', '__provides__', '__reduce__',
'__reduce_ex__', '__repr__', '__setattr__', '__setitem__', '__sizeof__',
'__str__', '__subclasshook__', '__weakref__', 'acquire', 'clear', 'copy',
'deepcopy', 'detach', 'filtereditems', 'filtereditervalues', 'filteredvalues',
'get', 'has_key', 'items', 'iteritems', 'iterkeys', 'itervalues', 'keys',
'name', 'noderepr', 'parent', 'path', 'pop', 'popitem', 'printtree', 'root',
'setdefault', 'storage', 'treerepr', 'update', 'values']

from node.behaviors import Attributes
from node.behaviors import DefaultInit
from node.behaviors import DictStorage
from node.behaviors import MappingNode
from plumber import plumbing

@plumbing(
    Attributes,
    DefaultInit,
    MappingNode,
    DictStorage)
class NodeWithAttributes:
    pass

>>> node = NodeWithAttributes()
>>> attrs = node.attrs
>>> attrs
<NodeAttributes object 'None' at ...>

>>> attrs['foo'] = 'foo'

>>> node.attribute_access_for_attrs = True
>>> attrs = node.attrs
>>> attrs.foo = 'bar'
>>> attrs.foo
'bar'

from node.behaviors import NodeAttributes

class CustomAttributes(NodeAttributes):
    pass

class CustomAttributesNode(NodeWithAttributes):
    attributes_factory = CustomAttributes

>>> node = CustomAttributesNode()
>>> node.attrs
<CustomAttributes object 'None' at ...>

from node import schema
from node.base import BaseNode
from node.behaviors import DefaultInit
from node.behaviors import DictStorage
from node.behaviors import MappingNode
from node.behaviors import Schema
from plumber import plumbing

@plumbing(
    DefaultInit,
    MappingNode,
    DictStorage,
    Schema)
class SchemaNode:
    schema = {
        'int': schema.Int(),
        'float': schema.Float(default=1.),
        'str': schema.Str(),
        'bool': schema.Bool(default=False),
        'node': schema.Node(BaseNode)
    }

>>> node = SchemaNode()
>>> node['int']
<UNSET>

>>> node['float']
1.0

>>> node['bool']
False

>>> node = SchemaNode()
>>> node['int'] = 'A'
Traceback (most recent call last):
  ...
ValueError: A is no <class 'int'> type

from node.behaviors import SchemaAsAttributes

@plumbing(SchemaAsAttributes)
class SchemaAsAttributesNode(BaseNode):
    schema = {
        'int': schema.Int(default=1),
    }

>>> node = SchemaAsAttributesNode()
>>> node.attrs['int']
1

from node.behaviors import SchemaProperties

@plumbing(
    DefaultInit,
    MappingNode,
    DictStorage,
    SchemaProperties)
class SchemaPropertiesNode:
    text = schema.Str(default='Text')

>>> node = SchemaPropertiesNode()
>>> node.text
'Text'

>>> node.text = 1
Traceback (most recent call last):
  ...
ValueError: 1 is no <class 'str'> type

Plumbing Behaviors

JSON 序列化

节点可以序列化为 JSON 并从 JSON 反序列化

>>> from node.serializer import serialize
>>> json_dump = serialize(BaseNode(name='node'))

>>> from node.serializer import deserialize
>>> deserialize(json_dump)
<BaseNode object 'node' at ...>

有关序列化 API 的详细信息，请阅读 docs/archive/serializer.rst 中的文件。

Python 版本

• Python 2.7, 3.7+

• 可能与其他版本兼容（未测试）

1.2.2 (2024-05-30)

• 确保 Unset 类在 __new__ 中始终返回相同的实例。修复了与 pickle 相关的问题。[rnix]

1.2.1 (2023-04-16)

• 在 node.base 中用 MappingOrder 替换已弃用的 Order 导入。[rnix]

1.2 (2022-12-05)

• 在 node.behaviors.UUIDAware.__init__ 中，如果 uuid 已经设置，则不要覆盖 uuid。 [rnix]

• 将 node.interfaces.IOrder 重命名为 node.interfaces.IMappingOrder，将 node.behaviors.Order 重命名为 node.behaviors.MappingOrder。B/C 保持不变。 [rnix]

• 引入 node.behaviors.ISequenceOrder 和 node.interfaces.SequenceOrder。 [rnix]

• 引入 node.interfaces.INodeOrder。用作 node.interfaces.IMappingOrder 和 node.interfaces.ISequenceOrder 的基础。 [rnix]

• 向 node.utils.Unset 添加丰富的比较函数 __lt__、__le__、__gt__ 和 __ge__。 [rnix]

破坏性变更:

• 从 node.behaviors.order 导入 B/C Order 行为不再工作。请从 node.behaviors 中导入。 [rnix]

1.1 (2022-10-06)

• 添加 node.schema.DateTime、node.schema.DateTimeSerializer 和 node.schema.datetime_serializer。 [rnix]

• 为 node.behaviors.lifecycle._lifecycle_context、node.behaviors.events._attribute_subscribers 和 node.behaviors.schema._schema_property 对象子类化 threading.local，以便安全地提供默认值。 [rnix]

• 引入 node.interfaces.IChildFilter、node.behaviors.MappingFilter 和 node.behaviors.SequenceFilter。 [rnix]

• 引入 node.interfaces.IWildcardFactory 和 node.behaviors.WildcardFactory。 [rnix]

• 引入 node.interfaces.INodeInit 和 node.behaviors.NodeInit。 [rnix]

• 弃用 IFixedChildren.fixed_children_factories，改用 IFixedChildren.factories。 [rnix]

• 引入 node.interfaces.IContentishNode 和 node.behaviors.ContentishNode。用作映射节点和序列节点的基础。 [rnix]

• insertbefore、insertafter 和 swap 在 node.behaviors.Order 中可交替接受节点名称作为参数。 [rnix]

• insertbefore、insertafter、insertfirst 和 insertlast 在 node.behaviors.Order 中内部使用 odict 的 movebefore、moveafter、movefirst 和 movelast，以避免在调用 __setitem__ 之前修改数据结构。 [rnix]

• 通过 movebefore、moveafter、movefirst 和 movelast 扩展 node.interfaces.IOrder 和 node.behaviors.Order。 [rnix]

• 在 node.behaviors.Node.detach 中重置 __parent__。节点不再包含在树中。 [rnix]

• 引入继承自 ValueError 的 IndexViolationError，并在相关行为中适当替换 ValueError。 [rnix]

• 引入 node.interfaces.INodeReference 和 node.behaviors.NodeReference。 [rnix]

• 引入 node.interfaces.ISequenceReference 和 node.behaviors.SequenceReference。 [rnix]

• 将 node.interfaces.IReference 重命名为 node.interfaces.IMappingReference，将 node.behaviors.Reference 重命名为 node.behaviors.MappingReference。兼容性保持。[rnix]

破坏性变更:

• 从 Lifecycle 行为中移除 _notify_suppress 标志。引入 suppress_lifecycle_events contextmanager 作为替代。[rnix]

• 从 node.behaviors.common 导入 ChildFactory 和 FixedChildren 不再有效。请从 node.behaviors 导入。[rnix]

• 从 node.behaviors.reference 导入 B/C Reference 行为不再有效。请从 node.behaviors 导入。[rnix]

1.0 (2022-03-17)

• 在 node.utils.UNSET 上实现 __copy__ 和 __deepcopy__。[rnix]

• 引入 node.interfaces.ISequenceConstraints 和 node.behaviors.SequenceConstraints。[rnix]

• 将 node.interfaces.INodeChildValidate 重命名为 node.interfaces.IMappingConstraints，将 node.behaviors.NodeChildValidate 重命名为 node.behaviors.MappingConstraints。《MappingConstraints》实现从 node.behaviors.common 移动到 node.behaviors.constraints。兼容性保持。[rnix]

• 引入 node.interfaces.ISequenceAdopt 和 node.behaviors.SequenceAdopt。[rnix]

• MappingAdopt 现在捕获所有异常，而不仅仅是 AttributeError、KeyError 和 ValueError。[rnix]

• 将 node.interfaces.IAdopt 重命名为 node.interfaces.IMappingAdopt，将 node.behaviors.Adopt 重命名为 node.behaviors.MappingAdopt。《MappingAdopt》实现从 node.behaviors.common 移动到 node.behaviors.adopt。兼容性保持。[rnix]

• node.behaviors.Attributes 现在即使没有应用 node.behaviors.Nodespaces 也能正常工作。[rnix]

• 引入仅实现 node.interfaces.INode 合同的 node.behaviors.Node。它被用作 node.behaviors.MappingNode 和 node.behaviors.SequcneNode 的基类。[rnix]

• 不再从 zope.interfaces.common.mapping.IFullMapping 继承 node.interfaces.INode。现在通过 node.interfaces.IMappingNode 和 node.interfaces.ISequenceNode 添加特定于数据模型接口。[rnix]

• 引入序列节点。序列节点通过 node.behaviors.SequcneNode 和 node.behaviors.ListStorage 实现。[rnix]

• 将 node.interfaces.INodify 重命名为 node.interfaces.IMappingNode，将 node.behaviors.Nodify 重命名为 node.behaviors.MappingNode。《MappingNode》实现从 node.behaviors.nodify 移动到 node.behaviors.mapping。兼容性保持。[rnix]

• 将 node.interfaces.IStorage 重命名为 node.interfaces.IMappingStorage，将 node.behaviors.Storage 重命名为 node.behaviors.Storage。兼容性保持。[rnix]

• 在适当的模式字段中添加键和值类型验证。[rnix]

• 向模式字段引入序列化器支持。向 node.schema.serializer 添加几个具体的字段序列化器实现。[rnix]

• 将 ODict 和 Node 模式字段添加到 node.schema.fields。[rnix]

• 添加 node.schema.fields.IterableField 并将其用作 List、Tuple 和 Set 模式字段的基础类。

• 引入 node.behaviors.schema.SchemaProperties 管道行为。[rnix]

• 将 node.schema 模块拆分为一个包。[rnix]

• 引入 node.behaviors.context.BoundContext 管道行为。[rnix]

破坏性变更:

• 移除 node.behaviors.GetattrChildren。如果您需要通过 __getattr__ 访问节点子项，请参阅 node.utils.AttributeAccess。[rnix]

• 从 node.behaviors.common 导入 B/C Adopt 行为不再有效。请从 node.behaviors 导入。[rnix]

• 从 node.behaviors.common 导入 B/C NodeChildValidate 行为不再有效。请从 node.behaviors 导入。[rnix]

• 从 node.behaviors.nodify 导入 B/C Nodify 行为不再有效。请从 node.behaviors 导入。[rnix]

• 移除已弃用的 B/C 导入位置 node.parts。[rnix]

• node.behaviors.schema.Schema 不再考虑通配符字段。[rnix]

• node.behaviors.schema.Schema.__setitem__ 如果值为 node.utils.UNSET，则从相关存储中删除字段的值。[rnix]

• node.behaviors.schema.Schema.__getitem__ 如果未设置默认值，则始终返回字段的默认值而不是引发 KeyError。[rnix]

• node.schema.fields.Field.default 的默认值现在是 node.utils.UNSET。[rnix]

• node.schema.fields.Field.validate 如果验证失败则引发异常，而不是返回布尔值。[rnix]

0.9.28 (2021-11-08)

• 添加缺失的 node.interfaces.INodeAttributes 接口。[rnix]

• 向 IAttributes 接口添加缺失的 attribute_access_for_attrs 属性。[rnix]

• 将 node.behaviors.common.NodeChildValidate.allow_non_node_childs 重命名为 allow_non_node_children。如果使用旧属性，则打印弃用警告。[rnix]

• 在 node.schema 中引入 node.behaviors.schema.Schema、node.behaviors.schema.SchemaAsAttributes 和相关模式定义。[rnix]

0.9.27 (2021-10-21)

• 在 Order 行为中公开 first_key、last_key、next_key 和 prev_key 来自 odict 存储。[rnix, 2021-10-21]

• 添加基本序列化设置机制。[rnix, 2021-07-20]

0.9.26 (2021-05-10)

• 在 node.behaviors.nodify.Nodify.treerepr 中使用 node.utils.safe_decode。[rnix, 2021-05-04]

• 添加 node.utils.safe_encode 和 node.utils.safe_decode。[rnix, 2021-05-04]

0.9.25 (2020-03-30)

• 在 node.interfaces.IUUIDAware 上引入 uuid_factory 函数，并在 node.behaviors.common.UUIDAware 中实现默认函数。[rnix, 2020-03-01]

• 将 NodeTestCase.expect_error 重命名为 NodeTestCase.expectError。[rnix, 2019-09-04]

• 将 NodeTestCase.check_output 重命名为 NodeTestCase.checkOutput。[rnix, 2019-09-04]

• 在 Nodify.treerepr 中引入 prefix 关键字参数。[rnix, 2019-09-04]

0.9.24 (2019-07-10)

• 重构 node.behaviors.Order。在适当的地方使用来自 odict 的相关函数。[rnix, 2019-07-10]

• 从 setup.py 中移除多余的 extra_require。[rnix, 2019-04-25]

• 停止支持 python < 2.7 和 < 3.3。[rnix, 2019-04-25]

0.9.23 (2018-11-07)

• 为 node.behaviors.reference.Reference.uuid 使用属性装饰器。[rnix, 2017-12-15]

0.9.22 (2017-07-18)

• 将always_dispatch关键字参数添加到node.behaviors.events.EventAttribute构造函数中，该参数定义了是否在__set__时始终分发事件，而不仅仅是属性值发生变化时。[rnix, 2017-06-20]

• 在node.behaviors.events.EventAttribute.__init__中将node.utils.UNSET用作默认值。[rnix, 2017-06-19]

• 引入了node.behaviors.events.EventAttribute.subscriber装饰器，可以用来注册属性订阅者。[rnix, 2017-06-19]

• 将事件分发相关类和函数从node.events移动到node.behaviors.events，并在node.events中从那里导入。[rnix, 2017-06-16]

• 引入了node.interfaces.IEvents并实现了node.behaviors.events.Events行为。包含来自node.events.EventDispatcher的业务逻辑。在EventDispatcher上使用新的行为。[rnix, 2017-06-16]

• 创建了一个suppress_events上下文管理器，可以与node.behaviors.Events行为一起使用以抑制事件通知。[rnix, 2017-06-15]

• 创建了一个node.behaviors.fallback.fallback_processing上下文管理器，并在node.behaviors.fallback.Fallback.__getitem__中使用它来检查是否启用了回退处理。[rnix, 2017-06-15]

0.9.21 (2017-06-15)

• 引入了node.events.EventDispatcher和node.events.EventAttribute。[rnix, 2017-06-15]

• 在instance_property装饰器中使用setattr而不是object.__setattr__，以避免与自定义低级__setattr__实现相关的错误。[rnix, 2017-06-14]

0.9.20 (2017-06-07)

• 在node.behaviors.Nodify.treerepr中将排序键转换为node.compat.UNICODE_TYPE以避免Unicode解码错误。[rnix, 2017-06-07]

0.9.19 (2017-06-07)

• Python 3和pypy兼容性。[rnix, 2017-06-02]

• 放弃对Python < 2.7的支持。[rnix, 2017-06-02]

• 向node.behaviors.Nodify添加__bool__。[rnix, 2017-06-02]

• 向node.utils.UNSET添加__bool__。[rnix, 2017-06-02]

• 在node.behaviors.nodify.Nodify中添加了treerepr，并将代码从printtree移动到它。返回树表示作为字符串，而不是打印它。现在printtree使用treerepr。作为增强，如果节点没有实现IOrdered，则treerepr会对节点的子节点进行排序，以确保一致的输出，这可以用来编写测试。[rnix, 2017-06-02]

• 在node.utils.instance_property中显式使用object.__getattribute__以检查属性值是否已经被计算，以避免在覆盖使用instance_property装饰器的类的__getattr__时出现问题。[rnix, 2017-06-02]

0.9.18.1 (2017-02-23)

• 修复权限。[rnix, 2017-02-23]

0.9.18 (2017-02-14)

• 添加了node.utils.node_by_path。[rnix, 2017-02-07]

• 由于没有使用，因此不依赖于unittest2。[jensens, 2017-01-17]

• 添加了node.behaviors.Fallback行为。[jensens, 2017-01-17]

0.9.17 (2017-01-17)

• 添加了基本的JSON序列化和反序列化器。[rnix, 2016-12-03]

0.9.16 (2015-10-08)

• 仅在名称是Unicode实例的情况下，在node.behaviors.nodify.Nodify.__repr__和node.behaviors.nodify.Nodify.noderepr中编码名称。[rnix, 2015-10-03]

• 改进了node.behaviors.nodify.Nodify.printtree。使用键打印空节点子节点。[rnix, 2015-10-03]

0.9.15 (2014-12-17)

• 修正依赖声明，使其在setuptools 8.x+中正常工作；现在使用 >= 而不是 >。 [jensens, 2014-12-17]

0.9.14

• 使用 plumbing 装饰器代替 plumber 元类。 [rnix, 2014-07-31]

0.9.13

• 引入 node.behaviors.cache.VolatileStorageInvalidate。 [rnix, 2014-01-15]

0.9.12

• 将 zope.component 添加到安装依赖项中。 [rnix, 2013-12-09]

0.9.11

• 在 node.behaviors.mapping.ExtendedWriteMapping.pop 中使用 node.utils.UNSET 实例。 [rnix, 2013-02-10]

• 改进 node.utils.Unset。在 node.utils.UNSET 中添加 Unset 实例。 [rnix, 2013-02-10]

0.9.10

• 修复 node.utils.StrCodec.encode，使其在字符串和解码失败时返回原值。 [rnix, 2012-11-07]

0.9.9

• 兼容Python 2.7。 [rnix, 2012-10-15]

• 移除 zope.component.event B/C。 [rnix, 2012-10-15]

• 移除 zope.location B/C。 [rnix, 2012-10-15]

• 移除 zope.lifecycleevent B/C。 [rnix, 2012-10-15]

• Pep8。 [rnix, 2012-10-15]

0.9.8

• 废弃 node.parts 的使用。使用 node.behaviors 代替。 [rnix, 2012-07-28]

• 适配 plumber 1.2。 [rnix, 2012-07-28]

0.9.7

• 引入 node.interfaces.IOrdered 标记接口。在 node.parts.storage.OdictStorage 上设置此接口。 [rnix, 2012-05-21]

• node.parts.mapping.ClonableMapping 现在支持 deepcopy。 [rnix, 2012-05-18]

• 在整个地方使用 zope.interface.implementer 代替 zope.interface.implements。 [rnix, 2012-05-18]

• 移除多余的接口。 [rnix, 2012-05-18]

• 从 node.utils 中移除 Zodict。 [rnix, 2012-05-18]

• 移除 AliasedNodespace，使用 Alias 部件代替。 [rnix, 2012-05-18]

• 将别名对象从 node.aliasing 移动到 node.parts.alias。 [rnix, 2012-05-18]

• 移除 composition 模块。 [rnix, 2012-05-18]

• 移除 bbb 模块。 [rnix, 2012-05-18]

0.9.6

• 不要从 node.parts.UUIDAware 继承 node.parts.Reference。 [rnix, 2012-01-30]

• 在 node.parts.Reference.__init__ plumb 中设置 uuid。 [rnix, 2012-01-30]

0.9.5

• 添加 node.parts.nodify.Nodify.acquire 函数。 [rnix, 2011-12-05]

• 添加 node.parts.ChildFactory plumb 部分。 [rnix, 2011-12-04]

• 添加 node.parts.UUIDAware plumb 部分。 [rnix, 2011-12-02]

• 修复 node.parts.Order.swap 以便与 pickled 节点一起工作。 [rnix, 2011-11-28]

• 在 node.parts.nodify.Nodify.path 中使用 node.name 而不是 node.__name__。 [rnix, 2011-11-17]

• 将 swap 添加到 node.parts.Order。 [rnix, 2011-10-05]

• 将 insertfirst 和 insertlast 添加到 node.parts.Order。 [rnix, 2011-10-02]

0.9.4

• 添加 node.utils.debug 装饰器。 [rnix, 2011-07-23]

• 从 node.aliasing.AliasedNodespace 中移除非存储合同特定属性。 [rnix, 2011-07-18]

• node.aliasing 测试完成。 [rnix, 2011-07-18]

• 为 node.aliasing.DictAliaser 添加非严格功能，以便在回退时按原样访问非别名键。 [rnix, 2011-07-18]

• 考虑在 node.utils.StrCodec 中实现 INode 对象。 [rnix, 2011-07-16]

• 从存储部分中移除重复的实现。 [rnix, 2011-05-16]

0.9.3

• 提高测试覆盖率。 [rnix, 2011-05-09]

• 为相关部分添加接口 IFixedChildren 和 IGetattrChildren。[rnix，2011-05-09]

• 将 Unicode 部分重命名为 UnicodeAware。[rnix，2011-05-09]

• 添加 node.utils.StrCodec。[rnix，2011-05-09]

• 从 INode 继承 INodify 接口。[rnix，2011-05-08]

• 锁定测试。在线程启动后添加 time.sleep。[rnix，2011-05-08]

• 清理 BaseTester，移除 sorted_output 标志（始终排序），同时也在 wherefrom 中搜索类基类进行检测。[rnix，2011-05-08]

• 在 utils.AttributeAccess 中移除无用的 try/except。[rnix，2011-05-08]

• 将 instance_property 装饰器添加到 utils 中。[rnix，2011-05-06]

• 添加 FixedChildren 和 GetattrChildren 部分。[chaoflow，2011-04-22]

0.9.2

• 在 Nodifiy 部分上添加 __nonzero__ 总是返回 True。[rnix，2011-03-15]

0.9.1

• 为迁移目的，为 node.base.Node 提供与 zodict.Node 相同的行为。[rnix，2011-02-08]

0.9

• 使其工作 [rnix，chaoflow 等]