Package: notions
Notions - A Python Client Library and CLI for NotionA command line client and API library forNotion.Uses theNotion APIto communicate with your Notion pages and databases.Homepage:https://github.com/micktwomey/notionsRepo:https://github.com/micktwomey/notionsPyPI project page:https://pypi.org/project/notions/Notions - A Python Client Library and CLI for NotionInstallationHomebrew for CLIpipx for CLI usage anywherepippoetrypipenvAuthenticationCommand Line UsageOutput FormatsCommandsnotions apinotions searchnotions database listnotions database querynotions page getAPIDeveloping NotionsWhat's the deal with the name?InstallationHomebrew for CLIYou can use thenotions tapto install:brewtapmicktwomey/notions
brewinstallnotions# Or in one line: `brew install micktwomey/notions/notions`pipx for CLI usage anywhereTo install as a CLI and make it available on your PATH you can usepipxto install:pipxinstallnotionspipTo install usingpip:pipinstallnotionspoetryTo add as a depdency usingpoetry:poetryaddnotionspipenvTo add as a dependency usingpipenv:pipenvinstallnotionsAuthenticationCurrently only authentication using an Notion API token is supported (seeNotion's Getting Started Guidefor full details).Rough steps to get a token you can use:Go tohttps://www.notion.so/my-integrationsCreate a new internal integrationNote down the API key, you'll need that laterGo to a Database or page in your notion (a top level item in your sidebar) and click on the sharing buttonAdd your integration to the shares. You need to do this for every database you want to share, Notion doesn't expose everything by default.Command Line UsageAuthenticate first, seeAuthentication, and get your API token (we'll refer to it asYOUR_KEY_GOES_HEREbelow)You can either pass in the key each time you call the client usingnotions --notion-api-key YOUR_KEY_GOES_HEREor set theNOTION_API_KEYenvironment variable.To set in fish:set -Ux NOTION_API_KEY YOUR_KEY_GOES_HERETo set in bash/zsh:export NOTION_API_KEY=YOUR_KEY_GOES_HERECallnotions --helpto explore your optionsSome options are global and go before the command, e.g.notions --output-format notion_yaml database query --query foo.Output FormatsFormats you can specify withnotions --output-formatnotion_json- Parses API output and dumps back as JSON, with multiple items contained in a list.notion_jsonl- Parses API output and dumps back as JSON, one JSON object per line.notion_yaml- Parses API output and dumps back as YAML, with multiple items in a list.text(default) - Parse API output and return a simple text representation. Handy for looking up page and database ids.json- Parses API output and dumps to a flatter JSON, more suitable for templating and processsing. Multiple items are placed in a list.jsonl- Parses API output and dumps to a flatter JSON, one per line, more suitable for templating and processsing.yaml- Parses API output and dumps to a flatter YAML, more suitable for templating and processsing. Multiple items are placed in a list.tsv- Parses API output and writes out tab separated values.csv- Parses API output and writes out comma separated values.Commandsnotions apinotions apiallows you to issue requests using the authentication features of the client.To make a request and get back the response JSON:notions api METHOD PATH.To make a request and leverage the pagination support (this will parse the response and give you the option to render as YAML or other formats):notions api --paginate METHOD PATH. Note that due to how the flags are handled you need the--paginateto trigger parsing and allow for different output formats.# Get all databases, without pagination and return raw JSON from Notion's APInotionsapiGET/v1/databases/# Get all databases with pagination and format output as YAML# This is the same as `notions --output-format yaml database list`notions--output-formatyamlapiGET/v1/databases/--paginatenotions searchnotions searchallows you to search across all databases and pages you have shared with the Notion integration you created. You can restrict the search with--query SOME_QUERY_STRINGand items which have a matching title will be returned.# show all pages and dbs with "example" in their titlenotionssearch--queryexamplenotions database listnotions database listlists all the databases the integration has access to.notions database queryRun a query against all pages in a given database. You'll need the database UUID from something likenotions database list.# Show all pages in the given db and sort by the HP property in descending ordernotionsdatabasequerycc5ef123-05f5-409e-9b34-38043df965b0--sort-propertyHP:descendingnotions page getGet a single page.# Get a page in YAMLnotions--output-formatyamlpagegetccad10e7-c776-423e-9662-6ad5fb1256d6APIThe main way to use the library is via the HTTP client (seeexamples/basic.pyfor same code):"""Example showing basic use of the client for API calls"""importasyncioimportosimporttypingimporthttpxfromnotions.clientimportNotionAsyncClientfromnotions.models.databaseimportDatabaseasyncdefhttp_list_databases(notion_client:NotionAsyncClient)->httpx.Response:"""Do a HTTP call with authentication to list databasesThis uses notions as a convenience for HTTP calls using httpx"""asyncwithnotion_client.async_client()asclient:url=notion_client.get_url_for_path("/v1/databases")returnawaitclient.request("GET",url.url)asyncdeflist_databases(notion_client:NotionAsyncClient,)->typing.AsyncIterable[Database]:"""Do a list db call (automatically reads all pages)This is the same underlying call as `http_list_databases` abovebut will also parse the response and handle pagination.Will yield notions.models.database.Database"""asyncfordbinnotion_client.list_databases():yielddbasyncdefmain():api_token=os.environ.get("NOTION_API_KEY","no-token-set")notion_client=NotionAsyncClient(api_token)response=awaithttp_list_databases(notion_client)print(response)print(response.json())response.raise_for_status()asyncfordbinlist_databases(notion_client):print(db.id)print(db.title)print(db)if__name__=="__main__":asyncio.run(main())Developing NotionsTo develop locally you'll need python 3.6+,poetryand make:make depto set up the development environment.make testto test all supported pythons ormake pytestto run tests more directly for your python.You'll need a plan which allows for creating Notion integrations (API access) to develop against Notion, but I'm going to assume you have that if you're interested in this library :DTo release ensure you're happy with the current state of main and runmake release.What's the deal with the name?"Notions" is sometimes used in Ireland to refer to someone who has ideas abover their station ("so and so has notions"). It's typically Irish and a little bit mean, but often used in an ironic way. I picked it 'cos I thought it'd be funny (and maybe I have notions about writing a client library for a product produced by a company called Notion).