polars-api 0.1.4__py3-none-any.whl

examples/test.py

@@ -0,0 +1,28 @@
+import polars as pl
+
+import polars_api  # noqa:F401
+
+BASE_URL = "https://jsonplaceholder.typicode.com/posts"
+print(
+    pl.DataFrame({
+        "url": [BASE_URL for _ in range(10)],
+    })
+    .with_columns(
+        pl.struct(
+            userId=3,
+        ).alias("params"),
+        pl.struct(
+            title=pl.lit("foo"),
+            body=pl.lit("bar"),
+            userId=pl.arange(10),
+        ).alias("body"),
+    )
+    .with_columns(
+        pl.col("url").api.get().str.json_decode().alias("get"),
+        pl.col("url").api.aget().str.json_decode().alias("aget"),
+        pl.col("url").api.get(params=pl.col("params")).str.json_decode().alias("get_params"),
+        pl.col("url").api.post(body=pl.col("body")).str.json_decode().alias("post"),
+        pl.col("url").api.apost(body=pl.col("body")).str.json_decode().alias("apost"),
+        pl.col("url").api.apost(params=pl.col("params")).alias("apost_params"),
+    )
+)

polars_api/__init__.py

@@ -0,0 +1,3 @@
+from .api import Api
+
+__all__ = ["Api"]

polars_api/api.py

@@ -0,0 +1,91 @@
+import asyncio
+from typing import Optional
+
+import httpx
+import polars as pl
+
+
+def check_status_code(status_code):
+    return status_code >= 200 and status_code < 300
+
+
+@pl.api.register_expr_namespace("api")
+class Api:
+    def __init__(self, url: pl.Expr) -> None:
+        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):
+            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):
+            return result.text
+        else:
+            return None
+
+    @staticmethod
+    async def _aget_one(url: str, params: str) -> str:
+        async with httpx.AsyncClient() as client:
+            r = await client.get(url, params=params)
+            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)])
+
+    def _aget(self, x, params):
+        return pl.Series(asyncio.run(self._aget_all(x, params)))
+
+    @staticmethod
+    async def _apost_one(url: str, params: str, body: str) -> str:
+        async with httpx.AsyncClient() as client:
+            r = await client.post(url, params=params, json=body)
+            return r.text
+
+    async def _apost_all(self, x, params, body):
+        return await asyncio.gather(*[
+            self._apost_one(url, _params, _body) 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 get(self, params: Optional[pl.Expr] = None) -> pl.Expr:
+        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"]),
+            return_dtype=pl.Utf8,
+        )
+
+    def post(self, params: Optional[pl.Expr] = None, body: Optional[pl.Expr] = None) -> pl.Expr:
+        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"]),
+            return_dtype=pl.Utf8,
+        )
+
+    def aget(self, params: Optional[pl.Expr] = None) -> pl.Expr:
+        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"))
+        )
+
+    def apost(self, params: Optional[pl.Expr] = None, body: Optional[pl.Expr] = None) -> pl.Expr:
+        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"))
+        )

polars_api-0.1.4.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Diego Garcia Lozano
+
+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.

polars_api-0.1.4.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.2
+Name: polars-api
+Version: 0.1.4
+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/
+Project-URL: Repository, https://github.com/diegoglozano/polars-api
+Project-URL: Documentation, https://diegoglozano.github.io/polars-api/
+Keywords: python
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+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
+
+# polars-api
+
+[![Release](https://img.shields.io/github/v/release/diegoglozano/polars-api)](https://img.shields.io/github/v/release/diegoglozano/polars-api)
+[![Build status](https://img.shields.io/github/actions/workflow/status/diegoglozano/polars-api/main.yml?branch=main)](https://github.com/diegoglozano/polars-api/actions/workflows/main.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/diegoglozano/polars-api/branch/main/graph/badge.svg)](https://codecov.io/gh/diegoglozano/polars-api)
+[![Commit activity](https://img.shields.io/github/commit-activity/m/diegoglozano/polars-api)](https://img.shields.io/github/commit-activity/m/diegoglozano/polars-api)
+[![License](https://img.shields.io/github/license/diegoglozano/polars-api)](https://img.shields.io/github/license/diegoglozano/polars-api)
+
+Polars extension for dealing with REST APIs
+
+- **Github repository**: <https://github.com/diegoglozano/polars-api/>
+- **Documentation** <https://diegoglozano.github.io/polars-api/>
+
+## Installation
+
+```sh
+uv add polars-api
+```
+
+```sh
+poetry add polars-api
+```
+
+```sh
+pip install polars-api
+```
+
+## Usage
+
+Just import the library as `import polars_api` and the new `api` namespace will be available.
+
+In the following example:
+
+- We set a base URL using [jsonplaceholder](https://jsonplaceholder.typicode.com/) as a fake REST API
+- For each row, we generate a different body using a `struct` type
+- Finally, we call different methods for getting the data:
+  - `.api.get()`: sync GET
+  - `.api.aget()`: async GET
+  - `.api.post()`: sync POST
+  - `.api.apost()`: async POST
+
+These methods will return the result as a `string`, but with polars you can convert it easily in a struct and access its values using `.str.json_decode()` method.
+
+```python
+import polars as pl
+import polars_api
+
+
+BASE_URL = "https://jsonplaceholder.typicode.com/posts"
+df = (
+    pl
+    .DataFrame({
+        "url": [BASE_URL for _ in range(10)],
+    })
+    .with_columns(
+        pl
+        .struct(
+            title=pl.lit("foo"),
+            body=pl.lit("bar"),
+            userId=pl.arange(10),
+        )
+        .alias("body"),
+    )
+    .with_columns(
+        pl
+        .col("url")
+        .api.get()
+        .str.json_decode()
+        .alias("get"),
+        pl
+        .col("url")
+        .api.aget()
+        .str.json_decode()
+        .alias("aget"),
+        pl
+        .col("url")
+        .api.post(body=pl.col("body"))
+        .str.json_decode()
+        .alias("post"),
+        pl
+        .col("url")
+        .api.apost(body=pl.col("body"))
+        .str.json_decode()
+        .alias("apost"),
+    )
+)
+
+```
+
+---
+
+Repository initiated with [fpgmaas/cookiecutter-uv](https://github.com/fpgmaas/cookiecutter-uv).

polars_api-0.1.4.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=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,,

polars_api-0.1.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

polars_api-0.1.4.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+examples
+polars_api
+tests

tests/test_api.py

@@ -0,0 +1,2 @@
+def test_get():
+    assert True