Metadata-Version: 2.4
Name: polars
Version: 1.10.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Rust
Classifier: Topic :: Scientific/Engineering
Requires-Dist: adbc-driver-manager[dbapi] ; extra == 'adbc'
Requires-Dist: adbc-driver-sqlite[dbapi] ; extra == 'adbc'
Requires-Dist: polars[async,cloudpickle,database,deltalake,excel,fsspec,graph,iceberg,numpy,pandas,plot,pyarrow,pydantic,style,timezone] ; extra == 'all'
Requires-Dist: gevent ; extra == 'async'
Requires-Dist: fastexcel>=0.9 ; extra == 'calamine'
Requires-Dist: cloudpickle ; extra == 'cloudpickle'
Requires-Dist: connectorx>=0.3.2 ; extra == 'connectorx'
Requires-Dist: polars[adbc,connectorx,sqlalchemy] ; extra == 'database'
Requires-Dist: nest-asyncio ; extra == 'database'
Requires-Dist: deltalake>=0.15.0 ; extra == 'deltalake'
Requires-Dist: polars[calamine,openpyxl,xlsx2csv,xlsxwriter] ; extra == 'excel'
Requires-Dist: fsspec ; extra == 'fsspec'
Requires-Dist: cudf-polars-cu12 ; extra == 'gpu'
Requires-Dist: matplotlib ; extra == 'graph'
Requires-Dist: pyiceberg>=0.5.0 ; extra == 'iceberg'
Requires-Dist: numpy>=1.16.0 ; extra == 'numpy'
Requires-Dist: openpyxl>=3.0.0 ; extra == 'openpyxl'
Requires-Dist: pandas ; extra == 'pandas'
Requires-Dist: polars[pyarrow] ; extra == 'pandas'
Requires-Dist: altair>=5.4.0 ; extra == 'plot'
Requires-Dist: pyarrow>=7.0.0 ; extra == 'pyarrow'
Requires-Dist: pydantic ; extra == 'pydantic'
Requires-Dist: sqlalchemy ; extra == 'sqlalchemy'
Requires-Dist: polars[pandas] ; extra == 'sqlalchemy'
Requires-Dist: great-tables>=0.8.0 ; extra == 'style'
Requires-Dist: backports-zoneinfo ; python_full_version < '3.9' and extra == 'timezone'
Requires-Dist: tzdata ; platform_system == 'Windows' and extra == 'timezone'
Requires-Dist: xlsx2csv>=0.8.0 ; extra == 'xlsx2csv'
Requires-Dist: xlsxwriter ; extra == 'xlsxwriter'
Provides-Extra: adbc
Provides-Extra: all
Provides-Extra: async
Provides-Extra: calamine
Provides-Extra: cloudpickle
Provides-Extra: connectorx
Provides-Extra: database
Provides-Extra: deltalake
Provides-Extra: excel
Provides-Extra: fsspec
Provides-Extra: gpu
Provides-Extra: graph
Provides-Extra: iceberg
Provides-Extra: numpy
Provides-Extra: openpyxl
Provides-Extra: pandas
Provides-Extra: plot
Provides-Extra: pyarrow
Provides-Extra: pydantic
Provides-Extra: sqlalchemy
Provides-Extra: style
Provides-Extra: timezone
Provides-Extra: xlsx2csv
Provides-Extra: xlsxwriter
License-File: LICENSE
Summary: Blazingly fast DataFrame library
Keywords: dataframe,arrow,out-of-core
Author-email: Ritchie Vink <ritchie46@gmail.com>
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/pola-rs/polars/releases
Project-URL: Documentation, https://docs.pola.rs/api/python/stable/reference/index.html
Project-URL: Homepage, https://www.pola.rs/
Project-URL: Repository, https://github.com/pola-rs/polars

  Documentation:
  Python (https://docs.pola.rs/api/python/stable/reference/index.html)
  -
  Rust (https://docs.rs/polars/latest/polars/)
  -
  Node.js (https://pola-rs.github.io/nodejs-polars/index.html)
  -
  R (https://pola-rs.github.io/r-polars/index.html)
  |
  StackOverflow:
  Python (https://stackoverflow.com/questions/tagged/python-polars)
  -
  Rust (https://stackoverflow.com/questions/tagged/rust-polars)
  -
  Node.js (https://stackoverflow.com/questions/tagged/nodejs-polars)
  -
  R (https://stackoverflow.com/questions/tagged/r-polars)
  |
  User guide (https://docs.pola.rs/)
  |
  Discord (https://discord.gg/4UfP5cfBE7)

## Polars: Blazingly fast DataFrames in Rust, Python, Node.js, R, and SQL

Polars is a DataFrame interface on top of an OLAP Query Engine implemented in Rust using
[Apache Arrow Columnar Format](https://arrow.apache.org/docs/format/Columnar.html) as the memory model.

- Lazy | eager execution
- Multi-threaded
- SIMD
- Query optimization
- Powerful expression API
- Hybrid Streaming (larger-than-RAM datasets)
- Rust | Python | NodeJS | R | ...

To learn more, read the [user guide](https://docs.pola.rs/).

## Python

```python
>>> import polars as pl
>>> df = pl.DataFrame(
...     {
...         "A": [1, 2, 3, 4, 5],
...         "fruits": ["banana", "banana", "apple", "apple", "banana"],
...         "B": [5, 4, 3, 2, 1],
...         "cars": ["beetle", "audi", "beetle", "beetle", "beetle"],
...     }
... )

# embarrassingly parallel execution & very expressive query language
>>> df.sort("fruits").select(
...     "fruits",
...     "cars",
...     pl.lit("fruits").alias("literal_string_fruits"),
...     pl.col("B").filter(pl.col("cars") == "beetle").sum(),
...     pl.col("A").filter(pl.col("B") > 2).sum().over("cars").alias("sum_A_by_cars"),
...     pl.col("A").sum().over("fruits").alias("sum_A_by_fruits"),
...     pl.col("A").reverse().over("fruits").alias("rev_A_by_fruits"),
...     pl.col("A").sort_by("B").over("fruits").alias("sort_A_by_B_by_fruits"),
... )
shape: (5, 8)
┌──────────┬──────────┬──────────────┬─────┬─────────────┬─────────────┬─────────────┬─────────────┐
│ fruits   ┆ cars     ┆ literal_stri ┆ B   ┆ sum_A_by_ca ┆ sum_A_by_fr ┆ rev_A_by_fr ┆ sort_A_by_B │
│ ---      ┆ ---      ┆ ng_fruits    ┆ --- ┆ rs          ┆ uits        ┆ uits        ┆ _by_fruits  │
│ str      ┆ str      ┆ ---          ┆ i64 ┆ ---         ┆ ---         ┆ ---         ┆ ---         │
│          ┆          ┆ str          ┆     ┆ i64         ┆ i64         ┆ i64         ┆ i64         │
╞══════════╪══════════╪══════════════╪═════╪═════════════╪═════════════╪═════════════╪═════════════╡
│ "apple"  ┆ "beetle" ┆ "fruits"     ┆ 11  ┆ 4           ┆ 7           ┆ 4           ┆ 4           │
│ "apple"  ┆ "beetle" ┆ "fruits"     ┆ 11  ┆ 4           ┆ 7           ┆ 3           ┆ 3           │
│ "banana" ┆ "beetle" ┆ "fruits"     ┆ 11  ┆ 4           ┆ 8           ┆ 5           ┆ 5           │
│ "banana" ┆ "audi"   ┆ "fruits"     ┆ 11  ┆ 2           ┆ 8           ┆ 2           ┆ 2           │
│ "banana" ┆ "beetle" ┆ "fruits"     ┆ 11  ┆ 4           ┆ 8           ┆ 1           ┆ 1           │
└──────────┴──────────┴──────────────┴─────┴─────────────┴─────────────┴─────────────┴─────────────┘
```

## SQL

```python
>>> df = pl.scan_csv("docs/assets/data/iris.csv")
>>> ## OPTION 1
>>> # run SQL queries on frame-level
>>> df.sql("""
...	SELECT species,
...	  AVG(sepal_length) AS avg_sepal_length
...	FROM self
...	GROUP BY species
...	""").collect()
shape: (3, 2)
┌────────────┬──────────────────┐
│ species    ┆ avg_sepal_length │
│ ---        ┆ ---              │
│ str        ┆ f64              │
╞════════════╪══════════════════╡
│ Virginica  ┆ 6.588            │
│ Versicolor ┆ 5.936            │
│ Setosa     ┆ 5.006            │
└────────────┴──────────────────┘
>>> ## OPTION 2
>>> # use pl.sql() to operate on the global context
>>> df2 = pl.LazyFrame({
...    "species": ["Setosa", "Versicolor", "Virginica"],
...    "blooming_season": ["Spring", "Summer", "Fall"]
...})
>>> pl.sql("""
... SELECT df.species,
...     AVG(df.sepal_length) AS avg_sepal_length,
...     df2.blooming_season
... FROM df
... LEFT JOIN df2 ON df.species = df2.species
... GROUP BY df.species, df2.blooming_season
... """).collect()
```

SQL commands can also be run directly from your terminal using the Polars CLI:

```bash
# run an inline SQL query
> polars -c "SELECT species, AVG(sepal_length) AS avg_sepal_length, AVG(sepal_width) AS avg_sepal_width FROM read_csv('docs/assets/data/iris.csv') GROUP BY species;"

# run interactively
> polars
Polars CLI v0.3.0
Type .help for help.

> SELECT species, AVG(sepal_length) AS avg_sepal_length, AVG(sepal_width) AS avg_sepal_width FROM read_csv('docs/assets/data/iris.csv') GROUP BY species;
```

Refer to the [Polars CLI repository](https://github.com/pola-rs/polars-cli) for more information.

## Performance 🚀🚀

### Blazingly fast

Polars is very fast. In fact, it is one of the best performing solutions available. See the [PDS-H benchmarks](https://www.pola.rs/benchmarks.html) results.

### Lightweight

Polars is also very lightweight. It comes with zero required dependencies, and this shows in the import times:

- polars: 70ms
- numpy: 104ms
- pandas: 520ms

### Handles larger-than-RAM data

If you have data that does not fit into memory, Polars' query engine is able to process your query (or parts of your query) in a streaming fashion.
This drastically reduces memory requirements, so you might be able to process your 250GB dataset on your laptop.
Collect with `collect(streaming=True)` to run the query streaming.
(This might be a little slower, but it is still very fast!)

## Setup

### Python

Install the latest Polars version with:

```sh
pip install polars
```

We also have a conda package (`conda install -c conda-forge polars`), however pip is the preferred way to install Polars.

Install Polars with all optional dependencies.

```sh
pip install 'polars[all]'
```

You can also install a subset of all optional dependencies.

```sh
pip install 'polars[numpy,pandas,pyarrow]'
```

See the [User Guide](https://docs.pola.rs/user-guide/installation/#feature-flags) for more details on optional dependencies

To see the current Polars version and a full list of its optional dependencies, run:

```python
pl.show_versions()
```

Releases happen quite often (weekly / every few days) at the moment, so updating Polars regularly to get the latest bugfixes / features might not be a bad idea.

### Rust

You can take latest release from `crates.io`, or if you want to use the latest features / performance
improvements point to the `main` branch of this repo.

```toml
polars = { git = "https://github.com/pola-rs/polars", rev = "<optional git tag>" }
```

Requires Rust version `>=1.80`.

## Contributing

Want to contribute? Read our [contributing guide](https://docs.pola.rs/development/contributing/).

## Python: compile Polars from source

If you want a bleeding edge release or maximal performance you should compile Polars from source.

This can be done by going through the following steps in sequence:

1. Install the latest [Rust compiler](https://www.rust-lang.org/tools/install)
2. Install [maturin](https://maturin.rs/): `pip install maturin`
3. `cd py-polars` and choose one of the following:
   - `make build-release`, fastest binary, very long compile times
   - `make build-opt`, fast binary with debug symbols, long compile times
   - `make build-debug-opt`, medium-speed binary with debug assertions and symbols, medium compile times
   - `make build`, slow binary with debug assertions and symbols, fast compile times

   Append `-native` (e.g. `make build-release-native`) to enable further optimizations specific to
   your CPU. This produces a non-portable binary/wheel however.

Note that the Rust crate implementing the Python bindings is called `py-polars` to distinguish from the wrapped
Rust crate `polars` itself. However, both the Python package and the Python module are named `polars`, so you
can `pip install polars` and `import polars`.

## Using custom Rust functions in Python

Extending Polars with UDFs compiled in Rust is easy. We expose PyO3 extensions for `DataFrame` and `Series`
data structures. See more in https://github.com/pola-rs/pyo3-polars.

## Going big...

Do you expect more than 2^32 (~4.2 billion) rows? Compile Polars with the `bigidx` feature
flag or, for Python users, install `pip install polars-u64-idx`.

Don't use this unless you hit the row boundary as the default build of Polars is faster and consumes less memory.

## Legacy

Do you want Polars to run on an old CPU (e.g. dating from before 2011), or on an `x86-64` build
of Python on Apple Silicon under Rosetta? Install `pip install polars-lts-cpu`. This version of
Polars is compiled without [AVX](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) target
features.

## Sponsors

[JetBrains logo](https://www.jetbrains.com)

