diff --git a/README.md b/README.md index 0e1dc0d..5a24602 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,22 @@ -Lob Python Wrapper -========== -[![Build Status](https://travis-ci.org/lob/lob-python.svg?branch=master)](https://travis-ci.org/lob/lob-python) [![PyPI version](https://badge.fury.io/py/lob.svg)](http://badge.fury.io/py/lob) [![Downloads](https://pypip.in/d/lob/badge.png)](https://crate.io/packages/lob) [![Coverage Status](https://coveralls.io/repos/lob/lob-python/badge.png?branch=master)](https://coveralls.io/r/lob/lob-python?branch=master) [![Dependency Status](https://gemnasium.com/lob/lob-python.svg)](https://gemnasium.com/lob/lob-python) +# lob-python +[![Build Status](https://travis-ci.org/lob/lob-python.svg?branch=master)](https://travis-ci.org/lob/lob-python) [![PyPI version](https://badge.fury.io/py/lob.svg)](http://badge.fury.io/py/lob) [![Downloads](https://pypip.in/d/lob/badge.png)](https://crate.io/packages/lob) [![Coverage Status](https://coveralls.io/repos/lob/lob-python/badge.png?branch=master)](https://coveralls.io/r/lob/lob-python?branch=master) [![Dependency Status](https://gemnasium.com/lob/lob-python.svg)](https://gemnasium.com/lob/lob-python) This is the python wrapper for the lob.com API. This wrapper works in the object oriented style, that is, to make calls you have to call the method on a class and the return types are python objects. To get a `dict` on any object, you can call the `to_dict()` method of the object. -Installation -============ +## Table of Contents + +- [Installation](#installation) +- [Usage](#usage) +- [Supported Image Types](#supported-image-types) +- [Initialization and Configuration](#initialization-and-configuration) +- [API Reference](#api-reference) +- [Testing](#testing) + +## Installation You can use `pip` or `easy_install` for installing the package. @@ -18,21 +25,12 @@ pip install lob easy_install lob ``` -Testing -======= - -Install all requirements with `pip install -r requirements.txt`. - -You can run all tests with the command `nosetests` in the main directory. - -Usage -====== +## Usage We've provided an example script you can run in examples/ that has examples of how to use the lob-python wrapper with some of our core endpoints. -Supported Image Types --------- +## Supported Image Types The lob.com API supports the following image types: - PDF @@ -41,13 +39,13 @@ The lob.com API supports the following image types: For more information on prepping the images please see the [Lob documentation](https://lob.com/docs#prepping) -## Creating a PDF +#### Creating a PDF We recommed using [python-pdfkit](https://github.com/JazzCore/python-pdfkit) to generate PDFs using HTML input. This depends on having [wkhtmltopdf](http://wkhtmltopdf.org/) installed. You can find an example [here](examples/create_pdf.py) -## Intialization and Configuration +## Initialization and Configuration To initialize the wrapper, import `lob` and set the `api_key` @@ -56,7 +54,156 @@ import lob lob.api_key = 'your-api-key' ``` -## Addresses +## API Reference +- [Simple Print Service](#simple-print-service) + - [lob.Job](#lobjob) + - [lob.Job.create](#lobjobcreate) + - [lob.Job.list](#lobjoblist) + - [lob.Job.retrieve](#lobjobretrieve) + - [lob.Address](#lobaddress) + - [lob.Address.create](#lobaddresscreate) + - [lob.Address.list](#lobaddresslist) + - [lob.Address.retrieve](#lobaddressretrieve) + - [lob.Address.delete](#lobaddressdelete) + - [lob.Object](#lobobject) + - [lob.Object.create](#lobobjectcreate) + - [lob.Object.list](#lobobjectlist) + - [lob.Object.retrieve](#lobobjectretrieve) + - [lob.Object.delete](#lobobjectdelete) + - [lob.Setting](#lobsetting) + - [lob.Setting.list](#lobsettinglist) + - [lob.Setting.retrieve](#lobsettingretrieve) + - [lob.Packaging](#lobpackaging) + - [lob.Packaging.list](#lobpackaginglist) + - [lob.services](#lobservice) + - [lob.services.list](#lobservicelist) +- [Simple Postcard Service](#simple-postcard-service) + - [lob.Postcard](#lobpostcard) + - [lob.Postcard.create](#lobpostcardcreate) + - [lob.Postcard.list](#lobpostcardlist) + - [lob.Postcard.retrieve](#lobpostcardretrieve) +- [Simple Check Service](#simple-check-service) + - [lob.Check](#lobcheck) + - [lob.Check.create](#lobcheckcreate) + - [lob.Check.list](#lobchecklist) + - [lob.Check.retrieve](#lobcheckretrieve) + - [lob.BankAccount](#lobbankaccount) + - [lob.BankAccount.create](#lobbankaccountcreate) + - [lob.BankAccount.list](#lobbankaccountlist) + - [lob.BankAccount.retrieve](#lobbankaccountretrieve) +- [Simple Area Mail](#simple-area-mail) + - [lob.Area](#lobarea) + - [lob.Area.create](#lobareacreate) + - [lob.Area.list](#lobarealist) + - [lob.Area.retrieve](#lobarearetrieve) + - [lob.Route](#lobroute) + - [lob.Route.retrieve](#lobrouteretrieve) + +## Simple Print Service + +### lob.Job + +#### lob.Job.list + +```python +#Returns a list of Job objects +lob.Job.list() + +#Can specify count and offset as well +lob.Job.list(count=5, offset=1) +``` + +#### lob.Job.retrieve + +```python +#Retrieve a specific job by id +lob.Job.retrieve() +``` + +#### lob.Job.create + +```python +#Create Job Using IDs for Address and Object +lob.Job.create( + name='Joe First Job', + to_address=, + from_address=, + objects = +) + +#Create a Job Using Lob Python Objects +addresses = lob.Address.list(count=2).data +to_addr = addresses[0] +from_addr = addresses[1] +obj = lob.Object.list(count=1).data[0] +lob.Job.create( + to_address = to_addr, + from_address = from_addr, + objects = obj +) + +#Create Job Using Inline Address and Object +lob.Job.create( + to_address = { + 'name': 'Lob', + 'address_line1': '185 Berry Street', + 'address_line2': 'Suite 1510', + 'address_city': 'San Francisco', + 'address_state': 'CA', + 'address_zip': '94107', + 'address_country': 'US' + }, + from_address = { + 'name': 'Lob', + 'address_line1': '185 Berry Street', + 'address_line2': 'Suite 1510', + 'address_city': 'San Francisco', + 'address_state': 'CA', + 'address_zip': '94107', + 'address_country': 'US' + }, + objects = { + 'name': 'Test Object', + 'file': 'https://www.lob.com/test.pdf', + 'setting_id': '201' + } +) + +#Create a Multi-Object Job +lob.Job.create( + to_address = { + 'name': 'Lob', + 'address_line1': '185 Berry Street', + 'address_line2': 'Suite 1510', + 'address_city': 'San Francisco', + 'address_state': 'CA', + 'address_zip': '94107', + 'address_country': 'US' + }, + from_address = { + 'name': 'Lob', + 'address_line1': '185 Berry Street', + 'address_line2': 'Suite 1510', + 'address_city': 'San Francisco', + 'address_state': 'CA', + 'address_zip': '94107', + 'address_country': 'US' + }, + objects = [{ + 'name': 'Test Object 1', + 'file': 'https://www.lob.com/test.pdf', + 'setting_id': '201' + }, { + 'name': 'Test Object 2', + 'file': 'https://www.lob.com/test.pdf', + 'setting_id': '201' + }] +) +``` + +### lob.Address + +#### lob.Address.list ```python #List addresses @@ -64,13 +211,19 @@ lob.Address.list() #List Addresses with Count and Offset lob.Address.list(count=5, offset=2) +``` +#### lob.Address.retrieve +```python # You can query an address with its `ID` lob.Address.retrieve(id=) #or another way lob.Address.retrieve() +``` +#### lob.Address.create +```python #Basic Address Create lob.Address.create( name='Joe Smith', @@ -93,7 +246,10 @@ lob.Address.create( address_country='US', address_zip='12345' ) +``` +#### lob.Address.delete +```python #Delete an address lob.Address.delete() @@ -101,115 +257,9 @@ lob.Address.delete() lob.Address.delete() ``` -## Address Verification +### lob.Object -```python -#You can verify an address using the following code: -print lob.Verification.create( - name='Lob', - address_line1='185 Berry Street', - address_line2='Suite 1510', - address_city='San Francisco', - address_state='CA', - address_zip='94107', - address_country='US -) -``` -This will output: -```bash -{ - "address": { - "address_city": "SAN FRANCISCO", - "address_country": "US", - "address_line1": "185 BERRY ST STE 1510", - "address_line2": "", - "address_state": "CA", - "address_zip": "94107-5705" - }, - "message": "Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address." -} -``` - -## Routes - -```python -#Retrieve routes for given zip codes -lob.Route.list(zip_codes=[94158,60031]) -``` - -## Areas - -```python -#List areas -lob.Area.list() - -#List Areas with Count and Offset -lob.Area.list(count=5, offset=2) - -# You can query an area with its `ID` -lob.Area.retrieve(id=) - -#or another way -lob.Area.retrieve() - -#Basic Area Create with Zip Codes -lob.Area.create( - name='Lob', - front = 'https://www.lob.com/areafront.pdf', - back = 'https://www.lob.com/areaback.pdf', - routes = ['94158','60031'], - target_type = 'all', - full_bleed = '1' -) - -#Basic Area Create with Routes Object -var routes = lob.Route.list(zip_codes=[94158,60031]) -lob.Area.create( - name='Lob', - front = 'https://www.lob.com/areafront.pdf', - back = 'https://www.lob.com/areaback.pdf', - routes = routes, - target_type = 'all', - full_bleed = '1' -) - - -#Create Area with Optional Parameters -lob.Area.create( - front = 'https://www.lob.com/areafront.pdf', - back = 'https://www.lob.com/areaback.pdf', - routes = '94158', -) -``` - -## Settings - -```python -#List All Settings -lob.Setting.list() - -#Retrieve a Setting -print lob.Setting.retrieve(id=100) - -#or another way -print lob.Setting.retrieve(100) -``` - -## Services - -```python -#List All Services -lob.Service.list() -``` - -## Packagings - -```python -#List All Packagings -lob.Packaging.list() -``` - -## Objects +#### lob.Object.list ```python # Returns a list of Object objects @@ -217,13 +267,18 @@ lob.Object.list() # Can specify count and offset lob.Object.list(count=4, offset=2) +``` +#### lob.Object.retrieve + +```python #Retrieve a specifc object lob.Object.retrieve() +``` -# Delete an object via it's ID -lob.Object.delete() +#### lob.Object.create +```python #Create an Object using a URL lob.Object.create( name='Joe Smith', @@ -251,102 +306,57 @@ lob.Object.create( quantity=1, double_sided=0 ) +``` +#### lob.Object.delete + +```python # Delete an object via it's ID lob.Object.delete() ``` -## Jobs +### lob.Setting + +#### lob.Setting.list ```python -# Returns a list of Job objects -lob.Job.list() +#List All Settings +lob.Setting.list() +``` -# Can specify count and offset as well -lob.Job.list(count=5, offset=1) +#### lob.Setting.retrieve -#Retrieve a specific job by id -lob.Job.retrieve() +```python +#Retrieve a Setting +print lob.Setting.retrieve(id=100) -#Create Job Using IDs for Address and Object -lob.Job.create( - name='Joe First Job', - to_address=, - from_address=, - objects = -) +#or another way +print lob.Setting.retrieve(100) +``` -#Create a Job Using Lob Python Objects -addresses = lob.Address.list(count=2).data -to_addr = addresses[0] -from_addr = addresses[1] -obj = lob.Object.list(count=1).data[0] -lob.Job.create( - to_address = to_addr, - from_address = from_addr, - objects = obj -) +### lob.Packaging -#Create Job Using Inline Address and Object -lob.Job.create( - to_address = { - 'name': 'Lob', - 'address_line1': '185 Berry Street', - 'address_line2': 'Suite 1510', - 'address_city': 'San Francisco', - 'address_state': 'CA', - 'address_zip': '94107', - 'address_country': 'US' - }, - from_address = { - 'name': 'Lob', - 'address_line1': '185 Berry Street', - 'address_line2': 'Suite 1510', - 'address_city': 'San Francisco', - 'address_state': 'CA', - 'address_zip': '94107', - 'address_country': 'US' - }, - objects = { - 'name': 'Test Object', - 'file': 'https://www.lob.com/test.pdf', - 'setting_id': '201' - } -) +#### lob.Packaging.list -#Create a Multi-Object Job -lob.Job.create( - to_address = { - 'name': 'Lob', - 'address_line1': '185 Berry Street', - 'address_line2': 'Suite 1510', - 'address_city': 'San Francisco', - 'address_state': 'CA', - 'address_zip': '94107', - 'address_country': 'US' - }, - from_address = { - 'name': 'Lob', - 'address_line1': '185 Berry Street', - 'address_line2': 'Suite 1510', - 'address_city': 'San Francisco', - 'address_state': 'CA', - 'address_zip': '94107', - 'address_country': 'US' - }, - objects = [{ - 'name': 'Test Object 1', - 'file': 'https://www.lob.com/test.pdf', - 'setting_id': '201' - }, { - 'name': 'Test Object 2', - 'file': 'https://www.lob.com/test.pdf', - 'setting_id': '201' - }] -) +```python +#List All Packagings +lob.Packaging.list() +``` + +### lob.Service + +#### lob.Service.list + +```python +#List All Services +lob.Service.list() ``` -## Postcards +## Simple Postcard Service + +### lob.Postcard + +#### lob.Postcard.list ```python # Returns a list of Postcard objects @@ -354,10 +364,16 @@ lob.Postcard.list() # Can specify count and offset as well lob.Postcard.list(count=5, offset=1) +``` +#### lob.Postcard.retrieve +```python #Retrieve a specific postcard by id lob.Postcard.retrieve() +``` +#### lob.Postcard.create +```python #Create a Postcard Using IDs for Address lob.Postcard.create( to_address=, @@ -449,7 +465,59 @@ lob.Postcard.create( message = 'Hello this is the message!' ) ``` -## Bank Accounts + +## Simple Check Service + +### lob.Check + +#### lob.Check.list +```python +# Returns a list of Check objects +lob.Check.list() + +# Can specify count and offset as well +lob.Check.list(count=5, offset=1) +``` + +#### lob.Check.retrieve +```python +#Retrieve a specific Check by id +lob.Check.retrieve() +``` + +#### lob.Check.create + +```python +#Create Check with Address Id +lob.Check.create( + name = 'Check Test', + to_address = , + bank_account = , + amount = 1000, + memo = 'Services Rendered' +) + +#Create Check with Inline Address +lob.Check.create( + name = 'Check Test', + to_address = { + 'name': 'Lob', + 'address_line1': '185 Berry Street', + 'address_line2': 'Suite 1510', + 'address_city': 'San Francisco', + 'address_state': 'CA', + 'address_zip': '94107', + 'address_country': 'US' + }, + bank_account = , + amount = 1000, + memo = 'Services Rendered' +) +``` + +### lob.BankAccount + +#### lob.BankAccount.list ```python # Returns a list of BankAccount objects @@ -457,10 +525,18 @@ lob.BankAccount.list() # Can specify count and offset as well lob.BankAccount.list(count=5, offset=1) +``` +#### lob.BankAccount.retrieve + +```python #Retrieve a specific BankAccount by id lob.BankAccount.retrieve() +``` + +#### lob.BankAccount.create +```python #Create Bank Account Using Address Ids lob.BankAccount.create( routing_number = '123456789', @@ -491,48 +567,115 @@ lob.BankAccount.create( 'address_country': 'US' } ) +``` +#### lob.BankAccount.delete + +```python #Delete a specific BankAccount by id lob.BankAccount.delete() ``` -## Checks + +## Simple Area Mail + +### lob.Area + +#### lob.Area.list ```python -# Returns a list of Check objects -lob.Check.list() +#List areas +lob.Area.list() -# Can specify count and offset as well -lob.Check.list(count=5, offset=1) +#List Areas with Count and Offset +lob.Area.list(count=5, offset=2) +``` -#Retrieve a specific Check by id -lob.Check.retrieve() +#### lob.Area.retrieve -#Create Check with Address Id -lob.Check.create( - name = 'Check Test', - to_address = , - bank_account = , - amount = 1000, - memo = 'Services Rendered' +```python +# You can query an area with its `ID` +lob.Area.retrieve(id=) + +#or another way +lob.Area.retrieve() +``` + +#### lob.Area.create + +```python +#Basic Area Create with Zip Codes +lob.Area.create( + name='Lob', + front = 'https://www.lob.com/areafront.pdf', + back = 'https://www.lob.com/areaback.pdf', + routes = ['94158','60031'], + target_type = 'all', + full_bleed = '1' ) -#Create Check with Inline Address -lob.Check.create( - name = 'Check Test', - to_address = { - 'name': 'Lob', - 'address_line1': '185 Berry Street', - 'address_line2': 'Suite 1510', - 'address_city': 'San Francisco', - 'address_state': 'CA', - 'address_zip': '94107', - 'address_country': 'US' - }, - bank_account = , - amount = 1000, - memo = 'Services Rendered' +#Basic Area Create with Routes Object +var routes = lob.Route.list(zip_codes=[94158,60031]) +lob.Area.create( + name='Lob', + front = 'https://www.lob.com/areafront.pdf', + back = 'https://www.lob.com/areaback.pdf', + routes = routes, + target_type = 'all', + full_bleed = '1' +) + +#Create Area with Optional Parameters +lob.Area.create( + front = 'https://www.lob.com/areafront.pdf', + back = 'https://www.lob.com/areaback.pdf', + routes = '94158', ) ``` +### lob.Route + +#### lob.Route.list +```python +#Retrieve routes for given zip codes +lob.Route.list(zip_codes=[94158,60031]) +``` + +## Address Verification + +### lob.Verification + +#### lob.Verification.create +```python +#You can verify an address using the following code: +print lob.Verification.create( + name='Lob', + address_line1='185 Berry Street', + address_line2='Suite 1510', + address_city='San Francisco', + address_state='CA', + address_zip='94107', + address_country='US +) +``` +This will output: +```bash +{ + "address": { + "address_city": "SAN FRANCISCO", + "address_country": "US", + "address_line1": "185 BERRY ST STE 1510", + "address_line2": "", + "address_state": "CA", + "address_zip": "94107-5705" + }, + "message": "Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address." +} +``` + +## Testing + +Install all requirements with `pip install -r requirements.txt`. + +You can run all tests with the command `nosetests` in the main directory.