polars-api 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

polars_api/api.py

@@ -2,90 +2,328 @@ import asyncio
 from typing import Optional
 
 import httpx
+import nest_asyncio
 import polars as pl
 
 
-def check_status_code(status_code):
+def _check_status_code(status_code):
+    """
+    Check if the status code indicates a successful response.
+
+    Parameters
+    ----------
+    status_code : int
+        The HTTP status code to check.
+
+    Returns
+    -------
+    bool
+        True if the status code is between 200 and 299, False otherwise.
+    """
     return status_code >= 200 and status_code < 300
 
 
 @pl.api.register_expr_namespace("api")
 class Api:
     def __init__(self, url: pl.Expr) -> None:
+        """
+        Initialize the Api class with a URL expression.
+
+        Parameters
+        ----------
+        url : pl.Expr
+            The URL expression.
+        """
         self._url = url
 
     @staticmethod
-    def _get(url: str, params: Optional[dict[str, str]] = None) -> Optional[str]:
-        result = httpx.get(url, params=params)
-        if check_status_code(result.status_code):
+    def _get(url: str, params: Optional[dict[str, str]] = None, timeout: Optional[float] = None) -> Optional[str]:
+        """
+        Perform a synchronous GET request.
+
+        Parameters
+        ----------
+        url : str
+            The URL to send the GET request to.
+        params : dict[str, str], optional
+            The query parameters to include in the request.
+        timeout : float, optional
+            The timeout for the request.
+
+        Returns
+        -------
+        str or None
+            The response text if the request is successful, None otherwise.
+        """
+        result = httpx.get(url, params=params, timeout=timeout)
+        if _check_status_code(result.status_code):
             return result.text
         else:
             return None
 
     @staticmethod
-    def _post(url: str, params: dict[str, str], body: str) -> Optional[str]:
-        result = httpx.post(url, params=params, json=body)
-        if check_status_code(result.status_code):
+    def _post(url: str, params: dict[str, str], body: str, timeout: float) -> Optional[str]:
+        """
+        Perform a synchronous POST request.
+
+        Parameters
+        ----------
+        url : str
+            The URL to send the POST request to.
+        params : dict[str, str]
+            The query parameters to include in the request.
+        body : str
+            The JSON body to include in the request.
+        timeout : float
+            The timeout for the request.
+
+        Returns
+        -------
+        str or None
+            The response text if the request is successful, None otherwise.
+        """
+        result = httpx.post(url, params=params, json=body, timeout=timeout)
+        if _check_status_code(result.status_code):
             return result.text
         else:
             return None
 
     @staticmethod
-    async def _aget_one(url: str, params: str) -> str:
+    async def _aget_one(url: str, params: str, timeout: float) -> str:
+        """
+        Perform an asynchronous GET request.
+
+        Parameters
+        ----------
+        url : str
+            The URL to send the GET request to.
+        params : str
+            The query parameters to include in the request.
+        timeout : float
+            The timeout for the request.
+
+        Returns
+        -------
+        str
+            The response text.
+        """
         async with httpx.AsyncClient() as client:
-            r = await client.get(url, params=params)
+            r = await client.get(url, params=params, timeout=timeout)
             return r.text
 
-    async def _aget_all(self, x, params):
-        return await asyncio.gather(*[self._aget_one(url, param) for url, param in zip(x, params)])
+    async def _aget_all(self, x, params, timeout):
+        """
+        Perform multiple asynchronous GET requests.
+
+        Parameters
+        ----------
+        x : list
+            List of URLs to send the GET requests to.
+        params : list
+            List of query parameters for each request.
+        timeout : float
+            The timeout for the requests.
+
+        Returns
+        -------
+        list
+            List of response texts.
+        """
+        return await asyncio.gather(*[self._aget_one(url, param, timeout) for url, param in zip(x, params)])
 
-    def _aget(self, x, params):
-        return pl.Series(asyncio.run(self._aget_all(x, params)))
+    def _aget(self, x, params, timeout):
+        """
+        Wrapper for performing multiple asynchronous GET requests.
+
+        Parameters
+        ----------
+        x : list
+            List of URLs to send the GET requests to.
+        params : list
+            List of query parameters for each request.
+        timeout : float
+            The timeout for the requests.
+
+        Returns
+        -------
+        pl.Series
+            Series of response texts.
+        """
+        return pl.Series(asyncio.run(self._aget_all(x, params, timeout)))
 
     @staticmethod
