Python

The novem Python library creates and manages resources through the API. Use it to build plots from pandas DataFrames, compose e-mails, and update resource settings from Python code.

Installation

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.

python -m novem --init

Configuration and authentication

Every novem object needs a token and an API root to reach the platform. They are resolved, in order of precedence, from:

1. an explicit keyword argument on the object (or a Session, see below)
2. values set programmatically on novem.config
3. the NOVEM_TOKEN / NOVEM_API_ROOT environment variables
4. the config file written by python -m novem --init

To configure a notebook, script, or CI task programmatically, set the token on novem.config. Objects created afterwards use that token unless you supply an explicit override:

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 to the constructor. An explicit argument takes precedence:

plot = novem.Plot("my-plot", token="your-token")

Multiple accounts

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

Plot

The Plot class maps to /v1/vis/plots/ in the API.

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'

Mail

The Mail class maps to /v1/vis/mails/ in the API. Supply Novem Markdown from a file or compose the content with the section classes.

Load Markdown from a file

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()

Compose content in Python

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()

Reference

Python API reference:

• Plot — the Plot class and table subclasses.
• Mail — the Mail class, attributes and the sections API.
• Utilities — selectors and helper classes.