Skip to main content

Pandas Flavor

The easy way to write your own flavor of Pandas

Pandas 0.23 added a (simple) API for registering accessors with Pandas objects.

Pandas-flavor extends Pandas' extension API by:

  1. adding support for registering methods as well.
  2. making each of these functions backwards compatible with older versions of Pandas.

What does this mean?

It is now simpler to add custom functionality to Pandas DataFrames and Series.

Import this package. Write a simple python function. Register the function using one of the following decorators.

Why?

Pandas is super handy. Its general purpose is to be a "flexible and powerful data analysis/manipulation library".

Pandas Flavor allows you add functionality that tailors Pandas to specific fields or use cases.

Maybe you want to add new write methods to the Pandas DataFrame? Maybe you want custom plot functionality? Maybe something else?

Register accessors

Accessors (in pandas) are objects attached to an attribute on the Pandas DataFrame/Series that provide extra, specific functionality. For example, pandas.DataFrame.plot is an accessor that provides plotting functionality.

Add an accessor by registering the function with the following decorator and passing the decorator an accessor name.

# my_flavor.py

import pandas_flavor as pf

@pf.register_dataframe_accessor('my_flavor')
class MyFlavor(object):

  def __init__(self, data):
    self._data = data

  def row_by_value(self, col, value):
    """Slice out row from DataFrame by a value."""
    return self._data[self._data[col] == value].squeeze()

Every dataframe now has this accessor as an attribute.

import my_flavor

# DataFrame.
df = pd.DataFrame(data={
  "x": [10, 20, 25],
  "y": [0, 2, 5]
})

# Print DataFrame
print(df)

#     x  y
# 0  10  0
# 1  20  2
# 2  25  5

# Access this functionality
df.my_flavor.row_by_value('x', 10)

# x    10
# y     0
# Name: 0, dtype: int64

To see this in action, check out pdvega, PhyloPandas, and pyjanitor!

Register methods

Using this package, you can attach functions directly to Pandas objects. No intermediate accessor is needed.

# my_flavor.py

import pandas_flavor as pf

@pf.register_dataframe_method
def row_by_value(df, col, value):
    """Slice out row from DataFrame by a value."""
    return df[df[col] == value].squeeze()
import pandas as pd
import my_flavor

# DataFrame.
df = pd.DataFrame(data={
  "x": [10, 20, 25],
  "y": [0, 2, 5]
})

# Print DataFrame
print(df)

#     x  y
# 0  10  0
# 1  20  2
# 2  25  5

# Access this functionality
df.row_by_value('x', 10)

# x    10
# y     0
# Name: 0, dtype: int64

Registered methods tracing

The pandas_flavor 0.5.0 release introduced tracing of the registered method calls. Now it is possible to add additional run-time logic around registered method execution which can be used for some support tasks. This extension was introduced to allow visualization of pyjanitor method chains as implemented in pyjviz

Available Methods

  • register_dataframe_method: register a method directly with a pandas DataFrame.
  • register_dataframe_accessor: register an accessor (and it's methods) with a pandas DataFrame.
  • register_series_method: register a methods directly with a pandas Series.
  • register_series_accessor: register an accessor (and it's methods) with a pandas Series.
  • register_groupby_method: register a methods directly with a pandas DataFrameGroupBy object.
  • register_groupby_accessor: register an accessor (and it's methods) with a pandas DataFrameGroupBy object.

Installation

You can install using pip:

pip install pandas_flavor

or conda (thanks @ericmjl)!

conda install -c conda-forge pandas-flavor

Contributing

Pull requests are always welcome! If you find a bug, don't hestitate to open an issue or submit a PR. If you're not sure how to do that, check out this simple guide.

If you have a feature request, please open an issue or submit a PR!

TL;DR

Pandas 0.23 introduced a simpler API for extending Pandas. This API provided two key decorators, register_dataframe_accessor and register_series_accessor, that enable users to register accessors with Pandas DataFrames and Series.

Pandas Flavor originated as a library to backport these decorators to older versions of Pandas (<0.23). While doing the backporting, it became clear that registering methods directly to Pandas objects might be a desired feature as well.*

*It is likely that Pandas deliberately chose not implement to this feature. If everyone starts monkeypatching DataFrames with their custom methods, it could lead to confusion in the Pandas community. The preferred Pandas approach is to namespace your methods by registering an accessor that contains your custom methods.

So how does method registration work?

When you register a method, Pandas flavor actually creates and registers a (this is subtle, but important) custom accessor class that mimics the behavior of a method by:

  1. inheriting the docstring of your function
  2. overriding the __call__ method to call your function.

Metadata

Release files for pandas-flavor 0.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pandas-flavor 0.0.0
File Size Uploaded Provenance Actions
pandas_flavor-0.0.0.tar.gz 11.4 kB Without provenance Details for pandas_flavor-0.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pandas-flavor 0.0.0
File Interpreter ABI Platform Actions
pandas_flavor-0.0.0-py3-none-any.whl Python 3 none any Details for pandas_flavor-0.0.0-py3-none-any.whl

Total release size: 20.0 kB

Release files / pandas_flavor-0.0.0.tar.gz

Download URL pandas_flavor-0.0.0.tar.gz
Size 11.4 kB
Tags Source
SHA-256 checksum
How to use checksums
409e6df084a946ed96abe87ec2705cefeb3808aecccc4595d26cf20770e1dc13
BLAKE2b-256 checksum
How to use checksums
5c862c911f99d811bab9ecaaa0e0807bf4b96f5efb1f9e0b560f7a57796a6ca1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Release files / pandas_flavor-0.0.0-py3-none-any.whl

Download URL pandas_flavor-0.0.0-py3-none-any.whl
Size 8.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ed8b9a5cecc100b0267d3f37797790dad4fdae935c8a6a637814c8290582e59d
BLAKE2b-256 checksum
How to use checksums
b8a73ec7f387f022a91056abd26845dc92a4390e661531c2107a8969bd35c251
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.25

Security for pandas-flavor 0.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page