-    async def _apost_one(url: str, params: str, body: str) -> str:
+    async def _apost_one(url: str, params: str, body: str, timeout: Optional[float]) -> str:
+        """
+        Perform an asynchronous POST request.
+
+        Parameters
+        ----------
+        url : str
+            The URL to send the POST request to.
+        params : str
+            The query parameters to include in the request.
+        body : str
+            The JSON body to include in the request.
+        timeout : float, optional
+            The timeout for the request.
+
+        Returns
+        -------
+        str
+            The response text.
+        """
         async with httpx.AsyncClient() as client:
-            r = await client.post(url, params=params, json=body)
+            r = await client.post(url, params=params, json=body, timeout=timeout)
             return r.text
 
-    async def _apost_all(self, x, params, body):
+    async def _apost_all(self, x, params, body, timeout):
+        """
+        Perform multiple asynchronous POST requests.
+
+        Parameters
+        ----------
+        x : list
+            List of URLs to send the POST requests to.
+        params : list
+            List of query parameters for each request.
+        body : list
+            List of JSON bodies for each request.
+        timeout : float
+            The timeout for the requests.
+
+        Returns
+        -------
+        list
+            List of response texts.
+        """
         return await asyncio.gather(*[
-            self._apost_one(url, _params, _body) for url, _params, _body in zip(x, params, body)
+            self._apost_one(url, _params, _body, timeout) for url, _params, _body in zip(x, params, body)
         ])
 
-    def _apost(self, x, params, body):
-        return pl.Series(asyncio.run(self._apost_all(x, params, body)))
+    def _apost(self, x, params, body, timeout):
+        """
+        Wrapper for performing multiple asynchronous POST requests.
+
+        Parameters
+        ----------
+        x : list
+            List of URLs to send the POST requests to.
+        params : list
+            List of query parameters for each request.
+        body : list
+            List of JSON bodies for each request.
+        timeout : float
+            The timeout for the requests.
+
+        Returns
+        -------
+        pl.Series
+            Series of response texts.
+        """
+        return pl.Series(asyncio.run(self._apost_all(x, params, body, timeout)))
+
+    def get(self, params: Optional[pl.Expr] = None, timeout: Optional[float] = None) -> pl.Expr:
+        """
+        Perform a synchronous GET request for each URL in the expression.
+
+        Parameters
+        ----------
+        params : pl.Expr, optional
+            The query parameters expression.
+        timeout : float, optional
+            The timeout for the requests.
 
-    def get(self, params: Optional[pl.Expr] = None) -> pl.Expr:
+        Returns
+        -------
+        pl.Expr
+            Expression containing the response texts.
+        """
         if params is None:
             params = pl.lit(None)
         return pl.struct(self._url.alias("url"), params.alias("params")).map_elements(
-            lambda x: self._get(x["url"], params=x["params"]),
+            lambda x: self._get(x["url"], params=x["params"], timeout=timeout),
             return_dtype=pl.Utf8,
         )
 
-    def post(self, params: Optional[pl.Expr] = None, body: Optional[pl.Expr] = None) -> pl.Expr:
+    def post(
+        self, params: Optional[pl.Expr] = None, body: Optional[pl.Expr] = None, timeout: Optional[float] = None
+    ) -> pl.Expr:
+        """
+        Perform a synchronous POST request for each URL in the expression.
+
+        Parameters
+        ----------
+        params : pl.Expr, optional
+            The query parameters expression.
+        body : pl.Expr, optional
+            The JSON body expression.
+        timeout : float, optional
+            The timeout for the requests.
+
+        Returns
+        -------
+        pl.Expr
+            Expression containing the response texts.
+        """
         if params is None:
             params = pl.lit(None)
         if body is None:
             body = pl.lit(None)
         return pl.struct(self._url.alias("url"), params.alias("params"), body.alias("body")).map_elements(
-            lambda x: self._post(x["url"], params=x["params"], body=x["body"]),
+            lambda x: self._post(x["url"], params=x["params"], body=x["body"], timeout=timeout),
             return_dtype=pl.Utf8,
         )
 
-    def aget(self, params: Optional[pl.Expr] = None) -> pl.Expr:
+    def aget(self, params: Optional[pl.Expr] = None, timeout: Optional[float] = None) -> pl.Expr:
+        """
+        Perform an asynchronous GET request for each URL in the expression.
+
+        Parameters
+        ----------
+        params : pl.Expr, optional
+            The query parameters expression.
+        timeout : float, optional
+            The timeout for the requests.
+
+        Returns
+        -------
+        pl.Expr
+            Expression containing the response texts.
+        """
+        nest_asyncio.apply()
         if params is None:
             params = pl.lit(None)
         return pl.struct(self._url.alias("url"), params.alias("params")).map_batches(
-            lambda x: self._aget(x.struct.field("url"), params=x.struct.field("params"))
+            lambda x: self._aget(x.struct.field("url"), params=x.struct.field("params"), timeout=timeout)
         )
 
