Package: topi
TopiTopi ("TINDObjectPythonInterface") is a Python package for getting basic data from a TIND server.Table of contentsIntroductionInstallationUsageKnown issues and limitationsGetting helpContributingLicenseAcknowledgmentsIntroductionTINDis anintegrated library system. The Caltech Library uses a hosted solution by TIND for itslibrary catalog.  Recent versions of TIND provide a REST API for getting a subset of information using network calls.  To make writing interfaces and automation scripts in Python easier, the Caltech LibraryDigital Library Development teamdeveloped Topi ("TINDObjectPythonInterface"), a Python package that provides an object-oriented interface to data in a TIND catalog.Topi is not a complete API for interacting with TIND instances.  At this time, it provides an interface for retrieving only  two kinds of objects: bibliographic records, and items/holdings associated with those records.A "topi" is also aspecies of antelopefound in Africa.  The topi is currently classified asvulnerableby theInternational Union for Conservation of Nature(IUCN) due tothreatsthat include human development, hunting and droughts.InstallationThe instructions below assume you have a Python interpreter installed on your computer; if that's not the case, please firstinstall Python version 3and familiarize yourself with running Python programs on your system.OnLinux,macOS, andWindowsoperating systems, you should be able to installtopiwithpip.  To installtopifrom thePython package repository (PyPI), run the following command:python3 -m pip install topiAs an alternative to getting it fromPyPI, you can usepipto installtopidirectly from GitHub, like this:python3-mpipinstallgit+https://github.com/caltechlibrary/topi.gitUsageTopi is a application programming interface (API) library; it does not offer a command-line interface.  There are three main option classes in Topi:Tind,TindRecord, andTindItem.  The rest of this section describes these classes and how to use them.Object classesTindAn object of theTindclass serves as the main point of interaction with a TIND server.  The constructor forTindtakes only one argument: the base network URL for the server.  Using it is very simple:fromtopiimportTindtind=Tind('https://caltech.tind.io')An instance of theTindclass offers just two methods:record, to createTindRecordobjects, anditem, to createTindItemobjects.  These object classes are described below.TindRecordThis object class represents a bibliographic record in a TIND database.  The fields of the record are derived from the MARC representation of the bibliographic record in TIND.  The following are the fields in a record object in Topi:Field nameTypeDescriptiontind_idstringThe TIND record identifiertind_urlstringThe URL to the online record page in TINDtitlestringThe title (derived from MARC data field 245)subtitlestringThe subtitle (derived from MARC data field 245)authorstringThe author(s) (derived from MARC data field 245 or 100)editionstringThe edition (derived from MARC data field 250)publisherstringThe publisher's name (extracted from MARC control field 260)yearstringThe year (extracted from MARC control field 008)isbn_issnlistISBN or ISSN numbers (from MARC data field 020)descriptionstringA description, concatenated from MARC data field 300bib_notestringThe value of MARC data field 504, subfield "a"thumbnail_urlstringThe URL of the cover image in TIND (if any)itemslistA list ofTindItemobjectsATindRecordobject can be obtained using the factory methodrecord(...)on theTindinterface object.  This method takes one of two mutually-exclusive keyword arguments: either a TIND record identifier, or a MARC XML string obtained from a TIND server for a TIND bibliographic record.  Here is an example:fromtopiimportTindtind=Tind('https://caltech.tind.io')rec=tind.record(tind_id=680311)Note the use of the keyword argument.  Below is an example of how to create a record from an existing MARC XML file obtained from a TIND server some other way – let's assume it is stored a file nameddownloaded-marc.xml:fromtopiimportTindwithopen('downloaded_marc.xml','r')asxf:xml_string=xf.read()tind=Tind('https://caltech.tind.io')rec=tind.record(marc_xml=xml_string)Thethumbnail_urlfield is lazily evaluated: its value is only obtained from the TIND server the first time the field is accessed by a calling program.  This is more efficient for situations where the thumbnail is never needed by an application, but it does mean that there is a delay the first time the field is accessed.TindItemConceptually, in TIND an "item" is a specific copy of a work; this copy has a barcode and other item-specific information such as a location.  Each item is associated with a TIND record (represented by aTindRecordin Topi, described above).  The following are the fields in an item object in Topi:Field nameTypeDescriptionparentTindRecordThe parent record for this itembarcodestringThe item's barcodetypestringThe type of item this is (e.g., "book")volumestringThe volumecall_numberstringThe call numberdescriptionstringA description of the specific item (e.g., "copy 1")librarystringThe library where the item is locatedlocationstringThe location of the item in the librarystatusstringStatus of the item listed in TINDWith Topi, aTindItemobject can be obtained using the factory methoditem(...)on theTindinterface object.  This method takes a single argument: a barcode.  Here is an example:fromtopiimportTindtind=Tind('https://caltech.tind.io')item=tind.item(35047018228114)Item records have parent pointers to the corresponding bibliographic record, in the form of aTindRecord.  Thus, given an item object, it's possible to look up the rest of the bibliographic record simply by dereferencing the.parentfield:fromtopiimportTindtind=Tind('https://caltech.tind.io')item=tind.item(35047018228114)print(item.parent.title)Calling theitemmethod onTindwill return an emptyTindItemobject.Additional notesTopi fills out thethumbnail_urlfield of aTindRecordobject by using TIND's API for the purpose.  This only retrieves what a given TIND database contains for the cover image of a work.  Other sources such as theOpen Library Covers APImay have cover images that a TIND database lacks, but it is outside the scope of Topi to provide an interface for looking outside the TIND database.Known issues and limitationsCurrently, the coverage of the fields inTindRecordis limited.  Not all fields of a MARC XML record are mapped to fields inTindRecordat this time.  (Code contributions are welcome!)Getting helpIf you find an issue, please submit it inthe GitHub issue trackerfor this repository.ContributingWe would be happy to receive your help and participation with enhancing Topi!  Please visit theguidelines for contributingfor some tips on getting started.LicenseSoftware produced by the Caltech Library is Copyright (C) 2021, Caltech.  This software is freely distributed under a BSD/MIT type license.  Please see theLICENSEfile for more information.AcknowledgmentsThis work was funded by the California Institute of Technology Library.Thevector artworkof an antelope, used as the icon for this repository, was created byparkjisunfor the Noun Project.  It is licensed under the Creative CommonsCC-BY 3.0license.Topi makes use of numerous open-source packages, without which Topi could not have been developed.  I want to acknowledge this debt.  In alphabetical order, the packages are:commonpy– a collection of commonly-useful Python functionscssselect–lxmladd-on to parse CSS3 selectorsipdb– the IPython debuggerlxml– an XML parsing library for Pythonsetuptools– library forsetup.pysidetrack– simple debug logging/tracing package