为BOTO3键入批注。在ide中添加代码完成,如pycharm。
boto3-type-annotations的Python项目详细描述
boto3_type_注释
一个以编程方式创建的包,它将boto3
服务定义为具有类型注释的备用类。boto3
是
一个非常有用、设计良好的aws api接口。然而,我们生活在一个自由的时代
pycharm ce具有完整的代码完成(intellisense)。因为boto3的服务是在运行时创建的,所以ide不是
能够索引其代码以提供代码完成或推断这些服务或创建的对象的类型
由他们。即使它能够这样做,客户机和服务资源也是使用与服务无关的工厂方法创建的。
和仅由该方法的字符串参数标识。IDE不解析参数来推断
方法,而它们可能不应该这样做。这意味着ide知道由
boto3.client('<;service>;')
允许在类型注释、类型注释或docstring中显式声明它,其中
让我们回到在运行时定义服务的原始问题。所有这些都是为了说明
boto3
有时会非常令人沮丧。
为了减少这种挫败感,boto3_type_annotations
为客户机、服务资源定义备用类,
Paginator和由Boto3服务提供的服务员。即使这些服务是由
运行时,它们仍然是成熟的python对象,aws已经足够好地在
这些对象方法的docstring。通过解析这些docstring,我们可以检索方法的类型
参数——还有,哪些参数是必需的,哪些可以省略——以及它们的返回类型
价值观。有了它,我们就可以创建模拟boto3对象的类结构的对象了。
使用python的输入模块,我们可以用
解析。这意味着我们可以使用这些替代对象来声明
自己的代码。
带或不带docstrings
这个包可以与docstring一起使用,命名为boto3\u type\u annotations\u with\u docs
on pypi(它包含
您可以在网上找到相同的文档),而且没有,在pypi上命名为boto3_type_annotations
。原因是
对于一个python包来说,boto3_type_annotations_with_docs
是巨大的。boto3_type_注释本身相当大
在2.2 MB,但是
boto3_type_annotations_with_docs
比它小41 MB。因为boto3
和botocore
加起来是34
mb,这对于许多用例来说可能并不理想。但是,有些用例中可能需要文档
你的ide,例如在开发过程中。下面详细介绍了此用例的可能工作流。
安装
没有文档:
pip install boto3_type_annotations
带文档:
pip install boto3_type_annotations_with_docs
用法
无论您安装的是哪个部署包,都将导入相同的包,boto3\u type\u annotations
。
它的组成包和模块可用于声明boto3
对象的类型。例如,每个人
最爱,s3:
importboto3fromboto3_type_annotations.s3importClient,ServiceResourcefromboto3_type_annotations.s3.waiterimportBucketExistsfromboto3_type_annotations.s3.paginatorimportListObjectsV2# With type annotationsclient:Client=boto3.client('s3')client.create_bucket(Bucket='foo')# Not only does your IDE knows the name of this method, # it knows the type of the `Bucket` argument too!# It also, knows that `Bucket` is required, but `ACL` isn't!# Waiters and paginators and defined also...waiter:BucketExists=client.get_waiter('bucket_exists')waiter.wait('foo')paginator:ListObjectsV2=client.get_paginator('list_objects_v2')response=paginator.paginate(Bucket='foo')# Along with service resources.resource:ServiceResource=boto3.resource('s3')bucket=resource.Bucket('bar')bucket.create()# With type commentsclient=boto3.client('s3')# type: Clientresponse=client.get_object(Bucket='foo',Key='bar')# In docstringsclassFoo:def__init__(self,client):""" :param client: It's an S3 Client and the IDE is gonna know what it is! :type client: Client """self.client=clientdefbar(self):""" :rtype: Client """self.client.delete_object(Bucket='foo',Key='bar')returnself.client
这个包与pyboto3
有何不同?
pyboto3
是一个有用的软件包,它的创建目的和方法与此相同
包裹。不过,它确实有缺点。首先,它只定义客户机,没有服务资源,服务生或
小精灵。第二,当boto3
创建的对象是类时,它将2个客户机定义为模块。这似乎
挑剔,直到你意识到模块不能用类型注释来声明类型。即使是一个变量
模块的最外层作用域将需要rst docstring来声明其类型。而且,这实际上是吹毛求疵,
包结构与boto3
的结构不同,您可以在文档中看到,即sqs.serviceresource
,
s3.bucket
,ec2.waiter.instanceexists
。尽管我不想说这是完美的一对一
在文件里。例如,文档中的大小写没有太多的一致性。你有时会看到
s3.waiter.bucket存在于
和其他位置。我选择遵循PEP8指南,其中模块名是
在snake情况下,类在pascal情况下。
使用docstring开发工作流
如前所述,可能存在这样的情况:您希望开发docstring,但不希望
将41MB的依赖项打包到生产代码中。为了适应这种和类似的情况,我决定提供
两个部署包,每个包都包含一个boto3_type_annotations
包。因此,一个工作流可能有两个
需求文件:requirements.txt和requirements-dev.txt(boto3
做了一些类似的事情
API资源的Requirements.txt和建筑文档的Requirements-docs.txt)。这两份文件
如下所示:
requirements.txt
boto3_type_annotations
# other dependencies
需求-dev.txt
boto3_type_annotations_with_docs
# other dependencies
然后在生产环境中安装requirements.txt
,在开发环境中安装requirements-dev.txt
。因为两者
部署包定义boto3_type_注释
包,您不必更改代码。你只需要
安装适当的展开包。
自定义生成
如果您只使用少量的boto3
服务,则可能不希望依赖包含
所有可用的服务。为了提供更大的灵活性,这个包提供了一种创建
boto3_type_注释
包。configs/
目录包含boto3_类型注释的配置
boto3_type_annotations_with_docs
,以及几个示例配置。
services:# A list of services. Use `boto3.session.Session.get_available_services()` to view services. -ec2-rds-sqs-sns-lambda-s3with_docs:true# Include docstrings.with_clients:true# Include client classeswith_service_resources:true# Include service resources.with_paginators:true# Include paginatorswith_waiters:true# Include waiterspackage_name:boto3_type_annotations_essentials# The name of the package.module_name:boto3_type_annotations# The name of the module.version:0.2.4# Version of the package.readme:README.md# Path to readme file.license:LICENSE# Path to file containing license.
前面的配置是config/example.essentials.yaml
的内容。当build.py
运行时
config,它将使用docstring解析和编写ec2、rds、sqs、sns、lambda和s3服务,包括
客户、服务资源、分页器和服务生。
$ python build_scripts/build.py ../configs/example.essentials.yaml
它将创建一个名为boto3\u type\u annotations\u essentials的目录
在存储库的根目录中。该目录将包含一个名为
boto3_type_annotations的python模块,
一个许可文件和一个
setup.py
文件。现在您只需将所有内容打包并安装即可。
$ python setup.py sdist bdist_wheel $ pip3 install dist/boto3_type_annotations_essentials-0.2.4-py3-none-any.whl --user
待办事项
创建一个仅包含常用服务(如lambda、s3、sqs和cloudformation)的"Essentials"部署包
将相关服务打包到单独的部署包中,以创建仅包含服务的较小包 对于某个用例来说是必不可少的,例如ec2和rds组。
创建自定义生成。如果项目只使用s3的服务资源,则提供一种构建部署包的方法 只有那个包裹。这需要某种配置和更成熟的构建脚本。减小
boto3_type_annotations_with_docs的大小。我已经在剪掉多余的新线和一些 将大小减少了10 MB(!)的空格但我愿意我希望看到它更接近34 MB的boto3
+botocore