Skip to main content

TopicDB is a topic map-based graph library (using PostgreSQL for persistence).

Project description

TopicDB is a topic map-based graph library (using PostgreSQL for persistence).

For a more in-depth introduction to topic maps, I recommend reading the excellent introductory article on topic maps over at MSDN: An Introduction to Topic Maps. With that being said, although TopicDB is inspired by the topic maps paradigm, it is not (and never will be) an implementation of the ISO/IEC 13250 Topic Maps data model standard.

TopicDB is intended to be used by other Python applications, and currently does not provide a web interface to the API. Story Engine is a good example of TopicDB being used by another application.


I build (story) worlds. TopicDB plays a crucial role in that endeavour: Interactive Scene Browser for Stories.

Feature Support

  • Pending


TopicDB officially supports Python 3.3–3.6. To install TopicDB, simply:

$ pip install topic-db

First-Time Use

from import TopicStore
from import RetrievalOption

from topicdb.core.models.topic import Topic
from topicdb.core.models.language import Language


# Instantiate and open topic store.
with TopicStore(username, password) as store:

    # Create the topic map and bootstrap default topics.
    store.set_topic_map(TOPIC_MAP_IDENTIFIER, "Topic Map Test")

    topic1 = Topic(identifier='test-topic1',
                   base_name='Tópico de Prueba',

    # Persist topic to store.
    if not store.topic_exists(TOPIC_MAP_IDENTIFIER, 'test-topic1'):
        store.set_topic(TOPIC_MAP_IDENTIFIER, topic1)

    # Retrieve topic from store (with the accompanying topic attributes).
    topic2 = store.get_topic(TOPIC_MAP_IDENTIFIER, 'test-topic1',


To get a better understanding of how to use TopicDB, check out the tutorial, here: TopicDB Tutorial (work-in-progress).


Documentation will be available soon.

How to Contribute

  1. Fork the repository on GitHub to start making your changes to the master branch (or branch off of it).
  2. Write a test which shows that the bug was fixed or that the feature works as expected.
  3. Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to AUTHORS.

Release History

0.7.1 (2017-06-16)


  • Refactored code base (specifically, the unit tests) to use the topic store as a context manager.
  • Updated pytest dependency (to latest version).


  • Fixed a context manager-related bug (in the TopicStore class).

0.7.0 (2017-06-15)


  • Various (API) improvements and fixes throughout the codebase (specifically, the TopicStore class) resulting in the bump of the project’s development status (now Beta).

0.6.0 (2017-03-04)


  • Moved away from SQLite to PostgreSQL as the persistence store.
  • Moved away from the ‘command’ pattern to the ‘repository’ pattern.

0.5.0 (2017-01-15)


  • Refactored Get* command classes (i.e., instance_of, scope, and language parameters) for the purposes of consistency and flexibility.
  • Removed hard-code maximum-depth in GetTopicsHierarchy command class.
  • Renamed several command classes to more accurately reflect their purpose.
  • Refactored code to ensure better compliance with PEP 8 (Style Guide for Python Code).


  • Fixed several command classes with regards to not closing SQLite cursor objects.

0.4.0 (2017-01-08)


  • Renamed GetAssociations command class to GetTopicAssociations.
  • Refactored topic map-related commands and models, including changes to the topic map definition (SQL).
  • Renamed several (important) variables for the purpose of improving clarity and consistency.

0.3.0 (2016-12-30)


  • Added functionality to delete associations (i.e., DeleteAssociation command class).

0.2.0 (2016-12-28)


  • Provided OntologyMode (either STRICT or LENIENT).
  • Sanitized backing store (SQLite) indexes.

0.1.1 (2016-12-26)


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for topic-db, version 0.7.1
Filename, size & hash File type Python version Upload date
topic_db-0.7.1-py3-none-any.whl (25.6 kB) View hashes Wheel py3
topic-db-0.7.1.tar.gz (17.1 kB) View hashes Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page