fixes #29 - skeleton and docs on how to create new service classes

awslimitchecker/services/newservice.py.example

@@ -0,0 +1,119 @@
+"""
+awslimitchecker/services/NewService.py
+
+The latest version of this package is available at:
+<https://github.com/jantman/awslimitchecker>
+
+################################################################################
+Copyright 2015 Jason Antman <jason@jasonantman.com> <http://www.jasonantman.com>
+
+    This file is part of awslimitchecker, also known as awslimitchecker.
+
+    awslimitchecker is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    awslimitchecker is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with awslimitchecker.  If not, see <http://www.gnu.org/licenses/>.
+
+The Copyright and Authors attributions contained herein may not be removed or
+otherwise altered, except to add the Author attribution of a contributor to
+this work. (Additional Terms pursuant to Section 7b of the AGPL v3)
+################################################################################
+While not legally required, I sincerely request that anyone who finds
+bugs please submit them at <https://github.com/jantman/pydnstest> or
+to me via email, and that you send any contributions or improvements
+either as a pull request on GitHub, or to me via email.
+################################################################################
+
+AUTHORS:
+Jason Antman <jason@jasonantman.com> <http://www.jasonantman.com>
+################################################################################
+"""
+
+import abc  # noqa
+import boto
+import logging
+
+from .base import _AwsService
+from ..limit import AwsLimit
+
+logger = logging.getLogger(__name__)
+
+
+class _NewServiceService(_AwsService):
+
+    service_name = 'NewService'
+
+    def connect(self):
+        if self.conn is None:
+            logger.debug("Connecting to {n}".format(
+                n=self.service_name))
+            # TODO: set this to the correct connection method:
+            self.conn = boto.connect_NewService()
+            logger.info("Connected to {n}".format(
+                n=self.service_name))
+
+    def find_usage(self):
+        """
+        Determine the current usage for each limit of this service,
+        and update corresponding Limit via
+        :py:meth:`~.AwsLimit._add_current_usage`.
+        """
+        logger.debug("Checking usage for service {n}".format(
+            n=self.service_name))
+        self.connect()
+        for lim in self.limits.values():
+            lim._reset_usage()
+        # TODO: update your usage here, i.e.:
+        """
+        u = (count of something, from boto)
+        u_id = (resource id from AWS)
+        self.limits['Number of u']._add_current_usage(u, aws_type='U', id=u_id)
+        """
+        logger.debug("Done checking usage.")
+
+    def get_limits(self):
+        """
+        Return all known limits for this service, as a dict of their names
+        to :py:class:`~.AwsLimit` objects.
+
+        :returns: dict of limit names to :py:class:`~.AwsLimit` objects
+        :rtype: dict
+        """
+        if self.limits != {}:
+            return self.limits
+        limits = {}
+        # TODO: declare Limits here, i.e.:
+        """
+        limits['Number of u'] = AwsLimit(
+            'Number of u',
+            self,
+            40000,
+            self.warning_threshold,
+            self.critical_threshold,
+            limit_type='U',
+        )
+
+        """
+        return limits
+
+    def required_iam_permissions(self):
+        """
+        Return a list of IAM Actions required for this Service to function
+        properly. All Actions will be shown with an Effect of "Allow"
+        and a Resource of "*".
+
+        :returns: list of IAM Action strings
+        :rtype: list
+        """
+        # TODO: update this to be all IAM permissions required for find_usage() to work
+        return [
+            "NewService:SomeAction",
+        ]

docs/source/development.rst

@@ -67,13 +67,20 @@ Adding New Services
 All Services are sublcasses of :py:class:`~awslimitchecker.services.base._AwsService`
 using the :py:mod:`abc` module.
 
-1. In ``awslimitchecker.services`` copy ``service_skeleton.py`` to ``new_service_name.py``.
-2. Change the file path on line 2 in the docstring, the class name, and the
-   ``service_name`` class attribute.
+1. The new service name should be all lowercase, preferably one word (if not one word, it should be underscore-separated).
+   In ``awslimitchecker/services``, where ``some_service`` is the name of the AWS Service you're adding support for:
+
+.. code-block:: bash
+
+   SVC_NAME='some_service' sed "s/NewService/${SVC_NAME}/gi" newservice.py.example > ${SVC_NAME}.py
+
+2. Find all "TODO" comments in the newly-created file; these have instructions on things to change for new services.
+   Add yourself to the Authors section in the header if desired.
 3. Add an import line for the new service in ``awslimitchecker/services/__init__.py``.
 4. Write at least high-level tests; TDD is greatly preferred.
 5. Implement all abstract methods from :py:class:`~awslimitchecker.services.base._AwsService` and any other methods you need;
-   small, easily-testable methods are preferred. Ensure all methods have full documentation.
+   small, easily-testable methods are preferred. Ensure all methods have full documentation. For simple services, you need only
+   to search for "TODO" in the new service class you created (#1).
 6. Test your code; 100% test coverage is expected, and mocks should be using ``autospec`` or ``spec_set``.
 7. Ensure the :py:meth:`~awslimitchecker.services.base._AwsService.required_iam_permissions` method of your new class
    returns a list of all IAM permissions required for it to work.