Skip to content

Commit 1b26629

Browse files
apexdodgeapexdodge
authored
better readme
1 parent aa77630 commit 1b26629

File tree

1 file changed

+121
-118
lines changed

1 file changed

+121
-118
lines changed

‎README.md‎

Lines changed: 121 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,56 @@
1-
# Api2Pdf - Python
2-
[Api2Pdf.com](https://www.api2pdf.com) | [Docs](https://www.api2pdf.com/documentation)
3-
4-
## What is Api2Pdf?
5-
Api2Pdf.com is a service for instantly generating PDFs.
6-
7-
- [Get Started](#get-started)
8-
- [HTML](#convert-from-html)
9-
- [URLs](#convert-from-urls)
10-
- [Microsoft Office documents (Word, Excel, Powerpoint)](#convert-from-office)
11-
- [Images](#convert-from-office)
12-
- [Merge / Concatenate two or more PDFs](#merge)
13-
- [Helper Methods](#helper-methods)
1+
# api2pdf.python
2+
Python bindings for [Api2pdf REST API](https://www.api2pdf.com/documentation)
3+
4+
Api2Pdf.com is a REST API for instantly generating PDF documents from HTML, URLs, Microsoft Office Documents (Word, Excel, PPT), and images. The API also supports merge / concatenation of two or more PDFs. Api2Pdf is a wrapper for popular libraries such as **wkhtmltopdf**, **Headless Chrome**, and **LibreOffice**.
5+
6+
- [Installation](#installation)
7+
- [Resources](#resources)
8+
- [Authorization](#authorization)
9+
- [Usage](#usage)
1410
- [FAQ](#faq)
1511

16-
Api2Pdf provides access to **wkhtmltopdf**, **Headless Chrome**, and **LibreOffice**, along with the ability to merge / concatenate PDFs together.
1712

13+
## <a name="installation"></a>Add a dependency
14+
15+
### PyPI
16+
17+
Run the pip command for installing the client `pip install api2pdf`
1818

19+
## <a name="resources"></a>Resources
1920

20-
## <a name="get-started"></a>Get Started
21-
This python library provides convenient methods for accessing the REST API [documented here](https://www.api2pdf.com/documentation/).
21+
Resources this API supports:
22+
23+
- [wkhtmltopdf](#wkhtmltopdf)
24+
- [Headless Chrome](#chrome)
25+
- [LibreOffice](#libreoffice)
26+
- [Merge / Concatenate PDFs](#merge)
27+
- [Helper Methods](#helpers)
28+
29+
## <a name="authorization"></a>Authorization
2230

2331
### Acquire API Key
2432
1. Create an account and login at [portal.api2pdf.com](https://portal.api2pdf.com)
2533
2. Add a balance to your account (no monthly commitment, sign up with as little as $1)
2634
3. Create an application and grab your API Key
27-
28-
### Install
29-
pip install api2pdf
3035

31-
### Usage
36+
## <a name="#usage"></a>Usage
37+
38+
### Initialize the Client
39+
40+
All usage starts by calling the import command and initializing the client by passing your API key as a parameter to the constructor.
3241

3342
from api2pdf import Api2Pdf
3443

35-
a2p = Api2Pdf('YOUR-API-KEY')
36-
api_response = a2p.HeadlessChrome.convert_from_html('<p>Hello, World</p>')
44+
a2p_client = Api2Pdf('YOUR-API-KEY')
45+
46+
Once you initialize the client, you can make calls like so:
47+
48+
api_response = a2p_client.HeadlessChrome.convert_from_html('<p>Hello, World</p>')
3749
print(api_response.result)
3850

39-
### Sample Result
51+
### Result Object
4052

41-
An `Api2PdfResponse` object is returned from every API call. Call the `result` attribute to retrieve the data. If a call is unsuccessful then `success` will show False and the `error` will provide the reason for failure. Additional attributes include the total data usage in, out, and the cost for the API call.
53+
An `Api2PdfResponse` object is returned from every API call. Call the `result` attribute to retrieve the data. If a call is unsuccessful then `success` will show False and the `error` will provide the reason for failure. Additional attributes include the total data usage in, out, and the cost for the API call, typically very small fractions of a penny.
4254

4355
{
4456
'pdf': 'https://link-to-pdf-only-available-for-24-hours',
@@ -50,159 +62,150 @@ An `Api2PdfResponse` object is returned from every API call. Call the `result` a
5062
'responseId': '6e46637a-650d-46d5-af0b-3d7831baccbb'
5163
}
5264

53-
For debugging, you can simply print the `Api2PdfResponse` object to see the request and response data.
65+
For debugging, you can print the `Api2PdfResponse` object to see the request and response data.
5466

55-
links_to_pdfs = ['https://LINK-TO-PDF', 'https://LINK-TO-PDF']
56-
merge_result = a2p.merge(links_to_pdfs)
57-
print(merge_result)
67+
api_response = a2p_client.HeadlessChrome.convert_from_html('<p>Hello, World</p>')
68+
print(api_response)
5869

5970
Output:
6071

6172
---- API2PDF REQUEST ----
62-
- Headers: {'Authorization': 'f8bd6792-f1cd-42df-9bf9-f7a35e59362f'}
63-
- Endpoint: https://v2018.api2pdf.com/merge
73+
- Headers: {'Authorization': 'YOUR-API-KEY'}
74+
- Endpoint: https://v2018.api2pdf.com/chrome/html
6475
- Payload:
65-
['https://LINK-TO-PDF', 'https://LINK-TO-PDF']
76+
{'html': '<p>Hello, World</p>'}
6677
---- API2PDF RESPONSE ----
6778
{'pdf': 'https://link-to-pdf-only-available-for-24-hours', 'mbIn': 0.08421039581298828, 'mbOut': 0.08830547332763672, 'cost': 0.00017251586914062501, 'success': True, 'error': None, 'responseId': '163c4d25-25d7-4b82-bf50-907597d2ad46'}
6879

6980

70-
## Documentation
71-
72-
### <a name="convert-from-html"></a>Convert HTML to PDF
81+
### <a name="wkhtmltopdf"></a> wkhtmltopdf
7382

74-
We support both **wkhtmltopdf** and **Headless Chrome** with the endpoint to convert raw html to PDFs. Both endpoints allow you to pass keyword arguments that are options available for their respective libraries.
83+
**Convert HTML to PDF**
7584

76-
##### HeadlessChrome.convert_from_html(html, inline_pdf=False, file_name=None, **options)
77-
##### WkHtmlToPdf.convert_from_html(html, inline_pdf=False, file_name=None, **options)
78-
79-
*Parameters:*
80-
81-
`html <string>` - raw string of html content
82-
83-
`inline_pdf <bool> (optional, default=False)` - if set to True, web browser will load the PDF in a new tab.
85+
api_response = a2p_client.WkHtmlToPdf.convert_from_html('<p>Hello, World</p>')
86+
87+
**Convert HTML to PDF (load PDF in browser window and specify a file name)**
8488

85-
`file_name <string> (optional, default=None)` - specify an optional file name like "report-03012019.pdf".
89+
api_response = a2p_client.WkHtmlToPdf.convert_from_html('<p>Hello, World</p>', inline_pdf=True, file_name='test.pdf')
90+
91+
**Convert HTML to PDF (use keyword arguments for advanced wkhtmltopdf settings)**
92+
[View full list of wkhtmltopdf options available.](https://www.api2pdf.com/documentation/advanced-options-wkhtmltopdf/)
8693

87-
`**options <keyword args> (optional, default=None)` - include options for generating a PDF with your chosen library. See available options here:
94+
options = {
95+
'orientation': 'landscape',
96+
'pageSize': 'A4'
97+
}
98+
api_response = a2p_client.WkHtmlToPdf.convert_from_html('<p>Hello, World</p>', **options)
8899

89-
- [wkhtmltopdf options](https://www.api2pdf.com/documentation/advanced-options-wkhtmltopdf/)
90-
- [headless chrome options](https://www.api2pdf.com/documentation/advanced-options-headless-chrome/)
100+
**Convert URL to PDF**
91101

92-
```
93-
from api2pdf import Api2Pdf
94-
a2p = Api2Pdf('YOUR-API-KEY')
95-
96-
# headless chrome
97-
headless_chrome_result = a2p.HeadlessChrome.convert_from_html('<p>Hello World</p>')
98-
print(headless_chrome_result.result)
102+
api_response = a2p_client.WkHtmlToPdf.convert_from_url('http://www.api2pdf.com')
99103

100-
# wkhtmltopdf
101-
wkhtmltopdf_result = a2p.WkHtmlToPdf.convert_from_html('<p>Hello World</p>')
102-
print(wkhtmltopdf_result.result)
103-
```
104+
**Convert URL to PDF (load PDF in browser window and specify a file name)**
105+
106+
api_response = a2p_client.WkHtmlToPdf.convert_from_url('http://www.api2pdf.com', inline_pdf=True, file_name='test.pdf')
104107

105-
### <a name="convert-from-url"></a>Convert URL to PDF
108+
**Convert URL to PDF (use keyword arguments for advanced wkhtmltopdf settings)**
109+
[View full list of wkhtmltopdf options available.](https://www.api2pdf.com/documentation/advanced-options-wkhtmltopdf/)
106110

107-
We support both wkhtmltopdf and Headless Chrome with the endpoint to convert urls to PDFs. Both endpoints allow you to pass keyword arguments that are options available for their respective libraries.
111+
options = {
112+
'orientation': 'landscape',
113+
'pageSize': 'A4'
114+
}
115+
api_response = a2p_client.WkHtmlToPdf.convert_from_url('http://www.api2pdf.com', **options)
108116

109-
##### HeadlessChrome.convert_from_url(url, inline_pdf=False, file_name=None, **options)
110117

111-
##### WkHtmlToPdf.convert_from_url(url, inline_pdf=False, file_name=None, **options)
118+
---
112119

113-
*Parameters:*
120+
## <a name="chrome"></a>Headless Chrome
114121

115-
`url <string>` - url to a pdf that Api2Pdf can consume
122+
**Convert HTML to PDF**
116123

117-
`inline_pdf <bool> (optional, default=False)` - if set to True, web browser will load the PDF in a new tab.
124+
api_response = a2p_client.HeadlessChrome.convert_from_html('<p>Hello, World</p>')
125+
126+
**Convert HTML to PDF (load PDF in browser window and specify a file name)**
118127

119-
`file_name <string> (optional, default=None)` - specify an optional file name like "report-03012019.pdf".
128+
api_response = a2p_client.HeadlessChrome.convert_from_html('<p>Hello, World</p>', inline_pdf=True, file_name='test.pdf')
129+
130+
**Convert HTML to PDF (use keyword arguments for advanced Headless Chrome settings)**
131+
[View full list of Headless Chrome options available.](https://www.api2pdf.com/documentation/advanced-options-headless-chrome/)
120132

121-
`**options <keyword args> (optional, default=None)` - include options for generating a PDF with your chosen library. See available options here:
133+
options = {
134+
'orientation': 'landscape',
135+
'pageSize': 'A4'
136+
}
137+
api_response = a2p_client.HeadlessChrome.convert_from_html('<p>Hello, World</p>', **options)
122138

123-
- [wkhtmltopdf options](https://www.api2pdf.com/documentation/advanced-options-wkhtmltopdf/)
124-
- [headless chrome options](https://www.api2pdf.com/documentation/advanced-options-headless-chrome/)
139+
**Convert URL to PDF**
125140

126-
```
127-
from api2pdf import Api2Pdf
128-
a2p = Api2Pdf('YOUR-API-KEY')
141+
api_response = a2p_client.HeadlessChrome.convert_from_url('http://www.api2pdf.com')
129142

130-
# headless chrome
131-
headless_chrome_result = a2p.HeadlessChrome.convert_from_url('https://LINK-TO-YOUR-WEBSITE')
132-
print(headless_chrome_result.result)
143+
**Convert URL to PDF (load PDF in browser window and specify a file name)**
144+
145+
api_response = a2p_client.HeadlessChrome.convert_from_url('http://www.api2pdf.com', inline_pdf=True, file_name='test.pdf')
133146

134-
# wkhtmltopdf
135-
wkhtmltopdf_result = a2p.WkHtmlToPdf.convert_from_url('https://LINK-TO-YOUR-WEBSITE')
136-
print(wkhtmltopdf_result.result)
137-
```
147+
**Convert URL to PDF (use keyword arguments for advanced Headless Chrome settings)**
148+
[View full list of Headless Chrome options available.](https://www.api2pdf.com/documentation/advanced-options-headless-chrome/)
149+
150+
options = {
151+
'orientation': 'landscape',
152+
'pageSize': 'A4'
153+
}
154+
api_response = a2p_client.HeadlessChrome.convert_from_url('http://www.api2pdf.com', **options)
138155

139-
### <a name="convert-from-office"></a>Convert Microsoft Office Documents and Images to PDF
156+
---
157+
158+
## <a name="libreoffice"></a>LibreOffice
140159

141-
We use **LibreOffice** to convert the following formats to PDF:
160+
LibreOffice supports the conversion to PDF from the following file formats:
142161

143162
- doc, docx, xls, xlsx, ppt, pptx, gif, jpg, png, bmp, rtf, txt, html
144163

145164
You must provide a url to the file. Our engine will consume the file at that URL and convert it to the PDF.
146165

147-
##### LibreOffice.convert_from_url(url, inline_pdf=False, file_name=None)
148-
149-
*Parameters:*
166+
**Convert Microsoft Office Document or Image to PDF**
150167

151-
`url <string>` - url to a file of one of the supported formats above
152-
153-
`inline_pdf <bool> (optional, default=False)` - if set to True, web browser will load the PDF in a new tab.
154-
155-
`file_name <string> (optional, default=None)` - specify an optional file name like "report-03012019.pdf".
168+
api_response = a2p_client.LibreOffice.convert_from_url('http://www.api2pdf.com')
169+
170+
**Convert Microsoft Office Document or Image to PDF (load PDF in browser window and specify a file name)**
156171

157-
```
158-
from api2pdf import Api2Pdf
159-
a2p = Api2Pdf('YOUR-API-KEY')
172+
api_response = a2p_client.LibreOffice.convert_from_url('http://www.api2pdf.com', inline_pdf=True, file_name='test.pdf')
160173

161-
libreoffice_result = a2p.LibreOffice.convert_from_html('https://LINK-TO-YOUR-FILE')
162-
print(libreoffice_result.result)
163-
```
174+
---
164175

165-
### <a name="merge"></a>Merge / Concatenate Two or More PDFs
176+
## <a name="merge"></a>Merge / Concatenate Two or More PDFs
166177

167178
To use the merge endpoint, supply a list of urls to existing PDFs. The engine will consume all of the PDFs and merge them into a single PDF, in the order in which they were provided in the list.
168179

169-
##### merge(list_of_urls, inline_pdf=False, file_name=None)
170-
171-
*Paramaters:*
180+
**Merge PDFs from list of URLs to existing PDFs**
172181

173-
`list_of_urls <list>` - list of urls to pdfs
174-
175-
`inline_pdf <bool> (optional, default=False)` - if set to True, web browser will load the PDF in a new tab.
182+
links_to_pdfs = ['https://LINK-TO-PDF', 'https://LINK-TO-PDF']
183+
merge_result = a2p_client.merge(links_to_pdfs)
176184

177-
`file_name <string> (optional, default=None)` - specify an optional file name like "report-03012019.pdf".
185+
**Merge PDFs from list of URLs to existing PDFs (load PDF in browser window and specify a file name)**
178186

179-
```
180-
from api2pdf import Api2Pdf
181-
a2p = Api2Pdf('YOUR-API-KEY')
187+
links_to_pdfs = ['https://LINK-TO-PDF', 'https://LINK-TO-PDF']
188+
merge_result = a2p_client.merge(links_to_pdfs, inline_pdf=True, file_name='test.pdf')
182189

183-
# merge pdfs
184-
links_to_pdfs = ['https://LINK-TO-PDF', 'https://LINK-TO-PDF']
185-
merge_result = a2p.merge(links_to_pdfs)
186-
print(merge_result.result)
187-
```
190+
---
188191

189-
### <a name="helper-methods"></a>Helper Methods
192+
## <a name="helpers"></a>Helper Methods
190193

191-
##### Api2PdfResponse: download_pdf()
194+
**Api2PdfResponse: download_pdf()**
192195

193-
On any `Api2PdfResponse` that succesfully generated a pdf, you can use the handy download_pdf() method to download the pdf to a file-like object which you can then save to your local cache. If the pdf generation was unsuccessful, it will throw a FileNotFoundException.
196+
On any `Api2PdfResponse` that succesfully generated a pdf, you can use the handy `download_pdf()` method to download the pdf to a file-like object which you can then save to your local cache. If the pdf generation was unsuccessful, it will throw a FileNotFoundException.
194197

195198
```
196199
from api2pdf import Api2Pdf
197-
a2p = Api2Pdf('YOUR-API-KEY')
200+
a2p_client = Api2Pdf('YOUR-API-KEY')
198201
199202
# merge pdfs
200203
links_to_pdfs = ['https://LINK-TO-PDF', 'https://LINK-TO-PDF']
201-
merge_result = a2p.merge(links_to_pdfs)
204+
merge_result = a2p_client.merge(links_to_pdfs)
202205
203206
pdf_as_file_object = merge_result.download_pdf()
204207
```
205-
208+
---
206209
## <a name="faq"></a>FAQ
207210

208211
#### How do you bill?
@@ -215,7 +218,7 @@ The average customer spents about $2/month on our product. We do not have free a
215218
We do not have any long term contracts. You can leave us at anytime with no further commitments. As our minimum cost is $1.00, we do not provide refunds.
216219

217220
#### Are there any limits?
218-
Api2Pdf does not set any specific limits on PDF file size, however our system does have processing power limitations. Each PDF request is provided 3 GB of RAM to work with and 110 seconds to generate the PDF. We offer WKHTMLTOPDF, Headless Chrome, and LibreOffice to do conversions. Our platform will have the same limits as those underlying components. If the underlying component fails to convert to PDF, it will also fail via our service. Some examples are:
221+
Api2Pdf does not set any specific limits on PDF file size, however our system does have processing power limitations. Each PDF request is provided 3 GB of RAM to work with and 90 seconds to generate the PDF. We offer WKHTMLTOPDF, Headless Chrome, and LibreOffice to do conversions. Our platform will have the same limits as those underlying components. If the underlying component fails to convert to PDF, it will also fail via our service. Some examples are:
219222

220223
- Password protected PDFs
221224
- Encrypted PDFs

0 commit comments

Comments
 (0)