notionary 0.2.14__tar.gz → 0.2.15__tar.gz

notionary-0.2.15/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.3
+Name: notionary
+Version: 0.2.15
+Summary: Python library for programmatic Notion workspace management - databases, pages, and content with advanced Markdown support
+License: MIT
+Author: Mathis Arends
+Author-email: mathisarends27@gmail.com
+Requires-Python: >=3.9
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Python :: 3.13
+Requires-Dist: httpx (>=0.28.0)
+Requires-Dist: pydantic (>=2.11.4)
+Requires-Dist: python-dotenv (>=1.1.0)
+Project-URL: Homepage, https://github.com/mathisarends/notionary
+Description-Content-Type: text/markdown
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./static/notionary-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="./static/notionary-light.png">
+  <img alt="Notionary logo: dark mode shows a white logo, light mode shows a black logo." src="./static/browser-use.png"  width="full">
+</picture>
+
+<h1 align="center">Notion API simplified for Python developers 🐍</h1>
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+- **Object-Oriented Design**: Clean, intuitive classes for Pages, Databases, and Workspaces with full CRUD operations
+- **Rich Markdown to Notion**: Convert extended Markdown (callouts, toggles, columns) directly into beautiful Notion blocks
+- **Smart Discovery**: Find pages and databases by name with fuzzy matching - no more hunting for URLs
+- **Async-First Architecture**: Built for modern Python with full async/await support and high performance
+- **AI-Ready Integration**: Generate LLM system prompts and let AI agents create Notion content seamlessly
+
+---
+
+# Quick start
+```bash
+pip install notionary
+```
+
+- Set up your Notion integration (notion.so/profile/integrations)
+- Add your integration key in your `.env` file.
+
+```bash
+NOTION_SECRET=YOUR_INTEGRATION_KEY
+```
+
+### Creating and Managing Pages 🚀
+```python
+from notionary import NotionPage
+
+async def main():
+    # Simpy find an existing page by its title
+    page = await NotionPage.from_page_name("My Test Page")
+    
+    # Add rich content with custom Markdown
+    content = """
+    # 🚀 Generated with Notionary
+    
+    !> [💡] This page was created programmatically!
+    
+    ## Features
+    - **Rich** Markdown support
+    - Database integration
+    - AI-ready content generation
+    
+    +++ Click to see more details
+    | Notionary makes it easy to create beautiful Notion pages
+    | directly from Python code with intuitive Markdown syntax.
+    """
+    
+    await page.replace_content(content)
+    print(f"✅ Page updated: {page.url}")
+
+asyncio.run(main())
+```
+
+---
+
+### Working with Databases 🔥
+
+```python
+import asyncio
+from notionary import NotionDatabase
+
+async def main():
+  # Connect to database by name (fuzzy matching)
+  db = await NotionDatabase.from_database_name("Projects")
+
+  # Create a new page with properties
+  page = await db.create_blank_page()
+  await page.set_title("🆕 New Project Entry")
+  await page.set_property_value_by_name("Status", "In Progress")
+  await page.set_property_value_by_name("Priority", "High")
+  
+  # find pages created in the last 7 days
+  count = 0
+  async for page in db.iter_pages_with_filter(
+      db.create_filter().with_created_last_n_days(7)
+  ):
+      count += 1
+      print(f"{count:2d}. {page.emoji_icon or '📄'} {page.title}")
+
+asyncio.run(main())
+```
+
+## Custom Markdown Syntax
+
+Notionary extends standard Markdown with special syntax to support Notion-specific features:
+
+### Text Formatting
+
+- Standard: `**bold**`, `*italic*`, `~~strikethrough~~`, `` `code` ``
+- Links: `[text](url)`
+- Quotes: `> This is a quote`
+- Divider: `---`
+
+### Callouts
+
+```markdown
+!> [💡] This is a default callout with the light bulb emoji  
+!> [🔔] This is a notification with a bell emoji  
+!> [⚠️] Warning: This is an important note
+```
+
+### Toggles
+
+```markdown
++++ How to use Notionary
+| 1. Initialize with NotionPage  
+| 2. Update metadata with set_title(), set_emoji_icon(), etc.  
+| 3. Add content with replace_content() or append_markdown()
+```
+
+### Multi-Column Layout
+
+```markdown
+::: columns
+::: column
+
+## Left Column
+
+- Item 1
+- Item 2
+- Item 3
+  :::
+  ::: column
+
+## Right Column
+
+This text appears in the second column. Multi-column layouts are perfect for:
+
+- Comparing features
+- Creating side-by-side content
+- Improving readability of wide content
+  :::
+  :::
+```
+
+### Code Blocks
+
+```python
+def hello_world():
+    print("Hello from Notionary!")
+```
+
+### To-do Lists
+
+```markdown
+- [ ] Define project scope
+- [x] Create timeline
+- [ ] Assign resources
+```
+
+### Tables
+
+```markdown
+| Feature         | Status      | Priority |
+| --------------- | ----------- | -------- |
+| API Integration | Complete    | High     |
+| Documentation   | In Progress | Medium   |
+```
+
+### More Elements
+
+```markdown
+![Caption](https://example.com/image.jpg)  
+@[Caption](https://youtube.com/watch?v=...)  
+[bookmark](https://example.com "Title" "Description")
+```
+
+## Examples
+
+Explore the `examples/` directory for comprehensive guides:
+
+### 🚀 Core Examples
+- [**Page Management**](examples/page_example.py) - Create, update, and manage Notion pages
+- [**Page Operations**](examples/page.py) - Advanced page manipulation and content handling
+- [**Database Operations**](examples/database.py) - Connect to and manage Notion databases
+- [**Database Iteration**](examples/database_iteration.py) - Query and filter database entries
+- [**Workspace Discovery**](examples/workspace_discovery.py) - Explore and discover your Notion workspace
+
+### 📝 Markdown Examples
+- [**Basic Formatting**](examples/markdown/basic.py) - Text formatting, lists, and basic elements
+- [**Callouts**](examples/markdown/callout.py) - Create beautiful callout blocks with icons
+- [**Toggles**](examples/markdown/toggle.py) - Collapsible content sections
+- [**Multi-Column Layouts**](examples/markdown/columns.py) - Side-by-side content arrangement
+- [**Code Blocks**](examples/markdown/code.py) - Syntax-highlighted code examples
+- [**Tables**](examples/markdown/table.py) - Structured data presentation
+- [**Media Embeds**](examples/markdown/embed.py) - Images, videos, and rich media
+- [**Audio Content**](examples/markdown/audio.py) - Audio file integration
+
+Each example is self-contained and demonstrates specific features with practical use cases.
+
+## Contributing
+
+Contributions welcome — feel free to submit a pull request!
+

