Skip to content
Browse files

Much more documentation work. Some privatizing of instance variables.

  • Loading branch information...
1 parent 75d9984 commit f878ad11d0e57c09eb845c69a558d59f694f06f2 @gtaylor committed Nov 7, 2012
View
54 doc_src/ref-route53.rst
@@ -6,6 +6,10 @@
route53 API Reference
=====================
+Below you will find the entire publicly exposed API for python-route53
+documented in its entirety. If you find anything missing, lacking detail,
+or incorrect, please file an issue on the `issue tracker`_.
+
route53
=======
@@ -30,6 +34,52 @@ route53.hosted_zone
route53.resource_record_set
===========================
-.. automodule:: route53.resource_record_set
+.. autoclass:: route53.resource_record_set.AResourceRecordSet
+ :members:
+ :undoc-members:
+ :inherited-members:
+
+.. autoclass:: route53.resource_record_set.AAAAResourceRecordSet
:members:
- :undoc-members:
+ :undoc-members:
+ :inherited-members:
+
+.. autoclass:: route53.resource_record_set.CNAMEResourceRecordSet
+ :members:
+ :undoc-members:
+ :inherited-members:
+
+.. autoclass:: route53.resource_record_set.MXResourceRecordSet
+ :members:
+ :undoc-members:
+ :inherited-members:
+
+.. autoclass:: route53.resource_record_set.NSResourceRecordSet
+ :members:
+ :undoc-members:
+ :inherited-members:
+
+.. autoclass:: route53.resource_record_set.PTRResourceRecordSet
+ :members:
+ :undoc-members:
+ :inherited-members:
+
+.. autoclass:: route53.resource_record_set.SOAResourceRecordSet
+ :members:
+ :undoc-members:
+ :inherited-members:
+
+.. autoclass:: route53.resource_record_set.SPFResourceRecordSet
+ :members:
+ :undoc-members:
+ :inherited-members:
+
+.. autoclass:: route53.resource_record_set.SRVResourceRecordSet
+ :members:
+ :undoc-members:
+ :inherited-members:
+
+.. autoclass:: route53.resource_record_set.TXTResourceRecordSet
+ :members:
+ :undoc-members:
+ :inherited-members:
View
15 route53/connection.py
@@ -13,23 +13,22 @@ class Route53Connection(object):
:py:class:`HostedZone <route53.hosted_zone.HostedZone>` instances.
.. warning:: Do not instantiate instances of this class yourself.
-
- :attr endpoint_version: The date-based API version.
"""
endpoint_version = '2012-02-29'
+ """The date-based API version. Mostly visible for your reference."""
def __init__(self, aws_access_key_id, aws_secret_access_key):
"""
:param str aws_access_key_id: An account's access key ID.
:param str aws_secret_access_key: An account's secret access key.
"""
- self.endpoint = 'https://route53.amazonaws.com/%s/' % self.endpoint_version
- self.xml_namespace = 'https://route53.amazonaws.com/doc/%s/' % self.endpoint_version
- self.aws_access_key_id = aws_access_key_id
- self.aws_secret_access_key = aws_secret_access_key
- self.transport = RequestsTransport(self)
+ self._endpoint = 'https://route53.amazonaws.com/%s/' % self.endpoint_version
+ self._xml_namespace = 'https://route53.amazonaws.com/doc/%s/' % self.endpoint_version
+ self._aws_access_key_id = aws_access_key_id
+ self._aws_secret_access_key = aws_secret_access_key
+ self._transport = RequestsTransport(self)
def _send_request(self, path, data, method):
"""
@@ -45,7 +44,7 @@ def _send_request(self, path, data, method):
:returns: An lxml Element root.
"""
- response_body = self.transport.send_request(path, data, method)
+ response_body = self._transport.send_request(path, data, method)
root = etree.fromstring(response_body)
#print(prettyprint_xml(root))
return root
View
64 route53/hosted_zone.py
@@ -10,7 +10,7 @@ class HostedZone(object):
Each hosted zone has its own metadata and configuration information.
.. warning:: Do not instantiate this directly yourself. Go through
- one of the methods on:py:class:`route53.connection.Route53Connection`.
+ one of the methods on :py:class:`route53.connection.Route53Connection`.
"""
def __init__(self, connection, id, name, caller_reference,
@@ -45,15 +45,14 @@ def __str__(self):
@property
def nameservers(self):
"""
- If this HostedZone was instantiated by ListHostedZones, the nameservers
- attribute didn't get populated. If the user requests it, we'll
- lazy load by querying it in after the fact. It's safe to cache like
- this since these nameserver values won't change.
-
:rtype: list
:returns: A list of nameserver strings for this hosted zone.
"""
+ # If this HostedZone was instantiated by ListHostedZones, the nameservers
+ # attribute didn't get populated. If the user requests it, we'll
+ # lazy load by querying it in after the fact. It's safe to cache like
+ # this since these nameserver values won't change.
if not self._nameservers:
# We'll just snatch the nameserver values from a fresh copy
# via GetHostedZone.
@@ -66,6 +65,14 @@ def nameservers(self):
def record_sets(self):
"""
Queries for the Resource Record Sets that are under this HostedZone.
+ This is typically the way to go to find specific record sets, or
+ to list them all.
+
+ We don't currently implement any filtering convenience method,
+ since it is very easy to do this yourself, catered to your own needs.
+ For example, if you find your match, you may choose to stop iterating
+ on the generator, potentially saving yourself extra API queries
+ (behind the scenes).
.. warning:: This result set can get pretty large if you have a ton
of records.
@@ -83,9 +90,12 @@ def delete(self, force=False):
to add records, or do anything else with the zone. You'd need to
re-create it, as zones are read-only after creation.
- :keyword bool force: If ``True``, delete the HostedZone, even if it
+ :keyword bool force: If ``True``, delete the
+ :py:class:`HostedZone <route53.hosted_zone.HostedZone>`, even if it
means nuking all associated record sets. If ``False``, an
- exception is raised if this HostedZone has record sets.
+ exception is raised if this
+ :py:class:`HostedZone <route53.hosted_zone.HostedZone>`
+ has record sets.
:rtype: dict
:returns: A dict of change info, which contains some details about
the request.
@@ -172,7 +182,7 @@ def create_a_record(self, name, values, ttl=60, weight=None, region=None,
set_identifier=None, alias_hosted_zone_id=None,
alias_dns_name=None):
"""
- Creates an A record attached to this hosted zone.
+ Creates and returns an A record attached to this hosted zone.
:param str name: The fully qualified name of the record to add.
:param list values: A list of value strings for the record.
@@ -194,7 +204,9 @@ def create_a_record(self, name, values, ttl=60, weight=None, region=None,
the DNS name for the ELB that the Alias points to.
:rtype: tuple
:returns: A tuple in the form of ``(rrset, change_info)``, where
- ``rrset`` is the newly created AResourceRecordSet instance.
+ ``rrset`` is the newly created
+ :py:class:`AResourceRecordSet <route53.resource_record_set.AResourceRecordSet>`
+ instance.
"""
self._halt_if_already_deleted()
@@ -329,38 +341,6 @@ def create_ptr_record(self, name, values, ttl=60):
return self._add_record(PTRResourceRecordSet, **values)
- def create_soa_record(self, name, values, ttl=60, weight=None, region=None,
- set_identifier=None):
- """
- Creates a SOA record attached to this hosted zone.
-
- :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
- 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
- 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
- resource record sets that have the same combination of DNS name
- and type. 1-128 chars.
- :rtype: tuple
- :returns: A tuple in the form of ``(rrset, change_info)``, where
- ``rrset`` is the newly created SOAResourceRecordSet instance.
- """
-
- self._halt_if_already_deleted()
-
- # Grab the params/kwargs here for brevity's sake.
- values = locals()
- del values['self']
-
- return self._add_record(SOAResourceRecordSet, **values)
-
def create_spf_record(self, name, values, ttl=60):
"""
Creates a SPF record attached to this hosted zone.
View
65 route53/resource_record_set.py
@@ -1,4 +1,5 @@
from route53.change_set import ChangeSet
+from route53.exceptions import Route53Error
class ResourceRecordSet(object):
"""
@@ -68,8 +69,12 @@ def hosted_zone(self):
"""
Queries for this record set's HostedZone.
- :rtype: HostedZone
- :returns: The matching HostedZone for this record set.
+ .. note:: This is not cached, it will always return the latest
+ data from the Route 53 API.
+
+ :rtype: :py:class:`HostedZone <route53.hosted_zone.HostedZone>`
+ :returns: The matching :py:class:`HostedZone <route53.hosted_zone.HostedZone>`
+ for this record set.
"""
return self.connection.get_hosted_zone_by_id(self.zone_id)
@@ -142,6 +147,11 @@ class AResourceRecordSet(ResourceRecordSet):
* Regular A records.
* Alias A records. These point at an ELB instance instead of an IP.
+
+ Create these via
+ :py:meth:`HostedZone.create_a_record <route53.hosted_zone.HostedZone.create_a_record>`.
+ Retrieve them via
+ :py:meth:`HostedZone.record_sets <route53.hosted_zone.HostedZone.record_sets>`.
"""
rrset_type = 'A'
@@ -182,71 +192,104 @@ def is_alias_record_set(self):
class AAAAResourceRecordSet(ResourceRecordSet):
"""
- Specific AAAA record class.
+ Specific AAAA record class. Create these via
+ :py:meth:`HostedZone.create_a_record <route53.hosted_zone.HostedZone.create_aaaa_record>`.
+ Retrieve them via
+ :py:meth:`HostedZone.record_sets <route53.hosted_zone.HostedZone.record_sets>`.
"""
rrset_type = 'AAAA'
class CNAMEResourceRecordSet(ResourceRecordSet):
"""
- Specific CNAME record class.
+ Specific CNAME record class. Create these via
+ :py:meth:`HostedZone.create_a_record <route53.hosted_zone.HostedZone.create_cname_record>`.
+ Retrieve them via
+ :py:meth:`HostedZone.record_sets <route53.hosted_zone.HostedZone.record_sets>`.
"""
rrset_type = 'CNAME'
class MXResourceRecordSet(ResourceRecordSet):
"""
- Specific MX record class.
+ Specific MX record class. Create these via
+ :py:meth:`HostedZone.create_a_record <route53.hosted_zone.HostedZone.create_mx_record>`.
+ Retrieve them via
+ :py:meth:`HostedZone.record_sets <route53.hosted_zone.HostedZone.record_sets>`.
"""
rrset_type = 'MX'
class NSResourceRecordSet(ResourceRecordSet):
"""
- Specific NS record class.
+ Specific NS record class. Create these via
+ :py:meth:`HostedZone.create_a_record <route53.hosted_zone.HostedZone.create_ns_record>`.
+ Retrieve them via
+ :py:meth:`HostedZone.record_sets <route53.hosted_zone.HostedZone.record_sets>`.
"""
rrset_type = 'NS'
class PTRResourceRecordSet(ResourceRecordSet):
"""
- Specific PTR record class.
+ Specific PTR record class. Create these via
+ :py:meth:`HostedZone.create_a_record <route53.hosted_zone.HostedZone.create_ptr_record>`.
+ Retrieve them via
+ :py:meth:`HostedZone.record_sets <route53.hosted_zone.HostedZone.record_sets>`.
"""
rrset_type = 'PTR'
class SOAResourceRecordSet(ResourceRecordSet):
"""
- Specific SOA record class.
+ Specific SOA record class. Retrieve these via
+ :py:meth:`HostedZone.record_sets <route53.hosted_zone.HostedZone.record_sets>`.
+ They can't be created.
"""
rrset_type = 'SOA'
+ def delete(self):
+ """
+ SOA records can't be created or deleted.
+ """
+
+ raise Route53Error("SOA records can't be created or deleted.")
+
class SPFResourceRecordSet(ResourceRecordSet):
"""
- Specific SPF record class.
+ Specific SPF record class. Create these via
+ :py:meth:`HostedZone.create_a_record <route53.hosted_zone.HostedZone.create_spf_record>`.
+ Retrieve them via
+ :py:meth:`HostedZone.record_sets <route53.hosted_zone.HostedZone.record_sets>`.
"""
rrset_type = 'SPF'
class SRVResourceRecordSet(ResourceRecordSet):
"""
- Specific SRV record class.
+ Specific SRV record class. Create these via
+ :py:meth:`HostedZone.create_a_record <route53.hosted_zone.HostedZone.create_srv_record>`.
+ Retrieve them via
+ :py:meth:`HostedZone.record_sets <route53.hosted_zone.HostedZone.record_sets>`.
"""
rrset_type = 'SRV'
class TXTResourceRecordSet(ResourceRecordSet):
"""
- Specific TXT record class.
+ Specific TXT record class. Create these via
+ :py:meth:`HostedZone.create_a_record <route53.hosted_zone.HostedZone.create_txt_record>`.
+ Retrieve them via
+ :py:meth:`HostedZone.record_sets <route53.hosted_zone.HostedZone.record_sets>`.
"""
rrset_type = 'TXT'
View
6 route53/transport.py
@@ -33,7 +33,7 @@ def endpoint(self):
:returns: The Route53 API endpoint to query against.
"""
- return self.connection.endpoint
+ return self.connection._endpoint
def _hmac_sign_string(self, string_to_sign):
"""
@@ -55,7 +55,7 @@ def _hmac_sign_string(self, string_to_sign):
# Just use SHA256, since we're all running modern versions
# of Python (right?).
new_hmac = hmac.new(
- self.connection.aws_secret_access_key.encode('utf-8'),
+ self.connection._aws_secret_access_key.encode('utf-8'),
digestmod=hashlib.sha256
)
new_hmac.update(string_to_sign.encode('utf-8'))
@@ -77,7 +77,7 @@ def get_request_headers(self):
# Amazon's super fun auth token.
auth_header = "AWS3-HTTPS AWSAccessKeyId=%s,Algorithm=HmacSHA256,Signature=%s" % (
- self.connection.aws_access_key_id,
+ self.connection._aws_access_key_id,
signing_key,
)
View
2 route53/xml_generators/change_resource_record_set.py
@@ -109,7 +109,7 @@ def change_resource_record_set_writer(connection, change_set, comment=None):
e_root = etree.Element(
"ChangeResourceRecordSetsRequest",
- xmlns=connection.xml_namespace
+ xmlns=connection._xml_namespace
)
e_change_batch = etree.SubElement(e_root, "ChangeBatch")
View
2 route53/xml_generators/created_hosted_zone.py
@@ -17,7 +17,7 @@ def create_hosted_zone_writer(connection, name, caller_reference, comment):
e_root = etree.Element(
"CreateHostedZoneRequest",
- xmlns=connection.xml_namespace
+ xmlns=connection._xml_namespace
)
e_name = etree.SubElement(e_root, "Name")

0 comments on commit f878ad1

Please sign in to comment.
Something went wrong with that request. Please try again.