Skip to main content

A tool that brings type safety and type checking enhancements to the Polars library.

Project description

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 to extract the needed info about your plugins.
  4. generates a lockfile for all the plugin data it extracted
  5. creates a backup of the files to be modified
  6. uses a copy of the backup fresh each run
  7. applies the libCST transformer to add the attribute with type hint onto the corresponding Polars class
  8. adds the corresponding import for your plugin into polars in a type checking block

Lockfile

Added Import

Added Attribute

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
  • install plugins from site-packages
  • basic logging
  • inital functional hypothesis testing setup
  • 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

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

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

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)

[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:

pp mount

Undoing Changes

If you need to undo the changes made by this package, simply:

pp unmount

Subscription Tiers on Polar

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

polar_patch-0.0.9.tar.gz (8.4 kB view details)

Uploaded Source

Built Distribution

polar_patch-0.0.9-py3-none-any.whl (12.6 kB view details)

Uploaded Python 3

File details

Details for the file polar_patch-0.0.9.tar.gz.

File metadata

  • Download URL: polar_patch-0.0.9.tar.gz
  • Upload date:
  • Size: 8.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.5

File hashes

Hashes for polar_patch-0.0.9.tar.gz
Algorithm Hash digest
SHA256 1c5c42a7b8d03d51a69cc1add384a5213d4d45b43707b3c0b27591f172b4144c
MD5 fb79b9a1986dbb36f6ab61cb9812b368
BLAKE2b-256 7e3aaa3d1df568b32ec0d6cbef7593ba82ba4e0a1f6c95ffe64bdd2eaaeb0299

See more details on using hashes here.

File details

Details for the file polar_patch-0.0.9-py3-none-any.whl.

File metadata

  • Download URL: polar_patch-0.0.9-py3-none-any.whl
  • Upload date:
  • Size: 12.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.5

File hashes

Hashes for polar_patch-0.0.9-py3-none-any.whl
Algorithm Hash digest
SHA256 7187456da3365ef1376b32183fefa5c1314fd5a7dfa93b076ced52bdf62c3432
MD5 513e26dd28a00d31178065bb9ef0b8ce
BLAKE2b-256 dbd8cc732ecc05e4e4674372d6a627c3d6ccd0bc0196aaa1ad54178c1f3f992f

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page