riko 0.73.0

Notes

Optional Dependencies

Notes

Why I built riko

Yahoo! Pipes [5] was a user friendly web application used to

aggregate, manipulate, and mashup content from around the web

Wanting to create custom pipes, I came across pipe2py which translated a Yahoo! Pipe into python code. pipe2py suited my needs at the time but was unmaintained and lacked asynchronous or parallel processing.

riko addresses the shortcomings of pipe2py and contains ~ 50 built-in modules, aka pipes, that allow you to programmatically perform most of the tasks Yahoo! Pipes allowed.

Why you should use riko

riko provides a number of benefits / differences from other stream processing applications such as Huginn, Flink, Spark, and Storm [6]. Namely:

• a small footprint (CPU and memory usage)

• native RSS/Atom support

• simple installation and usage

• a pure python library with supporting v3.12+

• builtin modular pipes to filter, sort, and modify streams

The subsequent tradeoffs riko makes are:

• not distributed (able to run on a cluster of servers)

• no GUI for creating flows

• doesn’t continually monitor streams for new data

• can’t react to specific events

• iterator (pull) based so streams only support a single consumer [7]

The following table summarizes these observations:

For more detailed information, please check-out the FAQ.

Notes

Usage Index

• Fetching feeds

• Synchronous processing

• Parallel processing

• Asynchronous processing

• Discovering modules

• API surface

• Pipeline lifecycle

• Fan-out (pubsub)

• Cookbook

Fetching feeds

riko can fetch rss feeds from both local and remote filepaths via “source” pipes. Each “source” pipe returns a stream, i.e., an iterator of dictionaries, aka items.

>>> from riko import get_path
>>> from riko.modules.fetch import pipe as fetch
>>> from riko.modules.fetchsitefeed import pipe as fetchsitefeed
>>>
>>> # Note: `get_path` looks up a cached copy of a url in the `data`
>>> # directory, so these examples run offline
>>>
>>> ### Fetch the first RSS feed found on a web page ###
>>> stream = fetchsitefeed(conf={'url': get_path('cnn.html')})
>>>
>>> ### Fetch an RSS feed ###
>>> stream = fetch(conf={'url': get_path('feed.xml')})
>>>
>>> ### View the fetched RSS feed(s) ###
>>> #
>>> # Note: regardless of how you fetch an RSS feed, it will have the same
>>> # structure
>>> item = next(stream)
>>> {'author', 'content', 'id', 'link', 'published', 'summary', 'title'} <= set(item)
True
>>> item['title'], item['author'], item['id']
('Donations', {'name': 'WriteToReply', 'uri': None}, 'http://writetoreply.org/?page_id=111')

Please see the FAQ for a complete list of supported file types and protocols. Please see Fetching data and feeds for more examples.

Synchronous processing

riko can modify streams via the 50 built-in pipes

>>> from riko import get_path
>>> from riko.collections import SyncPipe
>>>
>>> ### Set the pipe configurations ###
>>> fetch_conf = {'url': get_path('feed.xml')}
>>> filter_rule = {'field': 'title', 'op': 'contains', 'value': 'a'}
>>>
>>> ### Create a SyncPipe flow ###
>>> #
>>> # `SyncPipe` is a convenience class that creates chainable flows
>>> # and allows for parallel processing.
>>> #
>>> # The following flow will:
>>> #   1. fetch a (cached) RSS feed
>>> #   2. filter for items with an 'a' in the title
>>> #   3. sort the items ascending by title
>>> #
>>> # Note: sorting is not lazy so take caution when using this pipe
>>>
>>> flow = (
...     SyncPipe('fetch', conf=fetch_conf)               # 1
...         .filter(conf={'rule': filter_rule})          # 2
...         .sort(conf={'rule': {'field': 'title'}}))    # 3
>>>
>>> next(flow)['title']                                  # 4
'Donations'

Please see alternate workflow creation for an alternative (function based) method for creating a stream. Please see pipes for a complete list of available pipes.

Parallel processing

An example using riko’s parallel API to spawn a ThreadPool [14]

>>> from riko import get_path
>>> from riko.collections import SyncPipe
>>>
>>> ### Set the pipe configurations ###
>>> fetch_conf = {'url': get_path('feed.xml')}
>>> filter_rule = {'field': 'title', 'op': 'contains', 'value': 'a'}
>>>
>>> ### Create a parallel SyncPipe flow ###
>>> #
>>> # The following flow will:
>>> #   1. fetch a (cached) RSS feed
>>> #   2. filter for items with an 'a' in the title, in parallel (4 workers)
>>> #
>>> # Note: no point in sorting after the filter since parallel fetching doesn't guarantee
>>> # order
>>> flow = (
...     SyncPipe('fetch', conf=fetch_conf, parallel=True, workers=4)  # 1
...         .filter(conf={'rule': filter_rule}))                      # 2
>>>
>>> sorted(item['title'] for item in flow)                            # 3
['Donations', 'FAQ', 'General Comments', 'Notice & Takedown Policy', 'What’s it all about?']

Asynchronous processing

