Merge pull request #7 from Glenpl/v2.0.0

V2.0.0

.gitignore

@@ -64,3 +64,6 @@ target/
 #virtual env
 venv/
 venv
+
+#plaintext files
+.txt

.landscape.yml

@@ -12,3 +12,5 @@ pylint:
 pep8:
   disable:
     - E302
+    - E127
+    - E128

README.md

@@ -19,144 +19,124 @@ Usage example
 ```python
 from youtube.api import YoutubeApi
 
-found_items = YoutubeApi().search('lana del rey')
-found_playlists = YoutubeApi().search_playlists('lana del rey')
+videos = YoutubeApi().search_videos('lana del rey')
 
-print(found_items)
+for video in videos:
+    print(video.title)
 ```
 
 Documentation
 --------------------
-The main API class is YoutubeApi, which consists of 8 methods:
+The main API class is YoutubeApi, which consists of 7 methods:
 ```
-constructor(http_fetcher=None, nocache=False)
+constructor(http_fetcher=None, nocache=False, global_cache=False)
 
-search(search_string: str) -> List of VideoSignature, ChannelSignature and PlaylistSignature
-search_videos(search_string: str) -> List of VideoSignature
-search_channels(search_string: str) -> List of ChannelSignature
-search_playlists(search_string: str) -> List of PlaylistSignature
+search(search_string: str) -> Tuple of VideoSignature, ChannelSignature and PlaylistSignature
+search_videos(search_string: str) -> Tuple of VideoSignature
+search_channels(search_string: str) -> Tuple of ChannelSignature
+search_playlists(search_string: str) -> Tuple of PlaylistSignature
 get_video(video_id: str) -> YoutubeVideo object
 get_playlist(playlist_id: str) -> YoutubeChannel object
 get_channel(channel_id: str) -> YoutubePlaylist object
 clear_cache() -> None
 ```
-YoutubeApi constructor takes 2 optional arguments: http_fetcher and nocache flag.
-Object passed as http_fetcher is used to fetch www page source - it has to implement such an interface:
+YoutubeApi constructor takes 3 optional, keyword-only arguments: http_fetcher, nocache flag and global_cache flag.
+Object passed as http_fetcher is used to fetch page source - it has to implement such an interface:
 ```python
 class Fetcher():
-    def __init__(): pass  # default constructor
-    def fetch_page(url): pass  # returns utf-8 decoded page source
+    def fetch_page(self, url): pass  # returns utf-8 decoded page source
 ```
 It's probably best to just let the YoutubeApi use it's default http_fetcher - the one that works just fine.
 Important note: if you want to supply your own http_fetcher which doesn't make real http calls, it's best to set nocache to True.
+If nocache is set to True no cache is used at all. If nocache is set to False or omitted cache is used.
+If global_cache is set to True global cache (shared among all YoutubeApi instances with global_cache set to True) is used.
+If global_cache is set to False or omitted local cache (available just to this one particular YoutubeApi instance) is used.
 
 ---
 
 #####VideoSignature
-It's a value object.
+It's a hashable value object.
 May throw exceptions during construction.
-Member methods guaranteed not to throw exceptions.
+All fields are immutable.
 ```
-get_url() -> str
-get_id() -> str
-get_length() -> str
-get_title() -> str
-get_author() -> str
-get_views() -> str
-get_thumbnail_url() -> str
+url: str
+video_id: str
+length: str
+title: str
+author: str
+views: int
+thumbnail: str
 ```
 
 ---
 
 #####ChannelSignature
-It's a value object.
+It's a hashable value object.
 May throw exceptions during construction.
-Member methods guaranteed not to throw exceptions.
+All fields are immutable.
 ```
-get_url() -> str
-get_id() -> str
-get_name() -> str
-get_videos_amount() -> str
-get_subscriptions() -> str
-get_thumbnail_url() -> str
+url: str
+channel_id: str
+name: str
+videos_amount: int
+subscriptions: int
+thumbnail: str
 ```
 
 ---
 
 #####PlaylistSignature
-It's a value object.
+It's a hashable value object.
 May throw exceptions during construction.
-Member methods guaranteed not to throw exceptions.
+All fields are immutable.
 ```
-get_url() -> str
-get_id() -> str
-get_name() -> str
-get_length() -> str
-get_thumbnail_url() -> str
-get_author() -> str
-get_first_video_id() -> str
-get_first_video_url() -> str
+url: str
+playlist_id: str
+name: str
+length: int
+thumbnail: str
+author: str
+first_video_id: str
+first_video_url: str
 ```
 
 ---
 
 #####YoutubeVideo
-It's a value object.
+It's a hashable value object.
 May throw exceptions during construction.
-Member methods guaranteed not to throw exceptions.
+All fields are immutable.
 ```
-get_url() -> str
-get_length() -> str
-get_length_in_seconds() -> int
-get_author() -> str
-get_title() -> str
-get_id() -> str
-get_views() -> str
-get_thumbnail_url() -> str
-get_next_video() -> VideoSignature
-get_related_videos() -> List of VideoSignature
-```
-
----
-
-#####YoutubeChannel
-It's a value object.
-May throw exceptions during construction.
-Member methods guaranteed not to throw exceptions.
-```
-get_url() -> str
-get_id() -> str
-get_name() -> str
-get_videos_amount() -> str
-get_subscriptions() -> str
-get_thumbnail_url() -> str
-get_uploaded_videos() -> List of VideoSignature
+url: str
+length: str
+length_in_seconds: int
+author: str
+title: str
+video_id: str
+views: int
+thumbnail: str
+next_video: VideoSignature
+related_videos: Tuple of VideoSignature
 ```
 
 ---
 
 #####YoutubePlaylist
