skip to navigation
skip to content

topic-db 0.7.1

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

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)


File Type Py Version Uploaded on Size
topic-db-0.7.1.tar.gz (md5) Source 2017-06-16 16KB
topic_db-0.7.1-py3-none-any.whl (md5) Python Wheel py3 2017-06-16 25KB