The Topic Map processor is a piece of software that is capable of importing, exporting, querying and manipulating Topic Maps. Topic Maps is defined in an international standard, ISO/IEC 13250 Topic Maps.
See the reference documentation for a complete overview of topic map classes and their methods. Only a few of them are mentioned here in this introduction. For an introduction to the Topic Map concept itself see the standard or the papers at the Infoloom site.
The topic map processor can be started using the tmproc.py script. This tool takes several command line arguments. Use the -i option with the python interpreter to enter interactive mode after processing.
python [-i] tmproc.py [options] file.xml Options: --validate : use a validating SGML/XML parser --debug : write debug messages to stdout --arch=? : do architectural processing on the file, where ? is the architecture name --name : the name of the topic map --test : dump information about the topic map to stdout --module=? : load the topic map classes from the specified python module [default: tm]
The following command will import the topic map that is stored in the XML file music.xml
python -i tmproc.py music.xml
An example of architectural processing in combination with topic map processing (requires xmlarch).
python -i tmproc.py --arch=TOPICMAP playsmap1.xml
The music.xml file contains a sample topic map about The Beatles. The examples in this introduction is taken from that topic map. Play around with it yourself in order to see what it is about.
In all the examples below the tm object is an instance of the TopicMap class. When you execute tmproc.py in interactive mode an object called tm is available. The tm object is the resulting topic map after the import of the topic map document.
The string representation of a topic consists of the following
parts "<" + the name of the topic map module + "." + the name
of the Topic class + " " + the SGML id of the topic + ">"
.
Example: <tm.Topic t-lennon-john>
, where
tm
is the topicmap module and Topic
is
the topic class. t-lennon-john
is the SGML id of the
topic.
>>>
tm["t-lennon-john"]
<tm.Topic t-lennon-john>
>>>
tm.get_topic_by_sgml_id("t-starr-ringo")
<tm.Topic t-starr-ringo>
>>>
tm.get_topics()
[<tm.Topic at-born-in>, <tm.Topic t-1943-02-25>, <tm.Topic at-played-instrument-in>, <tm.Topic at-member-of>, <tm.Topic t-the-beatles>, <tm.Topic st-ettbinds-leksikon>, <tm.Topic t-starr-ringo>, <tm.Topic tt-guitarist>, <tm.Topic tt-bassist>, <tm.Topic tt-geography>, <tm.Topic tt-time>, <tm.Topic st-music>, <tm.Topic tt-musician>, <tm.Topic t-england>, <tm.Topic tt-pop-music>, <tm.Topic tt-city>, <tm.Topic t-mccartney-paul>, <tm.Topic st-store-norske-leksikon>, <tm.Topic tt-webpage>, <tm.Topic t-1940-09-10>, <tm.Topic ft-birth-date>, <tm.Topic t-1940-07-07>, <tm.Topic tt-artist>, <tm.Topic tt-country>, <tm.Topic t-liverpool>, <tm.Topic tt-julian-date>, <tm.Topic tt-vocalist>, <tm.Topic t-lennon-john>, <tm.Topic tt-person>, <tm.Topic tt-rock>, <tm.Topic tt-drummer>, <tm.Topic normalized>, <tm.Topic tt-music>, <tm.Topic tt-rock-music>, <tm.Topic tt-encyclopedia-article>, <tm.Topic t-1942-06-18>, <tm.Topic t-harrison-george>, <tm.Topic at-located-in>, <tm.Topic tt-band>]
>>>
tm.get_associations()
[<tm.Association instance at 81a1558>, <tm.Association instance at 81a15b0>, <tm.Association instance at 81a1f78>, <tm.Association instance at 81a2068>]
>>>
tm.get_facets()
[<tm.Facet instance at 81a3578>]
>>>
tm.is_type(tm["t-harrison-george"], tm["tt-guitarist"])
0
>>>
tm.is_type(tm["t-harrison-george"], tm["tt-person"])
1
>>>
tm.is_type(tm["t-harrison-george"], tm["tt-person"], transitive=1)
1
>>>
tm.has_topic(tm["t-dylan-bob"])
0
>>>
tm.has_topic(tm["t-lennon-john"])
1
Other variants:
tm.has_association(association)
tm.has_facet(facet)
>>>
tm.get_types_list(tm["t-mccartney-paul"])
[<tm.Topic tt-person>]
>>>
tm.get_types_list(tm["t-mccartney-paul"], transitive=1)
[<tm.Topic tt-person>]
>>>
tm.get_types_hierarchy(tm["t-mccartney-paul"])
[<tm.Topic t-mccartney-paul>, [<tm.Topic tt-person>]]
The generic method for this is TopicMap.get_object_types(self, tm_objects=None, transitive=0)
.
Returns a list of topics that are used as topic types
The method get_topic_types
may take up to three
parameters. topics
can be a list of topics, but if
None is specified all Topics of the TopicMap is evaluated. If
transitive
set to a true value all transitive types
[ie. types of types] are included in the result.
Get the types of all topics in the topic map
>>>
tm.get_topic_types()
[<tm.Topic tt-artist>, <tm.Topic tt-geography>, <tm.Topic tt-band>, <tm.Topic tt-music>, <tm.Topic tt-musician>, <tm.Topic tt-time>, <tm.Topic tt-country>, <tm.Topic tt-city>, <tm.Topic tt-person>]
Get the types of two topics
>>>
tm.get_topic_types([tm["t-lennon-john"], tm["t-starr-ringo"]])
[<tm.Topic tt-person>]
Get the types including transitive types
>>>
tm.get_topic_types(transitive=1)
[<tm.Topic tt-music>, <tm.Topic tt-person>, <tm.Topic tt-band>, <tm.Topic tt-geography>, <tm.Topic tt-musician>, <tm.Topic tt-time>, <tm.Topic tt-country>, <tm.Topic tt-city>, <tm.Topic tt-artist>]
>>>
tm.get_topic_types([tm["t-lennon-john"], tm["t-starr-ringo"]], transitive=1)
[<tm.Topic tt-person>]
Returns a list of all topics that are used as association types.
>>>
tm.get_association_types()
[<tm.Topic at-born-in>, <tm.Topic at-played-instrument-in>, <tm.Topic at-located-in>, <tm.Topic at-member-of>]
Other variants:
tm.get_association_types(transitive=1)
tm.get_association_types(associations)
tm.get_association_types(associations, transitive=1)
TopicMap.get_facet_types(associations=None, transitive=0)
Returns a list of all topics that are used as facet types.
Examples
>>>
tm.get_facet_types()
[<tm.Topic ft-birth-date>]
Other variants:
tm.get_facet_types(transitive=1)
tm.get_facet_types(facets)
tm.get_facet_types(facets, transitive=1)
Getting topics, associations and facets that are of a given type or a subtype
The generic method for this is TopicMap.get_objects_of_type(self, type, tm_objects=None, transitive=0)
.
TopicMap.get_topics_of_type(self, type, topics=None, transitive=0)
Returns a list of all topics that is of a given topic type or a subtype.
The method get_topics_of_type
may take up to three
parameters. type
must be an existing
topic. topics
can be a list of topics, but if None is
specified all Topics of the TopicMap is evaluated. If
transitive
set to a true value all topics of
transitive types [supertypes] are included in the result.
Examples
Get all topics in the topic map that are persons.
>>>
tm.get_topics_of_type(tm["tt-person"])
[<tm.Topic t-starr-ringo>, <tm.Topic t-mccartney-paul>, <tm.Topic tt-artist>, <tm.Topic t-lennon-john>, <tm.Topic t-harrison-george>]
Get topics that are persons from a list of three topics.
>>>
tm.get_topics_of_type(tm["tt-person"], [tm["t-liverpool"], tm["t-starr-ringo"], tm["tt-artist"], tm["t-mccartney-paul"]])
[<tm.Topic t-starr-ringo>, <tm.Topic tt-artist>, <tm.Topic t-mccartney-paul>]
Get the topics that are of the type "tt-person" or of a more specific type, like "tt-vocalist".
>>>
tm.get_topics_of_type(tm["tt-person"], transitive=1)
[<tm.Topic t-starr-ringo>, <tm.Topic tt-guitarist>, <tm.Topic tt-bassist>, <tm.Topic tt-musician>, <tm.Topic t-mccartney-paul>, <tm.Topic tt-artist>, <tm.Topic tt-vocalist>, <tm.Topic t-lennon-john>, <tm.Topic tt-drummer>, <tm.Topic t-harrison-george>]
>>>
tm.get_topics_of_type(tm["tt-person"], [tm["t-liverpool"], tm["t-starr-ringo"], tm["tt-artist"], tm["t-mccartney-paul"]], transitive=1)
[<tm.Topic t-starr-ringo>, <tm.Topic tt-artist>, <tm.Topic t-mccartney-paul>]
TopicMap.get_associations_of_type(self, type, associations=None, transitive=0)
Returns a list of all associations of a given association type.
Examples:
>>>
tm.get_associations_of_type(tm["at-member-of"])
[<tm.Association instance at 81a15b0>]
Other variants:
tm.get_associations_of_type(type, transitive=1)
tm.get_associations_of_type(type, associations)
tm.get_associations_of_type(type, associations, transitive=1)
TopicMap.get_facets_of_type(self, type, facets=None, transitive=0)
Returns a list of all facets of a given facet type.
Examples:
>>>
tm.get_facets_of_type(tm["ft-birth-date"])
[<tm.Facet instance at 81a3578>]
Other variants:
tm.get_facets_of_type(type, transitive=1)
tm.get_facets_of_type(type, facets)
tm.get_facets_of_type(type, facets, transitive=1)
Getting associations that exists within given scope or subscope
The generic method for this is
TopicMap.get_objects_in_scope(self, scope, tm_objects=None, transitive=0)
.
TopicMap.get_associations_in_scope(self, scope, associations=None, transitive=0)
Returns a list of associations that exists within the specified
scope or in any of its subscopes.
The method get_associations_in_scope
may take up
to three parameters. scope
must we an existing
topic. associations
can be a list of associations,
but if None is specified all Associations of the Topic Map is
evaluated. If transitive
set to a true value all
topics of transitive types [subtypes] are included in the
result.
Examples
Get all associations that exists in the "tt-pop-music" scope.
>>>
tm.get_associations_in_scope(tm["st-music"])
[<tm.Association instance at 81a15b0>]
Other variants:
tm.get_associations_in_scope(scope, associations)
tm.get_associations_in_scope(scope, associations, transitive=1)
Let's say that the [scoping] topics "st-pop-music" and
"st-opera" was both of type "st-music". Then
tm.get_associations_in_scope(tm["st-music"],
transitive=1)
would return all associations that were in
the "st-music", "st-pop-music" and "st-opera" scopes.
Querying a Topic
Get hold of the topic Paul McCartney: paul_mccartney = tm["t-mccartney-paul"]
Get the SGML id: paul_mccartney.get_sgml_id()
Get the internal id: paul_mccartney.get_id()
Get the basenames: paul_mccartney.get_basenames()
Get the identity: paul_mccartney.get_identity()
Get the names: paul_mccartney.get_names()
Get the occurrences: paul_mccartney.get_occurrences()
Get the types: paul_mccartney.get_types()
Querying a TopicName
Get hold of the name: name = paul_mccartney.get_names()[0]
Get the internal id: name.get_id()
Get the basename: name.get_basename()
Get the display names: name.get_dispnames()
Get the sort names: name.get_sortnames()
Get the scopes: name.get_names()
Querying an Occurrence
Get hold of the occurrence: occur = paul_mccartney.get_occurrences()[0]
Get the internal id: occur.get_id()
Get the locators: occur.get_locators()
Get the role name: occur.get_rolename()
Get the scopes: occur.get_scopes()
Querying an Association
Get hold of the association: assoc = tm.get_associations()[0]
Get the internal id: assoc.get_id()
Get the roles: assoc.get_roles()
Get the scopes: assoc.get_scopes()
Get the types: assoc.get_types()
Querying an AssociationRole
Get hold of the association role: assocrl = assoc.get_roles()[0]
Get the internal id: assocrl.get_id()
Get the locators: assocrl.get_locators()
Get the role name: assocrl.get_rolename()
Get the types: assocrl.get_types()
Querying a Facet
Get hold of the facet: facet = tm.get_facets()[0]
Get the internal id: facet.get_id()
Get the type: facet.get_type()
Get the values: facet.get_scopes()
Querying a FacetValue
Get hold of the facet value: fvalue = facet.get_values()[0]
Get the internal id: fvalue.get_id()
Get the locators: assocrl.get_locators()
Get the type: fvalue.get_type()
Get the value: fvalue.get_value()
Querying a Locator
Note that the Locator class is only used for Occurrences. The
get_locator methods on AssociationRole and FacetValue always
returns a list of Topic objects. This is a limitation of the
current implementation.
Get the internal id: loc.get_id()
Get the address: loc.get_adress()
Get the locator type: loc.get_loctype()
Exporting a topic map
Here is a short example of how to export a topic map to the
interchange format that is specified in the Topic Map
standard.
- Import the tmutils module which contains the TMExporter class.
import tmutils
- Create a TMExporter object.
e = tmutils.TMExporter()
- Import a module that contains a SAX document handler class.
from xml.arch import xmlarch
- Create a SAX document handler that should receive the SAX events.
doc_handler = xmlarch.Prettifier(writer=sys.stdout)
- Export the topic map.
e.export(tm, doc_handler)
- The document is then written to standard output. Any SAX
document handler may be used in combination with the TMExporter
class.
Geir O. Grønmo, grove@ontopia.net