-It's a value object.
+It's a hashable value object.
 May throw exceptions during construction.
-Member methods guaranteed not to throw exceptions.
+All fields are immutable.
 ```
-get_url() -> str
-get_id() -> str
-get_name() -> str
-get_author() -> str
-get_length() -> str
-get_thumbnail_url() -> str
-get_video(index: int) -> VideoSignature
-get_videos() -> List of VideoSignature
+url: str
+playlist_id: str
+name: str
+author: str
+length: str
+thumbnail: str
+videos: Tuple of VideoSignature
 ```
 
 ---
 
-#####_YoutubeCache
-It's an internal class.
-You should never interact with it directly.
-Assume that any interaction with this class will break the program.
-
 License
 --------------------
 MIT license.

requirements.txt

@@ -1,5 +1,6 @@
 beautifulsoup4==4.4.1
-coverage==4.0.3
+coverage==4.1
 coveralls==1.1
 docopt==0.6.2
-requests==2.9.1
+requests==2.10.0
+SimpleStruct==0.2.2

setup.py

@@ -5,10 +5,10 @@
 
 setup(
     name='openytapi',
-    version='1.0.6',
+    version='2.0.0',
     description='Open YouTube API library',
     url='https://github.com/Glenpl/openytapi',
-    download_url='https://github.com/Glenpl/openytapi/tarball/1.0.6',
+    download_url='https://github.com/Glenpl/openytapi/tarball/2.0.0',
     author='Glenpl/Jakub Molinski',
     author_email='kubamolinski@gmail.com',
     license='MIT',
@@ -23,7 +23,7 @@
     ],
     keywords='open youtube api',
     packages=['youtube'],
-    install_requires=['beautifulsoup4', 'requests']
+    install_requires=['beautifulsoup4', 'simplestruct']
 )
 
 __author__ = 'glenpl'

tests/testcache.py

@@ -9,22 +9,18 @@ def test_search_cache_time(self):
         # actual http request and parsing
         start = timer()
         videos = api.search('Lana')
-        videos = api.search('Lana del')
         videos = api.search('Lana del rey')
         time1 = timer() - start
 
         # get cached version
         start = timer()
         videos = api.search('Lana')
-        videos = api.search('Lana del')
         videos = api.search('Lana del rey')
         time2 = timer() - start
 
         # cached should be at least 1000 times faster
         self.assertTrue(time1 > time2 * 1000)
 
-        api.clear_cache()
-
     def test_search_cache_right_values(self):
         api = YoutubeApi()
 
@@ -37,8 +33,6 @@ def test_search_cache_right_values(self):
         # check if cache stores right values
         self.assertEqual(videos_a, videos_c)
 
-        api.clear_cache()
-
     def test_clear_cache(self):
         api = YoutubeApi()
 
@@ -62,27 +56,21 @@ def test_clear_cache(self):
 
         self.assertTrue(min(time1, time3) > time2 * 1000)
 
-        api.clear_cache()
-
     def test_get_object_cache_time(self):
         api = YoutubeApi()
 
         start = timer()
         video = api.get_video('nVjsGKrE6E8')
-        channel = api.get_channel('LanaDelReyVEVO')
         playlist = api.get_playlist('PLLUYFDT7vPkqBZQsTGBpGCjIoePETnOxi')
         time1 = timer() - start
 
         start = timer()
         video = api.get_video('nVjsGKrE6E8')
-        channel = api.get_channel('LanaDelReyVEVO')
         playlist = api.get_playlist('PLLUYFDT7vPkqBZQsTGBpGCjIoePETnOxi')
         time2 = timer() - start
 
         self.assertTrue(time1 > time2 * 1000)
 
-        api.clear_cache()
-
     def test_get_object_right_values(self):
         api = YoutubeApi()
 
@@ -91,4 +79,35 @@ def test_get_object_right_values(self):
 
         self.assertEqual(video1, video2)
 
-        api.clear_cache()
+    def test_global_cache_time(self):
+        api_1 = YoutubeApi(global_cache=True)
+        api_2 = YoutubeApi(global_cache=True)
+
+        start = timer()
+        video = api_1.get_video('nVjsGKrE6E8')
+        time1 = timer() - start
+
+        start = timer()
+        video = api_2.get_video('nVjsGKrE6E8')
+        time2 = timer() - start
+
+        self.assertTrue(time1 > time2 * 1000)
+        api_1.clear_cache()
+
+    def test_global_cache_is_shared(self):
+        api_1 = YoutubeApi(global_cache=True)
+        api_2 = YoutubeApi(global_cache=True)
+
+        start = timer()
+        video = api_1.get_video('nVjsGKrE6E8')
+        time1 = timer() - start
+
+        api_2.clear_cache()
+
+        start = timer()
+        video = api_1.get_video('nVjsGKrE6E8')
+        time2 = timer() - start
+
+        # assert both are real http calls with parsing
+        self.assertTrue(max(time1, time2) < min(time1, time2) * 15)
+        api_1.clear_cache()