Quickstart

Process all cables

cablemap.core provides a utility function which returns an iterable over all cables:

from cablemap.core import cables_from_source

for cable in cables_from_source('cables.csv'):
    print(cable.subject)

This function accepts also a directory which must contain HTML files and should follow the directory layout of the WikiLeaks Cablegate archive:

from cablemap.core import cables_from_source

for cable in cables_from_source('./cables/'):
    print(cable.subject)

The returned objects are cablemap.core.interfaces.ICable instances.

Process cables with an event handler

It is also possible to process the cables with an cablemap.core.interfaces.ICableHandler:

from cablemap.core import handle_source
from cablemap.core.handler import NoopCableHandler

class MyCableHandler(NoopCableHandler):

    def start_cable(self, reference_id, canonical_id):
        print("Start processing #%s" % canonical_id)

    def end_cable(self):
        print("Done with the current cable")

    def handle_subject(self, subject):
        print("Cable's subject: %s" % subject)


# handle_source('/path/to/directory/', MyCableHandler()) is also possible
handle_source('cables.csv', MyCableHandler())

The module cablemap.core.handler provides some ICableHandler implementations to pre-process and filter cables:

from cablemap.core import handle_source
from cablemap.core.handler import NoopCableHandler, \
                                  DefaultMetadataOnlyFilter, TeeCableHandler

class MyCableHandler(NoopCableHandler):

    def start_cable(self, reference_id, canonical_id):
        print("Start processing #%s" % canonical_id)

    def end_cable(self):
        print("Done with the current cable")

    def handle_subject(self, subject):
        print("Cable's subject: %s" % subject)

# The DefaultMetadataOnlyFilter swallows events like "handle_content" or "handle_header"
handler = DefaultMetadataOnlyFilter(MyCableHandler())
handle_source('cables.csv', handler)

# The TeeCableHandler delegates the events to two `ICableHandler` instances
# The following example is a bit useless since it uses two MyCableHandler instances
tee_handler = TeeCableHandler(MyCableHandler(), MyCableHandler())
handle_source('cables.csv', tee_handler)

# Combine the TeeCableHandler and the DefaultMetadataOnlyFilter
# Result: The underlying MyCableHandler instances will not receive
# "handle_header"/"handle_content" events
handler = DefaultMetadataOnlyFilter(TeeCableHandler(MyCableHandler(), MyCableHandler()))
handle_source('cables.csv', handler)

# Another possibility: One MyCableHandler receives no "handle_header"/"handle_content"
# events while the other receives all events:
handler = TeeCableHandler(DefaultMetadataOnlyFilter(MyCableHandler()), MyCableHandler())
handle_source('cables.csv', handler)