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

polars_api/api.py

@@ -2,61 +2,242 @@ 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, 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):
+        if _check_status_code(result.status_code):
             return result.text
         else:
             return None
 
     @staticmethod
     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):
+        if _check_status_code(result.status_code):
             return result.text
         else:
             return None
 
     @staticmethod
     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, timeout=timeout)
             return r.text
 
     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, 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, 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, timeout=timeout)
             return r.text
 
     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, timeout) for url, _params, _body in zip(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.
+
+        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(
@@ -67,6 +248,23 @@ class Api:
     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:
@@ -77,6 +275,22 @@ class Api:
         )
 
     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(
@@ -86,6 +300,24 @@ class Api:
     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:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: polars-api
-Version: 0.1.5
+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.5.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=Pqfc7LJ3o4yx__s2JQ4lTwB12PjdtzImYvmO8pKxGOs,3830
-tests/test_api.py,sha256=1OfyzFM1fUecl8TnY9CUkWt_zpUNgoIYnN_Ma9ZN77w,32
-polars_api-0.1.5.dist-info/LICENSE,sha256=Ms_a-6jJtWdrIBCOaYS_hKFCODG2QXHcNgsQJnbujnA,1076
-polars_api-0.1.5.dist-info/METADATA,sha256=eUtaFcZwWBXlcPc_sIpsQoTSi1YheIche_dxPVArs6M,3703
-polars_api-0.1.5.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-polars_api-0.1.5.dist-info/top_level.txt,sha256=irGgxpseyd3aPqxnvE54AITFumMlSLGg1O9-zg5Gpac,26
-polars_api-0.1.5.dist-info/RECORD,,