dfo.cards stores a chart, a table, or a headline number that DFO draws from a Dataset, and dfo.share publishes cards under one link that a page or an embed shows.
Cards and shares are public. Anyone with a share's link sees its page and can download the data behind each card from its data URLs, with no key. Share only data you would publish.
The blocks on this page run in order, as cells of one notebook.
A card draws one version of one Dataset, every series it holds, so narrow the rows first. Make a line chart and a headline number of German aid per person in Kenya, then publish both:
Card(line cmp_01M6292M9NTCMEE39WWMRRJXKZ, "German aid per person in Kenya", 1 series, draws ops_0fe63aa61ade066c970f174bf2392339 at ocv_129d9b2f36f398bb414c5f7a97230804)
Card(stat cmp_01M6292MB9ZN8GGHMP87CHF20A, "Change since 2018", 1 series, draws ops_0fe63aa61ade066c970f174bf2392339 at ocv_129d9b2f36f398bb414c5f7a97230804)
Share(live https://developmentfinance.org/s/7NHGA70g, 2 slots, revision 1)
https://developmentfinance.org/s/7NHGA70g
https://developmentfinance.org/embed/7NHGA70g
import dfo
aid = dfo.search("ODA from Germany to Kenya, 2018 to 2023").fetch()
people = dfo.search("Kenya population, 2018 to 2023").fetch()
per_person = dfo.analysis.quotient_of(aid, people, on={"destination": "place"})
line = dfo.cards.line(per_person, title="German aid per person in Kenya")
stat = dfo.cards.stat(
per_person, year=2023, compare_to=2018, change="percent", title="Change since 2018"
)
print(line)
print(stat)
share = dfo.share([line, stat], latest=True)
print(share)
print(share.url)
print(share.embed_url)Each card takes a slot, numbered from 1 in the order given. share.url is the page, share.embed_url the same cards for an iframe, and share.data_urls holds one download link per slot.
latest has no default, because it decides what the link shows over time:
latest=Truemakes a live share. Each card follows new data. A card of a Dataset fetched from a Spec or a recipe draws the newest version each time DFO publishes one, and a window ofdfo.latest_year(...)moves with it. A live share also takes new cards under the same link.latest=Falsemakes a snapshot. Each card keeps the version it draws today, for good.
Each caller has a daily allowance of cards. Once it is spent, dfo.cards raises QuotaExceededError (allowance_exhausted) with retry_after, the seconds until it resets.
dfo.cards has five kinds:
| Function | Draws |
|---|---|
line(data, window=None, title=None) |
One line per series over time |
bar(data, window=None, title=None) |
Bars that compare the series' members or the years |
table(data, window=None, title=None) |
Every series over the years |
stat(data, year=None, compare_to=None, change="difference", title=None) |
One value of a single series, with its change since compare_to |
source(data) |
The source, licence, dates, and citation of the data |
window takes (start, end), each a year or a dfo.latest_year(offset). A stat card's change="difference", the default, is the shown value minus the earlier one, in the data's unit. change="percent" is that difference as a percentage of the earlier value: 25.0 is a 25% rise. Without a title, DFO writes one from the data.
DFO gives a share's write token, shw_…, once, in the reply that makes the share. The client keeps it on the Share as share.write_token and leaves it out of the repr. Changing or taking down the share later needs it, so store it beside the URL, somewhere private:
import json
from pathlib import Path
Path("share.json").write_text(
json.dumps({"url": share.url, "write_token": share.write_token})
)Anyone with the token can change the share or take it down. A lost token cannot be recovered, and the share stays up.
dfo.share(cards, latest=True, replace=share) puts new cards on a live share under the same URLs, and raises its revision:
Share(live https://developmentfinance.org/s/7NHGA70g, 2 slots, revision 2)
recent = dfo.cards.table(
per_person,
window=(dfo.latest_year(-2), dfo.latest_year()),
title="German aid per person in Kenya, last three years",
)
share = dfo.share([recent, stat], latest=True, replace=share)
print(share)A Share carries its token. In a later session, pass the URL and the stored token:
saved = json.loads(Path("share.json").read_text())
share = dfo.share(
[recent, stat], latest=True, replace=saved["url"], write_token=saved["write_token"]
)replace takes a Share or the URL of its page or embed. A snapshot cannot be replaced. replace with latest=False raises InvalidRequestError before any request, and DFO refuses a snapshot's URL with share_not_replaceable. A replace with fewer cards leaves the later slots empty. Their data URLs answer not found, and dfo.fetch(share, slot=n) of an empty slot raises NotFoundError.
dfo.snapshot(share) turns a live share into a snapshot under the same URLs. Each slot keeps the version it shows now:
Share(snapshot https://developmentfinance.org/s/7NHGA70g, 2 slots, revision 4)
share = dfo.snapshot(share)
print(share)It sends the share's own token, or the one passed as write_token=.
dfo.fetch(share) returns the Dataset a slot shows now, dfo.history(share) lists what each slot has served, and dfo.fetch(share, as_of=...) returns what a slot showed on a past date. Pass slot= when the share has more than one:
<Dataset Computed by DFO: quotient_of.
Source: OECD DAC2A; World Development Indicators
Derived: quotient_of by financingRecipient, from 2 readings
Shown by: share 7NHGA70g, slot 1 "German aid per person in Kenya, last three years", on 28 October 2026
Version: ocv_129d9b2f36f398bb414c5f7a97230804 (exact), pinned
Rows: 6, time_period as text, such as "2022" or "2021/2022"
Keep: data.save(path) · newest later: dfo.fetch(data.ref, latest=True)>
Served(slot 1 cmp_01M6291ENV6KNJHFWJHWNR7JD9 from 28 Oct 2026: ops_0fe63aa61ade066c970f174bf2392339 at ocv_129d9b2f36f398bb414c5f7a97230804 · fetchable)
import datetime
shown = dfo.fetch(share, slot=1)
print(shown)
for served in dfo.history(share):
print(served)
today = dfo.fetch(share.url, slot=1, as_of=datetime.date.today())as_of takes a date, read as the end of that day in UTC, a datetime, read as UTC when it has no time zone, or ISO text such as "2026-10-28". The fetch returns the version the slot first served on or before that moment, and raises InvalidRequestError when the slot served nothing by then. Without as_of, it returns the version the slot shows now. The repr's Shown by line names the share, the slot, the card's title, and the day.
dfo.history(share) lists every version each slot served, newest first, as Served entries, and needs no token. A slot's entry appears once the share serves it, when a page, an embed, or a fetch first reads the slot. An entry marked fetchable can still be fetched. Each version a share serves is pinned, so it stays fetchable while the share is up. When a replace leaves a slot without a card, history adds an entry for that slot with card_id, card_revision, spec_id, and content_version all None, and fetch(share, slot=n, as_of=...) raises NotFoundError for a moment after it, until a later replace fills the slot.
A share fetch reads the frame layout, and refuses window, entities, facets, party_totals, latest=True, and any other layout, before any request.
dfo.unshare(share) takes the link down. Pass a URL with its stored token:
dfo.unshare(saved["url"], write_token=saved["write_token"])Taking a share down again with its token succeeds, so a retry after a lost reply is safe. After that, dfo.history and dfo.fetch of the share raise NotFoundError.
client.cards on a Client or AsyncClient has the same methods. Each returns a Card.
| Name | Signature |
|---|---|
line |
line(data, /, *, window=None, title=None) |
bar |
bar(data, /, *, window=None, title=None) |
table |
table(data, /, *, window=None, title=None) |
stat |
stat(data, /, *, year=None, compare_to=None, change="difference", title=None) |
source |
source(data, /) |
data takes a Dataset or a DatasetRef of one version, a dataset version or a derived one. These raise InvalidRequestError (invalid_argument) before any request: a Spec, a Recipe, or text, which you fetch first; a Dataset of several members; a Dataset with no rows; compare_to without year; and change without compare_to. change takes "difference" or "percent".
dfo.types.Card: id (cmp_…), revision, kind (line, bar, table, stat, or source), ref, the version it draws, title, held_until, pinned, and write_token (cmw_…, left out of the repr).
dfo.share(cards, /, *, latest, replace=None, write_token=None) -> Share, also client.share. cards takes a Card or a list of them. replace takes a live Share or its URL, and needs latest=True. write_token goes with replace only, and wins over the Share's own.
dfo.snapshot(share, /, *, write_token=None) -> Sharedfo.unshare(share, /, *, write_token=None) -> Nonedfo.history(share, /) -> tuple[Served, ...]
Each takes a Share or the URL of its page or embed, as https://developmentfinance.org/s/7NHGA70g. A bare share id raises InvalidRequestError. snapshot and unshare send write_token, else the Share's own token.
dfo.types.Share: id, url, embed_url, data_urls, one per slot, revision, latest, True for a live share, and write_token, left out of the repr.
dfo.types.Served, an entry of dfo.history: slot, card_id, card_revision, spec_id, content_version, all None for a slot left without a card, first_served, a UTC datetime, pinned, held_until, and fetchable.
dfo.fetch(target, /, *, as_of=None, slot=None, strict=False, timeout=CLIENT_TIMEOUT, progress=None) with a Share or its URL. slot counts from 1 and may be left out for a share of one slot. as_of takes a date, a datetime, or ISO text.
| Code | Class | Raised when |
|---|---|---|
write_token_required |
InvalidRequestError |
A change to a share carried no token |
write_token_invalid |
PermissionDeniedError |
The token is not the share's |
share_not_replaceable |
InvalidRequestError |
replace names a snapshot |
allowance_exhausted |
QuotaExceededError |
The day's share allowance is spent; retry_after says when it resets |
not_found |
NotFoundError |
No share has that id, or it was taken down |
- Compute a figure on DFO makes the derived results cards draw.
- Errors lists every code a share call can raise.