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 def move(self, page_id: str, **kwargs: Any) -> SyncAsync[Any]: 

316 """Use this API to move an existing Notion page to a new parent. 

317 

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

319 """ # noqa: E501 

320 return self.parent.request( 

321 path=f"pages/{page_id}/move", 

322 method="POST", 

323 body=pick(kwargs, "parent"), 

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

325 ) 

326 

327 

328class UsersEndpoint(Endpoint): 

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

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

331 

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

333 """ # noqa: E501 

334 return self.parent.request( 

335 path="users", 

336 method="GET", 

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

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

339 ) 

340 

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

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

343 

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

345 """ # noqa: E501 

346 return self.parent.request( 

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

348 ) 

349 

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

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

352 

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

354 """ # noqa: E501 

355 return self.parent.request( 

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

357 ) 

358 

359 

360class SearchEndpoint(Endpoint): 

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

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

363 

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

365 """ # noqa: E501 

366 return self.parent.request( 

367 path="search", 

368 method="POST", 

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

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

371 ) 

372 

373 

374class CommentsEndpoint(Endpoint): 

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

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

377 

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

379 """ # noqa: E501 

380 return self.parent.request( 

381 path="comments", 

382 method="POST", 

383 body=pick( 

384 kwargs, 

385 "rich_text", 

386 "attachments", 

387 "display_name", 

388 "parent", 

389 "discussion_id", 

390 ), 

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

392 ) 

393 

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

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

396 

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

398 """ # noqa: E501 

399 return self.parent.request( 

400 path="comments", 

401 method="GET", 

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

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

404 ) 

405 

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

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

408 

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

410 """ # noqa: E501 

411 return self.parent.request( 

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

413 method="GET", 

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

415 ) 

416 

417 

418class FileUploadsEndpoint(Endpoint): 

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

420 """Create a file upload. 

421 

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

423 """ # noqa: E501 

424 return self.parent.request( 

425 path="file_uploads", 

426 method="POST", 

427 body=pick( 

428 kwargs, 

429 "mode", 

430 "filename", 

431 "content_type", 

432 "number_of_parts", 

433 "external_url", 

434 ), 

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

436 ) 

437 

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

439 """Complete the file upload process. 

440 

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

442 """ # noqa: E501 

443 return self.parent.request( 

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

445 method="POST", 

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

447 ) 

448 

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

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

451 

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

453 """ # noqa: E501 

454 return self.parent.request( 

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

456 method="GET", 

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

458 ) 

459 

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

461 """List all file uploads. 

462 

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

464 """ # noqa: E501 

465 return self.parent.request( 

466 path="file_uploads", 

467 method="GET", 

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

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

470 ) 

471 

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

473 """Send a file upload 

474 

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

476 """ # noqa: E501 

477 return self.parent.request( 

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

479 method="POST", 

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

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

482 ) 

483 

484 

485class OAuthEndpoint(Endpoint): 

486 def token( 

487 self, client_id: str, client_secret: str, **kwargs: Any 

488 ) -> SyncAsync[Any]: 

489 """Create an access token that a third-party service can use to authenticate with Notion. 

490 

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

492 """ # noqa: E501 

493 return self.parent.request( 

494 path="oauth/token", 

495 method="POST", 

496 body=pick( 

497 kwargs, 

498 "grant_type", 

499 "code", 

500 "redirect_uri", 

501 "external_account", 

502 "refresh_token", 

503 ), 

504 auth={"client_id": client_id, "client_secret": client_secret}, 

505 ) 

506 

507 def introspect( 

508 self, client_id: str, client_secret: str, **kwargs: Any 

509 ) -> SyncAsync[Any]: 

510 """Get a token's active status, scope, and issued time. 

511 

512 *[🔗 Endpoint documentation](https://developers.notion.com/reference/introspect-token)* 

513 """ # noqa: E501 

514 return self.parent.request( 

515 path="oauth/introspect", 

516 method="POST", 

517 body=pick(kwargs, "token"), 

518 auth={"client_id": client_id, "client_secret": client_secret}, 

519 ) 

520 

521 def revoke( 

522 self, client_id: str, client_secret: str, **kwargs: Any 

523 ) -> SyncAsync[Any]: 

524 """Revoke an access token. 

525 

526 *[🔗 Endpoint documentation](https://developers.notion.com/reference/revoke-token)* 

527 """ # noqa: E501 

528 return self.parent.request( 

529 path="oauth/revoke", 

530 method="POST", 

531 body=pick(kwargs, "token"), 

532 auth={"client_id": client_id, "client_secret": client_secret}, 

533 )