From c3c5c9dbdb99cbcda464f7e23ab5848216fbd59b Mon Sep 17 00:00:00 2001
From: chaurasiayush <44316398+chaurasiayush@users.noreply.github.com>
Date: Sat, 4 Apr 2026 21:14:50 +0530
Subject: [PATCH] Enhance get_flights to return URL alongside flights

Updated the get_flights function to include a return_url parameter, allowing it to optionally return a tuple of flights and URL. Modified fetch_flights_html to return both HTML and the final URL.
---
 fast_flights/fetcher.py | 96 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 86 insertions(+), 10 deletions(-)

diff --git a/fast_flights/fetcher.py b/fast_flights/fetcher.py
index d5bd8fdb..6f38e134 100644
--- a/fast_flights/fetcher.py
+++ b/fast_flights/fetcher.py
@@ -1,4 +1,4 @@
-from typing import overload
+from typing import Literal, overload
 
 from primp import Client
 
@@ -10,7 +10,13 @@
 
 
 @overload
-def get_flights(q: str, /, *, proxy: str | None = None) -> MetaList:
+def get_flights(
+    q: str,
+    /,
+    *,
+    proxy: str | None = None,
+    return_url: Literal[False] = False,
+) -> MetaList:
     """Get flights using a str query.
 
     Examples:
@@ -19,7 +25,28 @@ def get_flights(q: str, /, *, proxy: str | None = None) -> MetaList:
 
 
 @overload
-def get_flights(q: Query, /, *, proxy: str | None = None) -> MetaList:
+def get_flights(
+    q: str,
+    /,
+    *,
+    proxy: str | None = None,
+    return_url: Literal[True],
+) -> tuple[MetaList, str]:
+    """Get flights using a str query, returning both flights and URL.
+
+    Examples:
+    - *Flights from TPE to MYJ on 2025-12-22 one way economy class*
+    """
+
+
+@overload
+def get_flights(
+    q: Query,
+    /,
+    *,
+    proxy: str | None = None,
+    return_url: Literal[False] = False,
+) -> MetaList:
     """Get flights using a structured query.
 
     Example:
@@ -44,21 +71,65 @@ def get_flights(q: Query, /, *, proxy: str | None = None) -> MetaList:
     """
 
 
+@overload
+def get_flights(
+    q: Query,
+    /,
+    *,
+    proxy: str | None = None,
+    return_url: Literal[True],
+) -> tuple[MetaList, str]:
+    """Get flights using a structured query, returning both flights and URL.
+
+    Example:
+    ```python
+    get_flights(
+        query(
+            flights=[
+                FlightQuery(
+                    date="2025-12-22",
+                    from_airport="TPE",
+                    to_airport="MYJ",
+                )
+            ],
+            seat="economy",
+            trip="one-way",
+            passengers=Passengers(adults=1),
+            language="en-US",
+            currency="",
+        ),
+        return_url=True
+    )
+    ```
+    """
+
+
 def get_flights(
     q: Query | str,
     /,
     *,
     proxy: str | None = None,
     integration: Integration | None = None,
-) -> MetaList:
+    return_url: bool = False,
+) -> MetaList | tuple[MetaList, str]:
     """Get flights.
 
     Args:
         q: The query.
         proxy (str, optional): Proxy.
+        return_url (bool, optional): If True, returns a tuple of (MetaList, url).
+            If False (default), returns only MetaList for backward compatibility.
+    
+    Returns:
+        MetaList if return_url is False (default), or
+        tuple of (MetaList, url) if return_url is True.
     """
-    html = fetch_flights_html(q, proxy=proxy, integration=integration)
-    return parse(html)
+    html, url = fetch_flights_html(q, proxy=proxy, integration=integration)
+    flights = parse(html)
+    
+    if return_url:
+        return flights, url
+    return flights
 
 
 def fetch_flights_html(
@@ -67,12 +138,16 @@ def fetch_flights_html(
     *,
     proxy: str | None = None,
     integration: Integration | None = None,
-) -> str:
-    """Fetch flights and get the **HTML**.
+) -> tuple[str, str]:
+    """Fetch flights and get the **HTML** and **URL**.
 
     Args:
         q: The query.
         proxy (str, optional): Proxy.
+    
+    Returns:
+        A tuple of (html, url) where html is the response text
+        and url is the final URL of the request.
     """
     if integration is None:
         client = Client(
@@ -90,7 +165,8 @@ def fetch_flights_html(
             params = {"q": q}
 
         res = client.get(URL, params=params)
-        return res.text
+        return res.text, str(res.url)
 
     else:
-        return integration.fetch_html(q)
+        html = integration.fetch_html(q)
+        return html, URL