7307310055

Committed 23 Dec 2023 08:59AM UTC coverage: 88.567% (+0.1%) from 88.472%

Build # 7307310055

Build Type

push

github

Committed by

FlorianWilhelm

Commit Message

Allow setting the title of a page

Run Details

572 of 760 branches covered (0.0%)

Branch coverage included in aggregate %.

37 of 37 new or added lines in 3 files covered. (100.0%)

1 existing line in 1 file now uncovered.

3611 of 3963 relevant lines covered (91.12%)

4.53 hits per line

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

85.46

/src/ultimate_notion/page.py

"""Functionality around Notion pages."""

from __future__ import annotations

from typing import TYPE_CHECKING, Any, cast

import mistune
from emoji import is_emoji

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

    def _get_title_col_name(self) -> str:
        """Get the name of the title property."""
        # As the 'title' property might be renamed in case of pages in databases, we look for the `id`.
        for name, prop in self.obj_ref.properties.items():
            if prop.id == 'title':
                return name
        msg = 'Encountered a page without title property'
        raise RuntimeError(msg)

    @property
    def title(self) -> RichText:
        """Title of the page."""
        title_prop_name = self._get_title_col_name()
        title_prop = self.obj_ref.properties[title_prop_name]
        title = cast(Title, PropertyValue.wrap_obj_ref(title_prop))
        return title.value

    @title.setter
    def title(self, text: RichText | str | None):
        """Set the title of the page."""
        if text is None:
            text = ''
        title = Title(text)
        title_prop_name = self._get_title_col_name()
        session = get_active_session()
        session.api.pages.update(self.obj_ref, **{title_prop_name: title.obj_ref})

    @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)

    @icon.setter
    def icon(self, icon: File | Emoji | str | None):
        """Set the icon of this page."""
        if isinstance(icon, str) and not isinstance(icon, Emoji):
            icon = Emoji(icon) if is_emoji(icon) else File(url=icon, name=None)
        icon_obj = None if icon is None else icon.obj_ref
        session = get_active_session()
        session.api.pages.set_attr(self.obj_ref, icon=icon_obj)

    @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)

    @cover.setter
    def cover(self, cover: File | str | None):
        """Set the cover fo this page."""
        if isinstance(cover, str):
            cover = File(url=cover, name=None)
        cover_obj = None if cover is None else cover.obj_ref
        session = get_active_session()
        session.api.pages.set_attr(self.obj_ref, cover=cover_obj)

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

ultimate-notion / ultimate-notion / 7307310055

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