Metadata-Version: 2.4
Name: notion2pandas
Version: 2.5.0
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:

- Managing the 2700 API calls / 15 minutes rate limit

## 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.