Permalink
Browse files

Quickstart touchup.

  • Loading branch information...
1 parent f878ad1 commit 91ec7738a6bec7da343fa9ab6d4f1a8343c1bcee @gtaylor committed Nov 8, 2012
Showing with 94 additions and 34 deletions.
  1. +66 −17 doc_src/quickstart.rst
  2. +8 −1 doc_src/ref-route53.rst
  3. +4 −0 route53/__init__.py
  4. +16 −16 route53/hosted_zone.py
@@ -25,52 +25,75 @@ Next, you'll want to import the module::
import route53
-You can then instantiate a connection to Route53::
+You can then instantiate a connection to Route53 via :py:func:`route53.connect`::
conn = route53.connect(
aws_access_key_id='YOURACCESSKEYHERE',
aws_secret_access_key='YOURSECRETACCESSKEYHERE',
)
-You are now ready to roll.
+You are now ready to roll. Continue reading to see how much fun there is
+to be had (hooray!).
Listing Hosted Zones
--------------------
-The :py:meth:`list_hosted_zones` method returns a generator of
-:py:class:`HostedZone` instances::
+Let's say you want to retrieve a representation of all of your currently
+existing hosted zones. These roughly correspond to domains, ala
+angry-squirrel.com, or python.org.
+
+The :py:meth:`Route53Connection.list_hosted_zones <route53.connection.Route53Connection.list_hosted_zones>`
+method returns a generator of
+:py:class:`HostedZone <route53.hosted_zone.HostedZone>` instances::
# This is a generator.
for zone in conn.list_hosted_zones():
+ # You can then do various things to the zone.
print(zone.name)
+ # Perhaps you want to see the record sets under this zone
+ for record_set in zone.record_sets:
+ print(record_set)
+ # Or maybe you don't like this zone, and want to blow it away.
+ zone.delete()
Creating a Hosted Zone
----------------------
-The :py:meth:`create_hosted_zone` method creates Hosted Zones::
+The :py:meth:`Route53Connection.create_hosted_zone <route53.connection.Route53Connection.create_hosted_zone>`
+method creates hosted zones, and returns a tuple that contains a
+:py:class:`HostedZone <route53.hosted_zone.HostedZone>`
+instance, and some details about the pending change from the API::
new_zone, change_info = conn.create_hosted_zone(
'some-domain.com.', comment='An optional comment.'
)
# You can then manipulate the HostedZone.
print("Zone ID", new_zone.id)
+ # This has some details about the change from the API.
+ print(change_info)
-In this case, ``new_zone`` is a new :py:class:`HostedZone` instance, and
-``change_info`` is a dict with some details about the changes pending (from
-the Route 53 API).
+In this case, ``new_zone`` is a new :py:class:`HostedZone <route53.hosted_zone.HostedZone>`
+instance, and ``change_info`` is a dict with some details about the changes
+pending (from the Route 53 API).
Retrieving a Hosted Zone
------------------------
-The :py:meth:`get_hosted_zone_by_id` method retrieves a specific Hosted Zone,
-by Zone ID::
+The
+:py:meth:`Route53Connection.get_hosted_zone_by_id <route53.connection.Route53Connection.get_hosted_zone_by_id>`
+method retrieves a specific hosted zone, by Zone ID::
zone = conn.get_hosted_zone_by_id('ZONE-ID-HERE')
+.. note:: A Zone ID is not the same thing as the domain name. The Zone ID
+ is a unique string identifier for the hosted zone, as per Route 53's
+ records.
+
Deleting a Hosted Zone
----------------------
-Simply call the :py:meth:`delete` method on a :py:class:`HostedZone` to delete
+Simply call the :py:meth:`HostedZone.delete <route53.hosted_zone.HostedZone.delete>`
+method on a :py:class:`HostedZone <route53.hosted_zone.HostedZone>` to delete
it::
zone = conn.get_hosted_zone_by_id('ZONE-ID-HERE')
@@ -87,7 +110,8 @@ Creating a record set
---------------------
Depending on which kind of record set you'd like to create, choose the
-appropriate ``create_*_record`` method on :py:class:`HostedZone`. The methods
+appropriate ``create_*_record`` method on
+:py:class:`HostedZone <route53.hosted_zone.HostedZone>`. The methods
return one of the :py:class:`ResourceRecordSet` sub-classes::
new_record, change_info = zone.create_a_record(
@@ -97,21 +121,46 @@ return one of the :py:class:`ResourceRecordSet` sub-classes::
values=['8.8.8.8'],
)
+ # Or maybe we want a weighted round-robin set.
+ wrr_record1, change_info = zone.create_a_record(
+ name='wrrtest.some-domain.com.',
+ values=['8.8.8.8'],
+ weight=1
+ set_identifier='set123,
+ )
+ wrr_record2, change_info = zone.create_a_record(
+ name='wrrtest.some-domain.com.',
+ values=['6.6.6.6'],
+ weight=2
+ set_identifier='set123,
+ )
+
Listing record sets
-------------------
-In order to list record sets, use the ``record_sets`` property on
-:py:class:`HostedZone`. Note that we don't currently implement any convenience
+In order to list record sets, use the
+:py:meth:`HostedZone.record_sets <route53.hosted_zone.HostedZone.record_sets>`
+property on :py:class:`HostedZone <route53.hosted_zone.HostedZone>`.
+Note that we don't currently implement any convenience
methods for finding record sets, so this is the way to go::
+ # Note that this is a fully-qualified domain name.
+ name_to_match = 'fuzzy.bunny.com.'
for record_set in zone.record_sets:
- print(record_set)
+ if record_set.name == name_to_match:
+ print(record_set)
+ # Stopping early may save some additional HTTP requests,
+ # since zone.record_sets is a generator.
+ break
+
+While it may seem like extra work to craft these filters yourself, it does
+prevent needless additional iteration, and keeps the API more concise.
Changing a record set
---------------------
-Simply change one of the attributes on the :py:class:`ResourceRecordSet`
-instance and call its :py:meth:`save` method::
+Simply change one of the attributes on the various :py:class:`ResourceRecordSet`
+sub-classed instances and call its :py:meth:`save` method::
record_set.values = ['8.8.8.7']
record_set.save()
@@ -82,4 +82,11 @@ route53.resource_record_set
.. autoclass:: route53.resource_record_set.TXTResourceRecordSet
:members:
:undoc-members:
- :inherited-members:
+ :inherited-members:
+
+route53.exceptions
+==================
+
+.. automodule:: route53.exceptions
+ :members:
+ :undoc-members:
View
@@ -10,6 +10,10 @@
def connect(aws_access_key_id=None, aws_secret_access_key=None, **kwargs):
"""
+ Instantiates and returns a :py:class:`route53.connection.Route53Connection`
+ instance, which is how you'll start your interactions with the Route 53
+ API.
+
:keyword str aws_access_key_id: Your AWS Access Key ID
:keyword str aws_secret_access_key: Your AWS Secret Access Key
@@ -187,15 +187,15 @@ def create_a_record(self, name, values, ttl=60, weight=None, region=None,
:param str name: The fully qualified name of the record to add.
:param list values: A list of value strings for the record.
:keyword int ttl: The time-to-live of the record (in seconds).
- :keyword int weight: For weighted record sets only. Among resource record
+ :keyword int weight: *For weighted record sets only*. Among resource record
sets that have the same combination of DNS name and type, a value
that determines what portion of traffic for the current resource
record set is routed to the associated location. Ranges from 0-255.
- :keyword str region: For latency-based record sets. The Amazon EC2 region
+ :keyword str region: *For latency-based record sets*. The Amazon EC2 region
where the resource that is specified in this resource record set
resides.
- :keyword str set_identifier: For weighted and latency resource record
- sets only. An identifier that differentiates among multiple
+ :keyword str set_identifier: *For weighted and latency resource record
+ sets only*. An identifier that differentiates among multiple
resource record sets that have the same combination of DNS name
and type. 1-128 chars.
:keyword str alias_hosted_zone_id: Alias A records have this specified.
@@ -225,15 +225,15 @@ def create_aaaa_record(self, name, values, ttl=60, weight=None, region=None,
:param str name: The fully qualified name of the record to add.
:param list values: A list of value strings for the record.
:keyword int ttl: The time-to-live of the record (in seconds).
- :keyword int weight: For weighted record sets only. Among resource record
+ :keyword int weight: *For weighted record sets only*. Among resource record
sets that have the same combination of DNS name and type, a value
that determines what portion of traffic for the current resource
record set is routed to the associated location. Ranges from 0-255.
- :keyword str region: For latency-based record sets. The Amazon EC2 region
+ :keyword str region: *For latency-based record sets*. The Amazon EC2 region
where the resource that is specified in this resource record set
resides.
- :keyword str set_identifier: For weighted and latency resource record
- sets only. An identifier that differentiates among multiple
+ :keyword str set_identifier: *For weighted and latency resource record
+ sets only*. An identifier that differentiates among multiple
resource record sets that have the same combination of DNS name
and type. 1-128 chars.
:rtype: tuple
@@ -257,15 +257,15 @@ def create_cname_record(self, name, values, ttl=60, weight=None, region=None,
:param str name: The fully qualified name of the record to add.
:param list values: A list of value strings for the record.
:keyword int ttl: The time-to-live of the record (in seconds).
- :keyword int weight: For weighted record sets only. Among resource record
+ :keyword int weight: *For weighted record sets only*. Among resource record
sets that have the same combination of DNS name and type, a value
that determines what portion of traffic for the current resource
record set is routed to the associated location. Ranges from 0-255.
- :keyword str region: For latency-based record sets. The Amazon EC2 region
+ :keyword str region: *For latency-based record sets*. The Amazon EC2 region
where the resource that is specified in this resource record set
resides.
- :keyword str set_identifier: For weighted and latency resource record
- sets only. An identifier that differentiates among multiple
+ :keyword str set_identifier: *For weighted and latency resource record
+ sets only*. An identifier that differentiates among multiple
resource record sets that have the same combination of DNS name
and type. 1-128 chars.
:rtype: tuple
@@ -389,15 +389,15 @@ def create_txt_record(self, name, values, ttl=60, weight=None, region=None,
:param str name: The fully qualified name of the record to add.
:param list values: A list of value strings for the record.
:keyword int ttl: The time-to-live of the record (in seconds).
- :keyword int weight: For weighted record sets only. Among resource record
+ :keyword int weight: *For weighted record sets only*. Among resource record
sets that have the same combination of DNS name and type, a value
that determines what portion of traffic for the current resource
record set is routed to the associated location. Ranges from 0-255.
- :keyword str region: For latency-based record sets. The Amazon EC2 region
+ :keyword str region: *For latency-based record sets*. The Amazon EC2 region
where the resource that is specified in this resource record set
resides.
- :keyword str set_identifier: For weighted and latency resource record
- sets only. An identifier that differentiates among multiple
+ :keyword str set_identifier: *For weighted and latency resource record
+ sets only*. An identifier that differentiates among multiple
resource record sets that have the same combination of DNS name
and type. 1-128 chars.
:rtype: tuple

0 comments on commit 91ec773

Please sign in to comment.