https://github.com/Summit-Sailors/polar_patch
A tool that brings type safety and type checking enhancements to the Polars library.
https://github.com/Summit-Sailors/polar_patch
Last synced: 5 months ago
JSON representation
A tool that brings type safety and type checking enhancements to the Polars library.
- Host: GitHub
- URL: https://github.com/Summit-Sailors/polar_patch
- Owner: Summit-Sailors
- License: mit
- Created: 2024-08-08T19:05:14.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-08-31T00:11:45.000Z (9 months ago)
- Last Synced: 2024-08-31T12:02:21.050Z (9 months ago)
- Language: Python
- Size: 3.34 MB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-polars - polar_patch - Python package that brings type safety and type checking for custom Polars plugins by [@Summit-Sailors](https://github.com/Summit-Sailors). (Libraries/Packages/Scripts / Python)
README
# Polar Patch
This package provides type hinting and IDE support for plugins to the Polars package, enhancing the development experience.
## Problem It Solves
Polars is a fast DataFrame library for Python, but it lacks a way to provide type hints with type checker and IDE support for custom plugins. The polars maintainers have no plans to fill this gap from within polars itself. So Summit Sailors is stepping in to help.
## Motivation
With this package, developers can:
- Write more robust and maintainable polars plugins.
- Utilize IDE Type Checker features such as autocompletion and inline documentation.
- Extend the polars ecosystem with more incentive to create new plugins
## How does it work?
1. PP parses your polar_patch.toml
2. scans files and folders you listed in ur toml
3. uses [libCST](https://libcst.readthedocs.io/en/latest/) to extract the needed info about your plugins.
4. creates a backup of the files to be modified
5. creates a copy of the backup fresh each run
6. applies the libCST transformer to add the attribute with type hint onto the corresponding Polars class
7. adds the corresponding import for your plugin into polars in a type checking block
## Notes
- It is important to note that while this is minimally invasive, it is monkey patching the executing interpreters polars package.
- libCST uses concrete syntax trees, thus the polars file is well preserved.
## Beta Blockers
- callable form of `pl.api`
- inital functional hypothesis testing setup
- basic logging
- basic exception handling
- unpin 3.12.4 to ^3.12
## Stable Blockers
- some maturity
- The blessing of the polars team for the approach on [issue](https://github.com/pola-rs/polars/issues/14475)
## Features
- automatic "hot reloading" since the type hint points directly to the implementation
- loads plugins from site-packages and generates a lockfile
## In development
- vsc extension for toml support via jsonschema
## Roadmap
- plugin store
## End Goal
An end-to-end framework for taking rust and/or python code into polars in python.
## Status
This package is currently in alpha and ideas are welcome. Only classes registered with the `@pl.api` decorator are currently supported. Lack of support for the callable form of `pl.api` is seen as a blocker for a beta release. Also, many edge cases have not been addressed. This is another blocker for a beta release. There is bare minimum direct testing. Thorough testing is a blocker for a stable release. only python 3.12.4 is supported atm.
## Installation
```bash
pip install polar-patch
```
## Configuration
To specify paths to be scanned for plugins, create a polar_patch.toml file in your project root.
(VSC IDE Support in Development)
```toml
[polar_patch]
include = ["path/to/your/plugin1.py", "path/to/your/polars/plugin/folder"]
```
## Usage
To use the CLI tool provided by this package, run the following command:
```bash
pp mount
```
## Undoing Changes
If you need to undo the changes made by this package, simply:
```bash
pp unmount
```
---
