Skip to content

Commit d177224

Browse files
author
Alex Schworer
committed
Merge branch 'master' into irqed-master
Conflicts: README.md
2 parents d719024 + af19067 commit d177224

File tree

2 files changed

+190
-49
lines changed

2 files changed

+190
-49
lines changed

‎README.md

Lines changed: 186 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,198 @@
1-
# Zencoder
1+
2+
Zencoder
3+
--------
4+
25
[![Build Status](https://travis-ci.org/zencoder/zencoder-py.png?branch=master)](https://travis-ci.org/zencoder/zencoder-py)
36

4-
A Python module for the [Zencoder](http://zencoder.com) API.
7+
A Python module for interacting with the [Zencoder](http://zencoder.com) API.
8+
9+
### Getting Started
10+
11+
Install from PyPI
12+
13+
$ pip install zencoder
14+
15+
Import zencoder
16+
17+
```python
18+
from zencoder import Zencoder
19+
```
20+
21+
Create an instance of the Zencoder client. This will accept an API key and version. If not API key is set, it will look for a `ZENCODER_API_KEY` environment variable. API version defaults to 'v2'.
22+
23+
# If you want to specify an API key when creating a client
24+
client = Zencoder('API_KEY')
25+
26+
# If you have the environment variable set
27+
client = Zencoder()
28+
29+
## [Jobs](https://app.zencoder.com/docs/api/jobs)
30+
31+
Create a [new job](https://app.zencoder.com/docs/api/jobs/create).
32+
33+
```python
34+
client.job.create('s3://bucket/key.mp4')
35+
client.job.create('s3://bucket/key.mp4',
36+
outputs=[{'label': 'vp8 for the web',
37+
'url': 's3://bucket/key_output.webm'}])
38+
```
39+
40+
This returns a `zencoder.Response` object. The body includes a Job ID, and one or more Output IDs (one for every output file created).
41+
42+
```python
43+
response = client.job.create('s3://bucket/key.mp4')
44+
response.code # 201
45+
response.body['id'] # 12345
46+
```
47+
48+
[List jobs](https://app.zencoder.com/docs/api/jobs/list).
49+
50+
By default the jobs listing is paginated with 50 jobs per page and sorted by ID in descending order. You can pass two parameters to control the paging: `page` and `per_page`.
51+
52+
```python
53+
client.job.list(per_page=10)
54+
client.job.list(per_page=10, page=2)
55+
```
56+
57+
Get [details](https://app.zencoder.com/docs/api/jobs/show) about a job.
58+
59+
The number passed to `details` is the ID of a Zencoder job.
60+
61+
```python
62+
client.job.details(1)
63+
```
64+
65+
Get [progress](https://app.zencoder.com/docs/api/jobs/progress) on a job.
66+
67+
The number passed to `progress` is the ID of a Zencoder job.
68+
69+
```python
70+
client.job.progress(1)
71+
```
72+
73+
[Resubmit](https://app.zencoder.com/docs/api/jobs/resubmit) a job
74+
75+
The number passed to `resubmit` is the ID of a Zencoder job.
76+
77+
```python
78+
client.job.resubmit(1)
79+
```
80+
81+
[Cancel](https://app.zencoder.com/docs/api/jobs/cancel) a job
82+
83+
The number passed to `cancel` is the ID of a Zencoder job.
584

6-
## Installation
7-
Install from PyPI using `easy_install` or `pip`.
85+
```python
86+
client.job.cancel(1)
87+
```
88+
89+
## [Inputs](https://app.zencoder.com/docs/api/inputs)
890

9-
pip install zencoder
91+
Get [details](https://app.zencoder.com/docs/api/inputs/show) about an input.
92+
93+
The number passed to `details` is the ID of a Zencoder job.
94+
95+
```python
96+
client.input.details(1)
97+
```
98+
99+
Get [progress](https://app.zencoder.com/docs/api/inputs/progress) for an input.
100+
101+
The number passed to `progress` is the ID of a Zencoder job.
102+
103+
```python
104+
client.input.progress(1)
105+
```
106+
## [Outputs](https://app.zencoder.com/docs/api/outputs)
10107

11-
## Dependencies
12-
`zencoder-py` depends on [requests](http://python-requests.org), and uses the `json` or `simplejson` module.
108+
Get [details](https://app.zencoder.com/docs/api/outputs/show) about an output.
13109

14-
## Usage
110+
The number passed to `details` is the ID of a Zencoder job.
15111

16-
from zencoder import Zencoder
17-
zen = Zencoder('abc123') # enter your api key
112+
```python
113+
client.output.details(1)
114+
```
18115

19-
# creates an encoding job with the defaults
20-
job = zen.job.create('http://input-file/movie.avi')
21-
print job.code
22-
print job.body
23-
print job.body['id']
116+
Get [progress](https://app.zencoder.com/docs/api/outputs/progress) for an output.
24117

25-
# get the transcode progress of the first output
26-
progress = zen.output.progress(job.body['outputs'][0]['id'])
27-
print progress.body
118+
The number passed to `progress` is the ID of a Zencoder job.
28119

120+
```python
121+
client.output.progress(1)
122+
```
29123

30-
# configure your outputs with dictionaries
31-
iphone = {
32-
'label': 'iPhone',
33-
'url': 's3://output-bucket/output-file-1.mp4',
34-
'width': 480,
35-
'height': 320
36-
}
37-
web = {
38-
'label': 'web',
39-
'url': 's3://output-bucket/output-file.vp8',
40-
'video_codec':, 'vp8'
41-
}
42-
# the outputs kwarg requires an iterable
43-
outputs = (iphone, web)
44-
another_job = zen.job.create(input_url, outputs=outputs)
124+
## [Reports](https://app.zencoder.com/docs/api/reports)
45125

46-
**Note:** If you set the `ZENCODER_API_KEY` environment variable to your api key, you don't have to provide it when initializing Zencoder.
126+
Reports are great for getting usage data for your account. All default to 30 days from yesterday with no [grouping](https://app.zencoder.com/docs/api/encoding/job/grouping), but this can be altered. These will return `422 Unprocessable Entity` if the date format is incorrect or the range is greater than 2 months.
47127

48-
## Specifying the API Version
49-
Set the version of the Zencoder API you want to use as the `api_version` keyword to the `Zencoder` object (defaults to `v2`):
128+
Get [all usage](https://app.zencoder.com/docs/api/reports/all) (Live + VOD).
50129

51130
```python
52-
# set to version 1: https://app.zencoder.com/api/v1/
53-
zen = Zencoder(api_version='v1')
131+
import datetime
132+
client.report.all()
133+
client.report.all(grouping="foo")
134+
client.report.all(start_date=datetime.date(2011, 10, 30),
135+
end_date=datetime.date(2011, 11, 24))
136+
client.report.all(start_date=datetime.date(2011, 10, 30),
137+
end_date=datetime.date(2011, 11, 24),
138+
grouping="foo")
139+
```
54140

55-
# set to the edge version: https://app.zencoder.com/api/
56-
zen = Zencoder(api_version='edge')
141+
Get [VOD usage](https://app.zencoder.com/docs/api/reports/vod).
142+
143+
```python
144+
import datetime
145+
client.report.vod()
146+
client.report.vod(grouping="foo")
147+
client.report.vod(start_date=datetime.date(2011, 10, 30),
148+
end_date=datetime.date(2011, 11, 24))
149+
client.report.vod(start_date=datetime.date(2011, 10, 30),
150+
end_date=datetime.date(2011, 11, 24),
151+
grouping="foo")
152+
```
153+
154+
Get [Live usage](https://app.zencoder.com/docs/api/reports/live).
155+
156+
```python
157+
import datetime
158+
client.report.live()
159+
client.report.live(grouping="foo")
160+
client.report.live(start_date=datetime.date(2011, 10, 30),
161+
end_date=datetime.date(2011, 11, 24))
162+
client.report.live(start_date=datetime.date(2011, 10, 30),
163+
end_date=datetime.date(2011, 11, 24),
164+
grouping="foo")
165+
```
166+
167+
## [Accounts](https://app.zencoder.com/docs/api/accounts)
168+
169+
Create a [new account](https://app.zencoder.com/docs/api/accounts/create). A unique email address and terms of service are required, but you can also specify a password (and confirmation) along with whether or not you want to subscribe to the Zencoder newsletter. New accounts will be created under the Test (Free) plan.
170+
171+
No API Key is required.
172+
173+
```python
174+
client.account.create('[email protected]', tos=1)
175+
client.account.create('[email protected]', tos=1,
176+
options={'password': 'abcd1234',
177+
'affiliate_code': 'foo'})
178+
```
179+
180+
Get [details](https://app.zencoder.com/docs/api/accounts/show) about the current account.
181+
182+
```python
183+
client.account.details()
184+
```
185+
186+
Turn [integration mode](https://app.zencoder.com/docs/api/accounts/integration) on (all jobs are test jobs).
187+
188+
```python
189+
client.account.integration()
190+
```
191+
192+
Turn off integration mode, which means your account is live (and you'll be billed for jobs).
193+
194+
```python
195+
client.account.live()
57196
```
58197

59198
## Additional settings
@@ -62,12 +201,13 @@ In adition Zencoder class consructor takes these arguments:
62201
* `cert` - (optional) if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.
63202
* `http_timeout` - (optional) Float describing the timeout of the request
64203

65-
## Documentation
66-
Docs are in progress, and hosted at Read the Docs: http://zencoder.rtfd.org
204+
## Tests
205+
206+
The tests use the `mock` library to stub in response data from the API. Run tests individually:
207+
208+
$ python test/test_jobs.py
67209

68-
## Contributors
69-
* [Senko Rasic](http://github.com/senko)
70-
* [Josh Kennedy](http://github.com/kennedyj)
71-
* [Issac Kelly](http://github.com/issackelly)
210+
Or use `nose`:
72211

212+
$ nosetests
73213

‎docs/index.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,11 @@ Contents:
1616

1717
Introduction:
1818

19-
`zencoder` is a Python module for the Zencoder API_. For Zencoder guides and API documentation, check out the official Zencoder docs here_.
19+
``zencoder`` is a Python module for the `Zencoder API`_.
2020

21-
Source is hosted at github: http://github.com/zencoder/zencoder-py
21+
Official Zencoder API Docs: https://app.zencoder.com/docs
22+
23+
``zencoder-py`` Github: http://github.com/zencoder/zencoder-py
2224

2325
Indices and tables
2426
==================
@@ -28,5 +30,4 @@ Indices and tables
2830
* :ref:`search`
2931

3032
.. _Zencoder API: https://app.zencoder.com/docs
31-
.. _here: https://app.zencoder.com/docs
3233

0 commit comments

Comments
 (0)