diff --git a/.gitignore b/.gitignore index c18dd39..45bfe99 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ *.pyc -Embedly.egg-info/ +*.egg-info/ +.tox/ build/ dist/ .virtualenv diff --git a/.travis.yml b/.travis.yml index 718566f..8891f22 100644 --- a/.travis.yml +++ b/.travis.yml @@ -4,6 +4,4 @@ python: - 2.7 - 3.2 - 3.3 -script: python embedly/tests.py -install: - - python setup.py -q install \ No newline at end of file +script: python setup.py test diff --git a/README.rst b/README.rst index 74d9ee9..f514ce2 100644 --- a/README.rst +++ b/README.rst @@ -1,7 +1,7 @@ embedly-python ============== -Python Library for interacting with Embedly's API. To get started sign up for -a key at `embed.ly/signup `_. +Python library for interacting with Embedly's API. To get started sign up for +a key at `embed.ly/signup `_. Install ------- @@ -9,43 +9,51 @@ Install with `Pip `_ (recommended):: pip install embedly -Or easy_install +Or easy_install:: - sudo easy_install Embedly + easy_install Embedly Or setuptools:: git clone git://github.com/embedly/embedly-python.git - sudo python setup.py + python setup.py +Setup requires Setuptools 0.7+ or Distribute 0.6.2+ in order to take advantage +of the ``2to3`` option. Setup will still run on earlier versions but you'll +see a warning and ``2to3`` won't happen. Read more in the Setuptools +`docs `_ Getting Started --------------- This library is meant to be a dead simple way to interact with the Embedly API. -There are only 2 main objects, the ``Embedly`` client and the ``Url`` model. -Here is a simple example and then we will go into the objects:: +There are only 2 main objects, the ``Embedly`` client and the ``Url`` response +model. Here is a simple example and then we will go into the objects:: >>> from embedly import Embedly >>> client = Embedly(:key) - >>> obj = client.oembed('http://instagr.am/p/BL7ti/') + >>> obj = client.oembed('http://instagram.com/p/BL7ti/') >>> obj['type'] u'photo' >>> obj['url'] - u'http://distillery.s3.amazonaws.com/media/2011/01/24/cdd759a319184cb79793506607ff5746_7.jpg' + u'http://images.ak.instagram.com/media/2011/01/24/cdd759a319184cb79793506607ff5746_7.jpg' - >>> obj = client.oembed('http://instagr.am/p/error') + >>> obj = client.oembed('http://instagram.com/error/error/') >>> obj['error'] True Embedly Client """""""""""""" -The Embedly client is a object that takes in a key and an optional User Agent -then handles all the interactions and HTTP requests to Embedly. To initialize -the object pass in your key you got from signing up for Embedly and an optional -User Agent. +The Embedly client is a object that takes in a key and optional User Agent +and timeout parameters then handles all the interactions and HTTP requests +to Embedly. To initialize the object, you'll need the key that you got when +you signed up for Embedly. +:: >>> from embedly import Embedly - >>> client = Embedly('key', 'Mozilla/5.0 (compatible; example-org;)') + >>> client = Embedly('key') + >>> client2 = Embedly('key', 'Mozilla/5.0 (compatible; example-org;)') + >>> client3 = Embedly('key', 'Mozilla/5.0 (compatible; example-org;)', 30) + >>> client4 = Embedly('key', timeout=10, user_agent='Mozilla/5.0 (compatible; example-org;)') The client object now has a bunch of different methods that you can use. @@ -68,6 +76,8 @@ The client object now has a bunch of different methods that you can use. ``preview`` + **Preview is no longer available to new users and has been replaced by extract.** + Corresponds to the `Preview endpoint `_. Passes back a simple object that allows you to retrieve a title, description, content, html and a list of @@ -77,6 +87,8 @@ The client object now has a bunch of different methods that you can use. ``objectify`` + **Objectify is no longer available to new users and has been replaced by extract.** + Corresponds to the `Objectify endpoint `_. Passes back a simple object that allows you to retrieve pretty much everything that Embedly knows about a @@ -85,14 +97,14 @@ The client object now has a bunch of different methods that you can use. >>> client.objectify('http://vimeo.com/18150336') -The above functions all take the same arguements, a URL or a list of URLs and +The above functions all take the same arguments, a URL or a list of URLs and keyword arguments that correspond to Embedly's `query arguments `_. Here is an example:: >>> client.oembed(['http://vimeo.com/18150336', 'http://www.youtube.com/watch?v=hD7ydlyhvKs'], maxwidth=500, words=20) -There are some supporting functions that allow you to limit urls before sending +There are some supporting functions that allow you to limit URLs before sending them to Embedly. Embedly can return metadata for any URL, these just allow a developer to only pass a subset of Embedly `providers `_. Note that URL shorteners like bit.ly or t.co are @@ -116,43 +128,60 @@ not supported through these regexes. Url Object """""""""" -The ``Url`` Object is just a smart dictionary that acts more like an object. -For example when you run ``oembed`` you get back a Url Object: +The ``Url`` object is basically a response dictionary returned from +one of the Embedly API endpoints. +:: - >>> obj = client.oembed('http://vimeo.com/18150336', words=10) + >>> response = client.oembed('http://vimeo.com/18150336', words=10) -Depending on the method you are using, the object has a different set of +Depending on the method you are using, the response will have different attributes. We will go through a few, but you should read the `documentation -`_ to get the full list of data that is passed back.:: +`_ to get the full list of data that is passed back. +:: - # Url Object can be accessed like a dictionary - >>> obj['type'] + >>> response['type'] u'video' + >>> response['title'] + u'Wingsuit Basejumping - The Need 4 Speed: The Art of Flight' + >>> response['provider_name'] + u'Vimeo' + >>> response['width'] + 1280 + +As you can see the ``Url`` object works like a dictionary, but it's slightly +enhanced. It will always have ``method`` and ``original_url`` attributes, +which represent the Embedly request type and the URL requested. +:: + + >>> response.method + 'oembed' + >>> response.original_url + 'http://vimeo.com/18150336' - # The url object always has an ``original_url`` attrbiute. - >>> obj.original_url - u'http://vimeo.com/18150336' - # The method used to retrieve the URL is also on the obj - >>> obj.method - u'oembed' + # useful because the response data itself may not have a URL + # (or it could have a redirected link, querystring params, etc) + >>> response['url'] + ... + KeyError: 'url' -For the Preview and Objectify endpoints the sub objects can also be accessed in +For the Preview and Objectify endpoints the sub-objects can also be accessed in the same manner. +:: >>> obj = client.preview('http://vimeo.com/18150336', words=10) >>> obj['object']['type'] u'video' - >>> obj['images'][0].url + >>> obj['images'][0]['url'] u'http://b.vimeocdn.com/ts/117/311/117311910_1280.jpg' Error Handling -------------- -If there was an error processing the request, The ``Url`` object will contain +If there was an error processing the request, the ``Url`` object will contain an error. For example if we use an invalid key, we will get a 401 response back :: >>> client = Embedly('notakey') - >>> obj = client.preview('http://vimeo.com/18150336', words=10) + >>> obj = client.preview('http://vimeo.com/18150336') >>> obj['error'] True >>> obj['error_code'] @@ -160,4 +189,4 @@ an error. For example if we use an invalid key, we will get a 401 response back Copyright --------- -Copyright (c) 2013 Embed.ly, Inc. See LICENSE for details. \ No newline at end of file +Copyright (c) 2013 Embed.ly, Inc. See LICENSE for details. diff --git a/embedly/__init__.py b/embedly/__init__.py index b94f7ab..11f965c 100644 --- a/embedly/__init__.py +++ b/embedly/__init__.py @@ -1,2 +1,4 @@ from __future__ import absolute_import -from .client import Embedly, __version__ +from .client import Embedly + +__version__ = '0.5.0.post0' diff --git a/embedly/client.py b/embedly/client.py index fbbbb8b..3aff738 100644 --- a/embedly/client.py +++ b/embedly/client.py @@ -4,21 +4,18 @@ The embedly object that interacts with the service """ -from __future__ import absolute_import +from __future__ import absolute_import, unicode_literals import re import httplib2 import json -try: - from urllib import quote, urlencode -except ImportError: - # py3k - from urllib.parse import quote, urlencode +from urllib import quote, urlencode from .models import Url -__version__ = '0.4.3' -USER_AGENT = 'Mozilla/5.0 (compatible; embedly-python/%s;)' % __version__ +def get_user_agent(): + from . import __version__ + return 'Mozilla/5.0 (compatible; embedly-python/%s;)' % __version__ class Embedly(object): @@ -26,22 +23,24 @@ class Embedly(object): Client """ - def __init__(self, key=None, user_agent=USER_AGENT, timeout=60): + def __init__(self, key=None, user_agent=None, timeout=60): """ Initialize the Embedly client - :param user_agent: User Agent passed to Embedly - :type user_agent: str :param key: Embedly Pro key :type key: str + :param user_agent: User Agent passed to Embedly + :type user_agent: str + :param timeout: timeout for HTTP connection attempts + :type timeout: int :returns: None """ - self.user_agent = user_agent - self.timeout = timeout self.key = key - self.services = [] + self.user_agent = user_agent or get_user_agent() + self.timeout = timeout + self.services = [] self._regex = None def get_services(self): @@ -50,22 +49,24 @@ def get_services(self): the list of supported providers and their regexes """ - if self.services: return self.services + if self.services: + return self.services - url = 'http://api.embed.ly/1/services/python' + url = 'https://api.embed.ly/1/services/python' http = httplib2.Http(timeout=self.timeout) - headers = {'User-Agent' : self.user_agent} + headers = {'User-Agent': self.user_agent, + 'Connection': 'close'} resp, content = http.request(url, headers=headers) if resp['status'] == '200': - resp_data = json.loads(content) + resp_data = json.loads(content.decode('utf-8')) self.services = resp_data - #build the regex that we can use later. + # build the regex that we can use later _regex = [] - for each in self.get_services(): - _regex.append('|'.join(each.get('regex',[]))) + for each in self.services: + _regex.append('|'.join(each.get('regex', []))) self._regex = re.compile('|'.join(_regex)) @@ -96,10 +97,10 @@ def _get(self, version, method, url_or_urls, **kwargs): raise ValueError('%s requires a url or a list of urls given: %s' % (method.title(), url_or_urls)) - #A flag we can use instead of calling isinstance all the time. + # a flag we can use instead of calling isinstance() all the time multi = isinstance(url_or_urls, list) - # Throw an error early for too many URLs + # throw an error early for too many URLs if multi and len(url_or_urls) > 20: raise ValueError('Embedly accepts only 20 urls at a time. Url ' 'Count:%s' % len(url_or_urls)) @@ -108,7 +109,7 @@ def _get(self, version, method, url_or_urls, **kwargs): key = kwargs.get('key', self.key) - #make sure that a key was set on the client or passed in. + # make sure that a key was set on the client or passed in if not key: raise ValueError('Requires a key. None given: %s' % key) @@ -121,11 +122,12 @@ def _get(self, version, method, url_or_urls, **kwargs): else: query += '&url=%s' % quote(url_or_urls) - url = 'http://api.embed.ly/%s/%s?%s' % (version, method, query) + url = 'https://api.embed.ly/%s/%s?%s' % (version, method, query) http = httplib2.Http(timeout=self.timeout) - headers = {'User-Agent': self.user_agent} + headers = {'User-Agent': self.user_agent, + 'Connection': 'close'} resp, content = http.request(url, headers=headers) diff --git a/embedly/models.py b/embedly/models.py index 5428990..e3f7ad8 100644 --- a/embedly/models.py +++ b/embedly/models.py @@ -1,15 +1,13 @@ -from __future__ import unicode_literals +from __future__ import absolute_import, unicode_literals +from .py3_utils import python_2_unicode_compatible, IterableUserDict -try: - from UserDict import IterableUserDict -except ImportError: - from collections import UserDict as IterableUserDict +@python_2_unicode_compatible class Url(IterableUserDict, object): """ A dictionary with two additional attributes for the method and url. UserDict provides a dictionary interface along with the regular - dictionary accsesible via the `data` attribute. + dictionary accessible via the `data` attribute. """ def __init__(self, data=None, method=None, original_url=None, **kwargs): @@ -18,7 +16,4 @@ def __init__(self, data=None, method=None, original_url=None, **kwargs): self.original_url = original_url def __str__(self): - return self.__unicode__().encode("utf-8") - - def __unicode__(self): return '<%s %s>' % (self.method.title(), self.original_url or "") diff --git a/embedly/py3_utils.py b/embedly/py3_utils.py new file mode 100644 index 0000000..089ce8e --- /dev/null +++ b/embedly/py3_utils.py @@ -0,0 +1,28 @@ +import sys + +# 2to3 doesn't handle the UserDict relocation +# put the import logic here for cleaner usage +try: + from collections import UserDict as IterableUserDict +except ImportError: # Python 2 + from UserDict import IterableUserDict + + +def python_2_unicode_compatible(klass): + """ + A decorator that defines __unicode__ and __str__ methods under Python 2. + Under Python 3 it does nothing. + + From django.utils.encoding.py in 1.4.2+, minus the dependency on Six. + + To support Python 2 and 3 with a single code base, define a __str__ method + returning text and apply this decorator to the class. + """ + if sys.version_info[0] == 2: + if '__str__' not in klass.__dict__: + raise ValueError("@python_2_unicode_compatible cannot be applied " + "to %s because it doesn't define __str__()." % + klass.__name__) + klass.__unicode__ = klass.__str__ + klass.__str__ = lambda self: self.__unicode__().encode('utf-8') + return klass diff --git a/embedly/tests.py b/embedly/tests.py index 3a7c168..90ac6d9 100644 --- a/embedly/tests.py +++ b/embedly/tests.py @@ -1,15 +1,23 @@ from __future__ import unicode_literals -import unittest +import re +import sys import json +try: # pragma: no cover + import unittest2 as unittest # Python 2.6 # pragma: no cover +except ImportError: # pragma: no cover + import unittest # pragma: no cover + +try: # pragma: no cover + from unittest import mock # pragma: no cover +except ImportError: # Python < 3.3 # pragma: no cover + import mock # pragma: no cover + from embedly.client import Embedly from embedly.models import Url -class EmbedlyTestCase(unittest.TestCase): - def setUp(self): - self.key = 'internal' - +class UrlTestCase(unittest.TestCase): def test_model(self): data = { 'provider_url': 'http://www.google.com/', @@ -61,10 +69,46 @@ def test_model(self): self.assertEqual(obj['new_key'], 'dict value') def test_model_data_can_serialize(self): - obj = Url({'a': {'key': 'value'}}) + obj = Url({'hash': {'key': 'value'}, + 'none': None, + 'empty': '', + 'float': 1.234, + 'int': 1, + 'string': 'string', + 'array': [0, -1]}) unserialzed = json.loads(json.dumps(obj.data)) self.assertDictEqual(obj.data, unserialzed) + def test_str_representation(self): + unistr = 'I\xf1t\xebrn\xe2ti\xf4n\xe0liz\xe6tion' + url = "http://test.com" + obj = Url(method=unistr, original_url=url) + + if sys.version_info[0] == 2: + self.assertTrue(unistr.encode('utf-8') in str(obj)) + self.assertTrue(url.encode('utf-8') in str(obj)) + else: + self.assertTrue(unistr in str(obj)) + self.assertTrue(url in str(obj)) + + +class EmbedlyTestCase(unittest.TestCase): + def setUp(self): + self.key = 'internal' + + def test_requires_api_key(self): + with self.assertRaises(ValueError): + Embedly()._get(1, "test", "http://fake") + + def test_requires_url(self): + with self.assertRaises(ValueError): + Embedly(self.key)._get(1, "test", None) + + def test_exception_on_too_many_urls(self): + urls = ['http://embed.ly'] * 21 + with self.assertRaises(ValueError): + Embedly(self.key)._get(1, "test", urls) + def test_provider(self): http = Embedly(self.key) @@ -81,7 +125,6 @@ def test_provider(self): obj = http.oembed('http://yfrog.com/h22eu4j') self.assertEqual(obj['provider_url'], 'http://yfrog.com') - def test_providers(self): http = Embedly(self.key) @@ -96,7 +139,6 @@ def test_providers(self): self.assertEqual(objs[0]['provider_url'], 'http://www.youtube.com/') self.assertEqual(objs[1]['provider_url'], 'http://yfrog.com') - def test_error(self): http = Embedly(self.key) @@ -131,14 +173,86 @@ def test_multi_errors(self): self.assertEqual(objs[0]['type'], 'photo') self.assertEqual(objs[1]['type'], 'error') + def test_raw_content_in_request(self): + client = Embedly(self.key) + response = client.oembed( + 'http://www.scribd.com/doc/13994900/Easter', + raw=True) - def test_exception_on_too_many_urls(self): - http = Embedly(self.key) - urls = ['http://embed.ly'] * 21 + self.assertEqual(response['raw'], response.data['raw']) - with self.assertRaises(ValueError): - http.oembed(urls) + parsed = json.loads(response['raw'].decode('utf-8')) + self.assertEqual(response['type'], parsed['type']) + + def test_regex_url_matches(self): + regex = [ + 'http://.*youtube\\.com/watch.*', + 'http://www\\.vimeo\\.com/.*'] + client = Embedly(self.key) + client._regex = re.compile('|'.join(regex)) + + self.assertTrue( + client.is_supported('http://www.youtube.com/watch?v=Zk7dDekYej0')) + self.assertTrue( + client.is_supported('http://www.vimeo.com/18150336')) + self.assertFalse( + client.is_supported('http://vimeo.com/18150336')) + self.assertFalse( + client.is_supported('http://yfrog.com/h22eu4j')) + + @mock.patch.object(Embedly, 'get_services') + def test_regex_access_triggers_get_services(self, mock_services): + client = Embedly(self.key) + client.regex + + self.assertTrue(mock_services.called) + self.assertIsNone(client._regex) + + def test_services_can_be_manually_configured(self): + client = Embedly(self.key) + client.services = ['nothing', 'like', 'real', 'response', 'data'] + + self.assertTrue('nothing' in client.get_services()) + self.assertEqual(len(client.get_services()), 5) + + @mock.patch('httplib2.Http', autospec=True) + def test_services_remains_empty_on_failed_http(self, MockHttp): + MockHttp.return_value.request.return_value = ({'status': 500}, "") + + client = Embedly(self.key) + client.get_services() + + self.assertFalse(client.services) + self.assertTrue(MockHttp.return_value.request.called) + + def test_get_services_retrieves_data_and_builds_regex(self): + client = Embedly(self.key) + client.get_services() + + self.assertGreater(len(client.services), 0) + self.assertTrue(client.regex.match('http://yfrog.com/h22eu4j')) + + def test_extract(self): + client = Embedly(self.key) + response = client.extract('http://vimeo.com/18150336') + + self.assertEqual(response.method, 'extract') + self.assertEqual(response['provider_name'], 'Vimeo') + + def test_preview(self): + client = Embedly(self.key) + response = client.preview('http://vimeo.com/18150336') + + self.assertEqual(response.method, 'preview') + self.assertEqual(response['provider_name'], 'Vimeo') + + def test_objectify(self): + client = Embedly(self.key) + response = client.objectify('http://vimeo.com/18150336') + + self.assertEqual(response.method, 'objectify') + self.assertEqual(response['provider_name'], 'Vimeo') -if __name__ == '__main__': - unittest.main() +if __name__ == '__main__': # pragma: no cover + unittest.main() # pragma: no cover diff --git a/setup.py b/setup.py index 1155c04..e0fef44 100644 --- a/setup.py +++ b/setup.py @@ -3,14 +3,21 @@ import codecs from setuptools import setup -extra = {} - required = ['httplib2'] +tests_require = [] + +if sys.version_info[:2] < (2, 7): + tests_require.append('unittest2') + +if sys.version_info[:2] < (3, 3): + tests_require.append('mock') -if sys.version_info[:2] < (2, 6): - required.append('simplejson') -version = __import__('embedly').__version__ +def get_version(): + with open(os.path.join('embedly', '__init__.py')) as f: + for line in f: + if line.startswith('__version__ ='): + return line.split('=')[1].strip().strip('"\'') if os.path.exists("README.rst"): long_description = codecs.open("README.rst", "r", "utf-8").read() @@ -20,7 +27,7 @@ setup( name='Embedly', - version=version, + version=get_version(), author='Embed.ly, Inc.', author_email='support@embed.ly', description='Python Library for Embedly', @@ -32,8 +39,11 @@ url="https://github.com/embedly/embedly-python", packages=['embedly'], install_requires=required, + tests_require=tests_require, + test_suite="embedly.tests", zip_safe=True, - classifiers=( + use_2to3=True, + classifiers=[ 'Development Status :: 5 - Production/Stable', 'Intended Audience :: Developers', 'Natural Language :: English', @@ -42,9 +52,7 @@ 'Programming Language :: Python', 'Programming Language :: Python :: 2.6', 'Programming Language :: Python :: 2.7', - 'Programming Language :: Python :: 3.1', 'Programming Language :: Python :: 3.2', 'Programming Language :: Python :: 3.3', - ), - **extra + ] ) diff --git a/tox.ini b/tox.ini index 2ffa83b..e039cb9 100644 --- a/tox.ini +++ b/tox.ini @@ -1,4 +1,16 @@ [tox] -envlist = py26,py27,py31,py32,py33 +envlist = py26,py27,py32,py33 + [testenv] -commands=python embedly/tests.py \ No newline at end of file +commands=python embedly/tests.py + +[testenv:py26] +deps = + mock + unittest2 + +[testenv:py27] +deps = mock + +[testenv:py32] +deps = mock