Merge pull request #152 from autoscrape-labs/thalissonvs/issue150

Implement singleton pattern for Tab instances and add tab retrieval method

Author: thalissonvs

docs/features.md

@@ -209,6 +209,133 @@ asyncio.run(background_bypass_example())
 
 Access websites that actively block automation tools without using third-party captcha solving services. This native captcha handling makes Pydoll suitable for automating previously inaccessible websites.
 
+## Multi-Tab Management
+
+Pydoll provides sophisticated tab management capabilities with a singleton pattern that ensures efficient resource usage and prevents duplicate Tab instances for the same browser tab.
+
+### Tab Singleton Pattern
+
+Pydoll implements a singleton pattern for Tab instances based on the browser's target ID. This means:
+
+- **One Tab instance per browser tab**: Multiple references to the same browser tab return the same Tab object
+- **Automatic resource management**: No duplicate connections or handlers for the same tab
+- **Consistent state**: All references to a tab share the same state and event handlers
+
+```python
+import asyncio
+from pydoll.browser.chromium import Chrome
+from pydoll.browser.tab import Tab
+
+async def singleton_demonstration():
+    async with Chrome() as browser:
+        tab = await browser.start()
+        
+        # Get the same tab through different methods - they're identical objects
+        same_tab = Tab(browser, browser._connection_port, tab._target_id)
+        opened_tabs = await browser.get_opened_tabs()
+        
+        # All references point to the same singleton instance
+        print(f"Same object? {tab is same_tab}")  # May be True if same target_id
+        print(f"Tab instances are managed as singletons")
+
+asyncio.run(singleton_demonstration())
+```
+
+### Creating New Tabs Programmatically
+
+Use `new_tab()` to create tabs programmatically with full control:
+
+```python
+import asyncio
+from pydoll.browser.chromium import Chrome
+
+async def programmatic_tab_creation():
+    async with Chrome() as browser:
+        # Start with the initial tab
+        main_tab = await browser.start()
+        
+        # Create additional tabs with specific URLs
+        search_tab = await browser.new_tab('https://google.com')
+        news_tab = await browser.new_tab('https://news.ycombinator.com')
+        docs_tab = await browser.new_tab('https://docs.python.org')
+        
+        # Work with multiple tabs simultaneously
+        await search_tab.find(name='q').type_text('Python automation')
+        await news_tab.find(class_name='storylink', find_all=True)
+        await docs_tab.find(id='search-field').type_text('asyncio')
+        
+        # Get all opened tabs
+        all_tabs = await browser.get_opened_tabs()
+        print(f"Total tabs open: {len(all_tabs)}")
+        
+        # Close specific tabs when done
+        await search_tab.close()
+        await news_tab.close()
+
+asyncio.run(programmatic_tab_creation())
+```
+
+### Handling User-Opened Tabs
+
+When users click links that open new tabs (target="_blank"), use `get_opened_tabs()` to detect and manage them:
+
+```python
+import asyncio
+from pydoll.browser.chromium import Chrome
+
+async def handle_user_opened_tabs():
+    async with Chrome() as browser:
+        main_tab = await browser.start()
+        await main_tab.go_to('https://example.com')
+        
+        # Get initial tab count
+        initial_tabs = await browser.get_opened_tabs()
+        initial_count = len(initial_tabs)
+        print(f"Initial tabs: {initial_count}")
+        
+        # Click a link that opens a new tab (target="_blank")
+        external_link = await main_tab.find(text='Open in New Tab')
+        await external_link.click()
+        
+        # Wait for new tab to open
+        await asyncio.sleep(2)
+        
+        # Detect new tabs
+        current_tabs = await browser.get_opened_tabs()
+        new_tab_count = len(current_tabs)
+        
+        if new_tab_count > initial_count:
+            print(f"New tab detected! Total tabs: {new_tab_count}")
+            
+            # Get the newly opened tab (last in the list)
+            new_tab = current_tabs[-1]
+            
+            # Work with the new tab
+            await new_tab.go_to('https://different-site.com')
+            title = await new_tab.execute_script('return document.title')
+            print(f"New tab title: {title}")
+            
+            # Close the new tab when done
+            await new_tab.close()
+
+asyncio.run(handle_user_opened_tabs())
+```
+
+### Key Benefits of Pydoll's Tab Management
+
+1. **Singleton Pattern**: Prevents resource duplication and ensures consistent state
+2. **Automatic Detection**: `get_opened_tabs()` finds all tabs, including user-opened ones
+3. **Concurrent Processing**: Handle multiple tabs simultaneously with asyncio
+4. **Resource Management**: Proper cleanup prevents memory leaks
+5. **Event Isolation**: Each tab maintains its own event handlers and state
+
+This sophisticated tab management makes Pydoll ideal for:
+- **Multi-page workflows** that require coordination between tabs
+- **Parallel data extraction** from multiple sources
+- **Testing applications** that use popup windows or new tabs
+- **Monitoring user behavior** across multiple browser tabs
+
+
 ## Concurrent Scraping
 
 Pydoll's async architecture allows you to scrape multiple pages or websites simultaneously for maximum efficiency:

pydoll/browser/chromium/base.py

