py-youtube-search 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

py_youtube_search/__init__.py

@@ -16,38 +16,40 @@ class Filters:
     long_this_month = "EgYIBBABGAI="
     long_this_year = "EgYIBRABGAI="
 
+
 class YouTubeSearch:
-    def __init__(self, keywords: str, sp: str = None, limit: int = 15):
+    def __init__(self):
         """
-        Initialize the search parameters.
-        Note: No network request happens here. Call .search() to fetch data.
+        Initialize the YouTubeSearch client.
+        The client is stateless; parameters are passed to the search method.
         """
-        self.keywords = keywords.replace(" ", "+")
-        self.sp = sp
-        self.limit = limit
-        self.source = None
         self.base_url = "https://www.youtube.com/results"
-
-    async def _fetch_source(self):
-        params = {"search_query": self.keywords}
-        if self.sp:
-            params["sp"] = self.sp
-
-        headers = {
+        self.headers = {
             "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
         }
 
+    async def _fetch_source(self, keywords: str, sp: str = None):
+        params = {"search_query": keywords.replace(" ", "+")}
+        if sp:
+            params["sp"] = sp
+
         async with aiohttp.ClientSession() as session:
-            async with session.get(self.base_url, params=params, headers=headers) as response:
+            async with session.get(self.base_url, params=params, headers=self.headers) as response:
                 return await response.text()
 
-    async def search(self):
+    async def search(self, keywords: str, sp: str = None, limit: int = 15):
         """
-        Asynchronously fetches and parses the search results.
-        Returns a list of videos.
+        Asynchronously fetches and parses search results for the given keywords.
+        
+        Args:
+            keywords (str): The search query.
+            sp (str, optional): The filter string (use Filters class). Defaults to None.
+            limit (int, optional): Max number of results. Defaults to 15.
+
+        Returns:
+            list: A list of dictionaries containing video details.
         """
-        if not self.source:
-            self.source = await self._fetch_source()
+        source = await self._fetch_source(keywords, sp)
 
         # Regex to capture distinct JSON fields for ID, Title, Duration, and Views.
         pattern = (
@@ -58,11 +60,11 @@ class YouTubeSearch:
             r'.+?\"viewCountText\":\{\"simpleText\":\"(?P<views>.+?)\"\}'
         )
 
-        matches = re.finditer(pattern, self.source)
+        matches = re.finditer(pattern, source)
         
         results = []
         for match in matches:
-            if len(results) >= self.limit:
+            if len(results) >= limit:
                 break
             
             data = match.groupdict()
@@ -79,7 +81,16 @@ class YouTubeSearch:
 # --- Usage Example (Async) ---
 # import asyncio
 # async def main():
-#     yt = YouTubeSearch("LangGraph", sp=Filters.long_this_week)
-#     videos = await yt.search()
-#     print(videos)
+#     yt = YouTubeSearch()
+#     
+#     # Search 1: Long videos about LangGraph
+#     print("Searching LangGraph...")
+#     videos1 = await yt.search("LangGraph", sp=Filters.long_this_week, limit=5)
+#     print(f"Found {len(videos1)} videos")
+#
+#     # Search 2: Short Python tutorials (reusing the same instance)
+#     print("Searching Python...")
+#     videos2 = await yt.search("Python", sp=Filters.medium_today, limit=3)
+#     print(f"Found {len(videos2)} videos")
+#
 # asyncio.run(main())

py_youtube_search-0.2.2.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: py-youtube-search
+Version: 0.2.2
+Summary: A lightweight, regex-based YouTube search library without API keys.
+Home-page: https://github.com/VishvaRam/py-youtube-search
+Author: VishvaRam
+Author-email: murthyvishva@gmail.com
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.8.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# py-youtube-search
+
+A lightweight, asynchronous Python library to search YouTube videos programmatically without an API key. 
+It scrapes search results using `aiohttp` and `re`, making it fast, robust, and perfect for high-performance applications.
+
+## Features
+
+- **Async Support**: Fully asynchronous using `aiohttp` for non-blocking execution.
+- **Reusable Client**: Create a single instance and run multiple searches with different configurations.
+- **No API Key Required**: Search YouTube directly without setting up Google Cloud projects.
+- **Advanced Filtering**: Built-in support for duration (Medium 3-20m, Long >20m) and upload date filters.
+- **Rich Data Extraction**: Extracts Video ID, Title, Duration, and View Count using optimized regex.
+
+## Installation
+
+```bash
+pip install py-youtube-search
+```
+
+## Quick Start
+
+### 1. Basic Async Search
+Initialize the client once and run multiple searches.
+
+```python
+import asyncio
+from py_youtube_search import YouTubeSearch
+
+async def main():
+    # 1. Initialize the client (reusable)
+    yt = YouTubeSearch()
+    
+    # 2. Run a search
+    videos = await yt.search("Python async tutorials", limit=5)
+
+    for v in videos:
+        print(f"Title: {v['title']}")
+        print(f"Duration: {v['duration']}")
+        print(f"Views: {v['views']}")
+        print(f"Link: https://www.youtube.com/watch?v={v['id']}\n")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### 2. Advanced Search with Filters
+Search for specific content, like long-form videos (>20m) uploaded this week.
+
+```python
+import asyncio
+from py_youtube_search import YouTubeSearch, Filters
+
+async def main():
+    yt = YouTubeSearch()
+
+    # Search 1: Long videos about LangGraph
+    print("Searching for LangGraph...")
+    videos = await yt.search("LangGraph", sp=Filters.long_this_week, limit=3)
+
+    for v in videos:
+        print(f"🎥 {v['title']} | ⏱ {v['duration']} | 👁 {v['views']}")
+
+    # Search 2: Reusing the same client for a different query
+    print("\nSearching for Python...")
+    videos_py = await yt.search("Python 3.12", sp=Filters.medium_today, limit=3)
+    
+    for v in videos_py:
+        print(f"🐍 {v['title']}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Available Filters
+
+Pass these constants into the `sp` parameter of the `search()` method.
+
+### Duration: Medium (3 - 20 Minutes)
+| Filter Attribute | Description |
+| :--- | :--- |
+| `Filters.medium_today` | Uploaded **Today** |
+| `Filters.medium_this_week` | Uploaded **This Week** |
+| `Filters.medium_this_month` | Uploaded **This Month** |
+| `Filters.medium_this_year` | Uploaded **This Year** |
+
+### Duration: Long (Over 20 Minutes)
+| Filter Attribute | Description |
+| :--- | :--- |
+| `Filters.long_today` | Uploaded **Today** |
+| `Filters.long_this_week` | Uploaded **This Week** |
+| `Filters.long_this_month` | Uploaded **This Month** |
+| `Filters.long_this_year` | Uploaded **This Year** |
+
+## Data Structure
+
+The `.search()` method returns a list of dictionaries:
+
+```json
+[
+  {
+    "id": "lDoYisPfcck",
+    "title": "Hack the planet! LangGraph AI HackBot Dev & Q/A",
+    "duration": "1:05:23",
+    "views": "1.2K views",
+    "url_suffix": "/watch?v=lDoYisPfcck"
+  }
+]
+```
+
+## Dependencies
+- `aiohttp` (for async requests)
+
+## License
+MIT License. See LICENSE file for details.

py_youtube_search-0.2.2.dist-info/RECORD

@@ -0,0 +1,5 @@
+py_youtube_search/__init__.py,sha256=Y_omeJ9q_6gaQOHlsYd0NZnHvmzBSATLtmjtY_TpJAA,3310
+py_youtube_search-0.2.2.dist-info/METADATA,sha256=OJ0-9Eof3gbuDCRPOeR37ZUfnsvQ7pU5Yop3BLzoaGk,4038
+py_youtube_search-0.2.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+py_youtube_search-0.2.2.dist-info/top_level.txt,sha256=4EMqIznKjzwgAcB_78SKaMIzZXpIxWQ4SRLeakY3fzQ,18
+py_youtube_search-0.2.2.dist-info/RECORD,,

py_youtube_search-0.2.0.dist-info/METADATA

@@ -1,144 +0,0 @@
-Metadata-Version: 2.4
-Name: py-youtube-search
-Version: 0.2.0
-Summary: A lightweight, regex-based YouTube search library without API keys.
-Home-page: https://github.com/VishvaRam/py-youtube-search
-Author: VishvaRam
-Author-email: murthyvishva@gmail.com
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
-Description-Content-Type: text/markdown
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: requires-python
-Dynamic: summary
-
-# py-youtube-search
-
-A lightweight, zero-dependency Python library to search YouTube videos programmatically without an API key. This library uses standard Python libraries (`urllib` and `re`) to scrape search results, making it fast, robust, and easy to integrate into any project.
-
-## Features
-
-- **No API Key Required**: Search YouTube directly without setting up Google Cloud projects or billing.
-- **Zero External Dependencies**: Built entirely using Python's standard library (`urllib`, `re`). No `requests`, `selenium`, or `beautifulsoup` needed.
-- **Advanced Filtering**: Built-in support for duration (Medium 3-20m, Long >20m) and upload date filters (Today, Week, Month, Year).
-- **Rich Data Extraction**: Robustly extracts Video ID, Title, Duration, and View Count.
-
-## Installation
-
-You can install the package via pip:
-
-```bash
-pip install py-youtube-search
-```
-
-## Quick Start
-
-### 1. Basic Search
-Fetch the top results for any keyword.
-
-```python
-from py_youtube_search import YouTubeSearch
-
-# Search for the top 5 results for "Python tutorials"
-search = YouTubeSearch("Python tutorials", limit=5)
-videos = search.videos()
-
-for v in videos:
-    print(f"Title: {v['title']}")
-    print(f"Duration: {v['duration']}")
-    print(f"Views: {v['views']}")
-    print(f"Link: https://www.youtube.com/watch?v={v['id']}\n")
-```
-
-### 2. Advanced Search with Filters
-Search for specific types of content, such as long-form tutorials uploaded this week.
-
-```python
-from py_youtube_search import YouTubeSearch, Filters
-
-# Search for "LangGraph" videos over 20 minutes long, uploaded this week
-# Use the Filters class to access constants
-search = YouTubeSearch("LangGraph", sp=Filters.long_this_week, limit=3)
-videos = search.videos()
-
-for v in videos:
-    print(f"🎥 {v['title']} | ⏱ {v['duration']} | 👁 {v['views']}")
-```
-
-## Available Filters
-
-You can access these filters using the `Filters` class (e.g., `Filters.long_today`).
-
-### Duration: Medium (3 - 20 Minutes)
-| Filter Attribute | Description |
-| :--- | :--- |
-| `Filters.medium_today` | Uploaded **Today** |
-| `Filters.medium_this_week` | Uploaded **This Week** |
-| `Filters.medium_this_month` | Uploaded **This Month** |
-| `Filters.medium_this_year` | Uploaded **This Year** |
-
-### Duration: Long (Over 20 Minutes)
-| Filter Attribute | Description |
-| :--- | :--- |
-| `Filters.long_today` | Uploaded **Today** |
-| `Filters.long_this_week` | Uploaded **This Week** |
-| `Filters.long_this_month` | Uploaded **This Month** |
-| `Filters.long_this_year` | Uploaded **This Year** |
-
-## Data Structure
-
-The `videos()` method returns a list of dictionaries with the following structure:
-
-```json
-[
-  {
-    "id": "lDoYisPfcck",
-    "title": "Hack the planet! LangGraph AI HackBot Dev & Q/A",
-    "duration": "1:05:23",
-    "views": "1.2K views",
-    "url_suffix": "/watch?v=lDoYisPfcck"
-  },
-  {
-    "id": "5LXLmUsEM20",
-    "title": "LangGraph Workflow Patterns - Part 1/10",
-    "duration": "42 seconds",
-    "views": "500 views",
-    "url_suffix": "/watch?v=5LXLmUsEM20"
-  }
-]
-```
-
-## License
-
-This project is licensed under the MIT License - see below for details.
-
-```text
-MIT License
-
-Copyright (c) 2026
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```

py_youtube_search-0.2.0.dist-info/RECORD

@@ -1,5 +0,0 @@
-py_youtube_search/__init__.py,sha256=hWJcqytPfRODGIFynNmDrCQm_9P5zWwg4DOcWIyrVog,2769
-py_youtube_search-0.2.0.dist-info/METADATA,sha256=-Z0VAXP6C5HNG4TriRWmPy9ZSrUPKqu9_1SX1dpPOkM,4833
-py_youtube_search-0.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-py_youtube_search-0.2.0.dist-info/top_level.txt,sha256=4EMqIznKjzwgAcB_78SKaMIzZXpIxWQ4SRLeakY3fzQ,18
-py_youtube_search-0.2.0.dist-info/RECORD,,