notionary-0.2.15/README.md

@@ -0,0 +1,201 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./static/notionary-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="./static/notionary-light.png">
+  <img alt="Notionary logo: dark mode shows a white logo, light mode shows a black logo." src="./static/browser-use.png"  width="full">
+</picture>
+
+<h1 align="center">Notion API simplified for Python developers 🐍</h1>
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+- **Object-Oriented Design**: Clean, intuitive classes for Pages, Databases, and Workspaces with full CRUD operations
+- **Rich Markdown to Notion**: Convert extended Markdown (callouts, toggles, columns) directly into beautiful Notion blocks
+- **Smart Discovery**: Find pages and databases by name with fuzzy matching - no more hunting for URLs
+- **Async-First Architecture**: Built for modern Python with full async/await support and high performance
+- **AI-Ready Integration**: Generate LLM system prompts and let AI agents create Notion content seamlessly
+
+---
+
+# Quick start
+```bash
+pip install notionary
+```
+
+- Set up your Notion integration (notion.so/profile/integrations)
+- Add your integration key in your `.env` file.
+
+```bash
+NOTION_SECRET=YOUR_INTEGRATION_KEY
+```
+
+### Creating and Managing Pages 🚀
+```python
+from notionary import NotionPage
+
+async def main():
+    # Simpy find an existing page by its title
+    page = await NotionPage.from_page_name("My Test Page")
+    
+    # Add rich content with custom Markdown
+    content = """
+    # 🚀 Generated with Notionary
+    
+    !> [💡] This page was created programmatically!
+    
+    ## Features
+    - **Rich** Markdown support
+    - Database integration
+    - AI-ready content generation
+    
+    +++ Click to see more details
+    | Notionary makes it easy to create beautiful Notion pages
+    | directly from Python code with intuitive Markdown syntax.
+    """
+    
+    await page.replace_content(content)
+    print(f"✅ Page updated: {page.url}")
+
+asyncio.run(main())
+```
+
+---
+
+### Working with Databases 🔥
+
+```python
+import asyncio
+from notionary import NotionDatabase
+
+async def main():
+  # Connect to database by name (fuzzy matching)
+  db = await NotionDatabase.from_database_name("Projects")
+
+  # Create a new page with properties
+  page = await db.create_blank_page()
+  await page.set_title("🆕 New Project Entry")
+  await page.set_property_value_by_name("Status", "In Progress")
+  await page.set_property_value_by_name("Priority", "High")
+  
+  # find pages created in the last 7 days
+  count = 0
+  async for page in db.iter_pages_with_filter(
+      db.create_filter().with_created_last_n_days(7)
+  ):
+      count += 1
+      print(f"{count:2d}. {page.emoji_icon or '📄'} {page.title}")
+
+asyncio.run(main())
+```
+
+## Custom Markdown Syntax
+
+Notionary extends standard Markdown with special syntax to support Notion-specific features:
+
+### Text Formatting
+
+- Standard: `**bold**`, `*italic*`, `~~strikethrough~~`, `` `code` ``
+- Links: `[text](url)`
+- Quotes: `> This is a quote`
+- Divider: `---`
+
+### Callouts
+
+```markdown
+!> [💡] This is a default callout with the light bulb emoji  
+!> [🔔] This is a notification with a bell emoji  
+!> [⚠️] Warning: This is an important note
+```
+
+### Toggles
+
+```markdown
++++ How to use Notionary
+| 1. Initialize with NotionPage  
+| 2. Update metadata with set_title(), set_emoji_icon(), etc.  
+| 3. Add content with replace_content() or append_markdown()
+```
+
+### Multi-Column Layout
+
+```markdown
+::: columns
+::: column
+
+## Left Column
+
+- Item 1
+- Item 2
+- Item 3
+  :::
+  ::: column
+
+## Right Column
+
+This text appears in the second column. Multi-column layouts are perfect for:
+
+- Comparing features
+- Creating side-by-side content
+- Improving readability of wide content
+  :::
+  :::
+```
+
+### Code Blocks
+
+```python
+def hello_world():
+    print("Hello from Notionary!")
+```
+
+### To-do Lists
+
+```markdown
+- [ ] Define project scope
+- [x] Create timeline
+- [ ] Assign resources
+```
+
+### Tables
+
+```markdown
+| Feature         | Status      | Priority |
+| --------------- | ----------- | -------- |
+| API Integration | Complete    | High     |
+| Documentation   | In Progress | Medium   |
+```
+
+### More Elements
+
+```markdown
+![Caption](https://example.com/image.jpg)  
+@[Caption](https://youtube.com/watch?v=...)  
+[bookmark](https://example.com "Title" "Description")
+```
+
+## Examples
+
+Explore the `examples/` directory for comprehensive guides:
+
+### 🚀 Core Examples
+- [**Page Management**](examples/page_example.py) - Create, update, and manage Notion pages
+- [**Page Operations**](examples/page.py) - Advanced page manipulation and content handling
+- [**Database Operations**](examples/database.py) - Connect to and manage Notion databases
+- [**Database Iteration**](examples/database_iteration.py) - Query and filter database entries
+- [**Workspace Discovery**](examples/workspace_discovery.py) - Explore and discover your Notion workspace
+
+### 📝 Markdown Examples
+- [**Basic Formatting**](examples/markdown/basic.py) - Text formatting, lists, and basic elements
+- [**Callouts**](examples/markdown/callout.py) - Create beautiful callout blocks with icons
+- [**Toggles**](examples/markdown/toggle.py) - Collapsible content sections
+- [**Multi-Column Layouts**](examples/markdown/columns.py) - Side-by-side content arrangement
+- [**Code Blocks**](examples/markdown/code.py) - Syntax-highlighted code examples
+- [**Tables**](examples/markdown/table.py) - Structured data presentation
+- [**Media Embeds**](examples/markdown/embed.py) - Images, videos, and rich media
+- [**Audio Content**](examples/markdown/audio.py) - Audio file integration
+
+Each example is self-contained and demonstrates specific features with practical use cases.
+
+## Contributing
+
+Contributions welcome — feel free to submit a pull request!

