Cleanup Env Documentation

There were some conflicting configuration details, namely .env_sample, and sendgrid.env. I've opted for .env_sample, as sendgrid.env actually seemed to be incorrect.
sendgrid · Oct 25, 2018 · e1f043c · e1f043c
1 parent edd02e4
commit e1f043c
Show file tree

Hide file tree

Showing 6 changed files with 295 additions and 16 deletions.
diff --git a/.gitignore b/.gitignore
@@ -20,6 +20,5 @@ README.txt
 coverage.xml
 htmlcov
 temp*.py
-sendgrid.env
 .vscode
 sendgrid/VERSION.txt
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -62,7 +62,7 @@ We welcome direct contributions to the sendgrid-python code base. Thank you!
 ### Development Environment ###
 #### There are two ways to get set up: ####
 #### 1. Using Docker ####
-This is usually the easiest and fastest way to get set up. 
+This is usually the easiest and fastest way to get set up.
 You can use our Docker image to avoid setting up the development environment yourself.  See [USAGE.md](https://github.com/sendgrid/sendgrid-python/blob/master/docker/USAGE.md).
 
 #### - OR - ####
@@ -87,9 +87,14 @@ First, get your free SendGrid account [here](https://sendgrid.com/free?source=se
 Next, update your environment with your [SENDGRID_API_KEY](https://app.sendgrid.com/settings/api_keys).
 
 ```bash
-echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env
-echo "sendgrid.env" >> .gitignore
-source ./sendgrid.env
+cp .env_sample .env
+```
+
+Then edit `.env` and insert your API key.
+
+```bash
+# You do not need to do this when using Docker Compose
+source .env
 ```
 
 ##### Execute: #####
@@ -184,8 +189,10 @@ Please run your code through:
    ```bash
    # Clone your fork of the repo into the current directory
    git clone https://github.com/sendgrid/sendgrid-python
+
    # Navigate to the newly cloned directory
    cd sendgrid-python
+
    # Assign the original repo to a remote called "upstream"
    git remote add upstream https://github.com/sendgrid/sendgrid-python
    ```

diff --git a/README.md b/README.md
@@ -0,0 +1,217 @@
+![SendGrid Logo](https://uiux.s3.amazonaws.com/2016-logos/email-logo%402x.png)
+
+[![Travis Badge](https://travis-ci.org/sendgrid/sendgrid-python.svg?branch=master)](https://travis-ci.org/sendgrid/sendgrid-python)
+[![codecov](https://img.shields.io/codecov/c/github/sendgrid/sendgrid-python/master.svg?style=flat-square&label=Codecov+Coverage)](https://codecov.io/gh/sendgrid/sendgrid-python)
+[![Docker Badge](https://img.shields.io/docker/automated/sendgrid/sendgrid-python.svg)](https://hub.docker.com/r/sendgrid/sendgrid-python/)
+[![Email Notifications Badge](https://dx.sendgrid.com/badge/python)](https://dx.sendgrid.com/newsletter/python)
+[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE.txt)
+[![Twitter Follow](https://img.shields.io/twitter/follow/sendgrid.svg?style=social&label=Follow)](https://twitter.com/sendgrid)
+[![GitHub contributors](https://img.shields.io/github/contributors/sendgrid/sendgrid-python.svg)](https://github.com/sendgrid/sendgrid-python/graphs/contributors)
+
+**NEW:**
+
+* Subscribe to email [notifications](https://dx.sendgrid.com/newsletter/python) for releases and breaking changes.
+* Quickly get started with [Docker](https://github.com/sendgrid/sendgrid-python/tree/master/docker).
+
+**This library allows you to quickly and easily use the SendGrid Web API v3 via Python.**
+
+Version 3.X.X+ of this library provides full support for all SendGrid [Web API v3](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html) endpoints, including the new [v3 /mail/send](https://sendgrid.com/blog/introducing-v3mailsend-sendgrids-new-mail-endpoint).
+
+This library represents the beginning of a new path for SendGrid. We want this library to be community driven and SendGrid led. We need your help to realize this goal. To help make sure we are building the right things in the right order, we ask that you create [issues](https://github.com/sendgrid/sendgrid-python/issues) and [pull requests](https://github.com/sendgrid/sendgrid-python/blob/master/CONTRIBUTING.md) or simply upvote or comment on existing issues or pull requests.
+
+Please browse the rest of this README for further detail.
+
+We appreciate your continued support, thank you!
+
+# Table of Contents
+
+* [Installation](#installation)
+* [Quick Start](#quick-start)
+* [Processing Inbound Email](#inbound)
+* [Usage](#usage)
+* [Use Cases](#use-cases)
+* [Announcements](#announcements)
+* [Roadmap](#roadmap)
+* [How to Contribute](#contribute)
+* [Troubleshooting](#troubleshooting)
+* [About](#about)
+* [License](#license)
+
+<a name="installation"></a>
+# Installation
+
+## Prerequisites
+
+- Python version 2.7 and 3.4+
+- The SendGrid service, starting at the [free level](https://sendgrid.com/free?source=sendgrid-python)
+
+## Setup Environment Variables
+
+Update the development environment with your [SENDGRID_API_KEY](https://app.sendgrid.com/settings/api_keys), for example:
+
+SendGrid also supports local environment file `.env`. Copy or rename `.env_sample` into `.env` and update [SENDGRID_API_KEY](https://app.sendgrid.com/settings/api_keys) with your key.
+
+Sendgrid also supports local environment file `.env`. Copy or rename `.env_sample` into `.env` and update [SENDGRID_API_KEY](https://app.sendgrid.com/settings/api_keys) with your key.
+
+## Install Package
+
+```bash
+pip install sendgrid
+```
+
+## Dependencies
+
+- [Python-HTTP-Client](https://github.com/sendgrid/python-http-client)
+
+<a name="quick-start"></a>
+# Quick Start
+
+## Hello Email
+
+The following is the minimum needed code to send an email with the [/mail/send Helper](https://github.com/sendgrid/sendgrid-python/tree/master/sendgrid/helpers/mail) ([here](https://github.com/sendgrid/sendgrid-python/blob/master/examples/helpers/mail/mail_example.py#L20) is a full example):
+
+### With Mail Helper Class
+
+```python
+import sendgrid
+import os
+from sendgrid.helpers.mail import *
+
+sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY'))
+from_email = Email("[email protected]")
+to_email = Email("[email protected]")
+subject = "Sending with SendGrid is Fun"
+content = Content("text/plain", "and easy to do anywhere, even with Python")
+mail = Mail(from_email, subject, to_email, content)
+response = sg.client.mail.send.post(request_body=mail.get())
+print(response.status_code)
+print(response.body)
+print(response.headers)
+```
+
+The `Mail` constructor creates a [personalization object](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/personalizations.html) for you. [Here](https://github.com/sendgrid/sendgrid-python/blob/master/examples/helpers/mail/mail_example.py#L16) is an example of how to add it.
+
+### Without Mail Helper Class
+
+The following is the minimum needed code to send an email without the /mail/send Helper ([here](https://github.com/sendgrid/sendgrid-python/blob/master/examples/mail/mail.py#L27) is a full example):
+
+```python
+import sendgrid
+import os
+
+sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY'))
+data = {
+  "personalizations": [
+    {
+      "to": [
+        {
+          "email": "[email protected]"
+        }
+      ],
+      "subject": "Sending with SendGrid is Fun"
+    }
+  ],
+  "from": {
+    "email": "[email protected]"
+  },
+  "content": [
+    {
+      "type": "text/plain",
+      "value": "and easy to do anywhere, even with Python"
+    }
+  ]
+}
+response = sg.client.mail.send.post(request_body=data)
+print(response.status_code)
+print(response.body)
+print(response.headers)
+```
+
+## General v3 Web API Usage (With [Fluent Interface](https://sendgrid.com/blog/using-python-to-implement-a-fluent-interface-to-any-rest-api/))
+
+```python
+import sendgrid
+import os
+
+sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY'))
+response = sg.client.suppression.bounces.get()
+print(response.status_code)
+print(response.body)
+print(response.headers)
+```
+
+## General v3 Web API Usage (Without Fluent Interface)
+
+```python
+import sendgrid
+import os
+
+sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY'))
+response = sg.client._("suppression/bounces").get()
+print(response.status_code)
+print(response.body)
+print(response.headers)
+```
+
+<a name="inbound"></a>
+# Processing Inbound Email
+
+Please see [our helper](https://github.com/sendgrid/sendgrid-python/tree/master/sendgrid/helpers/inbound) for utilizing our Inbound Parse webhook.
+
+<a name="usage"></a>
+# Usage
+
+- [SendGrid Documentation](https://sendgrid.com/docs/API_Reference/index.html)
+- [Library Usage Documentation](https://github.com/sendgrid/sendgrid-python/tree/master/USAGE.md)
+- [Example Code](https://github.com/sendgrid/sendgrid-python/tree/master/examples)
+- [How-to: Migration from v2 to v3](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/how_to_migrate_from_v2_to_v3_mail_send.html)
+- [v3 Web API Mail Send Helper](https://github.com/sendgrid/sendgrid-python/tree/master/sendgrid/helpers/mail) - build a request object payload for a v3 /mail/send API call.
+- [Processing Inbound Email](https://github.com/sendgrid/sendgrid-python/tree/master/sendgrid/helpers/inbound)
+
+<a name="use-cases"></a>
+# Use Cases
+
+[Examples of common API use cases](https://github.com/sendgrid/sendgrid-python/blob/master/use_cases/README.md), such as how to send an email with a transactional template.
+
+<a name="announcements"></a>
+# Announcements
+
+Join an experienced and passionate team that focuses on making an impact. Opportunities abound to grow the product - and grow your career! Check out our [Data Platform Engineer role](http://grnh.se/wbx1701)
+
+Please see our announcement regarding [breaking changes](https://github.com/sendgrid/sendgrid-python/issues/217). Your support is appreciated!
+
+All updates to this library are documented in our [CHANGELOG](https://github.com/sendgrid/sendgrid-python/blob/master/CHANGELOG.md) and [releases](https://github.com/sendgrid/sendgrid-python/releases). You may also subscribe to email [release notifications](https://dx.sendgrid.com/newsletter/java) for releases and breaking changes.
+
+<a name="roadmap"></a>
+# Roadmap
+
+If you are interested in the future direction of this project, please take a look at our open [issues](https://github.com/sendgrid/sendgrid-python/issues) and [pull requests](https://github.com/sendgrid/sendgrid-python/pulls). We would love to hear your feedback.
+
+<a name="contribute"></a>
+# How to Contribute
+
+We encourage contribution to our libraries (you might even score some nifty swag), please see our [CONTRIBUTING](https://github.com/sendgrid/sendgrid-python/blob/master/CONTRIBUTING.md) guide for details.
+
+Quick links:
+
+- [Feature Request](https://github.com/sendgrid/sendgrid-python/blob/master/CONTRIBUTING.md#feature-request)
+- [Bug Reports](https://github.com/sendgrid/sendgrid-python/blob/master/CONTRIBUTING.md#submit-a-bug-report)
+- [Sign the CLA to Create a Pull Request](https://cla.sendgrid.com/sendgrid/sendgrid-python)
+- [Improvements to the Codebase](https://github.com/sendgrid/sendgrid-python/blob/master/CONTRIBUTING.md#improvements-to-the-codebase)
+- [Review Pull Requests](https://github.com/sendgrid/sendgrid-python/blob/master/CONTRIBUTING.md#code-reviews)
+
+<a name="troubleshooting"></a>
+# Troubleshooting
+
+Please see our [troubleshooting guide](https://github.com/sendgrid/sendgrid-python/blob/master/TROUBLESHOOTING.md) for common library issues.
+
+<a name="about"></a>
+# About
+
+sendgrid-python is guided and supported by the SendGrid [Developer Experience Team](mailto:[email protected]).
+
+sendgrid-python is maintained and funded by SendGrid, Inc. The names and logos for sendgrid-python are trademarks of SendGrid, Inc.
+
+<a name="license"></a>
+# License
+[The MIT License (MIT)](LICENSE.txt)
diff --git a/docker/USAGE.md b/docker/USAGE.md
@@ -70,6 +70,63 @@ $ docker run -it -v /path/to/cool-sendgrid-python:/mnt/sendgrid-python sendgrid/
 
 Note that the paths you specify in `-v` must be absolute.
 
+# Docker Compose
+
+<a name="Quickstart"></a>
+# Quickstart
+
+1. Install docker-compose on your machine.
+2. Must copy .env_sample to .env file.
+3. Edit .env file for yours versions and paths.
+4. Must create env folder for clone yours repo.
+5. Have fun! :D
+
+## Using tag's for versions - DockerHub:
+
+### Edit variable TAG on .env/env_sample file
+
+```sh-session
+$ sed -ie 's/TAG=latest/TAG=choice_a_version/g'
+```
+### Run service using tags
+
+```sh-session
+$ cd /path/to/sendgrid-python/docker
+$ docker-compose up -d sendgrid
+```
+
+## Specifying specific versions:
+
+### Edit variable TAG on .env/env_sample file
+
+```sh-session
+$ sed -ie 's/SENDGRID_PYTHON_VERSION=vy.x.z/SENDGRID_PYTHON_VERSION=vx.y.z/g'
+$ sed -ie 's/HTTP_CLIENT_VERSION=vy.x.z/HTTP_CLIENT_VERSION=vx.y.z/g'
+```
+
+### Run service
+
+```sh-session
+$ cd /path/to/sendgrid-python/docker
+$ docker-compose up -d sendgrid-dev
+```
+
+## Specifying your own fork:
+
+### Edit variable TAG on .env/env_sample file
+
+```sh-session
+$ sed -ie 's/TAG=latest/TAG=choice_a_version/g'
+$ sed -ie 's/SENDGRID_PYTHON_VERSION=vy.x.z/SENDGRID_PYTHON_VERSION=vx.y.z/g'
+```
+
+### Run service
+
+```sh-session
+$ cd /path/to/sendgrid-python/docker
+$ docker-compose up -d sendgrid-beta
+```
+
 <a name="Testing"></a>
 # Testing
 Testing is easy!  Run the container, `cd sendgrid`, and run `tox`.

diff --git a/sendgrid.env b/sendgrid.env
diff --git a/use_cases/aws.md b/use_cases/aws.md
@@ -19,15 +19,15 @@ Before starting this tutorial, you will need to have access to an AWS account in
 ## Getting Started
 
 ### Create AWS CodeStar Project
-Log in to your AWS account and go to the AWS CodeStar service. Click "Start a project". For this tutorial we're going to choose a Python Web service, utilizing AWS Lambda. You can use the filters on the left hand side of the UI to narrow down the available choices. 
+Log in to your AWS account and go to the AWS CodeStar service. Click "Start a project". For this tutorial we're going to choose a Python Web service, utilizing AWS Lambda. You can use the filters on the left hand side of the UI to narrow down the available choices.
 
-After you've selected the template, you're asked to provide a name for your project. Go ahead and name it "hello-email". Once you've entered a name, click "Create Project" in the lower right hand corner. You can then choose which tools you want to use to interact with the project. For this tutorial, we'll be choosing "Command Line". 
+After you've selected the template, you're asked to provide a name for your project. Go ahead and name it "hello-email". Once you've entered a name, click "Create Project" in the lower right hand corner. You can then choose which tools you want to use to interact with the project. For this tutorial, we'll be choosing "Command Line".
 
-Once that is completed, you'll be given some basic steps to get Git installed and setup, and instructions for connecting to the AWS CodeCommit(git) repository. You can either use HTTPS, or SSH. Instructions for setting up either are provided. 
+Once that is completed, you'll be given some basic steps to get Git installed and setup, and instructions for connecting to the AWS CodeCommit(git) repository. You can either use HTTPS, or SSH. Instructions for setting up either are provided.
 
 Go ahead and clone the Git repository link after it is created. You may need to click "Skip" in the lower right hand corner to proceed.
 
-Once that's done, you've successfully created a CodeStar project! You should be at the dashboard, with a view of the wiki, change log, build pipeline, and application endpoint. 
+Once that's done, you've successfully created a CodeStar project! You should be at the dashboard, with a view of the wiki, change log, build pipeline, and application endpoint.
 
 ### Create SendGrid API Key
 Log in to your SendGrid account. Click on your user name on the left hand side of the UI and choose "Setup Guide" from the drop-down menu. On the "Welcome" menu, choose "Send Your First Email", and then "Integrate using our Web API or SMTP relay." Choose "Web API" as the recommended option on the next screen, as we'll be using that for this tutorial.  For more information about creating API keys, see https://sendgrid.com/docs/Classroom/Send/How_Emails_Are_Sent/api_keys.html
@@ -44,7 +44,7 @@ For the rest of the tutorial, we'll be working out of the git repository we clon
 ```
 $ cd hello-email
 ```
-note: this assumes you cloned the git repo inside your current directory. My directory is: 
+note: this assumes you cloned the Git repo inside your current directory. My directory is:
 
 ```
 ~/projects/hello-email
@@ -100,7 +100,7 @@ virtualenv venv
 source ./venv/bin/activate
 ```
 
-Prior to being able to deploy our Python code, we'll need to install the sendgrid Python module *locally*. One of the idiosyncracies of AWS Lambda is that all library and module dependencies that aren't part of the standard library have to be included with the code/build artifact. Virtual environments do not translate to the Lambda runtime environment. 
+Prior to being able to deploy our Python code, we'll need to install the sendgrid Python module *locally*. One of the idiosyncracies of AWS Lambda is that all library and module dependencies that aren't part of the standard library have to be included with the code/build artifact. Virtual environments do not translate to the Lambda runtime environment.
 
 In the root project directory, run the following command:
 ```
@@ -157,16 +157,16 @@ $ git commit -m 'hello-email app'
 $ git push
 ```
 
-Once the code is successfully pushed, head back to the AWS CodeStar dashboard for your project. After your commit successfully registers, an automated build and deployment process should kick off. 
+Once the code is successfully pushed, head back to the AWS CodeStar dashboard for your project. After your commit successfully registers, an automated build and deployment process should kick off.
 
 One more step left before our application will work correctly. After your code has bee deployed, head to the AWS Lambda console. Click on your function name, which should start with `awscodestar-hello-email-lambda-`, or similar.
 
-Scroll down to the "Environment Variables" section. Here we need to populate our SendGrid API key. Copy the value from the `sendgrid.env` file you created earlier, ensuring to capture the entire value. Make sure the key is titled:
+Scroll down to the "Environment Variables" section. Here we need to populate our SendGrid API key. Copy the value from the `.env` file you created earlier, ensuring to capture the entire value. Make sure the key is titled:
 
 ```
 SENDGRID_API_KEY
 ```
 
-Now, go back to your project dashboard in CodeStar. Click on the link under "Application endpoints". After a moment, you should be greeted with JSON output indicating an email was successfully sent. 
+Now, go back to your project dashboard in CodeStar. Click on the link under "Application endpoints". After a moment, you should be greeted with JSON output indicating an email was successfully sent.
 
-Congratulations, you've just used serverless technology to create an email sending app in AWS!
+Congratulations, you've just used serverless technology to create an email sending app in AWS!