diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..3aa1c51 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/acky.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/acky.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/acky" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/acky" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/source/AWS.rst b/docs/source/AWS.rst new file mode 100644 index 0000000..3321671 --- /dev/null +++ b/docs/source/AWS.rst @@ -0,0 +1,59 @@ +.. _AWS: + +================================ +A Guide to acky's AWS connection +================================ + +If you haven't already, you'll need to `set up your AWS config +`_. + +Once your credentials are set up, you will be ready to create an AWS object. + + +Creating an AWS object +---------------------- + +Creating an acky AWS object is as simple as providing a region and profile:: + + >>> import acky.aws + >>> aws = acky.aws.AWS('', '') + +Using the AWS object +-------------------- + +Currently, acky's AWS object can be used to access the EC2, IAM, RDS, SQS, +STS, and S3 interfaces. For example:: + + >>> aws.ec2.ElasticIPs.get() + [{u'Domain': 'standard', + u'InstanceId': 'i-d3adb33f', + u'PublicIp': '8.8.8.8'}, + {u'Domain': 'standard', + u'InstanceId': 'i-1337c0de', + u'PublicIp': '8.8.4.4'}] + +Specific instances can also be created from the aws objects:: + + >>> import acky.ec2 + >>> ec2 = acky.ec2.EC2(aws) + +Properties +---------- + +The aws object has other useful properties for introspection:: + + >>> aws.userinfo + {u'Arn': 'arn:aws:iam::000000000000:user/acky-test', + u'CreateDate': '2014-06-17T14:40:37Z', + u'Path': '/', + u'UserId': 'FFFFFFFFFFFFFFFFFFFFF', + u'UserName': 'acky-test'} + >>> aws.username + 'acky-test' + >>> aws.account_id + '000000000000' + >>> aws.environment + {'account': '000000000000', + 'date': '2014-07-29T16:21:21.916412', + 'region': 'us-east-1', + 'username': 'acky-tester'} diff --git a/docs/source/EC2.rst b/docs/source/EC2.rst new file mode 100644 index 0000000..34195c4 --- /dev/null +++ b/docs/source/EC2.rst @@ -0,0 +1,168 @@ +.. _EC2: + +=================================== +An Overview of acky's EC2 Interface +=================================== + +This guide focuses on the acky interface to Amazon's Elastic Compute Cloud. +You should already have :doc:`installed acky ` and have `configured an +aws profile `_. + +:doc:`ElasticIPs ` +------------------------------- + +:doc:`Elastic IPs ` can be used to provide robustness to both +classic EC2 domains and VPCs. + +.. function:: acky.ec2.ElasticIPs.get([filters=None]) + + List all EIPs and their associated information. Filters are supported. + +.. function:: acky.ec2.ElasticIPs.create([vpc=False]) + + Set ``vpc=True`` to create a VPC EIP. By default, an EIP + will be created for an EC2-Classic instance. + +.. function:: acky.ec2.ElasticIPs.destroy(eip_or_aid[, disassociate]) + + Release an EIP. Classic instances pass in the PublicIp for the first + parameter. For VPC instances, the first parameter is the allocation id. By + default, no attempt will be made to disassociate the address before + releasing it. + +.. function:: acky.ec2.ElasticIPs.associate(eip_or_aid[, instance_id[,\ + network_interface_id[,\ + private_ip]]]) + + Associate an EIP with a given instance or network interface. If + the EIP was allocated for a VPC instance, an AllocationId(aid) must + be provided instead of a PublicIp. + +.. function:: acky.ec2.ElasticIPs.disassociate(eip_or_aid) + + Classic instances pass in the PublicIp. VPC instances pass in an allocation + id. + +:doc:`Instances ` +---------------------------- + +Acky's :doc:`Instances ` interface provides a reusable Launcher for +convinience of configuration. + +.. function:: acky.ec2.Instances.get([filters=None]) + + List all EIPs and their associated information. Filters are supported. + +.. function:: acky.ec2.Instances.create(ami, count[, config=None]) + + Using the ``create()`` method is equivalent to calling the launcher once. + +.. function:: acky.ec2.Instances.destroy(instance_id) + + Terminate an instance by id. + +.. function:: acky.ec2.Instances.control(instances, action) + + Control a given instance using any of the supported action verbs: + ``start``, ``stop``, ``reboot``, ``terminate``, ``protect``, ``unprotect``. + +.. function:: acky.ec2.Instances.Launcher([config=None]) + + Returns a launcher that stores the given configuration. More convinience + features are described on the :doc:`Instances ` page. + +:doc:`KeyPairs ` +---------------------------- + +Acky's :doc:`KeyPairs ` interface provides a simple interface to +create keypairs. + +.. function:: acky.ec2.KeyPairs.get([filters=None]) + + Lists all keypairs and their associated info. Filters are supported. + +.. function:: acky.ec2.KeyPairs.create(key_name) + +.. function:: acky.ec2.KeyPairs.destroy(key_name) + +:doc:`PlacementGroups ` +---------------------------------------- + +.. function:: acky.ec2.PlacementGroups.get([filters=None]) + +.. function:: acky.ec2.PlacementGroups.create(group_name[, strategy="cluster"]) + +.. function:: acky.ec2.PlacementGroups.destroy(pg) + +:doc:`SecurityGroups ` +---------------------------------------- + +.. function:: acky.ec2.SecurityGroups.get([filters=None[, exclude_vpc=False]) + +.. function:: acky.ec2.SecurityGroups.create(name, description[, vpc=None]) + +.. function:: acky.ec2.SecurityGroups.destroy(sg) + +:doc:`IpPermissions ` +------------------------------------ + +.. function:: acky.ec2.IpPermissions.modify(api_action, sgid, other, proto_spec) + +.. function:: acky.ec2.IpPermissions.add(sgid, other, proto_spec[, direction="in"]) + +.. function:: acky.ec2.IpPermissions.remove(sgid, other, proto_spec[, direction="in"]) + +:doc:`Volumes ` +------------------------ + +.. function:: acky.ec2.Volumes.get([filters=None]) + + List EBS Volume info. + +.. function:: acky.ec2.Volumes.create(az, size_or_snap[, volume_type=None[, iops=None]]) + + Create an EBS Volume using an availability-zone and size_or_snap parameter, + encrypted by default. If the volume is crated from a snapshot, + (str)size_or_snap denotes the snapshot id. Otherwise, (int)size_or_snap + denotes the amount of GiB's to allocate. iops must be set if the volume + type is io1. + +.. function:: acky.ec2.Volumes.destroy(volume_id) + + Delete a volume by volume-id. Returns True on success. + +.. function:: acky.ec2.Volumes.attach(volume_id, instance_id, device_path) + + Attach a volume to an instance, exposing it with a device name. + +.. function:: acky.ec2.Volumes.detach(volume_id[, instance_id=''[, device_path=''[, force=False]]]) + + Detach a volume from an instance. + +:doc:`Snapshots ` +---------------------------- + +.. function:: acky.ec2.Snapshots.get([filters=None]) + +.. function:: acky.ec2.Snapshots.create(volume_id[, description=None]) + +.. function:: acky.ec2.Snapshots.destroy(snapshot_id) + +:doc:`Subnets ` +------------------------ + +.. function:: acky.ec2.Subnets.get([filters=None]) + +.. function:: acky.ec2.Subnets.create(vpc_id, cidr, availability_zone) + +.. function:: acky.ec2.Subnets.destroy(subnet_id) + +:doc:`Tags ` +------------------------ + +.. function:: acky.ec2.Tags.get([filters=None]) + +.. function:: acky.ec2.Tags.create(resource_ids, tags) + +.. function:: acky.ec2.Tags.destroy(resource_ids, tags) + diff --git a/docs/source/ElasticIPs.rst b/docs/source/ElasticIPs.rst new file mode 100644 index 0000000..033edd5 --- /dev/null +++ b/docs/source/ElasticIPs.rst @@ -0,0 +1,58 @@ +.. _ElasticIPs: + +============================================== +An Introduction to acky's Elastic IP Interface +============================================== + +`Elastic IPs `_ +(EIPs) enable high levels of durability for Amazon cloud instances. + +Creating one requires an :doc:`AWS` session object. + +Allocating New EIPs +------------------- + +Creating EIPs is straightforward:: + + >>> aws.ec2.ElasticIPs.create() + {u'Domain': 'standard', + u'PublicIp': '8.8.8.8', + 'ResponseMetadata': {'RequestId': '5d52723a-838a-4a04-b1a1-90c03ca54da7'}} + +``create()`` allocates an EIP on a classic domain by default. To create an EIP +for VPC instances, set ``vpc=True``:: + + >>> aws.ec2.ElasticIPs.create(vpc=True) + {u'AllocationId': 'eipalloc-13371337', + u'Domain': 'vpc', + u'PublicIp': '8.8.4.4', + 'ResponseMetadata': {'RequestId': '49bbfd1f-652b-48fe-a8f8-f2864b85d83f'}} + +Releasing EIPs +-------------- + +Releasing EIPs from a classic domain is just as simple as allocating them:: + + >>> aws.ec2.ElasticIPs.destroy('8.8.8.8') + True + +Note that EIPs allocated for VPC instances must be released using their +allocation id:: + + >>> aws.ec2.ElasticIPs.destroy('eipalloc-13371337') + True + +Listing EIPs +------------ + +The ElasticIPCollection.get method fetches all bound EIPs:: + + >>> aws.ec2.ElasticIPs.get() + [{u'Domain': 'standard', + u'InstanceId': 'i-d3adb33f', + u'PublicIp': '8.8.8.8'}, + {u'Domain': 'standard', + u'InstanceId': 'i-1337c0de', + u'PublicIp': '8.8.4.4'}] + +An optional filter can also be passed using ``filters=``. diff --git a/docs/source/Instances.rst b/docs/source/Instances.rst new file mode 100644 index 0000000..c7eef30 --- /dev/null +++ b/docs/source/Instances.rst @@ -0,0 +1,125 @@ +.. _Instances: + +======================================================= +An Introduction to acky's Instance Management Interface +======================================================= + +Instances are your virtual servers in the Amazon AWS cloud. This guide will +show you how to create, control, protect, and list instances using the acky +API library. + +Creating one requires an :doc:`AWS` session object. + +Lanching new instances +---------------------- + +Creating new Instances at minimum requires an AMI and an instance count:: + + >>> aws.ec2.Instances.create('ami-fedcba98', 1) + [{u'AmiLaunchIndex': 0, + u'Architecture': 'x86_64', + u'BlockDeviceMappings': [], + u'ClientToken': None, + u'EbsOptimized': False, + u'Hypervisor': 'xen', + u'ImageId': 'ami-ffffffff', + u'InstanceId': 'i-ffffffff', + u'InstanceType': 'm1.small', + u'KernelId': 'aki-ffffffff', + u'LaunchTime': '2014-07-28T22:20:32.000Z', + u'Monitoring': {u'State': 'disabled'}, + u'NetworkInterfaces': [], + u'Placement': {u'AvailabilityZone': 'us-east-1d', + u'GroupName': None, + u'Tenancy': 'default'}, + u'PrivateDnsName': None, + u'ProductCodes': [], + u'PublicDnsName': None, + u'RootDeviceName': '/dev/sda1', + u'RootDeviceType': 'ebs', + u'SecurityGroups': [{u'GroupId': 'secure', u'GroupName': 'default'}], + u'State': {u'Code': 0, u'Name': 'pending'}, + u'StateReason': {u'Code': 'pending', u'Message': 'pending'}, + u'StateTransitionReason': None, + u'VirtualizationType': 'paravirtual'}] + +Additional configuration options may be passed in using the ``config=`` +optional parameter. + +Advanced Instance Launching +--------------------------- + +acky has a configurable launcher to make instance launching more convenient:: + + >>> launcher = aws.ec2.Instances.Launcher() + +Configuration attributes can be passed in to the ``Launcher()`` using a +dictionary:: + + >>> launcher = aws.ec2.Instances.Launcher({'InstanceType': 'm3.large', + 'KeyName': 'uswest-test-key'}) + +Alternatively, ``Launcher`` attributes can be set as needed:: + + >>> launcher.InstanceType = 'm3.large' + >>> launcher.KeyName = 'uswest-test-key' + +Now lauching them is simple:: + + launcher.launch('ami-12345678', 1) + [{u'AmiLaunchIndex': 0, + u'Architecture': 'x86_64', + u'BlockDeviceMappings': [], + u'ClientToken': None, + u'EbsOptimized': False, + u'Hypervisor': 'xen', + u'ImageId': 'ami-ffffffff', + u'InstanceId': 'i-ffffffff', + u'InstanceType': 'm1.small', + u'KernelId': 'aki-ffffffff', + u'LaunchTime': '2014-07-28T22:20:32.000Z', + u'Monitoring': {u'State': 'disabled'}, + u'NetworkInterfaces': [], + u'Placement': {u'AvailabilityZone': 'us-east-1d', + u'GroupName': None, + u'Tenancy': 'default'}, + u'PrivateDnsName': None, + u'ProductCodes': [], + u'PublicDnsName': None, + u'RootDeviceName': '/dev/sda1', + u'RootDeviceType': 'ebs', + u'SecurityGroups': [{u'GroupId': 'secure', u'GroupName': 'default'}], + u'State': {u'Code': 0, u'Name': 'pending'}, + u'StateReason': {u'Code': 'pending', u'Message': 'pending'}, + u'StateTransitionReason': None, + u'VirtualizationType': 'paravirtual'}] + +Controlling Instances +--------------------- + +The InstanceCollection.control() method handles starting, stopping, +terminating, protecting, and unprotecting instances:: + + >>> ec2.Instances.control('i-ffffffff', 'stop') + >>> ec2.Instances.control('i-ffffffff', 'start') + >>> ec2.Instances.control('i-ffffffff', 'reboot') + >>> ec2.Instances.control('i-ffffffff', 'protect') + >>> ec2.Instances.control('i-ffffffff', 'unprotect') + >>> ec2.Instances.control('i-ffffffff', 'terminate') + +Listing Instances +----------------- + +The InstanceCollection.get() method fetches all instances owned:: + + >>> ec2.Instances.get() + [{u'AmiLaunchIndex': 0, + u'Architecture': 'x86_64', + . + . + . + u'State': {u'Code': 16, u'Name': 'running'}, + u'StateTransitionReason': None, + u'VirtualizationType': 'paravirtual'}] + +An optional filter can also be passed using ``filters=``. diff --git a/docs/source/Keypairs.rst b/docs/source/Keypairs.rst new file mode 100644 index 0000000..4a2566f --- /dev/null +++ b/docs/source/Keypairs.rst @@ -0,0 +1,42 @@ +.. _Keypairs: + +======================================== +A Guide to acky's EC2 Key Pair Interface +======================================== + +Creating a keypair requires an :doc:`AWS` session object. + +Making Keys +----------- + +To create a key pair:: + + >>> import acky.aws + >>> aws = acky.aws.AWS('us-east-1', 'my_profile') + >>> aws.ec2.KeyPairs.create('acky-test-key') + {u'KeyFingerprint': 'ff:00:ff:00:ff:00:ff:00:ff:00:ff:00:ff:00:ff:00:ff:00:ff:00', + u'KeyMaterial': '-----RSA PRIVATE KEY-----', + u'KeyName': 'acky-test-key', + 'ResponseMetadata': {'RequestId': 'da093fd3-fae6-4f4d-bec2-f1567575dcf6'}} + +Deleting Keys +------------- + +To delete a key pair:: + + >>> aws.ec2.KeyPairs.destroy('acky-test-key') + {'ResponseMetadata': {'RequestId': '9b4a86bd-7785-40f5-8725-eddd69dabc5b'}, + 'return': 'true'} + +Listing Keys +------------ + +To list all existing keys:: + + >>> aws.ec2.KeyPairs.get() + [{u'KeyFingerprint': 'ff:00:ff:00:ff:00:ff:00:ff:00:ff:00:ff:00:ff:00:ff:00:ff:00', + u'KeyName': 'acky-test-key'}, + {u'KeyFingerprint': 'ff:00:ff:00:ff:00:ff:00:ff:00:ff:00:ff:00:ff:00:ff:00:ff:00', + u'KeyName': 'acky-test-2'}] + +this method takes in an optional ``filters=`` argument. diff --git a/docs/source/S3.rst b/docs/source/S3.rst new file mode 100644 index 0000000..62a2f79 --- /dev/null +++ b/docs/source/S3.rst @@ -0,0 +1,81 @@ +.. _s3: + +====================================== +An Introduction to acky's S3 Interface +====================================== + +This tutorial focuses on the acky interface to Amazon S3. +This guide requires knowledge of how to use an :doc:`acky.aws.AWS` object. + +Creating Buckets and Objects +---------------------------- + +.. function:: acky.s3.create(url) + + Creating buckets takes in a bucket name or path:: + + >>> aws.s3.Bucket.create('s3://ackytest2') + {u'Location': '/ackytest2'} + + Note that the s3://bucket/key path syntax is required:: + + >>> aws.s3.Bucket.create('ackytest2') + InvalidURL: URL scheme must be s3:// + +Destroying Buckets and Objects +------------------------------ + +.. function:: acky.s3.destroy(url[, recursive=False]) + + Destroy a bucket, directory, or file. Specifying recursive=True + recursively deletes all subdirectories and files:: + + >>> aws.s3.destroy("s3://ackytest2", recursive=True) + '' + + Recursive deletion must be used for non-empty buckets. + +Listing Buckets and Objects +--------------------------- + +.. function:: acky.s3.get([url=None[, delimiter="/"]]) + + Listing all buckets couldn't be easier:: + + >>> aws.s3.get() + [{u'CreationDate': '2014-07-07T18:28:09.000Z', u'Name': 'ackytest0'}, + {u'CreationDate': '2014-07-01T21:45:46.000Z', u'Name': 'ackytest1'}] + + To get objects inside a bucket, specify the bucket as an argument:: + + >>> aws.s3.get("s3://ackytest0") + [{u'ETag': '"d41d8cd98f00b204e9800998ecf8427e"', + u'Key': 'obj0', + u'LastModified': '2014-07-03T16:56:04.000Z', + u'Owner': {u'DisplayName': 'aus-eng-ops-aws-sbx', + u'ID': '854d81f6b20fcb343152ca3f58bb1cba9f17e2b10e0fdb320f567ce15e217fa8'}, + u'Size': 0, + u'StorageClass': 'STANDARD'}, + {u'ETag': '"b672eeca80968471a07f1c56c823627b"', + u'Key': 'obj1', + u'LastModified': '2014-07-03T20:29:51.000Z', + u'Owner': {u'DisplayName': 'aus-eng-ops-aws-sbx', + u'ID': '854d81f6b20fcb343152ca3f58bb1cba9f17e2b10e0fdb320f567ce15e217fa8'}, + u'Size': 1024, + u'StorageClass': 'STANDARD'}] + +Uploading and Downloading Files +------------------------------- + +.. function:: acky.s3.upload(local_path, remote_url) + +.. function:: acky.s3.download(remote_url, local_path[, buffer_size=8*1024]) + +Moving and Copying +------------------ + +.. function:: acky.s3.copy(local_path, remote_url) + +.. function:: acky.s3.move(src_url, dst_url) + + diff --git a/docs/source/Volumes.rst b/docs/source/Volumes.rst new file mode 100644 index 0000000..e28daca --- /dev/null +++ b/docs/source/Volumes.rst @@ -0,0 +1,89 @@ +.. _Volumes: + +========================================== +An Introduction to acky's Volume Interface +========================================== + +This tutorial requires an :doc:`AWS` session object. + +Creating Volumes +---------------- + +The ``create()`` method takes in flexible parameters. The first parameter is +a required availability zone. The second parameter is either a size +specification in GiB, or a snapshot id:: + + >> aws.ec2.Volumes.create('us-east-1d', 10) + {u'Attachments': [], + u'AvailabilityZone': 'us-east-1d', + u'CreateTime': '2014-07-29T18:21:16.033Z', + u'Encrypted': True, + 'ResponseMetadata': {'RequestId': '588b6792-1a08-47f5-800d-560caf5611c6'}, + u'Size': 10, + u'SnapshotId': None, + u'State': 'creating', + u'Tags': [], + u'VolumeId': 'vol-d8525a94', + u'VolumeType': 'standard'} + +``volume_type``, ``iops``, and ``encrypted`` are optional parameters. Note +that ``encrypted=True`` by default. + +Attaching and Detaching +----------------------- + +The ``attach()`` and ``detach()`` methods are used to add and remove instances +from an existing volume. + +To attach to an instance:: + + >>> aws.ec2.Volumes.attach('vol-d8525a94', 'i-12341234', '/dev/sda1') + +To detach from an instance:: + + >>> aws.ec2.Volumes.deatach('vol-d8525a94') + + +Deleting Volumes +---------------- + +The ``destroy()`` method takes care of volume deletion with just the +``volume_id`` parameter:: + + >>> aws.ec2.Volumes.destroy('vol-d8525a94') + True + +Listing Volumes +--------------- + +The ``get()`` method fetches all existing volumes and their associated info:: + + >>> aws.ec2.Volumes.get() + [{u'Attachments': [{ + u'AttachTime': '2014-07-01T09:27:32.000Z', + u'DeleteOnTermination': True, + u'Device': '/dev/sda1', + u'InstanceId': 'i-f6bed1a4', + u'State': 'attached', + u'VolumeId': 'vol-40441d0c'}], + u'AvailabilityZone': 'us-east-1d', + u'CreateTime': '2014-07-01T09:27:32.178Z', + u'Encrypted': False, + u'Size': 8, + u'SnapshotId': 'snap-b047276d', + u'State': 'in-use', + u'VolumeId': 'vol-40441d0c', + u'VolumeType': 'standard'}, + {u'Attachments': [], + u'AvailabilityZone': 'us-east-1d', + u'CreateTime': '2014-07-07T21:08:48.523Z', + u'Encrypted': False, + u'Size': 10, + u'SnapshotId': None, + u'State': 'available', + u'VolumeId': 'vol-f5bb9bb9', + u'VolumeType': 'standard' + }] + + +An optional filter can also be passed using ``filters=``. diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..adfc64b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,258 @@ +# -*- coding: utf-8 -*- +# +# acky documentation build configuration file, created by +# sphinx-quickstart on Fri Jun 20 14:25:33 2014. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'acky' +copyright = u'2014, Matthew Wedgwood' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.0' +# The full version, including alpha/beta/rc tags. +release = '0.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'ackydoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'acky.tex', u'acky Documentation', + u'Matthew Wedgwood', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'acky', u'acky Documentation', + [u'Matthew Wedgwood'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'acky', u'acky Documentation', + u'Matthew Wedgwood', 'acky', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..934c8bd --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,129 @@ +.. _index: + +============ +Acky Library +============ + +The Acky library provides a consistent interface to +`AWS `_. Based on botocore, it abstracts some of the +API work involved and allows the user to interact with AWS APIs in a +consistent way with minimal overhead. + +Acky takes a different approach to the API from libraries such as the venerable +`Boto `_. Rather than model AWS objects as Python +objects, Acky simply wraps the API to provide a more consistent interface. Most +objects in AWS are represented as collections in Acky, with get(), create(), +and destroy() methods. The get() method always accepts a filter map, no matter +if the underlying API method does. + +In cases where the API's multitude of parameters would make for awkward method +calls (as is the case with EC2's :doc:`RunInstances`), Acky provides a utility class +whose attributes can be set before executing the API call. + +Getting Started +--------------- + +Acky uses a botocore-style AWS credential configuration, the same as the +official AWS CLI. Before you use Acky, you'll need to `set up your config +`_. + +Once your credentials are set up, using acky is as simple as creating an +instance of the AWS object:: + + from acky.aws import AWS + aws = AWS('us-east-1', '') + instances = aws.ec2.Instances.get(filters={'tag:Name': 'web-*'}) + print('Found {0} web servers'.format(len(instances))) + for instance in instances: + print(' {0}'.format(instance['PublicDnsName']) + +Currently Supported Services +---------------------------- + +The expected module structure for Acky follows. Many APIs are not yet +implemented, but those that are can be considered stable. + + +* AWS + + * username (property) + * userinfo (property) + * account_id (property) + * environment (property) + + * :doc:`Autoscaling ` + + * :doc:`EC2 ` + + * regions + * zones + * ACEs + * ACLs + * :doc:`ElasticIPs ` + * :doc:`Instances ` + * IpPermissions + * :doc:`KeyPairs ` + * PlacementGroups + * SecurityGroups + * Snapshots + * Subnets + * VPCs + * :doc:`Volumes ` + + * IAM + + * Users + * Groups + * Keys + + * RDS + + * engine_versions + * Instances + * Snapshots + * EventSubscriptions + * SecurityGroups + * SecurityGroupRules + + * SQS + + * Queues + * Messages + + * STS + + * GetFederationToken + * GetSessionToken + + * :doc:`S3 ` + + +Other services will be added in future versions. + +Installing acky +--------------- + +acky is available in PyPI and is installable via pip:: + + pip install acky + +You may also install acky from source, perhaps from the GitHub repo:: + + git clone https://github.com/RetailMeNot/acky.git + cd acky + python setup.py install + +.. toctree:: + :maxdepth: 2 + + tutorial/index + reference/* + topics/index + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` +