Coverage for notion_client/api_endpoints.py: 100%

1"""Notion API endpoints.""" # noqa: E501 

2 

3from typing import TYPE_CHECKING, Any 

4 

5from notion_client.helpers import pick 

6from notion_client.typing import SyncAsync 

7 

8if TYPE_CHECKING: # pragma: no cover 

9 from notion_client.client import BaseClient 

10 

11 

12class Endpoint: 

13 def __init__(self, parent: "BaseClient") -> None: 

14 self.parent = parent 

15 

16 

17class BlocksChildrenEndpoint(Endpoint): 

18 def append(self, block_id: str, **kwargs: Any) -> SyncAsync[Any]: 

19 """Create and append new children blocks to the block using the ID specified. 

20 

21 *[🔗 Endpoint documentation](https://developers.notion.com/reference/patch-block-children)* 

22 """ # noqa: E501 

23 return self.parent.request( 

24 path=f"blocks/{block_id}/children", 

25 method="PATCH", 

26 body=pick(kwargs, "children", "after"), 

27 auth=kwargs.get("auth"), 

28 ) 

29 

30 def list(self, block_id: str, **kwargs: Any) -> SyncAsync[Any]: 

31 """Return a paginated array of child [block objects](https://developers.notion.com/reference/block) contained in the block. 

32 

33 *[🔗 Endpoint documentation](https://developers.notion.com/reference/get-block-children)* 

34 """ # noqa: E501 

35 return self.parent.request( 

36 path=f"blocks/{block_id}/children", 

37 method="GET", 

38 query=pick(kwargs, "start_cursor", "page_size"), 

39 auth=kwargs.get("auth"), 

40 ) 

41 

42 

43class BlocksEndpoint(Endpoint): 

44 def __init__(self, *args: Any, **kwargs: Any) -> None: 

45 super().__init__(*args, **kwargs) 

46 self.children = BlocksChildrenEndpoint(*args, **kwargs) 

47 

48 def retrieve(self, block_id: str, **kwargs: Any) -> SyncAsync[Any]: 

49 """Retrieve a [Block object](https://developers.notion.com/reference/block) using the ID specified. 

50 

51 *[🔗 Endpoint documentation](https://developers.notion.com/reference/retrieve-a-block)* 

52 """ # noqa: E501 

53 return self.parent.request( 

54 path=f"blocks/{block_id}", method="GET", auth=kwargs.get("auth") 

55 ) 

56 

57 def update(self, block_id: str, **kwargs: Any) -> SyncAsync[Any]: 

58 """Update the content for the specified `block_id` based on the block type. 

59 

60 *[🔗 Endpoint documentation](https://developers.notion.com/reference/update-a-block)* 

61 """ # noqa: E501 

62 return self.parent.request( 

63 path=f"blocks/{block_id}", 

64 method="PATCH", 

65 body=pick( 

66 kwargs, 

67 "embed", 

68 "type", 

69 "archived", 

70 "in_trash", 

71 "bookmark", 

72 "image", 

73 "video", 

74 "pdf", 

75 "file", 

76 "audio", 

77 "code", 

78 "equation", 

79 "divider", 

80 "breadcrumb", 

81 "table_of_contents", 

82 "link_to_page", 

83 "table_row", 

84 "heading_1", 

85 "heading_2", 

86 "heading_3", 

87 "paragraph", 

88 "bulleted_list_item", 

89 "numbered_list_item", 

90 "quote", 

91 "to_do", 

92 "toggle", 

93 "template", 

94 "callout", 

95 "synced_block", 

96 "table", 

97 "column", 

98 ), 

99 auth=kwargs.get("auth"), 

100 ) 

101 

102 def delete(self, block_id: str, **kwargs: Any) -> SyncAsync[Any]: 

103 """Set a [Block object](https://developers.notion.com/reference/block), including page blocks, to `archived: true`. 

104 

105 *[🔗 Endpoint documentation](https://developers.notion.com/reference/delete-a-block)* 

106 """ # noqa: E501 

107 return self.parent.request( 

108 path=f"blocks/{block_id}", 

109 method="DELETE", 

110 auth=kwargs.get("auth"), 

111 ) 

112 

113 

114class DatabasesEndpoint(Endpoint): 

115 def retrieve(self, database_id: str, **kwargs: Any) -> SyncAsync[Any]: 

116 """Retrieves a [database object](https://developers.notion.com/reference/database) for a provided database ID. 

117 

118 *[🔗 Endpoint documentation](https://developers.notion.com/reference/database-retrieve)* 

119 """ # noqa: E501 

