Content
", 46 | content_format="html", publish_status="draft") 47 | 48 | # When your access token expires, use the refresh token to get a new one. 49 | client.exchange_refresh_token(auth["refresh_token"]) 50 | 51 | # Confirm everything went ok. post["url"] has the location of the created post. 52 | print "My new post!", post["url"] 53 | ``` 54 | 55 | ## Running tests 56 | 57 | To run tests against this package, first install the test requirements and make 58 | sure that the `medium` package is exportable. (We recommend using virtualenv.) 59 | 60 | ```bash 61 | $ pip install -r tests/requirements.txt 62 | $ pip install -e . 63 | ``` 64 | 65 | Then run the primary test file: 66 | 67 | ```bash 68 | $ python tests/test.py 69 | ``` 70 | 71 | ## Contributing 72 | 73 | Questions, comments, bug reports, and pull requests are all welcomed. If you 74 | haven't contributed to a Medium project before please head over to the [Open 75 | Source Project](https://github.com/Medium/opensource#note-to-external-contributors) 76 | and fill out an OCLA (it should be pretty painless). 77 | 78 | ## Authors 79 | 80 | - [Kyle Hardgrave](https://github.com/kylehg) 81 | 82 | ## License 83 | 84 | Copyright 2015 [A Medium Corporation](https://medium.com/) 85 | 86 | Licensed under Apache License Version 2.0. Details in the attached LICENSE file. 87 | -------------------------------------------------------------------------------- /medium/__init__.py: -------------------------------------------------------------------------------- 1 | # Copyright 2015 A Medium Corporation 2 | from os.path import basename 3 | try: 4 | from urllib.parse import urlencode 5 | except ImportError: 6 | from urllib import urlencode 7 | 8 | import requests 9 | 10 | BASE_PATH = "https://api.medium.com" 11 | 12 | 13 | class Client(object): 14 | """A client for the Medium OAuth2 REST API.""" 15 | 16 | def __init__(self, application_id=None, application_secret=None, 17 | access_token=None): 18 | self.application_id = application_id 19 | self.application_secret = application_secret 20 | self.access_token = access_token 21 | 22 | def get_authorization_url(self, state, redirect_url, scopes): 23 | """Get a URL for users to authorize the application. 24 | 25 | :param str state: A string that will be passed back to the redirect_url 26 | :param str redirect_url: The URL to redirect after authorization 27 | :param list scopes: The scopes to grant the application 28 | :returns: str 29 | """ 30 | qs = { 31 | "client_id": self.application_id, 32 | "scope": ",".join(scopes), 33 | "state": state, 34 | "response_type": "code", 35 | "redirect_uri": redirect_url, 36 | } 37 | 38 | return "https://medium.com/m/oauth/authorize?" + urlencode(qs) 39 | 40 | def exchange_authorization_code(self, code, redirect_url): 41 | """Exchange the authorization code for a long-lived access token, and 42 | set the token on the current Client. 43 | 44 | :param str code: The code supplied to the redirect URL after a user 45 | authorizes the application 46 | :param str redirect_url: The same redirect URL used for authorizing 47 | the application 48 | :returns: A dictionary with the new authorizations :: 49 | { 50 | 'token_type': 'Bearer', 51 | 'access_token': '...', 52 | 'expires_at': 1449441560773, 53 | 'refresh_token': '...', 54 | 'scope': ['basicProfile', 'publishPost'] 55 | } 56 | """ 57 | data = { 58 | "code": code, 59 | "client_id": self.application_id, 60 | "client_secret": self.application_secret, 61 | "grant_type": "authorization_code", 62 | "redirect_uri": redirect_url, 63 | } 64 | return self._request_and_set_auth_code(data) 65 | 66 | def exchange_refresh_token(self, refresh_token): 67 | """Exchange the supplied refresh token for a new access token, and 68 | set the token on the current Client. 69 | 70 | :param str refresh_token: The refresh token, as provided by 71 | ``exchange_authorization_code()`` 72 | :returns: A dictionary with the new authorizations :: 73 | { 74 | 'token_type': 'Bearer', 75 | 'access_token': '...', 76 | 'expires_at': 1449441560773, 77 | 'refresh_token': '...', 78 | 'scope': ['basicProfile', 'publishPost'] 79 | } 80 | """ 81 | data = { 82 | "refresh_token": refresh_token, 83 | "client_id": self.application_id, 84 | "client_secret": self.application_secret, 85 | "grant_type": "refresh_token", 86 | } 87 | return self._request_and_set_auth_code(data) 88 | 89 | def get_current_user(self): 90 | """Fetch the data for the currently authenticated user. 91 | 92 | Requires the ``basicProfile`` scope. 93 | 94 | :returns: A dictionary with the users data :: 95 | 96 | { 97 | 'username': 'kylehg', 98 | 'url': 'https://medium.com/@kylehg', 99 | 'imageUrl': 'https://cdn-images-1.medium.com/...', 100 | 'id': '1f86...', 101 | 'name': 'Kyle Hardgrave' 102 | } 103 | """ 104 | return self._request("GET", "/v1/me") 105 | 106 | def create_post(self, user_id, title, content, content_format, tags=None, 107 | canonical_url=None, publish_status=None, license=None): 108 | """Create a post for the current user. 109 | 110 | Requires the ``publishPost`` scope. 111 | 112 | :param str user_id: The application-specific user ID as returned by 113 | ``get_current_user()`` 114 | :param str title: The title of the post 115 | :param str content: The content of the post, in HTML or Markdown 116 | :param str content_format: The format of the post content, either 117 | ``html`` or ``markdown`` 118 | :param list tags: (optional), List of tags for the post, max 3 119 | :param str canonical_url: (optional), A rel="canonical" link for 120 | the post 121 | :param str publish_status: (optional), What to publish the post as, 122 | either ``public``, ``unlisted``, or ``draft``. Defaults to 123 | ``public``. 124 | :param license: (optional), The license to publish the post under: 125 | - ``all-rights-reserved`` (default) 126 | - ``cc-40-by`` 127 | - ``cc-40-by-sa`` 128 | - ``cc-40-by-nd`` 129 | - ``cc-40-by-nc`` 130 | - ``cc-40-by-nc-nd`` 131 | - ``cc-40-by-nc-sa`` 132 | - ``cc-40-zero`` 133 | - ``public-domain`` 134 | :returns: A dictionary with the post data :: 135 | 136 | { 137 | 'canonicalUrl': '', 138 | 'license': 'all-rights-reserved', 139 | 'title': 'My Title', 140 | 'url': 'https://medium.com/@kylehg/55050649c95', 141 | 'tags': ['python', 'is', 'great'], 142 | 'authorId': '1f86...', 143 | 'publishStatus': 'draft', 144 | 'id': '55050649c95' 145 | } 146 | """ 147 | data = { 148 | "title": title, 149 | "content": content, 150 | "contentFormat": content_format, 151 | } 152 | if tags is not None: 153 | data["tags"] = tags 154 | if canonical_url is not None: 155 | data["canonicalUrl"] = canonical_url 156 | if publish_status is not None: 157 | data["publishStatus"] = publish_status 158 | if license is not None: 159 | data["license"] = license 160 | 161 | path = "/v1/users/%s/posts" % user_id 162 | return self._request("POST", path, json=data) 163 | 164 | def upload_image(self, file_path, content_type): 165 | """Upload a local image to Medium for use in a post. 166 | 167 | Requires the ``uploadImage`` scope. 168 | 169 | :param str file_path: The file path of the image 170 | :param str content_type: The type of the image. Valid values are 171 | ``image/jpeg``, ``image/png``, ``image/gif``, and ``image/tiff``. 172 | :returns: A dictionary with the image data :: 173 | 174 | { 175 | 'url': 'https://cdn-images-1.medium.com/0*dlkfjalksdjfl.jpg', 176 | 'md5': 'd87e1628ca597d386e8b3e25de3a18b8' 177 | } 178 | """ 179 | with open(file_path, "rb") as f: 180 | filename = basename(file_path) 181 | files = {"image": (filename, f, content_type)} 182 | return self._request("POST", "/v1/images", files=files) 183 | 184 | def _request_and_set_auth_code(self, data): 185 | """Request an access token and set it on the current client.""" 186 | result = self._request("POST", "/v1/tokens", form_data=data) 187 | self.access_token = result["access_token"] 188 | return result 189 | 190 | def _request(self, method, path, json=None, form_data=None, files=None): 191 | """Make a signed request to the given route.""" 192 | url = BASE_PATH + path 193 | headers = { 194 | "Accept": "application/json", 195 | "Accept-Charset": "utf-8", 196 | "Authorization": "Bearer %s" % self.access_token, 197 | } 198 | 199 | resp = requests.request(method, url, json=json, data=form_data, 200 | files=files, headers=headers) 201 | json = resp.json() 202 | if 200 <= resp.status_code < 300: 203 | try: 204 | return json["data"] 205 | except KeyError: 206 | return json 207 | 208 | raise MediumError("API request failed", json) 209 | 210 | 211 | class MediumError(Exception): 212 | """Wrapper for exceptions generated by the Medium API.""" 213 | 214 | def __init__(self, message, resp={}): 215 | self.resp = resp 216 | try: 217 | error = resp["errors"][0] 218 | except KeyError: 219 | error = {} 220 | self.code = error.get("code", -1) 221 | self.msg = error.get("message", message) 222 | super(MediumError, self).__init__(self.msg) 223 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | requests==2.20.0 2 | -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [metadata] 2 | description-file = README.md 3 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | from distutils.core import setup 2 | setup( 3 | name='medium', 4 | packages=['medium'], 5 | install_requires=['requests'], 6 | version='0.3.0', 7 | description='SDK for working with the Medium API', 8 | author='Kyle Hardgrave', 9 | author_email='kyle@medium.com', 10 | url='https://github.com/Medium/medium-sdk-python', 11 | download_url='https://github.com/Medium/medium-sdk-python/tarball/v0.3.0', 12 | keywords=['medium', 'sdk', 'oauth', 'api'], 13 | classifiers=[], 14 | ) 15 | -------------------------------------------------------------------------------- /tests/requirements.txt: -------------------------------------------------------------------------------- 1 | responses==0.5.0 2 | -------------------------------------------------------------------------------- /tests/test.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Medium/medium-sdk-python/48a29d6a96258855ed89ceb7dce67f29219ac7e7/tests/test.png -------------------------------------------------------------------------------- /tests/test.py: -------------------------------------------------------------------------------- 1 | # Copyright 2015 A Medium Corporation 2 | import json 3 | import unittest 4 | try: 5 | from urllib.parse import parse_qs 6 | except ImportError: 7 | from urlparse import parse_qs 8 | 9 | import requests 10 | import responses 11 | 12 | from medium import Client 13 | 14 | class TestClient(unittest.TestCase): 15 | 16 | def setUp(self): 17 | self.client = Client(access_token="myaccesstoken") 18 | 19 | @responses.activate 20 | def test_exchange_authorization_code(self): 21 | def response_callback(payload): 22 | self.assertEqual(payload["code"][0], "mycode") 23 | self.assertEqual(payload["client_id"][0], "myclientid") 24 | self.assertEqual(payload["client_secret"][0], "myclientsecret") 25 | self.assertEqual(payload["grant_type"][0], "authorization_code") 26 | self.assertEqual(payload["redirect_uri"][0], 27 | "http://example.com/cb") 28 | data = { 29 | "token_type": "Bearer", 30 | "access_token": "myaccesstoken", 31 | "expires_at": 4575744000000, 32 | "refresh_token": "myrefreshtoken", 33 | "scope": ["basicProfile"], 34 | } 35 | return (201, data) 36 | self._mock_endpoint("POST", "/v1/tokens", response_callback, 37 | is_json=False) 38 | 39 | client = Client(application_id="myclientid", 40 | application_secret="myclientsecret") 41 | 42 | # TODO(kyle) Remove after Ceasar's refactoring 43 | resp = client.exchange_authorization_code("mycode", 44 | "http://example.com/cb") 45 | self.assertEqual(resp["access_token"], "myaccesstoken") 46 | self.assertEqual(resp["refresh_token"], "myrefreshtoken") 47 | self.assertEqual(resp["scope"], ["basicProfile"]) 48 | 49 | # TODO(kyle) Uncomment after Ceasar's refactoring 50 | # client.exchange_authorization_code("mycode", "http://example.com/cb") 51 | # self.assertEqual(client.access_token, "myaccesstoken") 52 | # self.assertEqual(client.refresh_token, "myrefreshtoken") 53 | 54 | @responses.activate 55 | def test_exchange_refresh_token(self): 56 | def response_callback(payload): 57 | self.assertEqual(payload["refresh_token"][0], "myrefreshtoken") 58 | self.assertEqual(payload["client_id"][0], "myclientid") 59 | self.assertEqual(payload["client_secret"][0], "myclientsecret") 60 | self.assertEqual(payload["grant_type"][0], "refresh_token") 61 | data = { 62 | "token_type": "Bearer", 63 | "access_token": "myaccesstoken2", 64 | "expires_at": 4575744000000, 65 | "refresh_token": "myrefreshtoken2", 66 | "scope": ["basicProfile"], 67 | } 68 | return (201, data) 69 | self._mock_endpoint("POST", "/v1/tokens", response_callback, 70 | is_json=False) 71 | 72 | client = Client(application_id="myclientid", 73 | application_secret="myclientsecret") 74 | 75 | # TODO(kyle) Remove after Ceasar's refactoring 76 | resp = client.exchange_refresh_token("myrefreshtoken") 77 | self.assertEqual(resp["access_token"], "myaccesstoken2") 78 | self.assertEqual(resp["refresh_token"], "myrefreshtoken2") 79 | self.assertEqual(resp["scope"], ["basicProfile"]) 80 | 81 | # TODO(kyle) Uncomment after Ceasar's refactoring 82 | # client.exchange_refresh_token("myrefreshtoken") 83 | # self.assertEqual(client.access_token, "myaccesstoken2") 84 | # self.assertEqual(client.refresh_token, "myrefreshtoken2") 85 | 86 | @responses.activate 87 | def test_get_current_user(self): 88 | def response_callback(payload): 89 | data = { 90 | "username": "nicki", 91 | "url": "https://medium.com/@nicki", 92 | "imageUrl": "https://images.medium.com/0*fkfQiTzT7TlUGGyI.png", 93 | "id": "5303d74c64f66366f00cb9b2a94f3251bf5", 94 | "name": "Nicki Minaj", 95 | } 96 | return 200, data 97 | self._mock_endpoint("GET", "/v1/me", response_callback) 98 | 99 | resp = self.client.get_current_user() 100 | self.assertEqual(resp, { 101 | "username": "nicki", 102 | "url": "https://medium.com/@nicki", 103 | "imageUrl": "https://images.medium.com/0*fkfQiTzT7TlUGGyI.png", 104 | "id": "5303d74c64f66366f00cb9b2a94f3251bf5", 105 | "name": "Nicki Minaj", 106 | }) 107 | 108 | @responses.activate 109 | def test_create_post(self): 110 | def response_callback(payload): 111 | self.assertEqual(payload, { 112 | "title": "Starships", 113 | "content": "Are meant to flyyyy
", 114 | "contentFormat": "html", 115 | "tags": ["stars", "ships", "pop"], 116 | "publishStatus": "draft", 117 | }) 118 | 119 | data = { 120 | "license": "all-rights-reserved", 121 | "title": "Starships", 122 | "url": "https://medium.com/@nicki/55050649c95", 123 | "tags": ["stars", "ships", "pop"], 124 | "authorId": "5303d74c64f66366f00cb9b2a94f3251bf5", 125 | "publishStatus": "draft", 126 | "id": "55050649c95", 127 | } 128 | return 200, data 129 | self._mock_endpoint( 130 | "POST", 131 | "/v1/users/5303d74c64f66366f00cb9b2a94f3251bf5/posts", 132 | response_callback 133 | ) 134 | 135 | resp = self.client.create_post( 136 | "5303d74c64f66366f00cb9b2a94f3251bf5", 137 | "Starships", 138 | "Are meant to flyyyy
", 139 | "html", 140 | tags=["stars", "ships", "pop"], 141 | publish_status="draft" 142 | ) 143 | self.assertEqual(resp, { 144 | "license": "all-rights-reserved", 145 | "title": "Starships", 146 | "url": "https://medium.com/@nicki/55050649c95", 147 | "tags": ["stars", "ships", "pop"], 148 | "authorId": "5303d74c64f66366f00cb9b2a94f3251bf5", 149 | "publishStatus": "draft", 150 | "id": "55050649c95", 151 | }) 152 | 153 | @responses.activate 154 | def test_upload_image(self): 155 | def response_callback(req): 156 | self.assertEqual(req.headers["Authorization"], 157 | "Bearer myaccesstoken") 158 | self.assertIn(b"Content-Type: image/png", req.body) 159 | return 200, {}, json.dumps({ 160 | "url": "https://cdn-images-1.medium.com/0*dlkfjalksdjfl.jpg", 161 | "md5": "d87e1628ca597d386e8b3e25de3a18bc", 162 | }) 163 | responses.add_callback(responses.POST, "https://api.medium.com/v1/images", 164 | content_type="application/json", 165 | callback=response_callback) 166 | 167 | resp = self.client.upload_image("./tests/test.png", "image/png") 168 | self.assertEqual(resp, { 169 | "url": "https://cdn-images-1.medium.com/0*dlkfjalksdjfl.jpg", 170 | "md5": "d87e1628ca597d386e8b3e25de3a18bc", 171 | }) 172 | 173 | def _mock_endpoint(self, method, path, callback, is_json=True): 174 | def wrapped_callback(req): 175 | if is_json: 176 | self.assertEqual(req.headers["Authorization"], 177 | "Bearer myaccesstoken") 178 | if req.body is not None: 179 | body = json.loads(req.body) if is_json else parse_qs(req.body) 180 | else: 181 | body = None 182 | status, data = callback(body) 183 | return (status, {}, json.dumps(data)) 184 | response_method = responses.GET if method == "GET" else responses.POST 185 | url = "https://api.medium.com" + path 186 | content_type = ("application/json" if is_json else 187 | "application/x-www-form-urlencoded") 188 | responses.add_callback(response_method, url, content_type=content_type, 189 | callback=wrapped_callback) 190 | 191 | 192 | if __name__ == "__main__": 193 | unittest.main() 194 | --------------------------------------------------------------------------------