7265533490

Committed 19 Dec 2023 05:40PM UTC coverage: 87.899% (+0.5%) from 87.419%

Build # 7265533490

Build Type

push

github

Committed by

FlorianWilhelm

Commit Message

Provide 'children' method for page to navigate sub-pages/databases

Run Details

554 of 747 branches covered (0.0%)

Branch coverage included in aggregate %.

123 of 130 new or added lines in 9 files covered. (94.62%)

1 existing line in 1 file now uncovered.

3492 of 3856 relevant lines covered (90.56%)

4.5 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

72.68

/src/ultimate_notion/page.py

"""Functionality around Notion pages."""

from __future__ import annotations

from typing import TYPE_CHECKING, Any, cast

import mistune

from ultimate_notion.blocks import Block, ChildDatabase, ChildPage, DataObject
from ultimate_notion.obj_api import blocks as obj_blocks
from ultimate_notion.obj_api import objects as objs
from ultimate_notion.obj_api import props as obj_props
from ultimate_notion.objects import Emoji, File, RichText
from ultimate_notion.props import PropertyValue, Title
from ultimate_notion.utils import get_active_session, get_repr, is_notebook

if TYPE_CHECKING:
    from ultimate_notion.database import Database


class PageProperty:
    """Property of a page implementing the descriptor protocol."""

    def __init__(self, prop_name: str):
        self._prop_name = prop_name

    def __get__(self, obj: PageProperties, type=None) -> PropertyValue:  # noqa: A002
        return obj[self._prop_name]

    def __set__(self, obj: PageProperties, value):
        obj[self._prop_name] = value


class PageProperties:
    """Properties of a page as defined in the schema of the database.

    This defines the `.props` namespace of a page `page` and updates the content
    on the Notion server side in case of an assignment.
    Access the properties with `page.props.property_name` or `page.props["Property Name"]`.
    """

    def __init__(self, page: Page):
        self._page = page

    @property
    def _properties(self) -> dict[str, obj_props.PropertyValue]:
        """Return the low-level page properties"""
        return self._page.obj_ref.properties

    def __getitem__(self, prop_name: str) -> PropertyValue:
        prop = self._properties.get(prop_name)
        if prop is None:
            msg = f'No such property: {prop_name}'
            raise AttributeError(msg)

        return cast(PropertyValue, PropertyValue.wrap_obj_ref(prop))

    def __setitem__(self, prop_name: str, value: Any):
        # Todo: use the schema of the database to see which properties are writeable at all.
        db = self._page.database
        if db is None:
            msg = f'Trying to set a property but page {self._page} is not bound to any database'
            raise RuntimeError(msg)

        if not isinstance(value, PropertyValue):
            # construct concrete PropertyValue using the schema
            prop_type = db.schema.to_dict()[prop_name]
            value = prop_type.prop_value(value)

        # update the property on the server (which will update the local data)
        session = get_active_session()
        session.api.pages.update(self._page.obj_ref, **{prop_name: value.obj_ref})

    def __iter__(self):
        """Iterator of property names."""
        yield from self._properties.keys()

    def to_dict(self) -> dict[str, PropertyValue]:
        """All page properties as dictionary."""
        return {prop_name: self[prop_name] for prop_name in self}


