Add documentation and improve pep8 compliance

CODE_OF_CONDUCT.md

@@ -0,0 +1,15 @@
+# Code Of Conduct
+
+Twilio strives to be an inclusive, tolerant, and welcoming community. We encourage participation from anyone regardless of age, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, political belief, race, religion, or sexual identity and orientation.
+
+> “A gentle word turns away wrath, but a harsh word stirs up anger."
+
+Our users, contributors, and collaborators are expected to treat each other with kindness and respect, to assume good intentions, and to gently correct, where possible, rather than react with escalation. While our goal is to be as accurate as possible, kindness and understanding are more valuable than correctness. Some examples of behavior we will not tolerate include, but is not limited to:
+
+* The use of sexualized language or imagery
+* Unwelcome advances, sexual or otherwise
+* Insults or derogatory comments, or personal or political attacks
+* Publishing others’ private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+If someone is violating this Code of Conduct you may email [[email protected]](mailto:[email protected]) to bring your concern to the Members. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. 

CONTRIBUTING.md

@@ -0,0 +1,160 @@
+# Contributing to `twilio-python`
+
+We'd love for you to contribute to our source code and to make `socless`
+even better than it is today! Here are the guidelines we'd like you to follow:
+
+ - [Code of Conduct](#coc)
+ - [Question or Problem?](#question)
+ - [Issues and Bugs](#issue)
+ - [Feature Requests](#feature)
+ - [Documentation fixes](#docs)
+ - [Submission Guidelines](#submit)
+ - [Coding Rules](#rules)
+
+
+## <a name="coc"></a> Code of Conduct
+
+Help us keep `socless` open and inclusive. Please be kind to and considerate
+of other developers, as we all have the same goal: make `socless` as good as
+it can be.
+
+## <a name="question"></a> Got an API/Product Question or Problem?
+
+If you have questions about how to use `socless`, please contact
+[[email protected]](mailto:[email protected]) with any issues you have.
+
+## <a name="issue"></a> Found an Issue?
+
+If you find a bug in the source code or a mistake in the documentation, you can
+help us by submitting [an issue][issue-link]. If the file in which the error
+exists has this header:
+```
+"""
+This code was generated by
+\ / _    _  _|   _  _
+ | (_)\/(_)(_|\/| |(/_  v1.0.0
+      /       /
+"""
+```
+then it is a generated file and the change will need to be made by us, but
+submitting an issue will help us track it and keep you up-to-date. If the file
+isn't generated, you can help us out even more by submitting a Pull Request with
+a fix.
+
+**Please see the [Submission Guidelines](#submit) below.**
+
+## <a name="feature"></a> Want a Feature?
+
+You can request a new feature by submitting an issue to our
+[GitHub Repository][github]. If you would like to implement a new feature then
+consider what kind of change it is:
+
+* **Major Changes** that you wish to contribute to the project should be
+  discussed first with `socless` contributors in an issue or pull request so
+  that we can develop a proper solution and better coordinate our efforts,
+  prevent duplication of work, and help you to craft the change so that it is
+  successfully accepted into the project.
+* **Small Changes** can be crafted and submitted to the
+  [GitHub Repository][github] as a Pull Request.
+
+## <a name="docs"></a> Want a Doc Fix?
+
+If you want to help improve the docs in the helper library, it's a good idea to
+let others know what you're working on to minimize duplication of effort. Create
+a new issue (or comment on a related existing one) to let others know what
+you're working on.
+
+For large fixes, please build and test the documentation before submitting the
+PR to be sure you haven't accidentally introduced layout or formatting issues.
+
+If you want to help improve the docs at
+[https://www.twilio.com/docs/libraries/python][docs-link], please contact
+[[email protected]](mailto:[email protected]).
+
+## <a name="submit"></a> Submission Guidelines
+
+### Submitting an Issue
+Before you submit your issue search the archive, maybe your question was already
+answered.
+
+If your issue appears to be a bug, and hasn't been reported, open a new issue.
+Help us to maximize the effort we can spend fixing issues and adding new
+features by not reporting duplicate issues. Providing the following information
+will increase the chances of your issue being dealt with quickly:
+
+* **Overview of the Issue** - if an error is being thrown a non-minified stack
+  trace helps
+* **Motivation for or Use Case** - explain why this is a bug for you
+* **`socless` Version(s)** - is it a regression?
+* **Operating System (if relevant)** - is this a problem with all systems or
+  only specific ones?
+* **Reproduce the Error** - provide an isolated code snippet or an unambiguous
+  set of steps.
+* **Related Issues** - has a similar issue been reported before?
+* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point
+  to what might be causing the problem (line of code or commit)
+
+**If you get help, help others. Good karma rules!**
+
+### Submitting a Pull Request
+Before you submit your pull request consider the following guidelines:
+
+* Search [GitHub][github] for an open or closed Pull Request that relates to
+  your submission. You don't want to duplicate effort.
+* Make your changes in a new git branch:
+
+    ```shell
+    git checkout -b my-fix-branch master
+    ```
+
+* Create your patch, **including appropriate test cases**.
+* Follow our [Coding Rules](#rules).
+* Run the full `socless` test suite (aliased by `make test`), and ensure
+  that all tests pass.
+* Commit your changes using a descriptive commit message.
+
+    ```shell
+    git commit -a
+    ```
+  Note: the optional commit `-a` command line option will automatically "add"
+  and "rm" edited files.
+
+* Build your changes locally to ensure all the tests pass:
+
+    ```shell
+    make test
+    ```
+
+* Push your branch to GitHub:
+
+    ```shell
+    git push origin my-fix-branch
+    ```
+
+In GitHub, send a pull request to `socless:master`.
+If we suggest changes, then:
+
+* Make the required updates.
+* Re-run the `socless` test suite to ensure tests are still passing.
+* Commit your changes to your branch (e.g. `my-fix-branch`).
+* Push the changes to your GitHub repository (this will update your Pull Request).
+
+That's it! Thank you for your contribution!
+
+#### After your pull request is merged
+
+After your pull request is merged, you can safely delete your branch and pull
+the changes from the main (upstream) repository.
+
+## <a name="rules"></a> Coding Rules
+
+To ensure consistency throughout the source code, keep these rules in mind as
+you are working:
+
+* All features or bug fixes **must be tested** by one or more tests.
+* All classes and methods **must be documented**.
+
+
+[docs-link]: https://www.twilio.com/docs/libraries/python
+[issue-link]: https://github.com/twilio/socless/issues/new
+[github]: https://github.com/twilio/socless

ISSUE_TEMPLATE.md

@@ -0,0 +1,26 @@
+*Note: These issues are for bugs and feature requests for the helper libraries.
+If you need help or support, please email [email protected] and one of our experts
+will assist you!*
+
+
+**Version:**
+
+### Code Snippet
+```python
+# paste code here
+```
+
+### Exception/Log
+```
+<place exception/log here>
+```
+
+### Steps to Reproduce
+1.
+2.
+3.
+
+
+### Feature Request
+_If this is a feature request, make sure you search Issues for an existing
+request before creating a new one!_

PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,36 @@
+# Description
+
+_Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change._
+
+Fixes #<issue>
+
+
+## Status
+**READY** | **UNDER DEVELOPMENT** | **ON HOLD**
+
+
+## Type of change
+
+_Please delete options that are not relevant._
+
+- Bug fix (non-breaking change which fixes an issue)
+- New feature (non-breaking change which adds functionality)
+- Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- This change requires a documentation update
+- Documentation (fix or adds documentation)
+
+
+# How Has This Been Tested?
+
+_Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration._
+
+- Test A
+- Test B
+
+
+# Checklist:
+
+- [ ] I have performed a self-review of my own code
+- [ ] I have made corresponding changes to the documentation (if applicable)
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes

functions/add_custom_mapping/lambda_function.py

@@ -11,19 +11,24 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License
-from socless import *
-import boto3, os
+import socless
+import boto3
+import os
+
 
 def handle_state(key, value):
     """
     Add a key-value pair to the Socless custom mapping table
     """
-    custom_mappings_table = boto3.resource('dynamodb').Table(os.environ.get('SOCLESS_CUSTOM_MAPPINGS_TABLE'))
+    table_name = os.environ.get('SOCLESS_CUSTOM_MAPPINGS_TABLE')
+    custom_mappings_table = boto3.resource('dynamodb').Table(table_name)
     response = custom_mappings_table.put_item(Item={
         "key": key,
         "value": value
     })
     return response
 
-def lambda_handler(event,context):
-    return socless_bootstrap(event,context,handle_state)
+
+def lambda_handler(event, context):
+    """Lambda function entry point"""
+    return socless_bootstrap(event, context, handle_state)

functions/cache_results/lambda_function.py

@@ -11,7 +11,8 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License
-from socless import *
+import socless
+
 
 def handle_state(execution_context, entries):
     """
@@ -26,17 +27,20 @@ def handle_state(execution_context, entries):
         A dictionary that contains the thing you want to be cached.
         {"cached": data}
     """
-    if isinstance(entries,str):
-        entries = socless_template_string(entries,execution_context)
+    if isinstance(entries, str):
+        entries = socless_template_string(entries, execution_context)
     elif isinstance(entries, dict):
         new_entries = {}
         for key, value in list(entries.items()):
-            if isinstance(value,str):
-                new_entries[key] = socless_template_string(value,execution_context)
+            if isinstance(value, str):
+                new_entries[key] = socless_template_string(value,
+                                                           execution_context)
             else:
                 new_entries[key] = value
         entries = new_entries
     return {"cached": entries}
 
-def lambda_handler(event,context):
-    return socless_bootstrap(event,context,handle_state, include_event=True)
+
+def lambda_handler(event, context):
+    """Lambda function entry point"""
+    return socless_bootstrap(event, context, handle_state, include_event=True)

functions/counter/lambda_function.py

@@ -14,7 +14,8 @@
 from socless import *
 import operator
 
-def handle_state(context,state_name,start,delta,direction='up'):
+
+def handle_state(context, state_name, start, delta, direction='up'):
     """
     Simple Counter
     Context: Socless Input object
@@ -35,17 +36,19 @@ def handle_state(context,state_name,start,delta,direction='up'):
     start = int(start)
     delta = int(delta)
     updated_count = {}
-    current_count = context.get('results',{}).get(state_name,{})
+    current_count = context.get('results', {}).get(state_name, {})
     if current_count:
         current_value = current_count['current_value']
         updated_count['previous_value'] = current_value
-        updated_count['current_value'] = DIRECTIONS_MAP[direction](current_value, delta)
+        updated_count['current_value'] = DIRECTIONS_MAP[direction](
+            current_value, delta)
     else:
         updated_count['previous_value'] = start
-        updated_count['current_value'] = DIRECTIONS_MAP[direction](start, delta)
+        updated_count['current_value'] = DIRECTIONS_MAP[direction](
+            start, delta)
     return updated_count
 
 
-
-def lambda_handler(event,context):
-    return socless_bootstrap(event,context,handle_state,include_event=True)
+def lambda_handler(event, context):
+    """Lambda function entry point"""
+    return socless_bootstrap(event, context, handle_state, include_event=True)

functions/create_events/lambda_function.py

@@ -11,13 +11,14 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License
-from socless import *
+import socless
+
 
 def lambda_handler(event, context):
 
     #Disclaimer: having the handle_state in the lambda_handler is a quick & dirty solution to the problem of exposing the lambda 'context' object to the handle_state function
     # so that the `create_events` function can use it. There should probably be a better way to do so.
-    def handle_state(event_context,event_type,details,playbook='',dedup_keys=[],data_types={}, add_to_details={}):
+    def handle_state(event_context, event_type, details, playbook='', dedup_keys=[], data_types={}, add_to_details={}):
         """
         Creates a new event in Socless using the socless_create_events api from the socless_python library
 
@@ -31,7 +32,7 @@ def handle_state(event_context,event_type,details,playbook='',dedup_keys=[],data
         Returns:
             A dict containing a boolean status code and, if successful, the investigation id assigned to the created event.
         """
-        execution_id = event_context.get('execution_id','n/a')
+        execution_id = event_context.get('execution_id', 'n/a')
 
         for each in details:
             each.update(add_to_details)
@@ -48,7 +49,7 @@ def handle_state(event_context,event_type,details,playbook='',dedup_keys=[],data
             }
         }
 
-        create_events(events,context)
+        create_events(events, context)
         return {"completed": True}
 
-    return socless_bootstrap(event,context, handle_state, include_event=True)
+    return socless_bootstrap(event, context, handle_state, include_event=True)