{notionary-0.2.14 → notionary-0.2.15}/notionary/database/notion_database.py

@@ -26,7 +26,7 @@ class NotionDatabase(LoggingMixin):
     @factory_only("from_database_id", "from_database_name")
     def __init__(
         self,
-        database_id: str,
+        id: str,
         title: str,
         url: str,
         emoji_icon: Optional[str] = None,
@@ -36,7 +36,7 @@ class NotionDatabase(LoggingMixin):
         """
         Initialize the minimal database manager.
         """
-        self._database_id = database_id
+        self._id = id
         self._title = title
         self._url = url
         self._emoji_icon = emoji_icon
@@ -46,13 +46,13 @@ class NotionDatabase(LoggingMixin):
 
     @classmethod
     async def from_database_id(
-        cls, database_id: str, token: Optional[str] = None
+        cls, id: str, token: Optional[str] = None
     ) -> NotionDatabase:
         """
         Create a NotionDatabase from a database ID using NotionDatabaseProvider.
         """
         provider = cls.get_database_provider()
-        return await provider.get_database_by_id(database_id, token)
+        return await provider.get_database_by_id(id, token)
 
     @classmethod
     async def from_database_name(
@@ -68,9 +68,9 @@ class NotionDatabase(LoggingMixin):
         return await provider.get_database_by_name(database_name, token, min_similarity)
 
     @property
-    def database_id(self) -> str:
+    def id(self) -> str:
         """Get the database ID (readonly)."""
-        return self._database_id
+        return self._id
 
     @property
     def title(self) -> str:
@@ -109,7 +109,7 @@ class NotionDatabase(LoggingMixin):
         """
         try:
             create_page_response: NotionPageResponse = await self.client.create_page(
-                parent_database_id=self.database_id
+                parent_database_id=self.id
             )
 
             return await NotionPage.from_page_id(page_id=create_page_response.id)
@@ -124,13 +124,13 @@ class NotionDatabase(LoggingMixin):
         """
         try:
             result = await self.client.update_database_title(
-                database_id=self.database_id, title=new_title
+                database_id=self.id, title=new_title
             )
 
             self._title = result.title[0].plain_text
             self.logger.info(f"Successfully updated database title to: {new_title}")
             self.database_provider.invalidate_database_cache(
-                database_id=self.database_id
+                database_id=self.id
             )
             return True
 
@@ -144,13 +144,13 @@ class NotionDatabase(LoggingMixin):
         """
         try:
             result = await self.client.update_database_emoji(
-                database_id=self.database_id, emoji=new_emoji
+                database_id=self.id, emoji=new_emoji
             )
 
             self._emoji_icon = result.icon.emoji if result.icon else None
             self.logger.info(f"Successfully updated database emoji to: {new_emoji}")
             self.database_provider.invalidate_database_cache(
-                database_id=self.database_id
+                database_id=self.id
             )
             return True
 
@@ -164,12 +164,12 @@ class NotionDatabase(LoggingMixin):
         """
         try:
             result = await self.client.update_database_cover_image(
-                database_id=self.database_id, image_url=image_url
+                database_id=self.id, image_url=image_url
             )
 
             if result.cover and result.cover.external:
                 self.database_provider.invalidate_database_cache(
-                    database_id=self.database_id
+                    database_id=self.id
                 )
                 return result.cover.external.url
             return None
@@ -193,12 +193,12 @@ class NotionDatabase(LoggingMixin):
         """
         try:
             result = await self.client.update_database_external_icon(
-                database_id=self.database_id, icon_url=external_icon_url
+                database_id=self.id, icon_url=external_icon_url
             )
 
             if result.icon and result.icon.external:
                 self.database_provider.invalidate_database_cache(
-                    database_id=self.database_id
+                    database_id=self.id
                 )
                 return result.icon.external.url
             return None
@@ -244,7 +244,7 @@ class NotionDatabase(LoggingMixin):
         """
         search_results: NotionQueryDatabaseResponse = (
             await self.client.query_database_by_title(
-                database_id=self.database_id, page_title=page_title
+                database_id=self.id, page_title=page_title
             )
         )
 
@@ -296,7 +296,7 @@ class NotionDatabase(LoggingMixin):
         except Exception as e:
             self.logger.error(
                 "Error fetching last_edited_time for database %s: %s",
-                self.database_id,
+                self.id,
                 str(e),
             )
             return None
@@ -345,7 +345,7 @@ class NotionDatabase(LoggingMixin):
                 current_body["start_cursor"] = start_cursor
 
             result = await self.client.query_database(
-                database_id=self.database_id, query_data=current_body
+                database_id=self.id, query_data=current_body
             )
 
             if not result or not result.results:
@@ -368,7 +368,7 @@ class NotionDatabase(LoggingMixin):
         emoji_icon = cls._extract_emoji_icon(db_response)
 
         instance = cls(
-            database_id=db_response.id,
+            id=db_response.id,
             title=title,
             url=db_response.url,
             emoji_icon=emoji_icon,

{notionary-0.2.14 → notionary-0.2.15}/notionary/database/notion_database_provider.py

@@ -55,10 +55,10 @@ class NotionDatabaseProvider(LoggingMixin, metaclass=SingletonMetaClass):
             database_name, token, min_similarity
         )
 
-        id_cache_key = self._create_id_cache_key(database.database_id)
+        id_cache_key = self._create_id_cache_key(database.id)
         if not force_refresh and id_cache_key in self._database_cache:
             self.logger.debug(
-                f"Found existing cached database by ID: {database.database_id}"
+                f"Found existing cached database by ID: {database.id}"
             )
             existing_database = self._database_cache[id_cache_key]
 
@@ -67,7 +67,7 @@ class NotionDatabaseProvider(LoggingMixin, metaclass=SingletonMetaClass):
 
         self._cache_database(database, token, database_name)
         self.logger.debug(
-            f"Cached database: {database.title} (ID: {database.database_id})"
+            f"Cached database: {database.title} (ID: {database.id})"
         )
 
         return database
@@ -96,7 +96,7 @@ class NotionDatabaseProvider(LoggingMixin, metaclass=SingletonMetaClass):
         name_keys_to_remove = [
             cache_key
             for cache_key, cached_db in self._database_cache.items()
-            if (cache_key.startswith("name:") and cached_db.database_id == database_id)
+            if (cache_key.startswith("name:") and cached_db.id == database_id)
         ]
 
         for name_key in name_keys_to_remove:
@@ -173,7 +173,7 @@ class NotionDatabaseProvider(LoggingMixin, metaclass=SingletonMetaClass):
     ) -> None:
         """Cache a database by both ID and name (if provided)."""
         # Always cache by ID
-        id_cache_key = self._create_id_cache_key(database.database_id)
+        id_cache_key = self._create_id_cache_key(database.id)
         self._database_cache[id_cache_key] = database
 
         if original_name:
@@ -199,7 +199,7 @@ class NotionDatabaseProvider(LoggingMixin, metaclass=SingletonMetaClass):
         emoji_icon = self._extract_emoji_icon(db_response)
 
         instance = NotionDatabase(
-            database_id=db_response.id,
+            id=db_response.id,
             title=title,
             url=db_response.url,
             emoji_icon=emoji_icon,

{notionary-0.2.14 → notionary-0.2.15}/notionary/page/notion_page.py

@@ -501,7 +501,7 @@ class NotionPage(LoggingMixin):
 
         parent_database = (
             await NotionDatabase.from_database_id(
-                database_id=parent_database_id, token=token
+                id=parent_database_id, token=token
             )
             if parent_database_id
             else None

notionary-0.2.15/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "notionary"
+version = "0.2.15"
+description = "Python library for programmatic Notion workspace management - databases, pages, and content with advanced Markdown support"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+    { name = "Mathis Arends", email = "mathisarends27@gmail.com" }
+]
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.28.0",
+    "python-dotenv>=1.1.0",
+    "pydantic>=2.11.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/mathisarends/notionary"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.group.dev.dependencies]
+mkdocs = "^1.6.1"
+mkdocs-material = "^9.6.15"
+