The metadata API#

We already learned how to display metadata to provide humans with context (e.g., Basic metadata).

If we want to build functionality on top of notebook metadata, we can access metadata through the API.

from nbproject import header, meta
import pandas as pd

header()

id	k6Bj4FXM9oPm
version	0
time_init	2022-06-29 14:38
time_run	2024-02-28 16:55
pypackage	nbproject==0.10.1 pandas==2.2.1

If you’d like a simple dictionary and intialization state, call:

header(metadata_only=True)

({'id': 'k6Bj4FXM9oPm',
  'time_init': '2022-06-29T14:38:42.171771+00:00',
  'version': '0'},
 False,
 Notebook(metadata={'kernelspec': {'display_name': 'Python 3 (ipykernel)', 'language': 'python', 'name': 'python3'}, 'language_info': {'codemirror_mode': {'name': 'ipython', 'version': 3}, 'file_extension': '.py', 'mimetype': 'text/x-python', 'name': 'python', 'nbconvert_exporter': 'python', 'pygments_lexer': 'ipython3', 'version': '3.9.12'}, 'nbproject': {'id': 'k6Bj4FXM9oPm', 'time_init': '2022-06-29T14:38:42.171771+00:00', 'version': '0'}, 'vscode': {'interpreter': {'hash': '2775e555cdc2d728c54aa22130c79afb1fa4da64f22f2fc6dcc2aa346c4e0672'}}}, nbformat=4, nbformat_minor=5, cells=[{'cell_type': 'markdown', 'id': '1b4d3825-6110-440b-a9c0-99cbb56f6ab6', 'metadata': {}, 'source': ['# The metadata API']}, {'cell_type': 'markdown', 'id': 'cba70490-5b5d-4e11-88a6-5bb338d32810', 'metadata': {}, 'source': ['We already learned how to display metadata to provide humans with context (e.g., {doc}`basic-metadata`).\n', '\n', 'If we want to build functionality on top of notebook metadata, we can access metadata through the API.']}, {'cell_type': 'code', 'execution_count': 1, 'id': 'a920ea06-3b40-4900-a83e-9aaf8632c098', 'metadata': {}, 'outputs': [], 'source': ['from nbproject import header, meta\n', 'import pandas as pd\n', '\n', 'header()']}, {'cell_type': 'markdown', 'id': 'd8052d5b', 'metadata': {}, 'source': ["If you'd like a simple dictionary and intialization state, call:"]}, {'cell_type': 'code', 'execution_count': 2, 'id': '5047184e', 'metadata': {}, 'outputs': [], 'source': ['header(metadata_only=True)']}, {'cell_type': 'markdown', 'id': 'f38546af-5976-482e-97be-ab4cc025b420', 'metadata': {}, 'source': ['For instance, we can retrieve the stored notebook ID as follows.']}, {'cell_type': 'code', 'execution_count': 3, 'id': 'c57e6a11-7d4f-4e39-9972-d6c9e4bd3412', 'metadata': {}, 'outputs': [], 'source': ['assert not meta.live.consecutive_cells']}, {'cell_type': 'code', 'execution_count': 4, 'id': '2fa7f01c-5187-43cc-aaab-67ebebf8c043', 'metadata': {}, 'outputs': [], 'source': ['meta.store.id']}, {'cell_type': 'code', 'execution_count': 5, 'id': '2361d6ac-7468-4bb3-9491-e7724f58c653', 'metadata': {'tags': ['hide-cell']}, 'outputs': [], 'source': ['assert meta.store.id == "k6Bj4FXM9oPm"\n', 'assert hasattr(meta.store, "time_init")']}, {'cell_type': 'code', 'execution_count': 6, 'id': '092b9b36', 'metadata': {}, 'outputs': [], 'source': ['meta.store.pypackage']}, {'cell_type': 'markdown', 'id': '5b314ad2', 'metadata': {}, 'source': ['Manually add pypackages to `meta.store.pypackage`.']}, {'cell_type': 'code', 'execution_count': 7, 'id': 'c89ede67', 'metadata': {}, 'outputs': [], 'source': ['meta.store.add_pypackages(["pytest"])']}, {'cell_type': 'code', 'execution_count': 8, 'id': '1e48fe0a', 'metadata': {}, 'outputs': [], 'source': ['meta.store.pypackage']}, {'cell_type': 'code', 'execution_count': 9, 'id': '774584db-2ecc-40ba-9445-05fad86018cd', 'metadata': {}, 'outputs': [], 'source': ['meta.live.title']}, {'cell_type': 'code', 'execution_count': 10, 'id': '46074a8f-e2c3-4420-a5a9-131c4afbecbc', 'metadata': {}, 'outputs': [], 'source': ["# assert meta.live.consecutive_cells  # it'd be nice to test this here, but that would require flushing the ci buffer before this cell"]}, {'cell_type': 'code', 'execution_count': 11, 'id': '32c40a13-7ca5-4f92-a874-5a925488b582', 'metadata': {}, 'outputs': [], 'source': ['meta.live.time_run']}, {'cell_type': 'code', 'execution_count': 12, 'id': 'e43f7cf2-2ec0-4c5b-9cf9-b57c7d703425', 'metadata': {}, 'outputs': [], 'source': ['meta.live.time_passed']}, {'cell_type': 'code', 'execution_count': 13, 'id': '9e230c96-c707-4247-a53f-8a5850f380b2', 'metadata': {}, 'outputs': [], 'source': ['meta.live.pypackage']}, {'cell_type': 'code', 'execution_count': 14, 'id': 'e4a9cdb0-c1d8-4541-b04c-3d34d08faac7', 'metadata': {}, 'outputs': [], 'source': ['meta.live']}]))

For instance, we can retrieve the stored notebook ID as follows.

assert not meta.live.consecutive_cells

❗ cells [(2, 4), (9, 11)] were not run consecutively

meta.store.id

'k6Bj4FXM9oPm'

meta.store.pypackage

Manually add pypackages to meta.store.pypackage.

meta.store.add_pypackages(["pytest"])

Wrapper object for the stored metadata:
  id='k6Bj4FXM9oPm' version='0' time_init='2022-06-29T14:38:42.171771+00:00' pypackage={'pytest': '8.0.2'} parent=None user_handle=None user_id=None user_name=None

meta.store.pypackage

{'pytest': '8.0.2'}

meta.live.title

'The metadata API'

# assert meta.live.consecutive_cells  # it'd be nice to test this here, but that would require flushing the ci buffer before this cell

meta.live.time_run

'2024-02-28T16:55:30.533725+00:00'

meta.live.time_passed

0.073662

meta.live.pypackage

{'nbproject': '0.10.1', 'pandas': '2.2.1'}

meta.live

Fields: consecutive_cells pypackage time_passed time_run title user_handle user_id user_name