metaodi / museumpy

MuseumPlus client for Python

museumpy

museumpy is a client for python to get data from Zetcom MuseumPlus instances using its API.

Table of Contents

• Installation
• Usage
  • search
  • fulltext_search
• Advanced Usage
  • module_item
  • download_attachement
  • Custom mapping of fields
• Release

Installation

museumpy is available on PyPI, so to install it simply use:

$ pip install museumpy

Usage

See the examples directory for more scripts.

search

import museumpy

records = museumpy.search(
    base_url='https://mpzurichrietberg.zetcom.com/MpWeb-mpZurichRietberg',
    field='ObjObjectNumberTxt',
    value='2019.184',
)


for record in records:
    print(record)

The return value of search is iterable, so you can easily loop over it. Or you can use indices to access elements, e.g. records[1] to get the second element, or records[-1] to get the last one.

Even slicing is supported, so you can do things like only iterate over the first 5 elements using

for records in records[:5]:
   print(record)

fulltext_search

import museumpy

records = museumpy.fulltext_search(
    base_url='https://test.zetcom.com/MpWeb-mpTest',
    query='Patolu',
)


for record in records:
    print(record)

Advanced usage

For more advanced usage of this library, it is recommened to first create a client instance and then use this to request data:

import museumpy
import requests

s = requests.Session()
s.auth = ('user', 'pass')
s.headers.update({'Accept-Language': 'de'})

client = museumpy.MuseumPlusClient(
    base_url='https://test.zetcom.com/MpWeb-mpTest',
    session=s
)

module_item

import museumpy

id = '98977'
module = 'Multimedia'
item = client.module_item(id, module)

download_attachement

import museumpy

id = '98977'
module = 'Multimedia'
# download attachment to a directory called `files`
attachment_path = client.download_attachment(id, module, 'files')
print(attachment_path)

Custom mapping of fields

There are most likely custom fields on the MuseumPlus Instance you want to query. The returned XML is converted to a python dict using the xmltodict library. The raw dict is returned on the raw key of the result:

import museumpy

records = museumpy.search(
    base_url='https://test.zetcom.com/MpWeb-mpTest',
    query='Patolu',
)
for record in records:
    print(record['raw'])

For convenience a default mapping is provided to access some fields more easily:

for record in records:
    print(record['hasAttachments'])
    print(record['ObjObjectNumberTxt'])

If you want to customize this mapping, you can pass a map_function to the client, which is then used on all subsequent calls to search and fulltext_search:

import museumpy

def my_custom_map(record, xml_rec):
    NS = "http://www.zetcom.com/ria/ws/module"
    ID_XPATH = f".//{{{NS}}}dataField[@name='ObjObjectNumberTxt']/{{{NS}}}value"
    TITLE_XPATH = f".//{{{NS}}}repeatableGroup[@name='ObjObjectTitleGrp']//{{{NS}}}dataField[@name='TitleTxt']//{{{NS}}}value"

    xml_parser = museumpy.xmlparse.XMLParser()
    my_new_record = {
        'my_id': xml_parser.find(xml_rec, ID_XPATH).text,
        'my_title': xml_parser.find(xml_rec, TITLE_XPATH).text 
    }
    return my_new_record


client = museumpy.MuseumPlusClient(
    base_url='https://test.zetcom.com/MpWeb-mpTest',
    map_function=my_custom_map,
)

records = client.search(
    base_url='https://test.zetcom.com/MpWeb-mpTest',
    query='Patolu',
)
for record in records:
    print(record['my_id'])
    print(record['my_title'])

Release

To create a new release, follow these steps (please respect Semantic Versioning):

1. Adapt the version number in museumpy/__init__.py
2. Update the CHANGELOG with the version
3. Create a pull request to merge develop into main (make sure the tests pass!)
4. Create a new release/tag on GitHub (on the main branch)
5. The publication on PyPI happens via GitHub Actions on every tagged commit

museumpy's Issues

Decouple build-in schema

• provide current schema as "plugin" of sorts
• Standard schema should contain only standard fields (?)
• maybe provide a default mapping per module (?)
• test with different instances

Allow setting custom headers

E.g. some returned values like "formattedValue" can changed based on the provided Accept-Language header, therefore it must be possible to provide custom headers.

CSV example

Extract XML parser in its own module

Add missing client methods to __init__.py

Enable pagination

It's currently possible to pass offset and limit parameters, but this should be done in the background by the library.

Add scripts for basic functions

Move map_function to each call to be able to reuse a client for different requests

Describe export in README

Improve test coverage