120 return self.parent.request( 

121 path=f"databases/{database_id}", 

122 method="GET", 

123 auth=kwargs.get("auth"), 

124 ) 

125 

126 def update(self, database_id: str, **kwargs: Any) -> SyncAsync[Any]: 

127 """Update the title or properties of an existing database. 

128 

129 *[🔗 Endpoint documentation](https://developers.notion.com/reference/update-a-database)* 

130 """ # noqa: E501 

131 return self.parent.request( 

132 path=f"databases/{database_id}", 

133 method="PATCH", 

134 body=pick( 

135 kwargs, 

136 "parent", 

137 "title", 

138 "description", 

139 "is_inline", 

140 "icon", 

141 "cover", 

142 "in_trash", 

143 "is_locked", 

144 ), 

145 auth=kwargs.get("auth"), 

146 ) 

147 

148 def create(self, **kwargs: Any) -> SyncAsync[Any]: 

149 """Create a new database. 

150 

151 *[🔗 Endpoint documentation](https://developers.notion.com/reference/create-a-database)* 

152 """ # noqa: E501 

153 return self.parent.request( 

154 path="databases", 

155 method="POST", 

156 body=pick( 

157 kwargs, 

158 "parent", 

159 "title", 

160 "description", 

161 "is_inline", 

162 "initial_data_source", 

163 "icon", 

164 "cover", 

165 ), 

166 auth=kwargs.get("auth"), 

167 ) 

168 

169 

170class DataSourcesEndpoint(Endpoint): 

171 def retrieve(self, data_source_id: str, **kwargs: Any) -> SyncAsync[Any]: 

172 """Retrieve a [data source](https://developers.notion.com/reference/data-source) object for a provided data source ID. 

173 

174 *[🔗 Endpoint documentation](https://developers.notion.com/reference/retrieve-a-data-source)* 

175 """ # noqa: E501 

176 return self.parent.request( 

177 path=f"data_sources/{data_source_id}", method="GET", auth=kwargs.get("auth") 

178 ) 

179 

180 def query(self, data_source_id: str, **kwargs: Any) -> SyncAsync[Any]: 

181 """Get a list of [Pages](https://developers.notion.com/reference/page) and/or [Data Sources](https://developers.notion.com/reference/data-source) contained in the data source. 

182 

183 *[🔗 Endpoint documentation](https://developers.notion.com/reference/query-a-data-source)* 

184 """ # noqa: E501 

185 return self.parent.request( 

186 path=f"data_sources/{data_source_id}/query", 

187 method="POST", 

188 query=pick(kwargs, "filter_properties"), 

189 body=pick( 

190 kwargs, 

191 "sorts", 

192 "filter", 

193 "start_cursor", 

194 "page_size", 

195 "archived", 

196 "in_trash", 

197 "result_type", 

198 ), 

199 auth=kwargs.get("auth"), 

200 ) 

201 

202 def create(self, **kwargs: Any) -> SyncAsync[Any]: 

203 """Add an additional [data source](https://developers.notion.com/reference/data-source) to an existing [database](https://developers.notion.com/reference/database). 

204 

205 *[🔗 Endpoint documentation](https://developers.notion.com/reference/create-a-data-source)* 

206 """ # noqa: E501 

207 return self.parent.request( 

208 path="data_sources", 

209 method="POST", 

210 body=pick(kwargs, "parent", "properties", "title", "icon"), 

211 auth=kwargs.get("auth"), 

212 ) 

213 

214 def update(self, data_source_id: str, **kwargs: Any) -> SyncAsync[Any]: 

215 """Updates the [data source](https://developers.notion.com/reference/data-source) object of a specified data source under a database. 

216 

217 *[🔗 Endpoint documentation](https://developers.notion.com/reference/update-a-data-source)* 

218 """ # noqa: E501 

219 return self.parent.request( 

220 path=f"data_sources/{data_source_id}", 

221 method="PATCH", 

222 body=pick( 

223 kwargs, "title", "icon", "properties", "in_trash", "archived", "parent" 

224 ), 

225 auth=kwargs.get("auth"), 

226 ) 

227 

228 def list_templates(self, data_source_id: str, **kwargs: Any) -> SyncAsync[Any]: 

229 """List page templates that are available for a data source. 

230 

231 *[🔗 Endpoint documentation](https://developers.notion.com/reference/list-data-source-templates)* 

232 """ # noqa: E501 

233 return self.parent.request( 

234 path=f"data_sources/{data_source_id}/templates", 

235 method="GET", 

236 query=pick(kwargs, "name", "start_cursor", "page_size"), 

237 auth=kwargs.get("auth"), 

238 ) 

239 