To enable asynchronous processing, you must install the async extra.

pip install riko[async]

An example using riko’s asynchronous API.

>>> from riko import get_path
>>> from riko.bado import run, issync
>>> from riko.collections import AsyncPipe
>>>
>>> ### Set the pipe configurations ###
>>> fetch_conf = {'url': get_path('feed.xml')}
>>> filter_rule = {'field': 'title', 'op': 'contains', 'value': 'a'}
>>>
>>> ### Create an AsyncPipe flow ###
>>> #
>>> # The following flow will:
>>> #   1. fetch a (cached) RSS feed
>>> #   2. filter for items with an 'a' in the title
>>> #   3. extract the first item's title
>>> async def main():
...     stream = await (
...         AsyncPipe('fetch', conf=fetch_conf)                 # 1
...             .filter(conf={'rule': filter_rule}))            # 2
...     print(next(stream)['title'])                            # 3
>>>
>>> if issync:
...     print('Donations')
... else:
...     run(main)
Donations

Discovering modules

from riko.collections import list_targets
from riko.modules import list_modules

# All modules
list_modules()

# All operators (broad, by decorator type)
list_modules(type='operator')

# All modules that support aggregation
list_modules(subtype='aggregator')

# Only modules whose default behavior is aggregation
list_modules(subtype='aggregator', primary=True)

# Full metadata for every module
list_modules(show_metadata=True)

# Available export targets (includes 'ofx'/'qif' only when csv2ofx is installed)
list_targets()

Semantics:

• type filters by decorator type (operator, processor, splitter).

• subtype filters against supported_subtypes.

• type and subtype are mutually exclusive — a subtype already implies its type.

• subtype in the metadata is the module’s default behavior.

• supported_subtypes includes behaviors reachable through options such as emit=True.

• Pass primary=True to match only the module’s default subtype; primary=True requires subtype.

• Module authors do not declare metadata attributes; it is derived from the decorator type, options, return annotation, and module name.

API surface

riko organizes its public interface into three import tiers:

• Stable — the top-level riko package (mirrored by riko.api) holds the SemVer-guaranteed API: the SyncPipe/AsyncPipe/SyncCollection/ AsyncCollection classes, Context, ExecutionMode, export, list_modules, list_targets, get_path, and the pipeline exceptions.

• Extension — riko.ext holds the symbols for authoring custom pipes: the processor/operator/splitter decorators and the module-metadata types.

• Private — every underscore-prefixed name or module (and the individual riko.modules.* implementations) is internal and may change without notice.

>>> import riko
>>> from riko import SyncPipe, get_path, export, list_modules
>>> from riko.ext import operator, processor, splitter
>>> sorted(riko.__all__)[:3]
['AsyncCollection', 'AsyncPipe', 'Context']

Pipeline lifecycle

A SyncPipe/AsyncPipe represents a single execution: iterating it consumes the stream, and iterating again yields an empty stream rather than silently re-running. Read the state/exhausted/closed/failed properties to inspect a pipe, and use it as a context manager (or call close()/terminate()) to release a parallel pipe’s worker pool deterministically.

>>> from riko.collections import SyncPipe, PipeState
>>>
>>> flow = SyncPipe('hash', source=[{'content': 'a'}, {'content': 'b'}])
>>> flow.state
<PipeState.NEW: 'new'>
>>> len(list(flow))
2
>>> flow.exhausted
True

See the cookbook for pool cleanup and the full state model.

Cookbook

Please see the cookbook or ipython notebook for more examples.

Notes

Notes

Fan-out (pubsub)

Sometimes you need to consume the same stream from multiple independent pipelines. For example, archiving every item while also sending urgent items, to an alert queue. Consuming the iterator twice would exhaust it, and materialising it into a list defeats lazy evaluation. riko solves this with the send and receive pipes.

• send is a transparent pass-through operator: it yields every item unchanged while pushing a copy to one or more named channels.

• receive is an independent pull iterator that drains a named receiver as items arrive.

Under the hood, each receiver is a generator-based coroutine (the same push pattern used by ijson). send calls .send(item) on the primed coroutine directly.

>>> from riko.modules.receive import pipe as receive
>>> from riko.modules.send import pipe as send
>>>
>>> stream = [{'title': 'Gravity paper', 'score': 42},
...           {'title': 'Breaking: riko 4.0', 'score': 980}]
>>>
>>> ### Prime a named receiver ###
>>> receiver = receive(conf={'name': 'receiver'})
>>> next(receiver)
{'state': <StreamState.PENDING: 1>}
>>>
>>> ### sender pushes items to 'receiver' ###
>>> sender = send(stream, others=['receiver'])
>>>
>>> ### Consuming the sender drives the push ###
>>> list(sender)
[{'title': 'Gravity paper', 'score': 42}, {'title': 'Breaking: riko 4.0', 'score': 980}]
>>>
>>> ### Drain the receiver independently ###
>>> # Note: an idle receiver yields a `PENDING` and `DONE` state markers, so filter
>>> # for real items when draining
>>> [item['title'] for item in receiver if 'title' in item]
['Gravity paper', 'Breaking: riko 4.0']

