.. image:: https://readthedocs.org/projects/jsonpolars/badge/?version=latest
:target: https://jsonpolars.readthedocs.io/en/latest/
:alt: Documentation Status
.. image:: https://github.com/MacHu-GWU/jsonpolars-project/actions/workflows/main.yml/badge.svg
:target: https://github.com/MacHu-GWU/jsonpolars-project/actions?query=workflow:CI
.. image:: https://codecov.io/gh/MacHu-GWU/jsonpolars-project/branch/main/graph/badge.svg
:target: https://codecov.io/gh/MacHu-GWU/jsonpolars-project
.. image:: https://img.shields.io/pypi/v/jsonpolars.svg
:target: https://pypi.python.org/pypi/jsonpolars
.. image:: https://img.shields.io/pypi/l/jsonpolars.svg
:target: https://pypi.python.org/pypi/jsonpolars
.. image:: https://img.shields.io/pypi/pyversions/jsonpolars.svg
:target: https://pypi.python.org/pypi/jsonpolars
.. image:: https://img.shields.io/badge/Release_History!--None.svg?style=social
:target: https://github.com/MacHu-GWU/jsonpolars-project/blob/main/release-history.rst
.. image:: https://img.shields.io/badge/STAR_Me_on_GitHub!--None.svg?style=social
:target: https://github.com/MacHu-GWU/jsonpolars-project
------
.. image:: https://img.shields.io/badge/Link-Document-blue.svg
:target: https://jsonpolars.readthedocs.io/en/latest/
.. image:: https://img.shields.io/badge/Link-API-blue.svg
:target: https://jsonpolars.readthedocs.io/en/latest/py-modindex.html
.. image:: https://img.shields.io/badge/Link-Install-blue.svg
:target: `install`_
.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg
:target: https://github.com/MacHu-GWU/jsonpolars-project
.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg
:target: https://github.com/MacHu-GWU/jsonpolars-project/issues
.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg
:target: https://github.com/MacHu-GWU/jsonpolars-project/issues
.. image:: https://img.shields.io/badge/Link-Download-blue.svg
:target: https://pypi.org/pypi/jsonpolars#files
Welcome to ``jsonpolars`` Documentation
==============================================================================
.. image:: https://jsonpolars.readthedocs.io/en/latest/_static/jsonpolars-logo.png
:target: https://jsonpolars.readthedocs.io/en/latest/
``jsonpolars`` is an innovative Python library designed to bridge the gap between JSON-based data manipulation syntax and the powerful Polars data processing library. This project aims to provide a flexible and intuitive way to express Polars operations using JSON structures, making it easier for developers to work with Polars in various contexts. The library allows users to define complex data transformations using JSON syntax, which can then be translated into native Polars operations.
Here's a simple example of how to use jsonpolars:
.. code-block:: python
import polars as pl
from jsonpolars.api import parse_dfop
# Create a sample DataFrame
df = pl.DataFrame(
[
{"id": 1, "firstname": "Alice", "lastname": "Smith"},
{"id": 2, "firstname": "Bob", "lastname": "Johnson"},
{"id": 3, "firstname": "Cathy", "lastname": "Williams"},
]
)
# Define the operation using JSON structure
dfop_data = {
"type": "with_columns",
"exprs": [
{
"type": "alias",
"name": "fullname",
"expr": {
"type": "plus",
"left": {"type": "column", "name": "firstname"},
"right": {
"type": "plus",
"left": {
"type": "lit",
"value": " ",
},
"right": {"type": "column", "name": "lastname"},
},
},
}
],
}
# Parse and apply the operation
op = parse_dfop(dfop_data)
df1 = op.to_polars(df)
print(df1)
Output:
.. code-block:: python
shape: (3, 4)
┌─────┬───────────┬──────────┬────────────────┐
│ id ┆ firstname ┆ lastname ┆ fullname │
│ --- ┆ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str ┆ str │
╞═════╪═══════════╪══════════╪════════════════╡
│ 1 ┆ Alice ┆ Smith ┆ Alice Smith │
│ 2 ┆ Bob ┆ Johnson ┆ Bob Johnson │
│ 3 ┆ Cathy ┆ Williams ┆ Cathy Williams │
└─────┴───────────┴──────────┴────────────────┘
In addition to JSON-based syntax, jsonpolars allows you to define operations using Python objects for a more Pythonic approach. Here's how you can use this feature:
.. code-block:: python
import json
# Define the operation using Python objects
op = dfop.WithColumns(
exprs=[
expr.Alias(
name="fullname",
expr=expr.Plus(
left=expr.Column(name="firstname"),
right=expr.Plus(
left=expr.Lit(value=" "),
right=expr.Column(name="lastname"),
),
),
)
]
)
# Convert the operation to JSON (optional, for visualization)
print(json.dumps(op.to_dict(), indent=4))
Output:
.. code-block:: javascript
{
"type": "with_columns",
"exprs": [
{
"type": "alias",
"name": "fullname",
"expr": {
"type": "add",
"left": {
"type": "column",
"name": "firstname"
},
"right": {
"type": "add",
"left": {
"type": "func_lit",
"value": " ",
"dtype": null,
"allow_object": false
},
"right": {
"type": "column",
"name": "lastname"
}
}
}
}
],
"named_exprs": {}
}
The ``to_polars()`` method seamlessly translates your Python object-based operation into Polars code, allowing you to apply complex transformations with ease.
.. code-block:: python
# Apply the operation to a Polars DataFrame
df1 = op.to_polars(df)
print(df1)
Output:
.. code-block:: python
shape: (3, 4)
┌─────┬───────────┬──────────┬────────────────┐
│ id ┆ firstname ┆ lastname ┆ fullname │
│ --- ┆ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str ┆ str │
╞═════╪═══════════╪══════════╪════════════════╡
│ 1 ┆ Alice ┆ Smith ┆ Alice Smith │
│ 2 ┆ Bob ┆ Johnson ┆ Bob Johnson │
│ 3 ┆ Cathy ┆ Williams ┆ Cathy Williams │
└─────┴───────────┴──────────┴────────────────┘
.. _install:
Install
------------------------------------------------------------------------------
``jsonpolars`` is released on PyPI, so all you need is to:
.. code-block:: console
$ pip install jsonpolars
To upgrade to latest version:
.. code-block:: console
$ pip install --upgrade jsonpolars
Raw data
{
"_id": null,
"home_page": "https://github.com/MacHu-GWU/jsonpolars-project",
"name": "jsonpolars",
"maintainer": "Sanhe Hu",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "husanhe@email.com",
"keywords": null,
"author": "Sanhe Hu",
"author_email": "husanhe@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/56/ea/c1f4b8b8d4d64604db2f02f3a2aa02b35ccadd80eafb9736943d6eca851e/jsonpolars-0.3.2.tar.gz",
"platform": "Windows",
"description": "\n.. image:: https://readthedocs.org/projects/jsonpolars/badge/?version=latest\n :target: https://jsonpolars.readthedocs.io/en/latest/\n :alt: Documentation Status\n\n.. image:: https://github.com/MacHu-GWU/jsonpolars-project/actions/workflows/main.yml/badge.svg\n :target: https://github.com/MacHu-GWU/jsonpolars-project/actions?query=workflow:CI\n\n.. image:: https://codecov.io/gh/MacHu-GWU/jsonpolars-project/branch/main/graph/badge.svg\n :target: https://codecov.io/gh/MacHu-GWU/jsonpolars-project\n\n.. image:: https://img.shields.io/pypi/v/jsonpolars.svg\n :target: https://pypi.python.org/pypi/jsonpolars\n\n.. image:: https://img.shields.io/pypi/l/jsonpolars.svg\n :target: https://pypi.python.org/pypi/jsonpolars\n\n.. image:: https://img.shields.io/pypi/pyversions/jsonpolars.svg\n :target: https://pypi.python.org/pypi/jsonpolars\n\n.. image:: https://img.shields.io/badge/Release_History!--None.svg?style=social\n :target: https://github.com/MacHu-GWU/jsonpolars-project/blob/main/release-history.rst\n\n.. image:: https://img.shields.io/badge/STAR_Me_on_GitHub!--None.svg?style=social\n :target: https://github.com/MacHu-GWU/jsonpolars-project\n\n------\n\n.. image:: https://img.shields.io/badge/Link-Document-blue.svg\n :target: https://jsonpolars.readthedocs.io/en/latest/\n\n.. image:: https://img.shields.io/badge/Link-API-blue.svg\n :target: https://jsonpolars.readthedocs.io/en/latest/py-modindex.html\n\n.. image:: https://img.shields.io/badge/Link-Install-blue.svg\n :target: `install`_\n\n.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg\n :target: https://github.com/MacHu-GWU/jsonpolars-project\n\n.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg\n :target: https://github.com/MacHu-GWU/jsonpolars-project/issues\n\n.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg\n :target: https://github.com/MacHu-GWU/jsonpolars-project/issues\n\n.. image:: https://img.shields.io/badge/Link-Download-blue.svg\n :target: https://pypi.org/pypi/jsonpolars#files\n\n\nWelcome to ``jsonpolars`` Documentation\n==============================================================================\n.. image:: https://jsonpolars.readthedocs.io/en/latest/_static/jsonpolars-logo.png\n :target: https://jsonpolars.readthedocs.io/en/latest/\n\n``jsonpolars`` is an innovative Python library designed to bridge the gap between JSON-based data manipulation syntax and the powerful Polars data processing library. This project aims to provide a flexible and intuitive way to express Polars operations using JSON structures, making it easier for developers to work with Polars in various contexts. The library allows users to define complex data transformations using JSON syntax, which can then be translated into native Polars operations.\n\nHere's a simple example of how to use jsonpolars:\n\n.. code-block:: python\n\n import polars as pl\n from jsonpolars.api import parse_dfop\n\n # Create a sample DataFrame\n df = pl.DataFrame(\n [\n {\"id\": 1, \"firstname\": \"Alice\", \"lastname\": \"Smith\"},\n {\"id\": 2, \"firstname\": \"Bob\", \"lastname\": \"Johnson\"},\n {\"id\": 3, \"firstname\": \"Cathy\", \"lastname\": \"Williams\"},\n ]\n )\n\n # Define the operation using JSON structure\n dfop_data = {\n \"type\": \"with_columns\",\n \"exprs\": [\n {\n \"type\": \"alias\",\n \"name\": \"fullname\",\n \"expr\": {\n \"type\": \"plus\",\n \"left\": {\"type\": \"column\", \"name\": \"firstname\"},\n \"right\": {\n \"type\": \"plus\",\n \"left\": {\n \"type\": \"lit\",\n \"value\": \" \",\n },\n \"right\": {\"type\": \"column\", \"name\": \"lastname\"},\n },\n },\n }\n ],\n }\n\n # Parse and apply the operation\n op = parse_dfop(dfop_data)\n df1 = op.to_polars(df)\n print(df1)\n\nOutput:\n\n.. code-block:: python\n\n shape: (3, 4)\n \u250c\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 id \u2506 firstname \u2506 lastname \u2506 fullname \u2502\n \u2502 --- \u2506 --- \u2506 --- \u2506 --- \u2502\n \u2502 i64 \u2506 str \u2506 str \u2506 str \u2502\n \u255e\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2561\n \u2502 1 \u2506 Alice \u2506 Smith \u2506 Alice Smith \u2502\n \u2502 2 \u2506 Bob \u2506 Johnson \u2506 Bob Johnson \u2502\n \u2502 3 \u2506 Cathy \u2506 Williams \u2506 Cathy Williams \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\nIn addition to JSON-based syntax, jsonpolars allows you to define operations using Python objects for a more Pythonic approach. Here's how you can use this feature:\n\n.. code-block:: python\n\n import json\n\n # Define the operation using Python objects\n op = dfop.WithColumns(\n exprs=[\n expr.Alias(\n name=\"fullname\",\n expr=expr.Plus(\n left=expr.Column(name=\"firstname\"),\n right=expr.Plus(\n left=expr.Lit(value=\" \"),\n right=expr.Column(name=\"lastname\"),\n ),\n ),\n )\n ]\n )\n\n # Convert the operation to JSON (optional, for visualization)\n print(json.dumps(op.to_dict(), indent=4))\n\nOutput:\n\n.. code-block:: javascript\n\n {\n \"type\": \"with_columns\",\n \"exprs\": [\n {\n \"type\": \"alias\",\n \"name\": \"fullname\",\n \"expr\": {\n \"type\": \"add\",\n \"left\": {\n \"type\": \"column\",\n \"name\": \"firstname\"\n },\n \"right\": {\n \"type\": \"add\",\n \"left\": {\n \"type\": \"func_lit\",\n \"value\": \" \",\n \"dtype\": null,\n \"allow_object\": false\n },\n \"right\": {\n \"type\": \"column\",\n \"name\": \"lastname\"\n }\n }\n }\n }\n ],\n \"named_exprs\": {}\n }\n\nThe ``to_polars()`` method seamlessly translates your Python object-based operation into Polars code, allowing you to apply complex transformations with ease.\n\n.. code-block:: python\n\n # Apply the operation to a Polars DataFrame\n df1 = op.to_polars(df)\n print(df1)\n\nOutput:\n\n.. code-block:: python\n\n shape: (3, 4)\n \u250c\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 id \u2506 firstname \u2506 lastname \u2506 fullname \u2502\n \u2502 --- \u2506 --- \u2506 --- \u2506 --- \u2502\n \u2502 i64 \u2506 str \u2506 str \u2506 str \u2502\n \u255e\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2561\n \u2502 1 \u2506 Alice \u2506 Smith \u2506 Alice Smith \u2502\n \u2502 2 \u2506 Bob \u2506 Johnson \u2506 Bob Johnson \u2502\n \u2502 3 \u2506 Cathy \u2506 Williams \u2506 Cathy Williams \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n\n.. _install:\n\nInstall\n------------------------------------------------------------------------------\n\n``jsonpolars`` is released on PyPI, so all you need is to:\n\n.. code-block:: console\n\n $ pip install jsonpolars\n\nTo upgrade to latest version:\n\n.. code-block:: console\n\n $ pip install --upgrade jsonpolars\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Package short description.",
"version": "0.3.2",
"project_urls": {
"Download": "https://pypi.python.org/pypi/jsonpolars/0.3.2#downloads",
"Homepage": "https://github.com/MacHu-GWU/jsonpolars-project"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ed45a58ef07d73b4943b15d4d3c136eb383f2fcfcf0eac3fa40f59d62944128c",
"md5": "372191ab3ff9b44d2f3025f55d73085d",
"sha256": "3f7172f7e3b832cb5d6185fdc8b77710be419947dab4ec4e9944dc8290848248"
},
"downloads": -1,
"filename": "jsonpolars-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "372191ab3ff9b44d2f3025f55d73085d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 38316,
"upload_time": "2024-09-05T17:43:17",
"upload_time_iso_8601": "2024-09-05T17:43:17.402649Z",
"url": "https://files.pythonhosted.org/packages/ed/45/a58ef07d73b4943b15d4d3c136eb383f2fcfcf0eac3fa40f59d62944128c/jsonpolars-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "56eac1f4b8b8d4d64604db2f02f3a2aa02b35ccadd80eafb9736943d6eca851e",
"md5": "e1328f6d65272148089c45df36c99125",
"sha256": "c1eb36179976b234f50a297b07a0ba783506260c335640c820ee453eb36c40ed"
},
"downloads": -1,
"filename": "jsonpolars-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "e1328f6d65272148089c45df36c99125",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 34038,
"upload_time": "2024-09-05T17:43:19",
"upload_time_iso_8601": "2024-09-05T17:43:19.207568Z",
"url": "https://files.pythonhosted.org/packages/56/ea/c1f4b8b8d4d64604db2f02f3a2aa02b35ccadd80eafb9736943d6eca851e/jsonpolars-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-05 17:43:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MacHu-GWU",
"github_project": "jsonpolars-project",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "polars",
"specs": [
[
">=",
"1.2.1"
],
[
"<",
"2.0.0"
]
]
},
{
"name": "simpletype",
"specs": [
[
"<",
"1.0.0"
],
[
">=",
"0.2.5"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.10.0"
]
]
}
],
"lcname": "jsonpolars"
}
JSON