class Page(DataObject[obj_blocks.Page], wraps=obj_blocks.Page):
    """A Notion page.

    Attributes:
        props: accessor for all page properties
    """

    props: PageProperties
    _render_md = mistune.create_markdown(plugins=['strikethrough', 'url', 'task_lists', 'math'], escape=False)
    _content: list[Block] | None = None

    @classmethod
    def wrap_obj_ref(cls, obj_ref: obj_blocks.Page, /) -> Page:
        obj = super().wrap_obj_ref(obj_ref)
        obj.props = obj._create_prop_attrs()
        return obj

    def _create_prop_attrs(self) -> PageProperties:
        """Create the attributes for the database properties of this page."""
        # We have to subclass in order to populate it with the descriptor `PageProperty``
        # as this only works on the class level and we want a unique class for each property.
        page_props_cls = type('_PageProperties', (PageProperties,), {})
        if self.database:
            for col in self.database.schema.get_cols():
                setattr(page_props_cls, col.attr_name, PageProperty(prop_name=col.name))
        return page_props_cls(page=self)

    def __str__(self) -> str:
        return str(self.title)

    def __repr__(self) -> str:
        return get_repr(self, desc=self.title)

    def _repr_html_(self) -> str:  # noqa: PLW3201
        """Called by Jupyter Lab automatically to display this page."""
        return self._render_md(self.to_markdown())  # Github flavored markdown

    @property
    def content(self) -> list[Block]:
        """Return the content of this page, i.e. all blocks belonging to this page"""
        if self._content is None:  # generate cache
            session = get_active_session()
            self._content = session._get_blocks(self.id)

        return self._content

    @property
    def children(self) -> list[Page | Database]:
        """Return all contained databases and pages within this page"""
        session = get_active_session()
        children: list[Page | Database] = []
        for block in self.content:
            if isinstance(block, ChildPage):
                children.append(session.get_page(block.id))
            elif isinstance(block, ChildDatabase):
                children.append(session.get_db(block.id))
        return children

    @property
    def database(self) -> Database | None:
        """If this page is located in a database return the database or None otherwise."""
        from ultimate_notion.database import Database  # noqa: PLC0415

        if isinstance(self.parent, Database):
            return self.parent
        else:
            return None

    @property
    def title(self) -> RichText:
        """Title of the page"""
        # As the 'title' property might be renamed in case of pages in databases, we look for the `id`.
        for prop in self.obj_ref.properties.values():
            if prop.id == 'title':
                title = cast(Title, PropertyValue.wrap_obj_ref(prop))
                return title.value
        msg = 'Encountered a page without title property'
        raise RuntimeError(msg)

    @property
    def icon(self) -> File | Emoji | None:
        """Icon of the page, i.e. emojis, Notion's icons, or custom images."""
        icon = self.obj_ref.icon
        if isinstance(icon, objs.ExternalFile):
            return File.wrap_obj_ref(icon)
        elif isinstance(icon, objs.EmojiObject):
            return Emoji.wrap_obj_ref(icon)
        elif icon is None:
            return None
        else:
            msg = f'unknown icon object of {type(icon)}'
            raise RuntimeError(msg)

    @property
    def cover(self) -> File | None:
        """Cover of the page."""
        cover = self.obj_ref.cover
        if isinstance(cover, objs.ExternalFile):
            return File.wrap_obj_ref(cover)
        elif cover is None:
            return None
        else:
            msg = f'unknown cover object of {type(cover)}'
            raise RuntimeError(msg)

    def to_markdown(self) -> str:
        """Return the content of the page as Markdown."""
        # ToDo: Since notion2md is also quite buggy, use an own implementation here using Mistune!
        import os  # noqa: PLC0415

        from notion2md.exporter.block import StringExporter  # noqa: PLC0415

        from ultimate_notion.session import ENV_NOTION_TOKEN, Session  # noqa: PLC0415

        auth_token = Session.get_or_create().client.options.auth
        if auth_token is None:
            msg = 'Impossible to pass the auth token to notion_client via an environment variable'
            raise RuntimeError(msg)
        os.environ[ENV_NOTION_TOKEN] = auth_token  # used internally by notion_client used by notion2md

        md = f'# {self.title}\n'
        md += StringExporter(block_id=self.id).export()
        return md

    def show(self, *, simple: bool | None = None):
        """Show the content of the page, rendered in Jupyter Lab"""
        simple = simple if simple is not None else is_notebook()
        md = self.to_markdown()

        if simple:
            print(md)  # noqa: T201
        else:
            from IPython.core.display import display_markdown  # noqa: PLC0415

            display_markdown(md, raw=True)

    def delete(self) -> Page:
        """Delete/archive this page."""
        if not self.is_deleted:
            session = get_active_session()
            session.api.pages.delete(self.obj_ref)
        return self

    def restore(self) -> Page:
        """Restore/unarchive this page."""
        if self.is_deleted:
            session = get_active_session()
            session.api.pages.restore(self.obj_ref)
        return self

    def reload(self) -> Page:
        """Reload this page."""
        session = get_active_session()
        self.obj_ref = session.api.pages.retrieve(self.obj_ref.id)
        self._content = None  # this forces a new retrieval next time
        return self

