Metadata-Version: 2.4
Name: notion2pandas
Version: 3.0.1
Summary: Notion Client extension to import notion Database into pandas Dataframe
Project-URL: Homepage, https://jaeger87.gitlab.io/notion2pandas/
Author-email: Andrea Rosati <rosati.1595834@gmail.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.10
Requires-Dist: notion-client==3.1.0
Requires-Dist: numpy>=2.2.6
Requires-Dist: pandas<4.0,>=2.3.3
Description-Content-Type: text/markdown

# Notion2Pandas

<p align="center">
<img src="https://gitlab.com/Jaeger87/notion2pandas/-/raw/main/readme_assets/logo.png?ref_type=heads"  class="center">
</p> <p align="center">

<div align="center">
  <p>
    <a href="https://pypi.org/project/notion2pandas/"><img src="https://gitlab.com/Jaeger87/notion2pandas/-/badges/release.svg" alt="Latest Release"></a>
    <a href="https://pepy.tech/projects/notion2pandas"><img src="https://static.pepy.tech/personalized-badge/notion2pandas?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=BRIGHTGREEN&left_text=downloads" alt="PyPI Downloads"></a>
  <a href="https://codecov.io/gl/Jaeger87/notion2pandas" >
<img src="https://codecov.io/gl/Jaeger87/notion2pandas/branch/main/graph/badge.svg?token=R4XZ2IWDDU"/>
</a>
</p>
</div>

Notion2Pandas is a Python 3 package that extends the capabilities of the
excellent [notion-sdk-py](https://ramnes.github.io/notion-sdk-py/)
by [Ramnes](https://github.com/ramnes). It enables the seamless import of a Notion database into a
pandas dataframe and vice versa, requiring just a single line of code.

## Installation

```bash
pip install notion2pandas
```

## Quick Start

### Synchronous Client

```python
from notion2pandas import Notion2PandasClient
import os

# Create client
n2p = Notion2PandasClient(auth=os.environ["NOTION_TOKEN"])

# Import database to NotionDataFrame
ndf = n2p.get_dataframe(os.environ["DATABASE_ID"])

# Work with your data
ndf.loc[ndf['Status'] == 'Todo', 'Status'] = 'In Progress'

# Save changes back to Notion
n2p.sync_to_notion(ndf)
```

### Asynchronous Client

```python
from notion2pandas import AsyncNotion2PandasClient
import os

# Create async client
async_n2p = AsyncNotion2PandasClient(auth=os.environ["NOTION_TOKEN"])

# Import database to NotionDataFrame (concurrent processing)
ndf = await async_n2p.get_dataframe(os.environ["DATABASE_ID"])

# Work with your data
ndf.loc[ndf['Status'] == 'Todo', 'Status'] = 'In Progress'

# Save changes back to Notion (concurrent updates)
await async_n2p.sync_to_notion(ndf)
```

For more complete, real-world examples, see the [examples](./examples) folder.

---

<p align="center">
<img src="https://gitlab.com/Jaeger87/notion2pandas/-/raw/main/readme_assets/n2p2.gif?ref_type=heads"  class="center">
</p>

---

## 📖 Documentation

This README covers the basics. For everything else — filters and sorts, data sources,
templates, callbacks, custom read/write functions, logging, and more — see the
**[full documentation](https://jaeger87.gitlab.io/notion2pandas/)**.

---

## Migrating from v1.x

Version 2.0 introduces several improvements and breaking changes. If you're upgrading from v1.x:

| v1.x                                   | v2.0                      |
|-----------------------------------------|---------------------------|
| `from_notion_DB_to_dataframe()`        | `get_dataframe()`         |
| `update_notion_DB_from_dataframe()`    | `sync_to_notion()`        |
| `from_notion_database_to_dataframes()` | `get_dataframes()`        |
| `delete_rows_and_pages()`              | `delete_pages()`          |
| Returns `pd.DataFrame`                 | Returns `NotionDataFrame` |
| `PageID` column                        | `page_id` index           |
| Manual row appending                   | `ndf.add_page()`          |

📖 **Complete migration guide with examples**: [MIGRATION-GUIDE.md](docs/migration/migration-guide.md)  
📚 **v1.x documentation**: [README-v1.md](docs/migration/v1-readme.md)

**All v1.x methods still work with deprecation warnings** - you have time to migrate!

## Roadmap

Planned features for upcoming releases:

- **DataFrame with property keys as column names**: an option to get the DataFrame back with Notion's internal property keys as column names instead of their display names. More cumbersome to read, but immune to column renames in Notion, so your code doesn't break when someone renames a property on the Notion side.

## Examples

Real-world scripts covering common use cases are available in the [examples](./examples) folder.

## Changelog

View the complete version history on
the [changelog page](https://gitlab.com/Jaeger87/notion2pandas/-/blob/main/CHANGELOG.md?ref_type=heads).

## Support

Notion2Pandas is an open-source project. Contributions are welcome!

- **Report Issues**: Found a
  bug? [Open an issue](https://gitlab.com/Jaeger87/notion2pandas/-/issues)
- **Propose Changes**: Have an
  improvement? [Submit a merge request](https://gitlab.com/Jaeger87/notion2pandas/-/merge_requests)
- **Fork the Project**: Disagree with the direction? You're free to fork with our blessing!

All proposals will be evaluated and responded to.

## License

This project is open-source and available under the MIT License.