fixes #68 - PR #64 - cleanup docs; finishes region and STS support

awslimitchecker/connectable.py

@@ -52,14 +52,18 @@ class Connectable(object):
 
     def connect_via(self, driver):
         """
-        Connect to API if not already connected; set self.conn. Use STS to
-        assume a role as another user if self.account_id has been set.
+        Connect to an AWS API and return the connection object. If
+        ``self.account_id`` is None, call ``driver(self.region)``. Otherwise,
+        call :py:meth:`~._get_sts_token` to get STS token credentials using
+        :py:meth:`boto.sts.STSConnection.assume_role` and call ``driver()`` with
+        those credentials to use an assumed role.
 
         :param driver: the connect_to_region() function of the boto
           submodule to use to create this connection
         :type driver: :py:obj:`function`
+        :returns: connected boto service class instance
         """
-        if(self.account_id):
+        if self.account_id is not None:
             logger.debug("Connecting to %s for account %s (STS; %s)",
                          self.service_name, self.account_id, self.region)
             self.credentials = self._get_sts_token()
@@ -76,7 +80,18 @@ def connect_via(self, driver):
         return conn
 
     def _get_sts_token(self):
-        """Attempt to get STS token, exit if fail."""
+        """
+        Assume a role via STS and return the credentials.
+
+        First connect to STS via :py:func:`boto.sts.connect_to_region`, then
+        assume a role using :py:meth:`boto.sts.STSConnection.assume_role`
+        using ``self.account_id`` and ``self.account_role`` (and optionally
+        ``self.external_id``). Return the resulting
+        :py:class:`boto.sts.credentials.Credentials` object.
+
+        :returns: STS assumed role credentials
+        :rtype: :py:class:`boto.sts.credentials.Credentials`
+        """
         logger.debug("Connecting to STS in region %s", self.region)
         sts = boto.sts.connect_to_region(self.region)
         arn = "arn:aws:iam::%s:role/%s" % (self.account_id, self.account_role)

docs/source/cli_usage.rst

@@ -187,7 +187,7 @@ using their IDs).
    AutoScaling/Auto Scaling groups                        50
    AutoScaling/Launch configurations                      50
    EBS/Active snapshots                                   10768
-   EBS/Active volumes                                     3023
+   EBS/Active volumes                                     3025
    EBS/General Purpose (SSD) volume storage (GiB)         47216
    (...)
    VPC/Rules per network ACL                              max: acl-4bd96a2e=4 (acl-4bd96a2e=4, acl-cd9f (...)
@@ -255,9 +255,9 @@ threshold only, and another has crossed the critical threshold):
    (venv)$ awslimitchecker --no-color
    EBS/Active snapshots                                   (limit 10000) CRITICAL: 10768
    EC2/EC2-VPC Elastic IPs                                (limit 5) CRITICAL: 51
-   EC2/Running On-Demand EC2 instances                    (limit 20) CRITICAL: 160
+   EC2/Running On-Demand EC2 instances                    (limit 20) CRITICAL: 166
+   EC2/Running On-Demand m1.small instances               (limit 20) WARNING: 17
    EC2/Running On-Demand m3.medium instances              (limit 20) CRITICAL: 22
-   EC2/Running On-Demand m3.xlarge instances              (limit 20) CRITICAL: 24
    (...)
    RDS/Subnet Groups                                      (limit 20) CRITICAL: 77
    VPC/Internet gateways                                  (limit 5) CRITICAL: 5
@@ -275,7 +275,7 @@ To set the warning threshold of 50% and a critical threshold of 75% when checkin
    (venv)$ awslimitchecker -W 97 --critical=98 --no-color
    EBS/Active snapshots                                   (limit 10000) CRITICAL: 10768
    EC2/EC2-VPC Elastic IPs                                (limit 5) CRITICAL: 51
-   EC2/Running On-Demand EC2 instances                    (limit 20) CRITICAL: 161
+   EC2/Running On-Demand EC2 instances                    (limit 20) CRITICAL: 166
    EC2/Running On-Demand m3.medium instances              (limit 20) CRITICAL: 22
    EC2/Running On-Demand m3.xlarge instances              (limit 20) CRITICAL: 24
    (...)