版本1 API客户端
v1pysdk的Python项目详细描述
一个python版本sdk
通过pypi（pip）正式发布为：v1pysdk
此软件包的旧版本（与此版本号一起流动）作为"v1pysdk unoffice"分发
versionone python sdk是versionone api的开源和社区支持的客户端。
作为一个开源和社区支持的项目，versionone python sdk不受versionone的正式支持。
也就是说，有很多解决问题的方法：
- stackoverflow：用于向versionone开发社区提问。
- github问题：提交其他人可能试图解决的问题。
一般来说，stackoverflow是获得对版本号python sdk支持的最佳选择。
python sdk版本的源代码是免费的、开源的，我们鼓励您通过提交pull请求来改进它！
概述
实例化连接
要进行交互，必须首先创建v1meta对象的实例。这要求您指定如何连接到服务器。
有两个选项，直接指定实例的完整URL或指定单个详细信息。
fromv1pysdkimportV1MetawithV1Meta(instance_url='http://localhost/VersionOne',# any instance, scheme, or address values will be ignoredusername='admin',password='admin')asv1:
或者
fromv1pysdkimportV1MetawithV1Meta(address='localhost',instance='VersionOne',scheme='http',#optional, defaults to httpsusername='admin',password='admin')asv1:
为了进行身份验证，提供了两种方法，如上面所示的用户名和密码，或者访问令牌。
令牌是通过Web界面登录到versionone、转到用户配置文件、转到应用程序并创建新的应用程序来创建的。这将提供类似于1.2cfhe7nkoo1kov/x8wlpw1nasjg=的访问令牌。请保守这个秘密，因为它是您实例上特定用户的秘密API访问密钥。
若要使用访问令牌，请将其用作密码，并设置指示它确实是访问令牌的标志。这将不再需要用户名。
fromv1pysdkimportV1MetawithV1Meta(address='localhost',instance='VersionOne',password='1.2cFHe7NkoO1kOV/x8WLpw1NasJg=',use_password_as_token=True,)asv1:
所有v1资产类型的动态反射：
只是实例化一个vMeta。服务器上定义的所有资产类型都可用 作为实例的属性。元数据只加载一次，因此必须 创建vmeta的新实例以获取元数据更改。各资产类别 为所有资产属性和操作提供属性。
fromv1pysdkimportV1MetawithV1Meta(instance_url='http://localhost/VersionOne',username='admin',password='admin')asv1:user=v1.Member(20)# internal numeric IDprintuser.CreateDate,user.Name
简单访问个人资产：
资产实例是按需创建并缓存的，因此具有相同oid的实例总是 同一个物体。您可以通过将资产id传递给资产类来检索实例：
s=v1.Story(1005)
或者提供一个oid令牌：
s=v1.asset_from_oid('Story:1005')printsisv1.Story(1005)# True
懒散地加载值和关系：
注意：在每个对象上同步发出属性访问请求代价高昂。我们推荐 使用查询语法从相关资产中选择、筛选、聚合和检索值 在单个http事务中。
资产实例是空创建的，如果可用，则使用查询结果创建。服务器是 为当前未获取的属性访问。获取一组基本属性 在第一个未找到的属性上。
epic=v1.Epic(324355)# No data fetched yet.printepic#=> Epic(324355)# Access an attribute.printepic.Name#=> "Team Features"# Now some basic data has been fetchedprintepic#=> Epic(324355).with_data({'AssetType': 'Epic','Description':"Make features easier for new team members",'AssetState':'64','SecurityScope_Name':'Projects','Number':'E-01958','Super_Number':'E-01902','Scope_Name':'Projects','Super_Name':'New Feature Development','Scope':[Scope(314406)],'SecurityScope':[Scope(314406)],'Super':[Epic(312659)],'Order':'-24','Name':'Team Features'})
# And further non-basic data is available, but will cause a request.
printepic.CreateDate#=> '2012-05-14T23:45:14.124'
关系网络可以任意穿越，并根据需要提取资产。
fromv1pysdkimportV1MetawithV1Meta(instance_url='http://localhost/VersionOne',# any instance, scheme, or address values will be ignoredusername='admin',password='admin')asv1:0
因为元数据是作为数据建模的，所以您可以找到"基本"属性的列表：
fromv1pysdkimportV1MetawithV1Meta(instance_url='http://localhost/VersionOne',# any instance, scheme, or address values will be ignoredusername='admin',password='admin')asv1:1
操作：
对资产的操作可以通过对资产实例调用适当的方法来启动：
fromv1pysdkimportV1MetawithV1Meta(instance_url='http://localhost/VersionOne',# any instance, scheme, or address values will be ignoredusername='admin',password='admin')asv1:2
成功时，资产实例数据将失效，因此将在下一次重新获取 属性访问。
遍历一个类型的所有资产
资产类别可以获取该类型的所有资产。这是模棱两可的NT到 "query"、"select"或"where"方法（如果没有参数）。
fromv1pysdkimportV1MetawithV1Meta(instance_url='http://localhost/VersionOne',# any instance, scheme, or address values will be ignoredusername='admin',password='admin')asv1:3
查询
查询对象
资产实例上的select（）、where（）和sort（）方法返回一个查询对象
在此基础上，您可以调用更多的.where（）'s、.select（）'s和.sort（）'s。
查询对象将运行查询。
查询对象上的.first（）、.queryall（）和.requeryall（）方法将立即运行查询。
并返回相应的结果。
find（）可用于在字段上执行服务器端的全词匹配，尽管它是服务器密集型的，
只能匹配一个字段，应使用备用字段。
page（）可用于限制执行服务器端分页的结果。
re queryall（）可以像queryall（）一样使用，但将清除所有以前缓存的数据并重新运行
如果更改了任何查询选项，则使用http查询，以便在仅
响应限制，如page（）已更改。
简单查询语法：
使用.where（attr="value"，…）引入"equals"比较，以及
。选择（"attr"，…）以附加到选择列表。
不支持非"相等"比较（请改用高级查询语法）。
fromv1pysdkimportV1MetawithV1Meta(instance_url='http://localhost/VersionOne',# any instance, scheme, or address values will be ignoredusername='admin',password='admin')asv1:4
高级查询，采用标准v1查询语法。
filter（）运算符将采用任意v1筛选条件。
fromv1pysdkimportV1MetawithV1Meta(instance_url='http://localhost/VersionOne',# any instance, scheme, or address values will be ignoredusername='admin',password='admin')asv1:5
通过分页限制服务器的结果
通过限制 返回的结果与查询匹配。分页要求对返回的项目数进行限制，并且 列表中要返回的第一项的索引。
api允许将索引保留为关闭状态，这假定默认的开始索引为0。
fromv1pysdkimportV1MetawithV1Meta(instance_url='http://localhost/VersionOne',# any instance, scheme, or address values will be ignoredusername='admin',password='admin')asv1:6
或者，可以使用requeryall（）根据更新的内容强制重新查询内容
查询设置，使分页更易于实现。
fromv1pysdkimportV1MetawithV1Meta(instance_url='http://localhost/VersionOne',# any instance, scheme, or address values will be ignoredusername='admin',password='admin')asv1:7
排序
通过指定要排序的列的顺序以及 这些列应该按升序或降序排序。默认的排序顺序是升序。
sort（）的操作类似于select（），其中字段名以引号列出，并且可以作为单独的参数列出
对于单个排序调用、单独的排序调用或两者的混合。
降序排序要求字段名以破折号"—"开头。
字段只能按排序顺序列出一次，重复项将被忽略。
要按名称的反字母顺序排序，请先按估计时间排序，再按详细估计时间排序：
fromv1pysdkimportV1MetawithV1Meta(instance_url='http://localhost/VersionOne',# any instance, scheme, or address values will be ignoredusername='admin',password='admin')asv1:8
匹配搜索
搜索，虽然可能，是非常服务器密集型的，应该尽量避免。服务器端 搜索可以在一个字段中匹配整个单词。由于这个原因，它应该是非常有限的 使用适当的筛选/where命令。
fromv1pysdkimportV1MetawithV1Meta(instance_url='http://localhost/VersionOne',# any instance, scheme, or address values will be ignoredusername='admin',password='admin')asv1:9
高级选择，采用标准v1选择语法。
select（）运算符将允许任意v1"select"术语，并将添加
它们与结果的"数据"映射，键与使用的术语相同。
fromv1pysdkimportV1MetawithV1Meta(address='localhost',instance='VersionOne',scheme='http',#optional, defaults to httpsusername='admin',password='admin')asv1:0
高级筛选和选择
列出所有致力于工作的人正在写的故事
fromv1pysdkimportV1MetawithV1Meta(address='localhost',instance='VersionOne',scheme='http',#optional, defaults to httpsusername='admin',password='admin')asv1:1
简单的创建语法：
gotcha:必须设置所有"必需"属性，否则服务器将拒绝数据。
fromv1pysdkimportV1MetawithV1Meta(address='localhost',instance='VersionOne',scheme='http',#optional, defaults to httpsusername='admin',password='admin')asv1:2
简单的更新语法。
在调用v1meta.commit（）并写出所有脏资产之前，不会写入任何内容。
fromv1pysdkimportV1MetawithV1Meta(address='localhost',instance='VersionOne',scheme='http',#optional, defaults to httpsusername='admin',password='admin')asv1:3
v1元对象还用作上下文管理器，它将在退出时提交脏对象。
fromv1pysdkimportV1MetawithV1Meta(address='localhost',instance='VersionOne',scheme='http',#optional, defaults to httpsusername='admin',password='admin')asv1:4
附件内容
附件文件正文可以在附件实例上使用特殊的"文件数据"属性进行提取或设置。
有关完整示例，请参阅v1pysdk/tests/test_attachment.py文件。
截至/历史查询
查询可以返回过去某个特定点的"截止"数据。.asof（）查询项可以
以ISO日期格式获取时间戳或字符串的列表（或多个位置参数）。
查询针对列表中的每个时间戳运行。返回一个iterable
迭代所有收集的结果。结果都将包含一个数据项
该项目的"截止日期"。
请注意，"截止日期"不是项目先前更改的日期，而是
传入查询的日期相同。
还需要注意的是，诸如"2012-01-01"之类的时间戳是从那天开始的午夜，这
自然排除了当天发生的任何活动。您可能需要指定时间戳
一个特定的小时，或第二天。
执行这些比较时使用的时区是为指定用户配置的时区
在v1元对象中，根据
服务器，
fromv1pysdkimportV1MetawithV1Meta(address='localhost',instance='VersionOne',scheme='http',#optional, defaults to httpsusername='admin',password='admin')asv1:5
轮询（TOdo）
将提供一个简单的回调api来挂钩资产更改
fromv1pysdkimportV1MetawithV1Meta(address='localhost',instance='VersionOne',scheme='http',#optional, defaults to httpsusername='admin',password='admin')asv1:6
性能说明
第一次引用每个资产类别时，会向服务器发出http请求。
资产在需要数据项之前不会发出请求。进一步的属性访问 如果上一个请求返回该属性，则缓存。否则将提出新的请求。
收集和使用一组资产的最快方法是使用属性查询
您希望使用包含在选择列表中的。将返回整个结果集
在单个http事务中，如果手动调用触发完整查询的方法之一。
这些方法包括\u iter\uuuu（）（例如join（）使用此方法）、\uuu len\uu（）、queryall（）和requeryall（）。
写入资产不需要读取它们；设置属性并调用提交 函数不调用"读取"管道。写入资产需要每个脏文件一个http post 资产实例。
当提交资产或调用操作时，资产数据将失效，并将 在下一个属性访问时再次读取。对更新进行分组，然后在新的 查询是提高性能的好方法。
gotcha:requeryall（）跟踪查询对象的脏状态，而不是跟踪资产数据的方式
更新后无效。除非查询的条件已更改，否则
不会更新缓存的数据，并且将为访问的每个无效数据项生成新查询。
为了避免这种情况，可以使用在查询对象上添加然后还原查询项来导致
重新查询以实际发生。
requeryall（）在实现分页、更改排序等时非常有用，但它应该
小心使用。它清除所有缓存的数据，以便原始查询中未包含的任何字段
从那以后被取回的也被清除。访问这些字段将提示同一个人
像以前一样查询。若要避免此问题，请在初始查询中包含额外字段，或
为更新后的查询词创建新的查询对象。
待办事项
时刻注意事情
在客户端和服务器之间转换类型（现在所有内容都是字符串）
添加调试日志记录
增强测试覆盖率
"其他资产"上下文中的"资产创建模板和创建"
正确处理多值属性，包括删除值。
安装
运行python setup.py install，或者将v1pysdk文件夹复制到ythonpath.
修订历史
2018-07-02 v0.6.2-修复一个重要的备忘录错误、错误响应打印、一些http/put调用、身份验证错误处理
由于使用了decorator而导致的一个重要的记忆错误阻止了同一字段超过 在python intepreter的一次调用中更新的同一类型的一项；即 无论v1元对象有多少，只能在python脚本中更新一个故事的标题 被创造出来。它还阻止使用单独的凭据创建v1元对象。
在处理和引发 异常，阻止打印随HTTP 400提供的实际错误响应。
处理ntlm身份验证的方式中的错误阻止引发http 401身份验证错误，并且 处理后，错误将在get/post命令未完成的情况下自动失败。
在python3中创建http post命令时出现错误，导致在没有 需要数据有效载荷。这将防止在v1对象上使用没有参数的操作。
添加了单元测试以确保某些操作正常工作。连接测试以确保凭据错误 还添加了导致可识别的失败连接的结果。专门为确保分离 同一测试中不同v1元对象之间的凭证产生不同的结果，因此 还添加了检查每个v1元对象的备忘录是否正常工作的功能。
2018-06-21 v0.6.1-修复新项创建错误并添加用于创建的单元测试
2018-06-21 v0.6-重新调整以包括一些在0.4到0.5之间丢失的历史变化。
修复了测试，以便它们可以运行并成功，包括添加检查功能的测试 连接和一些基本查询。
已恢复的关键丢失差异： OAuth令牌支持 备忘录修复程序
2018-06-13 v0.5.1-PYPI上传，通过PIP作为"v1Pysdk"提供。
2018-06-12 v0.5-添加了动态python3支持。
将page（）、sort（）、queryall（）、find（）、max_length（）、length（）和len（）用法支持添加到 查询对象。
主存储库已移动到已维护的分叉。
2013-09-27 v0.4-已更正多值关系设置程序代码。它使用了 XML"act"属性的值错误，因此无法正确设置多值属性。音符 此时，无法从多值关系中取消设置值。
2013-07-09 v0.3-为了支持https，在vmeta和v1client中添加了一个"scheme"参数 施工人员。
向vmeta和v1client添加了instance_url关键字参数。这个论点可以是 指定而不是地址、实例路径、方案和端口参数。
对"list（v1.story.name）"等调用进行了性能增强。请求的 如果属性不存在，则将其添加到选择列表中，从而防止http get 对于每个匹配的资产。
一些不好的例子被删除，一些地方的日志记录被清除。
修复ntlm和urllib2的一些问题。（谢谢坎贝尔）
丢失的属性现在返回一个不相似的对象，可以推迟到任何深度。（谢谢巴兹）
许可证
以源和二进制形式重新分配和使用，有无 允许修改，但条件如下 MET：
源代码的重新分发必须保留上述版权 注意，此条件列表和以下免责声明。
以二进制形式重新分配必须复制上述版权 注意，此条件列表和以下免责声明 分发时提供的文档和/或其他材料。
不是versionone，inc.的名字，也不是我的名字TS 贡献者可用于支持或推广来自 未经 versionone公司
本软件由版权所有者和 出资人"原样"和任何明示或默示保证， 包括但不限于 适销性和特定用途的适用性是 否认的在任何情况下，版权所有者或贡献者 对任何直接的，间接的，偶然的，特殊的， 惩戒性或后果性损害（包括但不限于 采购替代货物或服务；使用损失， 数据或利润；或营业中断）无论是什么原因引起的 任何责任理论，无论是在合同中，严格责任，还是 侵权行为（包括疏忽或其他）产生于 使用本软件，即使被告知 这样的损害。
欢迎加入QQ群-->： 979659372