1	"""Functionality around Notion pages."""	5✔
2
3	from __future__ import annotations	5✔
4
5	from typing import TYPE_CHECKING, Any, cast	5✔
6
7	import mistune	5✔
8
9	from ultimate_notion.blocks import Block, ChildDatabase, ChildPage, DataObject	5✔
10	from ultimate_notion.obj_api import blocks as obj_blocks	5✔
11	from ultimate_notion.obj_api import objects as objs	5✔
12	from ultimate_notion.obj_api import props as obj_props	5✔
13	from ultimate_notion.objects import Emoji, File, RichText	5✔
14	from ultimate_notion.props import PropertyValue, Title	5✔
15	from ultimate_notion.utils import get_active_session, get_repr, is_notebook	5✔
16
17	if TYPE_CHECKING:
18	from ultimate_notion.database import Database
19
20
21	class PageProperty:	5✔
22	"""Property of a page implementing the descriptor protocol."""	5✔
23
24	def __init__(self, prop_name: str):	5✔
25	self._prop_name = prop_name	5✔
26
27	def __get__(self, obj: PageProperties, type=None) -> PropertyValue: # noqa: A002	5✔
28	return obj[self._prop_name]	5✔
29
30	def __set__(self, obj: PageProperties, value):	5✔
31	obj[self._prop_name] = value	4✔
32
33
34	class PageProperties:	5✔
35	"""Properties of a page as defined in the schema of the database.	5✔
36
37	This defines the `.props` namespace of a page `page` and updates the content
38	on the Notion server side in case of an assignment.
39	Access the properties with `page.props.property_name` or `page.props["Property Name"]`.
40	"""
41
42	def __init__(self, page: Page):	5✔
43	self._page = page	5✔
44
45	@property	5✔
46	def _properties(self) -> dict[str, obj_props.PropertyValue]:	5✔
47	"""Return the low-level page properties"""
48	return self._page.obj_ref.properties	5✔
49
50	def __getitem__(self, prop_name: str) -> PropertyValue:	5✔
51	prop = self._properties.get(prop_name)	5✔
52	if prop is None:	5✔
53	msg = f'No such property: {prop_name}'	×
54	raise AttributeError(msg)	×
55
56	return cast(PropertyValue, PropertyValue.wrap_obj_ref(prop))	5✔
57
58	def __setitem__(self, prop_name: str, value: Any):	5✔
59	# Todo: use the schema of the database to see which properties are writeable at all.
60	db = self._page.database	4✔
61	if db is None:	4✔
62	msg = f'Trying to set a property but page {self._page} is not bound to any database'	×
63	raise RuntimeError(msg)	×
64
65	if not isinstance(value, PropertyValue):	4✔
66	# construct concrete PropertyValue using the schema
67	prop_type = db.schema.to_dict()[prop_name]	4✔
68	value = prop_type.prop_value(value)	4✔
69
70	# update the property on the server (which will update the local data)
71	session = get_active_session()	4✔
72	session.api.pages.update(self._page.obj_ref, **{prop_name: value.obj_ref})	4✔
73
74	def __iter__(self):	5✔
75	"""Iterator of property names."""
76	yield from self._properties.keys()	×
77
78	def to_dict(self) -> dict[str, PropertyValue]:	5✔
79	"""All page properties as dictionary."""
80	return {prop_name: self[prop_name] for prop_name in self}	×
81
82
83	class Page(DataObject[obj_blocks.Page], wraps=obj_blocks.Page):	5✔
84	"""A Notion page.	5✔
85
86	Attributes:
87	props: accessor for all page properties
88	"""
89
90	props: PageProperties	5✔
91	_render_md = mistune.create_markdown(plugins=['strikethrough', 'url', 'task_lists', 'math'], escape=False)	5✔
92	_content: list[Block] \| None = None	5✔
93
94	@classmethod	5✔
95	def wrap_obj_ref(cls, obj_ref: obj_blocks.Page, /) -> Page:	5✔
96	obj = super().wrap_obj_ref(obj_ref)	5✔
97	obj.props = obj._create_prop_attrs()	5✔
98	return obj	5✔
99
100	def _create_prop_attrs(self) -> PageProperties:	5✔
101	"""Create the attributes for the database properties of this page."""
102	# We have to subclass in order to populate it with the descriptor `PageProperty``
103	# as this only works on the class level and we want a unique class for each property.
104	page_props_cls = type('_PageProperties', (PageProperties,), {})	5✔
105	if self.database:	5✔
106	for col in self.database.schema.get_cols():	5✔
107	setattr(page_props_cls, col.attr_name, PageProperty(prop_name=col.name))	5✔
108	return page_props_cls(page=self)	5✔
109
110	def __str__(self) -> str:	5✔
111	return str(self.title)	×
112
113	def __repr__(self) -> str:
114	return get_repr(self, desc=self.title)
115
116	def _repr_html_(self) -> str: # noqa: PLW3201	5✔
117	"""Called by Jupyter Lab automatically to display this page."""
118	return self._render_md(self.to_markdown()) # Github flavored markdown	×
119
120	@property	5✔
121	def content(self) -> list[Block]:	5✔
122	"""Return the content of this page, i.e. all blocks belonging to this page"""
123	if self._content is None: # generate cache	5✔
124	session = get_active_session()	5✔
125	self._content = session._get_blocks(self.id)	5✔
126
127	return self._content	5✔
128
129	@property	5✔
130	def children(self) -> list[Page \| Database]:	5✔
131	"""Return all contained databases and pages within this page"""
132	session = get_active_session()	5✔
133	children: list[Page \| Database] = []	5✔
134	for block in self.content:	5!
135	if isinstance(block, ChildPage):	5✔
136	children.append(session.get_page(block.id))	5✔
NEW 137	elif isinstance(block, ChildDatabase):	×
NEW 138	children.append(session.get_db(block.id))	×
139	return children	5✔
140
141	@property	5✔
142	def database(self) -> Database \| None:	5✔
143	"""If this page is located in a database return the database or None otherwise."""
144	from ultimate_notion.database import Database # noqa: PLC0415	5✔
145
146	if isinstance(self.parent, Database):	5✔
147	return self.parent	5✔
148	else:
149	return None	5✔
150
151	@property	5✔
152	def title(self) -> RichText:	5✔
153	"""Title of the page"""
154	# As the 'title' property might be renamed in case of pages in databases, we look for the `id`.
155	for prop in self.obj_ref.properties.values():	5✔
156	if prop.id == 'title':	5✔
157	title = cast(Title, PropertyValue.wrap_obj_ref(prop))	5✔
158	return title.value	5✔
159	msg = 'Encountered a page without title property'	×
160	raise RuntimeError(msg)	×
161
162	@property	5✔
163	def icon(self) -> File \| Emoji \| None:	5✔
164	"""Icon of the page, i.e. emojis, Notion's icons, or custom images."""
165	icon = self.obj_ref.icon	×
166	if isinstance(icon, objs.ExternalFile):	×
167	return File.wrap_obj_ref(icon)	×
168	elif isinstance(icon, objs.EmojiObject):	×
169	return Emoji.wrap_obj_ref(icon)	×
170	elif icon is None:	×
171	return None	×
172	else:
173	msg = f'unknown icon object of {type(icon)}'	×
174	raise RuntimeError(msg)	×
175
176	@property	5✔
177	def cover(self) -> File \| None:	5✔
178	"""Cover of the page."""
179	cover = self.obj_ref.cover	×
180	if isinstance(cover, objs.ExternalFile):	×
181	return File.wrap_obj_ref(cover)	×
182	elif cover is None:	×
183	return None	×
184	else:
185	msg = f'unknown cover object of {type(cover)}'	×
186	raise RuntimeError(msg)	×
187
188	def to_markdown(self) -> str:	5✔
189	"""Return the content of the page as Markdown."""
190	# ToDo: Since notion2md is also quite buggy, use an own implementation here using Mistune!
191	import os # noqa: PLC0415	4✔
192
193	from notion2md.exporter.block import StringExporter # noqa: PLC0415	4✔
194
195	from ultimate_notion.session import ENV_NOTION_TOKEN, Session # noqa: PLC0415	4✔
196
197	auth_token = Session.get_or_create().client.options.auth	4✔
198	if auth_token is None:	4✔
199	msg = 'Impossible to pass the auth token to notion_client via an environment variable'	×
200	raise RuntimeError(msg)	×
201	os.environ[ENV_NOTION_TOKEN] = auth_token # used internally by notion_client used by notion2md	4✔
202
203	md = f'# {self.title}\n'	4✔
204	md += StringExporter(block_id=self.id).export()	4✔
205	return md	4✔
206
207	def show(self, *, simple: bool \| None = None):	5✔
208	"""Show the content of the page, rendered in Jupyter Lab"""
209	simple = simple if simple is not None else is_notebook()	4✔
210	md = self.to_markdown()	4✔
211
212	if simple:	4✔
213	print(md) # noqa: T201	×
214	else:
215	from IPython.core.display import display_markdown # noqa: PLC0415	4✔
216
217	display_markdown(md, raw=True)	4✔
218
219	def delete(self) -> Page:	5✔
220	"""Delete/archive this page."""
221	if not self.is_deleted:	5✔
222	session = get_active_session()	5✔
223	session.api.pages.delete(self.obj_ref)	5✔
224	return self	5!
225
226	def restore(self) -> Page:	5✔
227	"""Restore/unarchive this page."""
228	if self.is_deleted:	5✔
229	session = get_active_session()	5✔
230	session.api.pages.restore(self.obj_ref)	5✔
231	return self	5!
232
233	def reload(self) -> Page:	5✔
234	"""Reload this page."""
235	session = get_active_session()	5✔
236	self.obj_ref = session.api.pages.retrieve(self.obj_ref.id)	5✔
237	self._content = None # this forces a new retrieval next time	5✔
238	return self	5✔

ultimate-notion / ultimate-notion / 7265533490

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous