From e1f043c3e1be47815c65efa080d1b7a02252b132 Mon Sep 17 00:00:00 2001 From: David McKay Date: Thu, 25 Oct 2018 15:42:41 +0100 Subject: [PATCH] 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. --- .gitignore | 1 - CONTRIBUTING.md | 15 +++- README.md | 217 +++++++++++++++++++++++++++++++++++++++++++++++ docker/USAGE.md | 57 +++++++++++++ sendgrid.env | 1 - use_cases/aws.md | 20 ++--- 6 files changed, 295 insertions(+), 16 deletions(-) create mode 100644 README.md delete mode 100644 sendgrid.env diff --git a/.gitignore b/.gitignore index 4ac2623b4..dd43e4a8d 100644 --- 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 index c4aa2c4a5..344605834 100644 --- 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 new file mode 100644 index 000000000..48b56f48c --- /dev/null +++ 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) + + +# 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) + + +# 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("test@example.com") +to_email = Email("test@example.com") +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": "test@example.com" + } + ], + "subject": "Sending with SendGrid is Fun" + } + ], + "from": { + "email": "test@example.com" + }, + "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) +``` + + +# Processing Inbound Email + +Please see [our helper](https://github.com/sendgrid/sendgrid-python/tree/master/sendgrid/helpers/inbound) for utilizing our Inbound Parse webhook. + + +# 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) + + +# 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. + + +# 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. + + +# 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. + + +# 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) + + +# Troubleshooting + +Please see our [troubleshooting guide](https://github.com/sendgrid/sendgrid-python/blob/master/TROUBLESHOOTING.md) for common library issues. + + +# About + +sendgrid-python is guided and supported by the SendGrid [Developer Experience Team](mailto:dx@sendgrid.com). + +sendgrid-python is maintained and funded by SendGrid, Inc. The names and logos for sendgrid-python are trademarks of SendGrid, Inc. + + +# License +[The MIT License (MIT)](LICENSE.txt) diff --git a/docker/USAGE.md b/docker/USAGE.md index cd543c402..1a4473766 100644 --- 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 + + +# 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 +``` + # Testing Testing is easy! Run the container, `cd sendgrid`, and run `tox`. diff --git a/sendgrid.env b/sendgrid.env deleted file mode 100644 index 954b741c7..000000000 --- a/sendgrid.env +++ /dev/null @@ -1 +0,0 @@ -export SENDGRID_API_KEY='echo export SENDGRID_API_KEY=YOUR_API_KEY > sendgrid.env' diff --git a/use_cases/aws.md b/use_cases/aws.md index 9c30fd7ed..2d5ebdcb1 100644 --- 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! \ No newline at end of file +Congratulations, you've just used serverless technology to create an email sending app in AWS!