@@ -215,10 +215,30 @@ async def get_targets(self) -> list[TargetInfo]:
 
         Targets include pages, service workers, shared workers, and browser process.
         Useful for debugging and managing multiple tabs.
+
+        Returns:
+            List of TargetInfo objects.
         """
         response: GetTargetsResponse = await self._execute_command(TargetCommands.get_targets())
         return response['result']['targetInfos']
 
+    async def get_opened_tabs(self) -> list[Tab]:
+        """
+        Get all opened tabs that are not extensions and have the type 'page'
+
+        Returns:
+            List of Tab instances. The last tab is the most recent one.
+        """
+        targets = await self.get_targets()
+        valid_tab_targets = [
+            target for target in targets if target['type'] == 'page'
+            and 'extension' not in target['url']
+        ]
+        return [
+            Tab(self, self._connection_port, target['targetId']) for target
+            in reversed(valid_tab_targets)
+        ]
+
     async def set_download_path(self, path: str, browser_context_id: Optional[str] = None):
         """Set download directory path (convenience method for set_download_behavior)."""
         return await self._execute_command(

pydoll/browser/tab.py

@@ -68,8 +68,43 @@ class Tab(FindElementsMixin):  # noqa: PLR0904
     Primary interface for web page automation including navigation, DOM manipulation,
     JavaScript execution, event handling, network monitoring, and specialized tasks
     like Cloudflare bypass.
+
+    This class implements a singleton pattern based on target_id to ensure
+    only one Tab instance exists per browser tab.
     """
 
+    _instances: dict[str, 'Tab'] = {}
+
+    def __new__(
+        cls,
+        browser: 'Browser',
+        connection_port: int,
+        target_id: str,
+        browser_context_id: Optional[str] = None,
+    ) -> 'Tab':
+        """
+        Create or return existing Tab instance for the given target_id.
+
+        Args:
+            browser: Browser instance that created this tab.
+            connection_port: CDP WebSocket port.
+            target_id: CDP target identifier for this tab.
+            browser_context_id: Optional browser context ID.
+
+        Returns:
+            Tab instance (new or existing) for the target_id.
+        """
+        if target_id in cls._instances:
+            existing_instance = cls._instances[target_id]
+            existing_instance._browser = browser
+            existing_instance._connection_port = connection_port
+            existing_instance._browser_context_id = browser_context_id
+            return existing_instance
+
+        instance = super().__new__(cls)
+        cls._instances[target_id] = instance
+        return instance
+
     def __init__(
         self,
         browser: 'Browser',
@@ -86,18 +121,57 @@ def __init__(
             target_id: CDP target identifier for this tab.
             browser_context_id: Optional browser context ID.
         """
-        self._browser = browser
-        self._connection_port = connection_port
-        self._target_id = target_id
-        self._connection_handler = ConnectionHandler(connection_port, self._target_id)
-        self._page_events_enabled = False
-        self._network_events_enabled = False
-        self._fetch_events_enabled = False
-        self._dom_events_enabled = False
-        self._runtime_events_enabled = False
-        self._intercept_file_chooser_dialog_enabled = False
+        if hasattr(self, '_initialized') and self._initialized:
+            return
+
+        self._browser: 'Browser' = browser
+        self._connection_port: int = connection_port
+        self._target_id: str = target_id
+        self._connection_handler: ConnectionHandler = ConnectionHandler(
+            connection_port, self._target_id
+        )
+        self._page_events_enabled: bool = False
+        self._network_events_enabled: bool = False
+        self._fetch_events_enabled: bool = False
+        self._dom_events_enabled: bool = False
+        self._runtime_events_enabled: bool = False
+        self._intercept_file_chooser_dialog_enabled: bool = False
         self._cloudflare_captcha_callback_id: Optional[int] = None
-        self._browser_context_id = browser_context_id
+        self._browser_context_id: Optional[str] = browser_context_id
+        self._initialized: bool = True
+
+    @classmethod
+    def _remove_instance(cls, target_id: str) -> None:
+        """
+        Remove instance from registry when tab is closed.
+
+        Args:
+            target_id: Target ID to remove from registry.
+        """
+        cls._instances.pop(target_id, None)
+
+    @classmethod
+    def get_instance(cls, target_id: str) -> Optional['Tab']:
+        """
+        Get existing Tab instance for target_id if it exists.
+
+        Args:
+            target_id: Target ID to look up.
+
+        Returns:
+            Existing Tab instance or None if not found.
+        """
+        return cls._instances.get(target_id)
+
+    @classmethod
+    def get_all_instances(cls) -> dict[str, 'Tab']:
+        """
+        Get all active Tab instances.
+
+        Returns:
+            Dictionary mapping target_id to Tab instances.
+        """
+        return cls._instances.copy()
 
     @property
     def page_events_enabled(self) -> bool:
@@ -283,7 +357,9 @@ async def close(self):
         Note:
             Tab instance becomes invalid after calling this method.
         """
-        return await self._execute_command(PageCommands.close())
+        result = await self._execute_command(PageCommands.close())
+        self._remove_instance(self._target_id)
+        return result
 
     async def get_frame(self, frame: WebElement) -> IFrame:
         """