240 

241class PagesPropertiesEndpoint(Endpoint): 

242 def retrieve(self, page_id: str, property_id: str, **kwargs: Any) -> SyncAsync[Any]: 

243 """Retrieve a `property_item` object for a given `page_id` and `property_id`. 

244 

245 *[🔗 Endpoint documentation](https://developers.notion.com/reference/retrieve-a-page-property)* 

246 """ # noqa: E501 

247 return self.parent.request( 

248 path=f"pages/{page_id}/properties/{property_id}", 

249 method="GET", 

250 auth=kwargs.get("auth"), 

251 query=pick(kwargs, "start_cursor", "page_size"), 

252 ) 

253 

254 

255class PagesEndpoint(Endpoint): 

256 def __init__(self, *args: Any, **kwargs: Any) -> None: 

257 super().__init__(*args, **kwargs) 

258 self.properties = PagesPropertiesEndpoint(*args, **kwargs) 

259 

260 def create(self, **kwargs: Any) -> SyncAsync[Any]: 

261 """Create a new page in the specified database or as a child of an existing page. 

262 

263 *[🔗 Endpoint documentation](https://developers.notion.com/reference/post-page)* 

264 """ # noqa: E501 

265 return self.parent.request( 

266 path="pages", 

267 method="POST", 

268 body=pick( 

269 kwargs, 

270 "parent", 

271 "properties", 

272 "icon", 

273 "cover", 

274 "content", 

275 "children", 

276 "template", 

277 ), 

278 auth=kwargs.get("auth"), 

279 ) 

280 

281 def retrieve(self, page_id: str, **kwargs: Any) -> SyncAsync[Any]: 

282 """Retrieve a [Page object](https://developers.notion.com/reference/page) using the ID specified. 

283 

284 *[🔗 Endpoint documentation](https://developers.notion.com/reference/retrieve-a-page)* 

285 """ # noqa: E501 

286 return self.parent.request( 

287 path=f"pages/{page_id}", 

288 method="GET", 

289 query=pick(kwargs, "filter_properties"), 

290 auth=kwargs.get("auth"), 

291 ) 

292 

293 def update(self, page_id: str, **kwargs: Any) -> SyncAsync[Any]: 

294 """Update [page property values](https://developers.notion.com/reference/page#property-value-object) for the specified page. 

295 

296 *[🔗 Endpoint documentation](https://developers.notion.com/reference/patch-page)* 

297 """ # noqa: E501 

298 return self.parent.request( 

299 path=f"pages/{page_id}", 

300 method="PATCH", 

301 body=pick( 

302 kwargs, 

303 "properties", 

304 "icon", 

305 "cover", 

306 "is_locked", 

307 "template", 

308 "erase_content", 

309 "archived", 

310 "in_trash", 

311 ), 

312 auth=kwargs.get("auth"), 

313 ) 

314 

315 

316class UsersEndpoint(Endpoint): 

317 def list(self, **kwargs: Any) -> SyncAsync[Any]: 

318 """Return a paginated list of [Users](https://developers.notion.com/reference/user) for the workspace. 

319 

320 *[🔗 Endpoint documentation](https://developers.notion.com/reference/get-users)* 

321 """ # noqa: E501 

322 return self.parent.request( 

323 path="users", 

324 method="GET", 

325 query=pick(kwargs, "start_cursor", "page_size"), 

326 auth=kwargs.get("auth"), 

327 ) 

328 

329 def retrieve(self, user_id: str, **kwargs: Any) -> SyncAsync[Any]: 

330 """Retrieve a [User](https://developers.notion.com/reference/user) using the ID specified. 

331 

332 *[🔗 Endpoint documentation](https://developers.notion.com/reference/get-user)* 

333 """ # noqa: E501 

334 return self.parent.request( 

335 path=f"users/{user_id}", method="GET", auth=kwargs.get("auth") 

336 ) 

337 

338 def me(self, **kwargs: Any) -> SyncAsync[Any]: 

339 """Retrieve the bot [User](https://developers.notion.com/reference/user) associated with the API token. 

340 

341 *[🔗 Endpoint documentation](https://developers.notion.com/reference/get-self)* 

342 """ # noqa: E501 

343 return self.parent.request( 

344 path="users/me", method="GET", auth=kwargs.get("auth") 

345 ) 

346 

347 

348class SearchEndpoint(Endpoint): 

349 def __call__(self, **kwargs: Any) -> SyncAsync[Any]: 

350 """Search all pages and child pages that are shared with the integration. 

351 

352 *[🔗 Endpoint documentation](https://developers.notion.com/reference/post-search)* 

353 """ # noqa: E501 