send composes naturally in a SyncPipe chain via .send(others=[...]). The stream continues down the main pipeline while a copy flows to each named receiver:

>>> from riko.collections import SyncPipe
>>> from riko.modules.receive import pipe as receive
>>>
>>> ### `archive` and `notify` stand in for your real side effects ###
>>> #
>>> # Note: a receive `func` automatically filters away state markers, e.g., `PENDING`
>>> archived, alerted = [], []
>>>
>>> ### Prime two named channels ###
>>> everything = receive(conf={'name': 'everything'}, func=archived.append)
>>> next(everything)
{'state': <StreamState.PENDING: 1>}
>>> breaking = receive(conf={'name': 'breaking'}, func=alerted.append)
>>> next(breaking)
{'state': <StreamState.PENDING: 1>}
>>>
>>> items = [
...     {'title': 'quiet', 'score': 42},
...     {'title': 'breaking: riko 4.0', 'score': 980},
...     {'title': 'also big', 'score': 750}]
>>>
>>> ### Send ALL items to 'everything', filter, then send matches to 'breaking' ###
>>> flow = (
...     SyncPipe(source=items)
...         .send(others=['everything'])
...         .filter(conf={'rule': [{'field': 'score', 'value': 500, 'op': 'greater'}]})
...         .send(others=['breaking'])
...         .sort(conf={'rule': [{'field': 'score'}]}))
>>>
>>> ### Consume the main pipeline (this also drives the pushes) ###
>>> [item['title'] for item in flow]  # sorted high score items
['also big', 'breaking: riko 4.0']
>>>
>>> ### Drain each receiver: each `func` runs as items arrive ###
>>> # When passed `func`, receivers contain the func return value. In this case, our
>>> # funcs mutate lists, so we don't care about the return results.
>>> _ = list(everything)
>>> [item['title'] for item in archived]  # all items in original order
['quiet', 'breaking: riko 4.0', 'also big']
>>> _ = list(breaking)
>>> [item['title'] for item in alerted]  # high score items in original order
['breaking: riko 4.0', 'also big']

Multiple receivers can listen on different channels from the same send call by passing additional names to others:

sender = send(stream, others=['breaking', 'archive', 'metrics'])

Each receiver is drained independently; draining one does not affect the others.

>>> from riko.modules.split import pipe as split
>>>
>>> items = [{'title': 'riko pt. 1'}, {'title': 'riko pt. 2'}]
>>> stream1, stream2 = split(items)
>>> next(stream1)
{'title': 'riko pt. 1'}
>>> next(stream2)
{'title': 'riko pt. 1'}

CLI Usage

usage: run-pipe [pipeid]

description: Runs a riko pipe

positional arguments:

pipeid The pipe to run (default: reads from stdin).

optional arguments:

-h, --help

show this help message and exit

-a, --async

Load async pipe.

-t, --test

Run in test mode (uses default inputs).

CLI Setup

flow.py

from riko.collections import SyncPipe

conf1 = {'attrs': [{'value': 'https://google.com', 'key': 'content'}]}
conf2 = {'rule': [{'find': 'com', 'replace': 'co.uk'}]}

def pipe(test=False):
    kwargs = {'conf': conf1, 'test': test}
    flow = SyncPipe('itembuilder', **kwargs).strreplace(conf=conf2)

    for i in flow:
        print(i)

CLI Examples

Now to execute flow.py, type the command run-pipe flow. You should then see the following output in your terminal:

https://google.co.uk

run-pipe will also search the examples directory for workflows. Type run-pipe demo and you should see the following output:

Deadline to clear up health law eligibility near 682

Compiling workflows

riko also ships two commands for working with JSON pipe definitions (the Yahoo! Pipes-style {"modules": [...], "wires": [...]} format):

• compile translates a JSON pipe definition into a runnable Python module.

• convert-dag expands a bare-bones DAG into a full JSON pipe definition.

A bare-bones DAG is a minimal authoring format: a list of modules (id/type/conf) plus optional [source, target] wire pairs. When wires are omitted the modules are chained linearly, and a missing id defaults to sw-{n}, so the terse form is just:

{
    "modules": [
        {"type": "fetchdata", "conf": {"url": "feed.json", "path": "value.items"}},
        {"type": "truncate", "conf": {"count": {"value": "3"}}}
    ]
}

Chaining the two commands turns a DAG straight into runnable Python (both write to stdout, or to a file via -o):

convert-dag flow.dag.json -o flow.json
compile flow.json -o flow.py

See docs/DAG_FORMAT.md for the full format and expansion rules.

Regenerating config types

Each module’s parse-time objconf type in riko/types/configs.py is generated from the matching <Name>Conf TypedDict contract in riko/types/modules.py. After editing a contract, regenerate and reformat the config types with a single command:

gen-config

A drift guard (tests/internal/test_gen_config.py) fails if the two layers fall out of sync.

Setup

pip install riko[develop]

Examples

Run python linter and nose tests

manage lint
manage test