Package: boto3-type-annotations-with-docs
boto3_type_annotationsA programmatically created package that definesboto3services as stand in classes with type annotations.boto3is
an incredibly useful, well designed interface to the AWS API. However, we live in an age where even free IDEs like
PyCharm CE have full code completion (IntelliSense). Becauseboto3's services are created at runtime, IDEs aren't
able to index its code in order to provide code completion or infer the type of these services or of the objects created
by them. Even if it was able to do so, clients and service resources are created using a service agnostic factory method
and are only identified by a string argument of that method. IDEs don't parse arguments to infer the return type of a
method, and they probably shouldn't. Meaning that the only way for an IDE to know the type of a client created byboto3.client('<service>')is for it to be explicitly declared in type annotations, type comments, or docstrings, which
brings us back to the original problem of services being defined at runtime. All of that to say that working withboto3can be very frustrating at times.To reduce this frustration,boto3_type_annotationsdefines stand in classes for the clients, service resources,
paginators, and waiters provided byboto3's services. Even though these services are created byboto3are created at
runtime, they are still full fledged Python objects, and AWS has been nice enough to include documentation in the
docstrings of these objects' methods. By parsing those docstrings, we can retrieve the types of method
arguments--also, which arguments are required and which may be omitted--and the types of their return
values. With that, we have everything we need to create objects which mimic the class structure ofboto3's objects.
And with Python'stypingmodule, we can annotate the methods of the stand in objects with the types which we've
parsed. What this means is that we can use these stand in objects to declare the type ofboto3service objects in our
own code.With or Without DocstringsThis package is available both with docstrings, namedboto3_type_annotations_with_docson PyPi (which contains the
same documentation you'll find online), and without, namedboto3_type_annotationson PyPi. The reason for this is
that, for a python package,boto3_type_annotations_with_docsis HUGE.boto3_type_annotationsis pretty large itself
at 2.2 MB, butboto3_type_annotations_with_docsdwarfs it at 41 MB. Being thatboto3andbotocoreadd up to be 34
MB, this is likely not ideal for many use cases. However, there are use cases in which you may want documentation in
your IDE, during development for example. A possible workflow for this use case is detailed below.InstallationWithout docs:pip install boto3_type_annotationsWith docs:pip install boto3_type_annotations_with_docsUsageRegardless of which deployment package you install, you'll still import the same package,boto3_type_annotations.
Its constituent packages and modules can be used to declare the type ofboto3objects. For instance, everybody's
favorite, 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.clientHow Is This Package Different Frompyboto3?pyboto3has been a useful package which was created for the same purpose and using the same methodology as this
package. It does have its shortcomings, though. For one, it only defines clients, no service resources, waiters, or
paginators. Two, it defines2 clients as modules when the objects created byboto3are classes. This seems
nitpicky until you realize that modules can't be used to declare type with type annotations. Even a variable in the
outermost scope of a module would require rst docstring to declare its type. Also, and this is actually is nitpicky,
the package structure doesn't mimic that ofboto3--which you can see in the documentation i.e.sqs.ServiceResource,s3.Bucket,ec2.waiter.InstanceExists. Though I don't want to purport that this is perfectly one to one with what is
in the docs. For instance, there's not much consistency in the docs as far as casing. You'll sometimes seeS3.Waiter.BucketExistsand in other placessqs.Bucket. I chose to go with the pep8 guidelines where module names are
in snake case and classes are in Pascal case.Development Workflow With DocstringAs mentioned above, there may be scenarios in which you would want to have docstrings in development, but not want
to package a 41MB dependency with your production code. To accommodate this and similar scenarios, I decided to provide
two deployment packages, each containing aboto3_type_annotationspackage. So, one workflow may be to have two
requirements files: requirements.txt and requirements-dev.txt (boto3does something similar in that they have
requirements.txt for the API resource and requirements-docs.txt for building documentation.). These two files would
look like this:requirements.txtboto3_type_annotations
# other dependenciesrequirements-dev.txtboto3_type_annotations_with_docs
# other dependenciesYou would then installrequirements.txtin production andrequirements-dev.txtin development. Because both
deployment packages define theboto3_type_annotationspackage, you won't have to change your code. You just need to
install the appropriate deployment package.Custom BuildsIn cases when you're only using a small number ofboto3services, you may not want to depend on a package containing
every service available. To provide a bit more flexibility, this package provides a way to create a custom build of
theboto3_type_annotationspackage. Theconfigs/directory contains configurations forboto3_type_annotationsandboto3_type_annnotations_with_docs, along with a couple example configurations.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.The preceding configuration is the contents ofconfig/example.essentials.yaml. Whenbuild.pyis run with this
config, it will parse and write the ec2, rds, sqs, sns, lambda, and s3 services with docstrings and including all
clients, service resources, paginators, and waiters.$pythonbuild_scripts/build.py../configs/example.essentials.yamlIt will create a directory namedboto3_type_annotations_essentialsin the root directory of the repository. That directory will contain a python module namedboto3_type_annotations,
a license file, and asetup.pyfile. Now all you need to do is package everything up and install it.$pythonsetup.pysdistbdist_wheel

$pip3installdist/boto3_type_annotations_essentials-0.2.4-py3-none-any.whl--userTODOCreate an "essentials" deployment package only containing often used services like Lambda, S3, SQS, and CloudFormationPackage related services into separate deployment packages, to create smaller packages containing only services
which are essential to a certain use case, group EC2 and RDS for instance.Create custom builds. If a project only uses S3's service resource, provide a way to build a deployment package
containing just that package. This would require some sort of configuration and more mature build script.Reduce the size ofboto3_type_annotations_with_docs. I'm already cutting out extraneous new lines and some
whitespaces which reduced the size by 10 MB(!), but I'd like to see it closer to the 34 MB ofboto3+botocore.