354 return self.parent.request( 

355 path="search", 

356 method="POST", 

357 body=pick(kwargs, "query", "sort", "filter", "start_cursor", "page_size"), 

358 auth=kwargs.get("auth"), 

359 ) 

360 

361 

362class CommentsEndpoint(Endpoint): 

363 def create(self, **kwargs: Any) -> SyncAsync[Any]: 

364 """Create a new comment in the specified page or existing discussion thread. 

365 

366 *[🔗 Endpoint documentation](https://developers.notion.com/reference/create-a-comment)* 

367 """ # noqa: E501 

368 return self.parent.request( 

369 path="comments", 

370 method="POST", 

371 body=pick( 

372 kwargs, 

373 "rich_text", 

374 "attachments", 

375 "display_name", 

376 "parent", 

377 "discussion_id", 

378 ), 

379 auth=kwargs.get("auth"), 

380 ) 

381 

382 def list(self, **kwargs: Any) -> SyncAsync[Any]: 

383 """Retrieve a list of un-resolved [Comment objects](https://developers.notion.com/reference/comment-object) from the specified block. 

384 

385 *[🔗 Endpoint documentation](https://developers.notion.com/reference/list-comments)* 

386 """ # noqa: E501 

387 return self.parent.request( 

388 path="comments", 

389 method="GET", 

390 query=pick(kwargs, "block_id", "start_cursor", "page_size"), 

391 auth=kwargs.get("auth"), 

392 ) 

393 

394 def retrieve(self, comment_id: str, **kwargs: Any) -> SyncAsync[Any]: 

395 """Retrieve a [Comment object](https://developers.notion.com/reference/comment-object) from its `comment_id`. 

396 

397 *[🔗 Endpoint documentation](https://developers.notion.com/reference/retrieve-comment)* 

398 """ # noqa: E501 

399 return self.parent.request( 

400 path=f"comments/{comment_id}", 

401 method="GET", 

402 auth=kwargs.get("auth"), 

403 ) 

404 

405 

406class FileUploadsEndpoint(Endpoint): 

407 def create(self, **kwargs: Any) -> SyncAsync[Any]: 

408 """Create a file upload. 

409 

410 *[🔗 Endpoint documentation](https://developers.notion.com/reference/create-a-file-upload)* 

411 """ # noqa: E501 

412 return self.parent.request( 

413 path="file_uploads", 

414 method="POST", 

415 body=pick( 

416 kwargs, 

417 "mode", 

418 "filename", 

419 "content_type", 

420 "number_of_parts", 

421 "external_url", 

422 ), 

423 auth=kwargs.get("auth"), 

424 ) 

425 

426 def complete(self, file_upload_id: str, **kwargs: Any) -> SyncAsync[Any]: 

427 """Complete the file upload process. 

428 

429 *[🔗 Endpoint documentation](https://developers.notion.com/reference/complete-a-file-upload)* 

430 """ # noqa: E501 

431 return self.parent.request( 

432 path=f"file_uploads/{file_upload_id}/complete", 

433 method="POST", 

434 auth=kwargs.get("auth"), 

435 ) 

436 

437 def retrieve(self, file_upload_id: str, **kwargs: Any) -> SyncAsync[Any]: 

438 """Retrieve a file upload object using the ID specified. 

439 

440 *[🔗 Endpoint documentation](https://developers.notion.com/reference/retrieve-a-file-upload)* 

441 """ # noqa: E501 

442 return self.parent.request( 

443 path=f"file_uploads/{file_upload_id}", 

444 method="GET", 

445 auth=kwargs.get("auth"), 

446 ) 

447 

448 def list(self, **kwargs: Any) -> SyncAsync[Any]: 

449 """List all file uploads. 

450 

451 *[🔗 Endpoint documentation](https://developers.notion.com/reference/list-file-uploads)* 

452 """ # noqa: E501 

453 return self.parent.request( 

454 path="file_uploads", 

455 method="GET", 

456 query=pick(kwargs, "status", "start_cursor", "page_size"), 

457 auth=kwargs.get("auth"), 

458 ) 

459 

460 def send(self, file_upload_id: str, **kwargs: Any) -> SyncAsync[Any]: 

461 """Send a file upload 

462 

463 *[🔗 Endpoint documentation](https://developers.notion.com/reference/send-a-file-upload)* 

464 """ # noqa: E501 

465 return self.parent.request( 

466 path=f"file_uploads/{file_upload_id}/send", 

467 method="POST", 

468 form_data=pick(kwargs, "file", "part_number"), 

469 auth=kwargs.get("auth"), 

470 )