notionary 0.3.1__py3-none-any.whl → 0.4.1__py3-none-any.whl

notionary/data_source/query/schema.py

@@ -3,7 +3,13 @@ from __future__ import annotations
 from enum import StrEnum
 from typing import Self
 
-from pydantic import BaseModel, ValidationInfo, field_validator, model_serializer, model_validator
+from pydantic import (
+    BaseModel,
+    ValidationInfo,
+    field_validator,
+    model_serializer,
+    model_validator,
+)
 
 from notionary.shared.properties.type import PropertyType
 from notionary.shared.typings import JsonDict
@@ -93,7 +99,9 @@ class TimeUnit(StrEnum):
     YEARS = "years"
 
 
-type Operator = StringOperator | NumberOperator | BooleanOperator | DateOperator | ArrayOperator
+type Operator = (
+    StringOperator | NumberOperator | BooleanOperator | DateOperator | ArrayOperator
+)
 type FilterValue = str | int | float | bool | list[str | int | float]
 
 
@@ -156,7 +164,10 @@ class FilterCondition(BaseModel):
             self._ensure_value_is_number()
         elif self.field_type == FieldType.BOOLEAN:
             self._ensure_value_is_boolean()
-        elif self.field_type in (FieldType.DATE, FieldType.DATETIME) or self.field_type in (
+        elif self.field_type in (
+            FieldType.DATE,
+            FieldType.DATETIME,
+        ) or self.field_type in (
             FieldType.ARRAY,
             FieldType.RELATION,
             FieldType.PEOPLE,
@@ -196,7 +207,9 @@ class FilterCondition(BaseModel):
         operator_value = value if isinstance(value, str) else value.value
 
         if not cls._is_operator_valid_for_field_type(operator_value, field_type):
-            raise ValueError(f"Operator '{operator_value}' is not valid for field type '{field_type}'")
+            raise ValueError(
+                f"Operator '{operator_value}' is not valid for field type '{field_type}'"
+            )
 
         return value
 
@@ -234,7 +247,10 @@ class PropertyFilter(BaseModel):
         if self.value is None:
             return self
 
-        if self.property_type in (PropertyType.PEOPLE, PropertyType.RELATION) and not isinstance(self.value, str):
+        if self.property_type in (
+            PropertyType.PEOPLE,
+            PropertyType.RELATION,
+        ) and not isinstance(self.value, str):
             raise ValueError(
                 f"Value for property type '{self.property_type.value}' must be a string, "
                 f"got {type(self.value).__name__}"
@@ -254,7 +270,9 @@ class PropertyFilter(BaseModel):
 
         return {
             "property": self.property,
-            property_type_str: {operator_str: filter_value if filter_value is not None else True},
+            property_type_str: {
+                operator_str: filter_value if filter_value is not None else True
+            },
         }
 
 

notionary/data_source/query/validator.py

@@ -39,7 +39,9 @@ class QueryValidator:
         self, property_name: str, property_obj: DataSourceProperty, operator: Operator
     ) -> None:
         if not self._is_operator_valid_for_property_type(property_obj.type, operator):
-            valid_operators = self._get_valid_operators_for_property_type(property_obj.type)
+            valid_operators = self._get_valid_operators_for_property_type(
+                property_obj.type
+            )
             raise InvalidOperatorForPropertyType(
                 property_name=property_name,
                 property_type=property_obj.type,
@@ -47,23 +49,33 @@ class QueryValidator:
                 valid_operators=valid_operators,
             )
 
-    def _is_operator_valid_for_property_type(self, property_type: PropertyType, operator: Operator) -> bool:
+    def _is_operator_valid_for_property_type(
+        self, property_type: PropertyType, operator: Operator
+    ) -> bool:
         allowed_operator_types = self._PROPERTY_TYPE_OPERATORS.get(property_type, [])
-        valid_operator_values = self._get_operator_values_from_types(allowed_operator_types)
+        valid_operator_values = self._get_operator_values_from_types(
+            allowed_operator_types
+        )
         return operator.value in valid_operator_values
 
-    def _get_operator_values_from_types(self, operator_types: list[type[Operator]]) -> set[str]:
+    def _get_operator_values_from_types(
+        self, operator_types: list[type[Operator]]
+    ) -> set[str]:
         values: set[str] = set()
         for operator_type in operator_types:
             for operator in operator_type:
                 values.add(operator.value)
         return values
 
-    def _get_valid_operators_for_property_type(self, property_type: PropertyType) -> list[Operator]:
+    def _get_valid_operators_for_property_type(
+        self, property_type: PropertyType
+    ) -> list[Operator]:
         allowed_operator_types = self._PROPERTY_TYPE_OPERATORS.get(property_type, [])
         return self._collect_all_operators_from_types(allowed_operator_types)
 
-    def _collect_all_operators_from_types(self, operator_types: list[type[Operator]]) -> list[Operator]:
+    def _collect_all_operators_from_types(
+        self, operator_types: list[type[Operator]]
+    ) -> list[Operator]:
         operators: list[Operator] = []
         for operator_type in operator_types:
             operators.extend(self._get_all_enum_values(operator_type))

notionary/data_source/schema/registry.py

@@ -13,36 +13,52 @@ class DatabasePropertyTypeDescriptorRegistry:
     def __init__(self):
         self._DESCRIPTORS = {
             PropertyType.TITLE: PropertyTypeDescriptor(
-                display_name="Title", description="Required field for the main heading of the entry"
+                display_name="Title",
+                description="Required field for the main heading of the entry",
             ),
             PropertyType.RICH_TEXT: PropertyTypeDescriptor(
-                display_name="Rich Text", description="Free-form text field for additional information"
+                display_name="Rich Text",
+                description="Free-form text field for additional information",
+            ),
+            PropertyType.NUMBER: PropertyTypeDescriptor(
+                display_name="Number", description="Numeric value field"
             ),
-            PropertyType.NUMBER: PropertyTypeDescriptor(display_name="Number", description="Numeric value field"),
             PropertyType.CHECKBOX: PropertyTypeDescriptor(
                 display_name="Checkbox", description="Boolean value (true/false)"
             ),
-            PropertyType.DATE: PropertyTypeDescriptor(display_name="Date", description="Date or date range field"),
-            PropertyType.URL: PropertyTypeDescriptor(display_name="URL", description="Web address field"),
-            PropertyType.EMAIL: PropertyTypeDescriptor(display_name="Email", description="Email address field"),
+            PropertyType.DATE: PropertyTypeDescriptor(
+                display_name="Date", description="Date or date range field"
+            ),
+            PropertyType.URL: PropertyTypeDescriptor(
+                display_name="URL", description="Web address field"
+            ),
+            PropertyType.EMAIL: PropertyTypeDescriptor(
+                display_name="Email", description="Email address field"
+            ),
             PropertyType.PHONE_NUMBER: PropertyTypeDescriptor(
                 display_name="Phone Number", description="Phone number field"
             ),
             PropertyType.FILES: PropertyTypeDescriptor(
                 display_name="Files & Media", description="Upload or link to files"
             ),
-            PropertyType.PEOPLE: PropertyTypeDescriptor(display_name="People", description="Reference to Notion users"),
+            PropertyType.PEOPLE: PropertyTypeDescriptor(
+                display_name="People", description="Reference to Notion users"
+            ),
             PropertyType.SELECT: PropertyTypeDescriptor(
-                display_name="Single Select", description="Choose one option from available choices"
+                display_name="Single Select",
+                description="Choose one option from available choices",
             ),
             PropertyType.MULTI_SELECT: PropertyTypeDescriptor(
-                display_name="Multi Select", description="Choose multiple options from available choices"
+                display_name="Multi Select",
+                description="Choose multiple options from available choices",
             ),
             PropertyType.STATUS: PropertyTypeDescriptor(
-                display_name="Status", description="Track status with predefined options"
+                display_name="Status",
+                description="Track status with predefined options",
             ),
             PropertyType.RELATION: PropertyTypeDescriptor(
-                display_name="Relation", description="Link to entries in another database"
+                display_name="Relation",
+                description="Link to entries in another database",
             ),
             PropertyType.CREATED_TIME: PropertyTypeDescriptor(
                 display_name="Created Time",
@@ -97,7 +113,10 @@ class DatabasePropertyTypeDescriptorRegistry:
     def get_descriptor(self, property_type: PropertyType) -> PropertyTypeDescriptor:
         return self._DESCRIPTORS.get(
             property_type,
-            PropertyTypeDescriptor(display_name=self._format_unknown_type_name(property_type), description=""),
+            PropertyTypeDescriptor(
+                display_name=self._format_unknown_type_name(property_type),
+                description="",
+            ),
         )
 
     def _format_unknown_type_name(self, property_type: PropertyType) -> str:

notionary/data_source/schema/service.py

@@ -8,7 +8,10 @@ from notionary.data_source.properties.schemas import (
     DataSourceSelectProperty,
     DataSourceStatusProperty,
 )
-from notionary.data_source.schema.registry import DatabasePropertyTypeDescriptorRegistry, PropertyTypeDescriptor
+from notionary.data_source.schema.registry import (
+    DatabasePropertyTypeDescriptorRegistry,
+    PropertyTypeDescriptor,
+)
 from notionary.shared.properties.type import PropertyType
 
 
@@ -17,12 +20,16 @@ class PropertyFormatter:
 
     def __init__(
         self,
-        relation_options_fetcher: Callable[[DataSourceRelationProperty], Awaitable[list[str]]],
+        relation_options_fetcher: Callable[
+            [DataSourceRelationProperty], Awaitable[list[str]]
+        ],
         type_descriptor_registry: DatabasePropertyTypeDescriptorRegistry | None = None,
         data_source_resolver: DataSourceNameIdResolver | None = None,
     ) -> None:
         self._relation_options_fetcher = relation_options_fetcher
-        self._type_descriptor_registry = type_descriptor_registry or DatabasePropertyTypeDescriptorRegistry()
+        self._type_descriptor_registry = (
+            type_descriptor_registry or DatabasePropertyTypeDescriptorRegistry()
+        )
         self._data_source_resolver = data_source_resolver or DataSourceNameIdResolver()
 
     async def format_property(self, prop: DataSourceProperty) -> list[str]:
@@ -32,22 +39,35 @@ class PropertyFormatter:
             return [*specific_details, *self._format_custom_description(prop)]
 
         descriptor = self._type_descriptor_registry.get_descriptor(prop.type)
-        return [*self._format_property_description(descriptor), *self._format_custom_description(prop)]
-
-    def _format_property_description(self, descriptor: PropertyTypeDescriptor) -> list[str]:
+        return [
+            *self._format_property_description(descriptor),
+            *self._format_custom_description(prop),
+        ]
+
+    def _format_property_description(
+        self, descriptor: PropertyTypeDescriptor
+    ) -> list[str]:
         if not descriptor.description:
             return []
         return [f"{self.INDENTATION}{descriptor.description}"]
 
-    async def _format_property_specific_details(self, prop: DataSourceProperty) -> list[str]:
+    async def _format_property_specific_details(
+        self, prop: DataSourceProperty
+    ) -> list[str]:
         if isinstance(prop, DataSourceSelectProperty):
-            return self._format_available_options("Choose one option from", prop.option_names)
+            return self._format_available_options(
+                "Choose one option from", prop.option_names
+            )
 
         if isinstance(prop, DataSourceMultiSelectProperty):
-            return self._format_available_options("Choose multiple options from", prop.option_names)
+            return self._format_available_options(
+                "Choose multiple options from", prop.option_names
+            )
 
         if isinstance(prop, DataSourceStatusProperty):
-            return self._format_available_options("Available statuses", prop.option_names)
+            return self._format_available_options(
+                "Available statuses", prop.option_names
+            )
 
         if isinstance(prop, DataSourceRelationProperty):
             return await self._format_relation_details(prop)
@@ -63,11 +83,15 @@ class PropertyFormatter:
         options_text = ", ".join(options)
         return [f"{self.INDENTATION}{label}: {options_text}"]
 
-    async def _format_relation_details(self, prop: DataSourceRelationProperty) -> list[str]:
+    async def _format_relation_details(
+        self, prop: DataSourceRelationProperty
+    ) -> list[str]:
         if not prop.related_data_source_id:
             return []
 
-        data_source_name = await self._data_source_resolver.resolve_id_to_name(prop.related_data_source_id)
+        data_source_name = await self._data_source_resolver.resolve_id_to_name(
+            prop.related_data_source_id
+        )
         data_source_display = data_source_name or prop.related_data_source_id
         lines = [f"{self.INDENTATION}Links to datasource: {data_source_display}"]
 
@@ -78,7 +102,9 @@ class PropertyFormatter:
 
         return lines
 
-    async def _fetch_relation_entries(self, prop: DataSourceRelationProperty) -> list[str] | None:
+    async def _fetch_relation_entries(
+        self, prop: DataSourceRelationProperty
+    ) -> list[str] | None:
         try:
             return await self._relation_options_fetcher(prop)
         except Exception:
@@ -88,14 +114,22 @@ class PropertyFormatter:
 class DataSourcePropertySchemaFormatter:
     def __init__(
         self,
-        relation_options_fetcher: Callable[[DataSourceRelationProperty], Awaitable[list[str]]] | None = None,
+        relation_options_fetcher: Callable[
+            [DataSourceRelationProperty], Awaitable[list[str]]
+        ]
+        | None = None,
         data_source_resolver: DataSourceNameIdResolver | None = None,
     ) -> None:
         self._property_formatter = PropertyFormatter(
             relation_options_fetcher, data_source_resolver=data_source_resolver
         )
 
-    async def format(self, title: str, description: str | None, properties: dict[str, DataSourceProperty]) -> str:
+    async def format(
+        self,
+        title: str,
+        description: str | None,
+        properties: dict[str, DataSourceProperty],
+    ) -> str:
         lines = self._format_header(title, description)
         lines.append("Properties:")
         lines.append("")
@@ -112,7 +146,9 @@ class DataSourcePropertySchemaFormatter:
 
         return lines
 
-    async def _format_properties(self, properties: dict[str, DataSourceProperty]) -> list[str]:
+    async def _format_properties(
+        self, properties: dict[str, DataSourceProperty]
+    ) -> list[str]:
         lines = []
         sorted_properties = self._sort_with_title_first(properties)
 
@@ -121,14 +157,24 @@ class DataSourcePropertySchemaFormatter:
 
         return lines
 
-    def _sort_with_title_first(self, properties: dict[str, DataSourceProperty]) -> list[tuple[str, DataSourceProperty]]:
-        return sorted(properties.items(), key=lambda item: (self._is_not_title_property(item[1]), item[0]))
+    def _sort_with_title_first(
+        self, properties: dict[str, DataSourceProperty]
+    ) -> list[tuple[str, DataSourceProperty]]:
+        return sorted(
+            properties.items(),
+            key=lambda item: (self._is_not_title_property(item[1]), item[0]),
+        )
 
     def _is_not_title_property(self, prop: DataSourceProperty) -> bool:
         return prop.type != PropertyType.TITLE
 
-    async def _format_single_property(self, index: int, name: str, prop: DataSourceProperty) -> list[str]:
-        lines = [f"{index}. - Property Name: '{name}'", f"   - Property Type: '{prop.type.value}'"]
+    async def _format_single_property(
+        self, index: int, name: str, prop: DataSourceProperty
+    ) -> list[str]:
+        lines = [
+            f"{index}. - Property Name: '{name}'",
+            f"   - Property Type: '{prop.type.value}'",
+        ]
 
         lines.extend(await self._property_formatter.format_property(prop))
         lines.append("")

notionary/data_source/schemas.py

@@ -1,7 +1,7 @@
 from pydantic import BaseModel
 
 from notionary.blocks.rich_text.models import RichText
-from notionary.data_source.properties.schemas import DiscriminatedDataSourceProperty
+from notionary.data_source.properties.schemas import AnyDataSourceProperty
 from notionary.page.schemas import NotionPageDto
 from notionary.shared.entity.schemas import EntityResponseDto, NotionEntityUpdateDto
 from notionary.shared.models.parent import Parent
@@ -24,4 +24,4 @@ class DataSourceDto(EntityResponseDto):
     title: list[RichText]
     description: list[RichText]
     archived: bool
-    properties: dict[str, DiscriminatedDataSourceProperty]
+    properties: dict[str, AnyDataSourceProperty]

notionary/data_source/service.py

@@ -4,9 +4,13 @@ import asyncio
 from collections.abc import AsyncIterator, Callable
 from typing import TYPE_CHECKING, Self
 
-from notionary.blocks.rich_text.rich_text_markdown_converter import RichTextToMarkdownConverter
+from notionary.blocks.rich_text.rich_text_markdown_converter import (
+    RichTextToMarkdownConverter,
+)
 from notionary.data_source.http.client import DataSourceClient
-from notionary.data_source.http.data_source_instance_client import DataSourceInstanceClient
+from notionary.data_source.http.data_source_instance_client import (
+    DataSourceInstanceClient,
+)
 from notionary.data_source.properties.schemas import (
     DataSourceMultiSelectProperty,
     DataSourceProperty,
@@ -16,18 +20,29 @@ from notionary.data_source.properties.schemas import (
     DataSourceSelectProperty,
     DataSourceStatusProperty,
 )
-from notionary.data_source.query import DataSourceQueryBuilder, DataSourceQueryParams, QueryResolver
+from notionary.data_source.query import (
+    DataSourceQueryBuilder,
+    DataSourceQueryParams,
+    QueryResolver,
+)
 from notionary.data_source.schema.service import DataSourcePropertySchemaFormatter
 from notionary.data_source.schemas import DataSourceDto
-from notionary.exceptions.data_source.properties import DataSourcePropertyNotFound, DataSourcePropertyTypeError
-from notionary.page.properties.models import PageTitleProperty
+from notionary.exceptions.data_source.properties import (
+    DataSourcePropertyNotFound,
+    DataSourcePropertyTypeError,
+)
+from notionary.file_upload.service import NotionFileUpload
+from notionary.page.properties.schemas import PageTitleProperty
 from notionary.page.schemas import NotionPageDto
 from notionary.shared.entity.dto_parsers import (
     extract_description,
     extract_title,
 )
-from notionary.shared.entity.entity_metadata_update_client import EntityMetadataUpdateClient
+from notionary.shared.entity.entity_metadata_update_client import (
+    EntityMetadataUpdateClient,
+)
 from notionary.shared.entity.service import Entity
+from notionary.user.service import UserService
 from notionary.workspace.query.service import WorkspaceQueryService
 
 if TYPE_CHECKING:
@@ -43,8 +58,12 @@ class NotionDataSource(Entity):
         properties: dict[str, DataSourceProperty],
         data_source_instance_client: DataSourceInstanceClient,
         query_resolver: QueryResolver | None = None,
+        user_service: UserService | None = None,
+        file_upload_service: NotionFileUpload | None = None,
     ) -> None:
-        super().__init__(dto=dto)
+        super().__init__(
+            dto=dto, user_service=user_service, file_upload_service=file_upload_service
+        )
 
         self._parent_database: NotionDatabase | None = None
         self._title = title
@@ -116,6 +135,10 @@ class NotionDataSource(Entity):
     def properties(self) -> dict[str, DataSourceProperty]:
         return self._properties
 
+    @property
+    def data_source_query_builder(self) -> DataSourceQueryBuilder:
+        return DataSourceQueryBuilder(properties=self._properties)
+
     async def create_blank_page(self, title: str | None = None) -> NotionPage:
         return await self._data_source_client.create_blank_page(title=title)
 
@@ -138,7 +161,9 @@ class NotionDataSource(Entity):
         self._archived = False
 
     async def update_description(self, description: str) -> None:
-        self._description = await self._data_source_client.update_description(description)
+        self._description = await self._data_source_client.update_description(
+            description
+        )
 
     async def get_options_for_property_by_name(self, property_name: str) -> list[str]:
         prop = self._properties.get(property_name)
@@ -161,22 +186,36 @@ class NotionDataSource(Entity):
         return []
 
     def get_select_options_by_property_name(self, property_name: str) -> list[str]:
-        select_prop = self._get_typed_property_or_raise(property_name, DataSourceSelectProperty)
+        select_prop = self._get_typed_property_or_raise(
+            property_name, DataSourceSelectProperty
+        )
         return select_prop.option_names
 
-    def get_multi_select_options_by_property_name(self, property_name: str) -> list[DataSourcePropertyOption]:
-        multi_select_prop = self._get_typed_property_or_raise(property_name, DataSourceMultiSelectProperty)
+    def get_multi_select_options_by_property_name(
+        self, property_name: str
+    ) -> list[DataSourcePropertyOption]:
+        multi_select_prop = self._get_typed_property_or_raise(
+            property_name, DataSourceMultiSelectProperty
+        )
         return multi_select_prop.option_names
 
     def get_status_options_by_property_name(self, property_name: str) -> list[str]:
-        status_prop = self._get_typed_property_or_raise(property_name, DataSourceStatusProperty)
+        status_prop = self._get_typed_property_or_raise(
+            property_name, DataSourceStatusProperty
+        )
         return status_prop.option_names
 
-    async def get_relation_options_by_property_name(self, property_name: str) -> list[str]:
-        relation_prop = self._get_typed_property_or_raise(property_name, DataSourceRelationProperty)
+    async def get_relation_options_by_property_name(
+        self, property_name: str
+    ) -> list[str]:
+        relation_prop = self._get_typed_property_or_raise(
+            property_name, DataSourceRelationProperty
+        )
         return await self._get_relation_options(relation_prop)
 
-    async def _get_relation_options(self, relation_prop: DataSourceRelationProperty) -> list[str]:
+    async def _get_relation_options(
+        self, relation_prop: DataSourceRelationProperty
+    ) -> list[str]:
         related_data_source_id = relation_prop.related_data_source_id
         if not related_data_source_id:
             return []
@@ -197,7 +236,11 @@ class NotionDataSource(Entity):
             return None
 
         title_property = next(
-            (prop for prop in page.properties.values() if isinstance(prop, PageTitleProperty)),
+            (
+                prop
+                for prop in page.properties.values()
+                if isinstance(prop, PageTitleProperty)
+            ),
             None,
         )
 
@@ -206,7 +249,9 @@ class NotionDataSource(Entity):
 
         return "".join(item.plain_text for item in title_property.title)
 
-    def _get_typed_property_or_raise(self, name: str, property_type: type[DataSourcePropertyT]) -> DataSourcePropertyT:
+    def _get_typed_property_or_raise(
+        self, name: str, property_type: type[DataSourcePropertyT]
+    ) -> DataSourcePropertyT:
         prop = self._properties.get(name)
 
         if prop is None:
@@ -217,52 +262,61 @@ class NotionDataSource(Entity):
 
         if not isinstance(prop, property_type):
             raise DataSourcePropertyTypeError(
-                property_name=name, expected_type=property_type.__name__, actual_type=type(prop).__name__
+                property_name=name,
+                expected_type=property_type.__name__,
+                actual_type=type(prop).__name__,
             )
 
         return prop
 
-    def filter(self) -> DataSourceQueryBuilder:
+    def get_query_builder(self) -> DataSourceQueryBuilder:
         return DataSourceQueryBuilder(properties=self._properties)
 
-    async def query_pages(
-        self, filter_fn: Callable[[DataSourceQueryBuilder], DataSourceQueryBuilder]
-    ) -> list[NotionPage]:
-        builder = DataSourceQueryBuilder(properties=self._properties)
-        configured_builder = filter_fn(builder)
-        query_params = configured_builder.build()
-
-        return await self.get_pages(query_params)
-
-    async def query_pages_stream(
-        self, filter_fn: Callable[[DataSourceQueryBuilder], DataSourceQueryBuilder]
-    ) -> AsyncIterator[NotionPage]:
-        builder = DataSourceQueryBuilder(properties=self._properties)
-        configured_builder = filter_fn(builder)
-        query_params = configured_builder.build()
-
-        async for page in self.get_pages_stream(query_params):
-            yield page
-
     async def get_pages(
         self,
+        *,
+        filter_fn: Callable[[DataSourceQueryBuilder], DataSourceQueryBuilder]
+        | None = None,
         query_params: DataSourceQueryParams | None = None,
     ) -> list[NotionPage]:
         from notionary import NotionPage
 
+        if filter_fn is not None and query_params is not None:
+            raise ValueError("Use either filter_fn OR query_params, not both")
+
+        if filter_fn is not None:
+            builder = DataSourceQueryBuilder(properties=self._properties)
+            configured_builder = filter_fn(builder)
+            query_params = configured_builder.build()
+
         resolved_params = await self._resolve_query_params_if_needed(query_params)
-        query_response = await self._data_source_client.query(query_params=resolved_params)
+        query_response = await self._data_source_client.query(
+            query_params=resolved_params
+        )
         return [await NotionPage.from_id(page.id) for page in query_response.results]
 
-    async def get_pages_stream(
+    async def iter_pages(
         self,
+        *,
+        filter_fn: Callable[[DataSourceQueryBuilder], DataSourceQueryBuilder]
+        | None = None,
         query_params: DataSourceQueryParams | None = None,
     ) -> AsyncIterator[NotionPage]:
         from notionary import NotionPage
 
+        if filter_fn is not None and query_params is not None:
+            raise ValueError("Use either filter_fn OR query_params, not both")
+
+        if filter_fn is not None:
+            builder = DataSourceQueryBuilder(properties=self._properties)
+            configured_builder = filter_fn(builder)
+            query_params = configured_builder.build()
+
         resolved_params = await self._resolve_query_params_if_needed(query_params)
 
-        async for page in self._data_source_client.query_stream(query_params=resolved_params):
+        async for page in self._data_source_client.query_stream(
+            query_params=resolved_params
+        ):
             yield await NotionPage.from_id(page.id)
 
     async def _resolve_query_params_if_needed(
@@ -275,5 +329,11 @@ class NotionDataSource(Entity):
         return await self.query_resolver.resolve_params(query_params)
 
     async def get_schema_description(self) -> str:
-        formatter = DataSourcePropertySchemaFormatter(relation_options_fetcher=self._get_relation_options)
-        return await formatter.format(title=self._title, description=self._description, properties=self._properties)
+        formatter = DataSourcePropertySchemaFormatter(
+            relation_options_fetcher=self._get_relation_options
+        )
+        return await formatter.format(
+            title=self._title,
+            description=self._description,
+            properties=self._properties,
+        )