Python
AI assisted, human approved — novem uses AI to review and keep our documentation up to date.
The novem python api provides utility and convenience functions for using the novem api from python.
The primary use-case is creating charts based on pandas dataframes, but other relevant novem functionality is also exposed through the api.
This document explains the overall design of the library and how to use it, for examples of specific use-cases please see the relevant sections on plots and e-mails.
The novem python library requires python 3.8.5 or higher and is available from PyPI. The source code can also be found on our GitHub.
pip install novem
Once the novem library is installed you can run python -m novem --init (or
just novem --init depending on your system setup) to generate a new token and
create the default config file.
For more details, please see documentation for the novem cli.
username@computer:~/$ python -m novem --init
• novem.io username: <your_username>
• novem.io password: <your_password>
✓ authenticated
✓ token created
✓ new token "novem-python-computer-rj8chk2j" saved to ~/.config/novem/novem.conf
username@computer:~/$ _
Every novem object needs a token and an API root to reach the platform. They are resolved, in order of precedence, from:
- an explicit keyword argument on the object (or a
Session, see below) - values set programmatically on
novem.config - the
NOVEM_TOKEN/NOVEM_API_ROOTenvironment variables - the config file written by
python -m novem --init
The config file (step 4) is the simplest setup. To configure novem
programmatically instead — handy in notebooks, scripts or CI — set a token on
the global novem.config once, and every object created afterwards picks it up
automatically:
import novem
novem.config.set_token("your-token")
plot = novem.Plot("my-plot")
novem.config also exposes set_api_root(...) to point at a non-default API,
and use_profile(...) to select a profile from the config file.
To override the global default for a single object, pass the token straight to the constructor — an explicit argument always wins:
plot = novem.Plot("my-plot", token="your-token")
A Session captures connection settings (a token and api root, or a config-file
profile) and constructs objects bound to them without touching the global
defaults — useful when working against several accounts at once:
import novem
work = novem.Session(profile="work")
personal = novem.Session(profile="personal")
# copy a plot's data from one account to the other
personal.Plot("earnings").data = work.Plot("earnings").data
The plot module exposes a novem plot class that maps to the /v1/vis/plots/ api end-point.
The class takes one positional parameter, the plot name, and several optional named parameters. All the named parameters in the constructor are also available as properties.
"""
Below we show the various ways you can set the options on your novem plot
"""
from novem import Plot
# everything in the constructor
barchart = Plot('barchart',
type='bar',
title='barchart title',
caption='caption',
)
# property approach
barchart = Plot('plot_name')
barchart.type = 'bar'
barchart.title = 'barchart title'
barchart.caption = 'caption'
The mail module exposes a novem plot class that maps to the /v1/vis/mails/ api end-point.
The class allows two primary way of constructing an e-mail. Either by supplying a novem markdown document as a content file or constructing the e-mail programmatically.
from novem import Mail
mail = Mail('name') # create mail object
mail.to = "user@example.com" # add recipient
with open('content.txt', 'r') as f:
mail(f) # add content to mail
mail.send()
from novem import Mail
from novem.mail import PreviewSection, MarkdownSection
mail = Mail('name') # create mail object
mail.to = "user@example.com" # add recipient
mail.subject = "Test e-mail"
mail.add_section(PreviewSection("""
Preview summary that is not visible in the main
body of the mail
"""))
mail.add_section(MarkdownSection("""
Markdown text for text section
"""))
mail.send()
The full python API reference: