Add novem.config + Session, fix the kwargs sprawl (0.6)

CLI.md

@@ -2,53 +2,115 @@
 The novem cli provides a simple and easy way to interact with the novem service
 from the command line. Below is a set of examples followed by some details.
 
-For a shorthand overview you can always use the `-h` or `--help` commands
+For a shorthand overview you can always use the `-h` or `--help` commands, and
+see [novem.io](https://novem.io) for the full documentation.
 
-## Examples
+The resource you operate on is selected by a flag: `-p` plot, `-g` grid,
+`-m` mail, `-d` doc, `-j` job. Most examples below use `-p`, but the same
+options apply to the other resource types.
+
+
+## Authentication
 ```bash
-  # create a new line chart with no data
-  novem -p test_chart -t line
+  # interactively set up a profile (username/password or token) in the config file
+  novem --init
+
+  # authenticate with an existing token instead
+  novem --init token
+
+  # one-off: pick a non-default profile, or pass a token directly
+  novem --profile work -p my_chart
+  novem --token <token> -p my_chart
+
+  # the NOVEM_TOKEN / NOVEM_API_ROOT environment variables are also honoured
+```
 
-  # write data to the line chart, three different ways
-  novem -p test_chart -w data @data.csv                   # explicitly specify file and endpoint
-  cat data.csv | novem -p test_chart -w data              # send stdin to endpoint
-  cat data.csv | novem -p test_chart                      # send stdin to default endpoint (/data)
 
-  # write description from markdown file
-  cat desc.md | novem -p test_plot -w description         # send content from stdin to /description
+## Creating and writing visualisations
+```bash
+  # create a new line chart with no data (--type sets the chart type)
+  novem -p test_chart --type line
 
-  # write caption from file
-  cat caption.md | novem -p test_plot -w config/caption   # send content from stdin to /config/caption
+  # write data to the chart, three different ways
+  novem -p test_chart -w data @data.csv         # write a file to the /data endpoint
+  cat data.csv | novem -p test_chart -w data     # send stdin to the /data endpoint
+  cat data.csv | novem -p test_chart             # send stdin to the default (/data) endpoint
 
-  # create a plot and open the url with chrome on linux (use open for mac)
-  cat data.csv | novem -p plot_name -t line -r url | xdg-rpen
+  # write description / caption from a markdown file via stdin
+  cat desc.md    | novem -p test_chart -w description
+  cat caption.md | novem -p test_chart -w config/caption
 
-  # Create a new view and have the browser show it, then create a new line chart and display it in
-  # the view
-  novem -v default_view -r url | xdg-rpen                                     # create the view
-  cat data.csv | novem -p plot_name -t line -r url | novem -v default_view    # create chart and show
+  # create a grid, a mail and a doc
+  cat layout.txt | novem -g  dashboard
+  cat body.md    | novem -m  welcome --subject "Hello" --to a@b.com
+  cat report.md  | novem -d  q1_report
+```
 
-  # list all plots with a detailed view
+
+## Reading, listing and deleting
+```bash
+  # read a value (e.g. the public url) and open it in the browser
+  novem -p plot_name -r url | xdg-open   # use `open` on macOS
+
+  # create a chart and print its url in one go
+  cat data.csv | novem -p plot_name --type line -r url
+
+  # list all plots (use -l for ids only)
+  novem -p
   novem -p -l
 
   # delete a plot
   novem -p old_plot_name -D
+```
 
-  # make a plot public
-  novem -p plot_name -s public
 
-  # make a plot private
-  novem -p plot_name -s public -D
+## Sharing
+Add a share with `-C`, remove it with `-D`, and list current shares with a
+bare `-s`.
+```bash
+  # list current shares
+  novem -p plot_name -s
 
-  # share a plot with a usergroup
-  novem -p plot_name -s @username~groupname
+  # make a plot public / remove the public share
+  novem -p plot_name -s public -C
+  novem -p plot_name -s public -D
 
-  # unshare a plot with a usergroup
+  # share / unshare with a user group
+  novem -p plot_name -s @username~groupname -C
   novem -p plot_name -s @username~groupname -D
 
-  # share a plot with a org-group
-  novem -p plot_name -s +orgname~groupname
-
-  # unshare a plot with a org-group
+  # share / unshare with an org group
+  novem -p plot_name -s +orgname~groupname -C
   novem -p plot_name -s +orgname~groupname -D
 ```
+
+
+## Tagging
+Tags work like shares: `-C` to add, `-D` to remove, bare `-t` to list. Multiple
+tags can be comma-separated.
+```bash
+  # list current tags
+  novem -p plot_name -t
+
+  # add / remove tags
+  novem -p plot_name -t fav -C
+  novem -p plot_name -t fav,+demo -C
+  novem -p plot_name -t fav -D
+```
+
+
+## Raw API access
+```bash
+  # read / write arbitrary api paths
+  novem --get vis/plots/plot_name/url
+  novem --post vis/plots/plot_name/data @data.csv
+  novem --put  vis/plots/plot_name/config/type line
+  novem --delete vis/plots/plot_name
+```
+
+
+## Inspecting structure
+```bash
+  # print the api tree for a visualisation
+  novem -p plot_name --tree
+```

README.md

@@ -1,40 +1,43 @@
 
 # novem - data visualisation for coders
 
-A wrapper library for the novem.no data visualisation platform. Create charts,
+A wrapper library for the novem.io data visualisation platform. Create charts,
 documents, e-mails and dashboards through one simple API.
 
 **NB:** novem is currently in closed alpha, if you want to try it out please
-reach out to hello@novem.no
+reach out to hello@novem.io
 
 
-## Exampels
+## Examples
 
-Create a linechart from a dataframe using pandas data reader
+Create a linechart from a pandas dataframe (assumes a configured profile —
+see "Getting started" below).
 
 ```python
-from pandas_datareader import data
+import numpy as np
+import pandas as pd
 from novem import Plot
 
-line = Plot("aapl_price_hist", type="line", name="Apple price history")
+# a sample price-like series; swap in your own dataframe. Name the index and
+# series so the CSV has a proper "Date,Price" header.
+dates = pd.date_range("2015-01-01", "2021-12-31", freq="B", name="Date")
+prices = pd.Series(
+    100 + np.random.randn(len(dates)).cumsum(), index=dates, name="Price"
+)
 
-# Only get the adjusted close.
-aapl = data.DataReader("AAPL",
-                       start="2015-1-1",
-                       end="2021-12-31",
-                       data_source="yahoo")["Adj Close"]
+line = Plot("price_hist", type="line", name="Sample price history")
 
 # send data to the plot
-aapl.pipe(line)
+prices.pipe(line)
 
-# url to view plot
+# url to view the plot
 print(line.url)
 ```
 
 
 ## Getting started
 To get started with novem you will have to register an account. Please
-[reach out](mailto:hello@novem.no) to us!
+[reach out](mailto:hello@novem.io) to us!
 
 Once you have a username and password you can setup your environment using:
 ```bash
@@ -46,6 +49,54 @@ includes an extensive command-line interface (cli). Check out CLI.md in this
 repository or [novem.io](https://novem.io) for more details.
 
 
+## Configuration and authentication
+Every novem object needs a token and an API root to talk to the platform.
+These are resolved, in order of precedence, from:
+
+ 1. explicit keyword arguments on the object (or a `Session`, see below)
+ 2. values set programmatically via `novem.config`
+ 3. the `NOVEM_TOKEN` / `NOVEM_API_ROOT` environment variables
+ 4. the config file written by `python -m novem --init`
+
+The simplest setup is the config file (`--init` above). To configure novem
+programmatically instead — handy in notebooks, scripts or CI — set a token on
+the global `novem.config` object once, and objects created afterwards pick it
+up automatically:
+
+```python
+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).
+
+Alternatively, pass the token straight to the object. An explicit argument
+always wins over whatever is on `novem.config`:
+
+```python
+plot = novem.Plot("my-plot", token="your-token")
+```
+
+### Multiple accounts / profiles
+A `Session` captures connection settings (token, 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:
+
+```python
+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
+```
+
+
 
 ## Creating a plot
 Novem represents plots as a `Plot` class that can be imported from the main

novem/__init__.py

@@ -1,10 +1,12 @@
 from .claim import Claim
 from .comments import Comment, Context, Message, Topic
+from .config import NovemConfig, config
 from .events import EventMessage, Events
 from .group.org import Org
 from .job import Job
 from .profile import Profile
 from .repo import Repo
+from .session import Session
 from .version import __version__
 from .vis.doc import Doc
 from .vis.grid import Grid
@@ -27,5 +29,8 @@
     "Comment",
     "Topic",
     "Message",
+    "config",
+    "NovemConfig",
+    "Session",
     "__version__",
 ]