-    def apost(self, params: Optional[pl.Expr] = None, body: Optional[pl.Expr] = None) -> pl.Expr:
+    def apost(
+        self, params: Optional[pl.Expr] = None, body: Optional[pl.Expr] = None, timeout: Optional[float] = None
+    ) -> pl.Expr:
+        """
+        Perform an asynchronous POST request for each URL in the expression.
+
+        Parameters
+        ----------
+        params : pl.Expr, optional
+            The query parameters expression.
+        body : pl.Expr, optional
+            The JSON body expression.
+        timeout : float, optional
+            The timeout for the requests.
+
+        Returns
+        -------
+        pl.Expr
+            Expression containing the response texts.
+        """
+        nest_asyncio.apply()
         if params is None:
             params = pl.lit(None)
         if body is None:
             body = pl.lit(None)
         return pl.struct(self._url.alias("url"), params.alias("params"), body.alias("body")).map_batches(
-            lambda x: self._apost(x.struct.field("url"), params=x.struct.field("params"), body=x.struct.field("body"))
+            lambda x: self._apost(
+                x.struct.field("url"), params=x.struct.field("params"), body=x.struct.field("body"), timeout=timeout
+            )
         )

{polars_api-0.1.4.dist-info → polars_api-0.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: polars-api
-Version: 0.1.4
+Version: 0.1.6
 Summary: Polars extension for dealing with REST APIs
 Author-email: Diego Garcia Lozano <diegoglozano96@gmail.com>
 Project-URL: Homepage, https://diegoglozano.github.io/polars-api/
@@ -20,7 +20,8 @@ Requires-Python: <4.0,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: polars>=1.19.0
+Requires-Dist: nest-asyncio>=1.6.0
+Requires-Dist: polars>=1.0.0
 
 # polars-api
 

polars_api-0.1.6.dist-info/RECORD

@@ -0,0 +1,9 @@
+examples/test.py,sha256=e-4VmxKdfRJZ01UN_3IAyAdnENTDGSZsrhGzJOtHwh0,927
+polars_api/__init__.py,sha256=JoRS_iy8pZLEz_ADKooXOqOPlUQcd5wvdcSa_PMuGLs,40
+polars_api/api.py,sha256=Dd94nz5C7qCt_rmDZuwWh-xtMS1YvvBT0ptWyaIILvs,9811
+tests/test_api.py,sha256=1OfyzFM1fUecl8TnY9CUkWt_zpUNgoIYnN_Ma9ZN77w,32
+polars_api-0.1.6.dist-info/LICENSE,sha256=Ms_a-6jJtWdrIBCOaYS_hKFCODG2QXHcNgsQJnbujnA,1076
+polars_api-0.1.6.dist-info/METADATA,sha256=kunT_W9Gz1eoShBIYnTgYPPcPPwJWB-F3sSJPuXUspE,3737
+polars_api-0.1.6.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+polars_api-0.1.6.dist-info/top_level.txt,sha256=irGgxpseyd3aPqxnvE54AITFumMlSLGg1O9-zg5Gpac,26
+polars_api-0.1.6.dist-info/RECORD,,

polars_api-0.1.4.dist-info/RECORD

@@ -1,9 +0,0 @@
-examples/test.py,sha256=e-4VmxKdfRJZ01UN_3IAyAdnENTDGSZsrhGzJOtHwh0,927
-polars_api/__init__.py,sha256=JoRS_iy8pZLEz_ADKooXOqOPlUQcd5wvdcSa_PMuGLs,40
-polars_api/api.py,sha256=XjGJu4Hhg_7aN_FmMqeH953sD7V1l1OS2F5JcNKJBaY,3341
-tests/test_api.py,sha256=1OfyzFM1fUecl8TnY9CUkWt_zpUNgoIYnN_Ma9ZN77w,32
-polars_api-0.1.4.dist-info/LICENSE,sha256=Ms_a-6jJtWdrIBCOaYS_hKFCODG2QXHcNgsQJnbujnA,1076
-polars_api-0.1.4.dist-info/METADATA,sha256=8Vra2wJdHNE-h1MgOI8rNTUmT9pFDOD9VyRbyKaFp8U,3703
-polars_api-0.1.4.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-polars_api-0.1.4.dist-info/top_level.txt,sha256=irGgxpseyd3aPqxnvE54AITFumMlSLGg1O9-zg5Gpac,26
-polars_api-0.1.4.dist-info/RECORD,,