api.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# default_exp api"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Omeka S API client\n",
    "\n",
    "> Tools to interact with the Omeka S REST API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#hide\n",
    "from nbdev.showdoc import *\n",
    "import random\n",
    "import os\n",
    "from copy import deepcopy\n",
    "import pytest\n",
    "%load_ext dotenv\n",
    "%dotenv"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "import requests\n",
    "import requests_cache\n",
    "import json\n",
    "from requests.adapters import HTTPAdapter\n",
    "from requests.packages.urllib3.util.retry import Retry\n",
    "from pathlib import Path\n",
    "\n",
    "class OmekaAPIClient(object):\n",
    "    \n",
    "    def __init__(self, api_url, key_identity=None, key_credential=None, use_cache=True):\n",
    "        self.api_url = api_url\n",
    "        self.credentials = {\n",
    "            'key_identity': key_identity,\n",
    "            'key_credential': key_credential\n",
    "        }\n",
    "        # Set up session and caching\n",
    "        if use_cache:\n",
    "            self.s = requests_cache.CachedSession(expire_after=3600)\n",
    "            self.s.cache.clear()\n",
    "        else:\n",
    "            self.s = requests.Session()\n",
    "        retries = Retry(total=10, backoff_factor=1, status_forcelist=[ 502, 503, 504, 524 ])\n",
    "        self.s.mount('http://', HTTPAdapter(max_retries=retries))\n",
    "        self.s.mount('https://', HTTPAdapter(max_retries=retries))\n",
    "        \n",
    "    def clear_cache():\n",
    "        self.s.cache.clear()\n",
    "        \n",
    "    def process_response(self, response):\n",
    "        '''\n",
    "        Handle Omeka responses, raising exceptions on errors.\n",
    "        '''\n",
    "        # Raise exception on HTTP error\n",
    "        response.raise_for_status()\n",
    "        # Try extracting JSON data\n",
    "        try:\n",
    "            data = response.json()\n",
    "        # If there's no JSON, display the raw response text and raise exception\n",
    "        except (json.decoder.JSONDecodeError, ValueError):\n",
    "            print(f'Bad JSON: {response.text}')\n",
    "            raise\n",
    "        else:\n",
    "            return data\n",
    "        \n",
    "    def format_resource_id(self, resource_id, resource_type):\n",
    "        '''\n",
    "        Generate a formatted id for the resource with the specified Omeka id number and resource type.\n",
    "        \n",
    "        Parameters:\n",
    "        * `resource_id` - numeric identifier used by Omeka for this resource\n",
    "        * `resource_type` - one of Omeka's resource types, eg: 'items', 'properties'\n",
    "        \n",
    "        Returns:\n",
    "        * a dict with values for '@id' and 'o:id'\n",
    "        '''\n",
    "        formatted_id = {\n",
    "            '@id': f'{self.api_url}/{resource_type}/{resource_id}',\n",
    "            'o:id': resource_id\n",
    "        }\n",
    "        return formatted_id\n",
    "\n",
    "    def get_resources(self, resource_type, **kwargs):\n",
    "        '''\n",
    "        Get a list of resources matching the supplied parameters.\n",
    "        This will return the first page of matching results. To retrieve additional pages, \n",
    "        you can supply the `page` parameter to move through the full result set.\n",
    "        \n",
    "        Parameters:\n",
    "        * `resource_type` - one of Omeka's resource types, eg: 'items', 'properties'\n",
    "        * there are many additional parameters you can supply as kwargs, see the Omeka documention\n",
    "        \n",
    "        Returns a dict with the following values:\n",
    "        * `total_results` - number of matching resources\n",
    "        * `results` - a list of dicts, each containing a JSON-LD formatted representation of a resource\n",
    "        '''\n",
    "        kwargsWithCredentials = kwargs | self.credentials#credential offers to get non-public (hidden) data\n",
    "        response = self.s.get(f'{self.api_url}/{resource_type}/', params=kwargsWithCredentials)\n",
    "        data = self.process_response(response)\n",
    "        return {'total_results': int(response.headers['Omeka-S-Total-Results']), 'results': data}\n",
    "    \n",
    "    def get_resource(self, resource_type, **kwargs):\n",
    "        '''\n",
    "        Get the first resource matching the supplied parameters.\n",
    "        \n",
    "        Parameters:\n",
    "        * `resource_type` - one of Omeka's resource types, eg: 'items', 'properties'\n",
    "        * there are many additional parameters you can supply as kwargs, see the Omeka documention\n",
    "        \n",
    "        Returns\n",
    "        * a dict containing a JSON-LD formatted representation of the resource\n",
    "        '''\n",
    "        \n",
    "        data = self.get_resources(resource_type, **kwargs)\n",
    "        try:\n",
    "            resource = data['results'][0]\n",
    "        except IndexError:\n",
    "            return\n",
    "        else:\n",
    "            return resource\n",
    "\n",
    "    def get_resource_by_id(self, resource_id, resource_type='items'):\n",
    "        '''\n",
    "        Get a resource from its Omeka id.\n",
    "        \n",
    "        Parameters:\n",
    "        * `resource_id` - numeric identifier used by Omeka for this resource\n",
    "        * `resource_type` - one of Omeka's resource types, eg: 'items', 'properties'\n",
    "        \n",
    "        Returns\n",
    "        * a dict containing a JSON-LD formatted representation of the resource\n",
    "        '''\n",
    "        response = self.s.get(f'{self.api_url}/{resource_type}/{resource_id}/', params=self.credentials)\n",
    "        data = self.process_response(response)\n",
    "        return data\n",
    "\n",
    "    def get_template_by_label(self, label):\n",
    "        '''\n",
    "        Get a resource template from its Omeka label.\n",
    "        \n",
    "        Parameters:\n",
    "        * `label` - the name of the resource template in Omeka (eg. 'NewspaperArticle')\n",
    "        \n",
    "        Returns:\n",
    "        * dict containing representation of the template\n",
    "        '''\n",
    "        return self.get_resource('resource_templates', label=label)\n",
    "    \n",
    "    def get_resource_by_term(self, term, resource_type='properties'):\n",
    "        '''\n",
    "        Get the resource (property or class) associated with the suppied term.\n",
    "        \n",
    "        Parameters:\n",
    "        * `term` - property label qualified with vocabulary prefix (eg: 'schema:name')\n",
    "        \n",
    "        Returns:\n",
    "        * dict containing representation of the resource\n",
    "        '''\n",
    "        return self.get_resource(resource_type, term=term)\n",
    "    \n",
    "    def get_resource_from_vocab(self, local_name, vocabulary_namespace_uri='http://schema.org/', resource_type='properties'):\n",
    "        '''\n",
    "        Get the resource (property or class) associated with the suppied vocabulary and label.\n",
    "        \n",
    "        Parameters:\n",
    "        * `local_name` - label of the property or class\n",
    "        * `vocabulary_namespace_uri` - URI defining the vocab\n",
    "        \n",
    "        Returns:\n",
    "        * dict containing representation of the resource\n",
    "        '''\n",
    "        return self.get_resource(resource_type, local_name=local_name, vocabulary_namespace_uri=vocabulary_namespace_uri)\n",
    "        \n",
    "    def get_property_id(self, term):\n",
    "        '''\n",
    "        Get the numeric identifier associated with the supplied property term.\n",
    "        \n",
    "        Parameters:\n",
    "        * `term` - property label qualified with vocabulary prefix (eg: 'schema:name')\n",
    "        \n",
    "        Returns:\n",
    "        * numeric identifier\n",
    "        '''\n",
    "        resource = self.get_resource_by_term(term=term)\n",
    "        if resource:\n",
    "            return resource['o:id']\n",
    "    \n",
    "    def get_class_id(self, term):\n",
    "        '''\n",
    "        Get the numeric identifier associated with the supplied class term.\n",
    "\n",
    "        Parameters:\n",
    "        * `term` - class label qualified with vocabulary prefix (eg: 'crm:E65_Creation')\n",
    "\n",
    "        Returns:\n",
    "        * numeric identifier\n",
    "        '''\n",
    "        resource = self.get_resource_by_term(term=term, resource_type='resource_classes')\n",
    "        if resource:\n",
    "            return resource['o:id']\n",
    "\n",
    "    def get_template_id(self, label):\n",
    "        '''\n",
    "        Get the numeric identifier associated with the supplied template label.\n",
    "\n",
    "        Parameters:\n",
    "        * `label` - template label used in the omeka instance (eg: 'creation')\n",
    "\n",
    "        Returns:\n",
    "        * numeric identifier\n",
    "        '''\n",
    "        resource = self.get_template_by_label(label)\n",
    "        if resource:\n",
    "            return resource['o:id']\n",
    "\n",
    "    def get_itemset_id(self, label):\n",
    "        '''\n",
    "        Get the numeric identifier associated with the supplied item-set label.\n",
    "        \n",
    "        Parameters:\n",
    "        * `label` - item-set label as recorded in omeka (eg: 'my collection')\n",
    "        \n",
    "        Returns:\n",
    "        * numeric identifier\n",
    "        '''\n",
    "        resource = self.get_resource('item_sets', search=label)\n",
    "        if resource:\n",
    "            return resource['o:id']\n",
    "\n",
    "\n",
    "\n",
    "    def filter_items(self, params, **extra_filters):\n",
    "        for filter_type in ['resource_template_id', 'resource_class_id', 'item_set_id', 'is_public']:\n",
    "            filter_value = extra_filters.get(filter_type)\n",
    "            if filter_value:\n",
    "                params[filter_type] = filter_value\n",
    "        return params\n",
    "    \n",
    "    def filter_items_by_property(self, filter_property='schema:name', filter_value='', filter_type='eq', page=1, **extra_filters):\n",
    "        '''\n",
    "        Filter the list of items by searching for a value in a particular property.\n",
    "        Additional filters can also limit to items associated with particular templates, classes, or item sets.\n",
    "        \n",
    "        Parameters:\n",
    "        * `filter_property` - property term (eg: 'schema:name')\n",
    "        * `filter_value` - the value you want to find\n",
    "        * `filter_type` - how `filter_value` should be compared to the stored values (eg: 'eq')\n",
    "        * `page` - number of results page\n",
    "        \n",
    "        Additional parameters:\n",
    "        * `resource_template_id` - numeric identifier\n",
    "        * `resource_class_id` - numeric identifier\n",
    "        * `item_set_id` - numeric identifier\n",
    "        * `is_public` - boolean, True or False\n",
    "        \n",
    "        Returns a dict with the following values:\n",
    "        * `total_results` - number of matching resources\n",
    "        * `results` - a list of dicts, each containing a JSON-LD formatted representation of a resource\n",
    "        \n",
    "        '''\n",
    "        # We need to get the id of the property we're using\n",
    "        property_id = self.get_property_id(filter_property)\n",
    "        params = {\n",
    "            'property[0][joiner]': 'and', # and / or joins multiple property searches\n",
    "            'property[0][property]': property_id, # property id\n",
    "            'property[0][type]': filter_type, # See above for options\n",
    "            'property[0][text]': filter_value,\n",
    "            'page': page\n",
    "        }\n",
    "        params = self.filter_items(params, **extra_filters)\n",
    "        # print(params)\n",
    "        results = self.get_resources('items', **params)\n",
    "        return results\n",
    "    \n",
    "    def search_items(self, query, search_type='fulltext_search', page=1, **extra_filters):\n",
    "        '''\n",
    "        Search for matching items.\n",
    "        Two search types are available:\n",
    "        * 'search` - looks for an exact match of the query in a property value\n",
    "        * 'fulltext_search` - looks for the occurance of the query anywhere\n",
    "        \n",
    "        Parameters:\n",
    "        * `query` - the text you want to search for\n",
    "        * `search_type` - one of 'fulltext_search' or 'search'\n",
    "        * `page` - number of results page\n",
    "        \n",
    "        Additional parameters:\n",
    "        * `resource_template_id` - numeric identifier\n",
    "        * `resource_class_id` - numeric identifier\n",
    "        * `item_set_id` - numeric identifier\n",
    "        * `is_public` - boolean, True or False\n",
    "        \n",
    "        Returns a dict with the following values:\n",
    "        * `total_results` - number of matching resources\n",
    "        * `results` - a list of dicts, each containing a JSON-LD formatted representation of a resource\n",
    "        '''\n",
    "        params = {'page': page}\n",
    "        params[search_type] = query\n",
    "        params = self.filter_items(params, **extra_filters)\n",
    "        results = self.get_resources('items', **params)\n",
    "        return results\n",
    "\n",
    "    def get_template_properties(self, template_id):\n",
    "        '''\n",
    "        List properties used by the specified template.\n",
    "        \n",
    "        The resource template objects returned by the API don't include property terms.\n",
    "        This function gets the additional details, and organises the properties in a dictionary, \n",
    "        organised by term. This makes it easy to check if a particular term is used by a template.\n",
    "        \n",
    "        Parameters:\n",
    "        * `template_id` - numeric identifier for a template\n",
    "        \n",
    "        Returns:\n",
    "        * a dict organised by property terms, with values for `property_id` and `type`\n",
    "        '''\n",
    "        properties = {}\n",
    "        template = self.get_resource_by_id(template_id, 'resource_templates')\n",
    "        for prop in template['o:resource_template_property']:\n",
    "            prop_url = prop['o:property']['@id']\n",
    "            # The resource template doesn't include property terms, so we have to go to the property data\n",
    "            response = self.s.get(prop_url)\n",
    "            data = self.process_response(response)\n",
    "            # Use default data types if they're not defined in the resource template\n",
    "            data_type = ['literal', 'uri', 'resource:item'] if prop['o:data_type'] == [] else prop['o:data_type']\n",
    "            properties[data['o:term']] = {'property_id': data['o:id'], 'type': data_type}\n",
    "        return properties\n",
    "    \n",
    "    # ADDING ITEMS\n",
    "        \n",
    "    def prepare_property_value(self, value, property_id):\n",
    "        '''\n",
    "        Formats a property value according to its datatype as expected by Omeka. \n",
    "        The formatted value can be used in a payload to create a new item.\n",
    "        \n",
    "        Parameters:\n",
    "        * `value` - a dict containing a `value` and (optionally) a `type`\n",
    "        * `property_id` - the numeric identifier of the property\n",
    "        \n",
    "        Note that is no `type` is supplied, 'literal' will be used by default.\n",
    "        \n",
    "        Returns:\n",
    "        * a dict with values for `property_id`, `type`, and either `@id` or `@value`.\n",
    "        '''\n",
    "        if not isinstance(value, dict):\n",
    "            value = {'value': value}\n",
    "            \n",
    "        try:\n",
    "            data_type = value['type']\n",
    "        except KeyError:\n",
    "            data_type = 'literal'\n",
    "        \n",
    "        property_value = {\n",
    "            'property_id': property_id,\n",
    "            'type': data_type\n",
    "        }\n",
    "        \n",
    "        if data_type == 'resource:item':\n",
    "            property_value['@id'] = f'{self.api_url}/items/{value[\"value\"]}'\n",
    "            property_value['value_resource_id'] = value['value']\n",
    "            property_value['value_resource_name'] = 'items'\n",
    "        elif data_type == 'numeric:timestamp':\n",
    "            property_value['@value'] = value['value']\n",
    "        elif data_type == 'uri':\n",
    "            property_value['@id'] = value['value']\n",
    "            if value['label']:\n",
    "                property_value['o:label'] = value['label']\n",
    "        else:\n",
    "            property_value['@value'] = value['value']\n",
    "        return property_value\n",
    "\n",
    "    def add_item(self, payload, media_files=None, template_id=None, class_id=None, item_set_id=None):\n",
    "        '''\n",
    "        Create a new item from the supplied payload, optionally uploading attached media files.\n",
    "        \n",
    "        Parameters:\n",
    "        * `payload` - a dict generated by `prepare_item_payload()` or `prepare_item_payload_using_template()`\n",
    "        * `media_files` - a list of paths pointing to media files, or a list of dicts with `path` and `title` values\n",
    "        * `template_id` - internal Omeka identifier of a resource template you want to attach to this item\n",
    "        * `class_id` - internal Omeka identifier of a resource class you want to attach to this item\n",
    "        * `item_set_id` - internal Omeka identifier for an item set you want to add this item to\n",
    "        \n",
    "        Returns:\n",
    "        * a dict providing the JSON-LD representation of the new item from Omeka\n",
    "        '''\n",
    "        if template_id:\n",
    "            payload['o:resource_template'] = self.format_resource_id(template_id, 'resource_templates')\n",
    "            # If class is not set explicitly, use class associated with template\n",
    "            if not class_id:\n",
    "                template = self.get_resource_by_id(template_id, 'resource_templates')\n",
    "                class_id = template['o:resource_class']['o:id']\n",
    "        if class_id:\n",
    "            payload['o:resource_class'] = self.format_resource_id(class_id, 'resource_classes')\n",
    "        if item_set_id:\n",
    "            payload['o:item_set'] = self.format_resource_id(item_set_id, 'item_sets')\n",
    "        if media_files:\n",
    "            files = self.add_media_to_payload(payload, media_files)\n",
    "            response = self.s.post(f'{self.api_url}/items', files=files, params=self.credentials)\n",
    "        else:\n",
    "            response = self.s.post(f'{self.api_url}/items', json=payload, params=self.credentials)\n",
    "        #print(response.text)\n",
    "        data = self.process_response(response)\n",
    "        return data\n",
    "    \n",
    "    def prepare_item_payload(self, terms):\n",
    "        '''\n",
    "        Prepare an item payload, ready for upload.\n",
    "        \n",
    "        Parameters:\n",
    "        * `terms`: a dict of terms, values, and (optionally) data types\n",
    "        \n",
    "        Returns:\n",
    "        * the payload dict\n",
    "        '''\n",
    "        payload = {}\n",
    "        for term, values in terms.items():\n",
    "            # Get the property id of the supplied term\n",
    "            try:\n",
    "                property_id = self.get_property_id(term)\n",
    "            except IndexError:\n",
    "                print(f'Term \"{term}\" not found')\n",
    "            else:\n",
    "                payload[term] = []\n",
    "                for value in values:\n",
    "                    # Add a value formatted according to the data type\n",
    "                    payload[term].append(self.prepare_property_value(value, property_id))\n",
    "        return payload\n",
    "    \n",
    "    def prepare_item_payload_using_template(self, terms, template_id):\n",
    "        '''\n",
    "        Prepare an item payload, checking the supplied terms and values against the specified template.\n",
    "        Note:\n",
    "        * terms that are not in the template will generate a warning and be dropped from the payload\n",
    "        * data types that don't match the template definitions will generate a warning and the term will be dropped from the payload\n",
    "        * if no data type is supplied, a type that conforms with the template definition will be used\n",
    "        \n",
    "        Parameters:\n",
    "        * `terms`: a dict of terms, values, and (optionally) data types\n",
    "        * `template_id`: Omeka's internal numeric identifier for the template\n",
    "        \n",
    "        Returns:\n",
    "        * the payload dict\n",
    "        '''\n",
    "        template_properties = self.get_template_properties(template_id)\n",
    "        payload = {}\n",
    "        for term, values in terms.items():\n",
    "            if term.split(':', 1)[0] == 'o' or term in ['@context', '@id', '@type', 'thumbnail_display_urls']:\n",
    "                #its an internal omeka term\n",
    "                continue\n",
    "            if term in template_properties:\n",
    "                property_details = template_properties[term]\n",
    "                payload[term] = []\n",
    "                for value in values:\n",
    "                    if not isinstance(value, dict):\n",
    "                        value = {'value': value}\n",
    "                    # The supplied data type doesn't match the template\n",
    "                    if 'type' in value and value['type'] not in property_details['type']:\n",
    "                        print(f'Data type \"{value[\"type\"]}\" for term \"{term}\" not allowed by template')\n",
    "                        break\n",
    "                    elif 'type' not in value:\n",
    "                        # Use default datatype from template if none is supplied\n",
    "                        if len(property_details['type']) == 1:\n",
    "                            value['type'] = property_details['type'][0]\n",
    "                        # Use literal if allowed by template and data type not supplied\n",
    "                        elif 'literal' in property_details['type']:\n",
    "                            value['type'] = 'literal'\n",
    "                        # Don't know what data type to use\n",
    "                        else:\n",
    "                            print(f'Specify data type for term \"{term}\"')\n",
    "                            break\n",
    "                    # Add a value formatted according to the data type\n",
    "                    payload[term].append(self.prepare_property_value(value, property_details['property_id']))\n",
    "            # The supplied term is not in the template\n",
    "            else:\n",
    "                print(f'Term {term} not in template') \n",
    "        return payload\n",
    "    \n",
    "    def add_media_to_payload(self, payload, media_files):\n",
    "        '''\n",
    "        Add media files to the item payload.\n",
    "        \n",
    "        Parameters:\n",
    "        * `payload` - the payload dict to be modified\n",
    "        * `media_files` - media files to be uploaded\n",
    "        \n",
    "        The value of `media_files` can be either:\n",
    "        * a list of paths to the image/media files (filename is used as title)\n",
    "        * a list of dicts, each containing `title`, and `path` values\n",
    "        \n",
    "        The path values can either be strings or pathlib Paths.\n",
    "        \n",
    "        Returns: \n",
    "        * the modified payload dict\n",
    "        '''\n",
    "        payload['o:media'] = []\n",
    "        files = {}\n",
    "        for index, media_file in enumerate(media_files):\n",
    "            if isinstance(media_file, dict):\n",
    "                title = media_file['title']\n",
    "                path = Path(media_file['path'])\n",
    "            else:\n",
    "                path = Path(media_file)\n",
    "                title = path.name\n",
    "            payload['o:media'].append({'o:ingester': 'upload', 'file_index': str(index), 'o:item': {}, 'dcterms:title': [{'property_id': 1, '@value': title, 'type': 'literal'}]})\n",
    "            files[f'file[{index}]'] = path.read_bytes()\n",
    "        files['data'] = (None, json.dumps(payload), 'application/json')\n",
    "        #files['data'] = (json.dumps(payload), 'application/json')\n",
    "        return files\n",
    "    \n",
    "    # UPDATING RESOURCES\n",
    "    \n",
    "    def delete_resource(self, resource_id, resource_type):\n",
    "        '''\n",
    "        Deletes a resource. No confirmation is requested, so use carefully.\n",
    "        \n",
    "        Parameters:\n",
    "        * `resource_id` - local Omeka identifier of the resource you want to delete\n",
    "        * `resource_type` - type of the resource (eg 'items')\n",
    "        \n",
    "        Returns:\n",
    "        * dict with JSON-LD representation of the deleted resource\n",
    "        '''\n",
    "        response = self.s.delete(f'{self.api_url}/{resource_type}/{resource_id}', params=self.credentials)\n",
    "        data = self.process_response(response)\n",
    "        return data\n",
    "    \n",
    "    def update_resource(self, payload, resource_type='items'):\n",
    "        '''\n",
    "        Update an existing resource.\n",
    "        \n",
    "        Parameters:\n",
    "        * `payload` - the updated resource data\n",
    "        * `resource_type` - the type of resource\n",
    "        \n",
    "        To avoid problems, it's generally easiest to retrieve the resource first,\n",
    "        make your desired changes to it, then submit the updated resource as your payload.\n",
    "        '''\n",
    "        response = self.s.put(f'{self.api_url}/{resource_type}/{payload[\"o:id\"]}', json=payload, params=self.credentials)\n",
    "        data = self.process_response(response)\n",
    "        return data\n",
    "    \n",
    "    def add_media_to_item(self, item_id, media_file, payload={}, template_id=None, class_id=None):\n",
    "        '''\n",
    "        Upload a media file and associate it with an existing item.\n",
    "        \n",
    "        Parameters:\n",
    "        * `item_id` - the Omeka id of the item this media file should be added to\n",
    "        * `media_path` - a path to an image/media file (string or pathlib Path)\n",
    "        * `payload` (optional) - metadata to attach to media object, either \n",
    "           a dict generated by `prepare_item_payload()` or `prepare_item_payload_using_template()`,\n",
    "           or a string which is used as the value for `dcterms:title`.\n",
    "        * `template_id` - internal Omeka identifier of a resource template you want to attach to this item\n",
    "        * `class_id` - internal Omeka identifier of a resource class you want to attach to this item\n",
    "        \n",
    "        Returns: \n",
    "        * a dict providing a JSON-LD representation of the new media object\n",
    "        '''\n",
    "        files = {}\n",
    "        # For backwards compatibility\n",
    "        if isinstance(media_file, dict):\n",
    "            path = media_file['path']\n",
    "            payload = media_file['title']\n",
    "        # Make sure path is a Path object\n",
    "        path = Path(media_file)\n",
    "        if isinstance(payload, str):\n",
    "            payload = self.prepare_item_payload({'dcterms:title': [payload]})\n",
    "        if template_id:\n",
    "            payload['o:resource_template'] = self.format_resource_id(template_id, 'resource_templates')\n",
    "            if not class_id:\n",
    "                template = self.get_resource_by_id(template_id, 'resource_templates')\n",
    "                class_id = template['o:resource_class']['o:id']\n",
    "        if class_id:\n",
    "            payload['o:resource_class'] = self.format_resource_id(class_id, 'resource_classes')\n",
    "        file_data = {\n",
    "            'o:ingester': 'upload', \n",
    "            'file_index': '0',\n",
    "            'o:source': path.name,\n",
    "            'o:item': {'o:id': item_id},\n",
    "        }\n",
    "        payload.update(file_data)\n",
    "        files[f'file[0]'] = path.read_bytes()\n",
    "        files['data'] = (None, json.dumps(payload), 'application/json')\n",
    "        response = self.s.post(f'{self.api_url}/media', files=files, params=self.credentials)\n",
    "        data = self.process_response(response)\n",
    "        return data\n",
    "    \n",
    "    # MANAGING TEMPLATES\n",
    "    \n",
    "    def localise_custom_vocabs(self, data_types):\n",
    "        '''\n",
    "        Check a list of data types for references to custom vocabs.\n",
    "        If found, look for the local identifier of the custom vocab, \n",
    "        and insert it into the data type information.\n",
    "        \n",
    "        Parameters:\n",
    "        * `data_types` - a list of data types from an exported template property\n",
    "        \n",
    "        Returns:\n",
    "        * list of datatypes with local identifiers\n",
    "        '''\n",
    "        dt_names = []\n",
    "        for dt in data_types:\n",
    "            if dt['name'].startswith('customvocab'):\n",
    "                try:\n",
    "                    cv_id = self.get_resource('custom_vocabs', label=dt['label'])['o:id']\n",
    "                except TypeError:\n",
    "                    print(f'Custom vocab {dt[\"label\"]} not found')\n",
    "                else:\n",
    "                    dt_names.append(f'customvocab:{cv_id}')\n",
    "            else:\n",
    "                dt_names.append(dt['name'])\n",
    "        return dt_names\n",
    "    \n",
    "    def get_template_class_id(self, template):\n",
    "        '''\n",
    "        Get the local id of the resource class associated with the supplied template.\n",
    "        \n",
    "        Parameters:\n",
    "        * `template` - dict from exported template\n",
    "        \n",
    "        Returns:\n",
    "        * class identifier\n",
    "        '''\n",
    "        resource_class = self.get_resource_from_vocab(\n",
    "            local_name=template['o:resource_class']['local_name'],\n",
    "            vocabulary_namespace_uri=template['o:resource_class']['vocabulary_namespace_uri'],\n",
    "            resource_type='resource_classes'\n",
    "        )\n",
    "        if resource_class:\n",
    "            return resource_class['o:id']\n",
    "        else:\n",
    "            print(f'Resource class \"{template[\"o:resource_class\"][\"local_name\"]}\" not found')\n",
    "    \n",
    "    def get_template_property_id(self, template, term):\n",
    "        '''\n",
    "        Get the local id of the property associated with the supplied template.\n",
    "        \n",
    "        Parameters:\n",
    "        * `template` - dict from exported template\n",
    "        * `term` - property term (eg 'o:title_property')\n",
    "        \n",
    "        Returns:\n",
    "        * property identifier\n",
    "        '''\n",
    "        prop = self.get_resource_from_vocab(\n",
    "            local_name=template[term]['local_name'],\n",
    "            vocabulary_namespace_uri=template[term]['vocabulary_namespace_uri'],\n",
    "            resource_type='properties'\n",
    "        )\n",
    "        if prop:\n",
    "            return prop['o:id']\n",
    "        else:\n",
    "            print(f'Property \"{template[term][\"local_name\"]}\" not found')\n",
    "    \n",
    "    def prepare_template_payload(self, template_file):\n",
    "        '''\n",
    "        Insert local property, class, and vocab identifiers into a resource template\n",
    "        exported from Omeka so that it can be uploaded to the local instance.\n",
    "        \n",
    "        Parameters:\n",
    "        * `template_file` - path to a template exported from Omeka (str or pathlib Path)\n",
    "        \n",
    "        Returns:\n",
    "        * template payload with local identifiers inserted\n",
    "        '''\n",
    "        # Load the template file from the filesystem\n",
    "        template = json.loads(Path(template_file).read_bytes())\n",
    "        # Get local resource class id\n",
    "        resource_class_id = self.get_template_class_id(template)\n",
    "        # Get id of property used for title\n",
    "        title_id = self.get_template_property_id(template, 'o:title_property')\n",
    "        # Get id of property used for description\n",
    "        description_id = self.get_template_property_id(template, 'o:description_property')\n",
    "        # Create skeleton payload\n",
    "        template_payload = {\n",
    "            'o:label': template['o:label'],\n",
    "            'o:resource_class': self.format_resource_id(resource_class_id, 'resource_classes'),\n",
    "            'o:title_property': self.format_resource_id(title_id, 'properties'),\n",
    "            'o:description_property': self.format_resource_id(description_id, 'properties'),\n",
    "            'o:resource_template_property': []\n",
    "        }\n",
    "        # The property list in the JSON file exported from Omeka doesn't include property ids, so we need to add them.\n",
    "        for prop in template['o:resource_template_property']:\n",
    "            # Keep the namespaced values in the property dictionary\n",
    "            prop_payload = {k: v for k, v in prop.items() if k.startswith('o:')}\n",
    "\n",
    "            # Add data types\n",
    "            prop_payload['o:data_type'] = self.localise_custom_vocabs(prop['data_types'])\n",
    "\n",
    "            # Get the property id\n",
    "            prop_data = self.get_resource_from_vocab(\n",
    "                local_name=prop['local_name'],\n",
    "                vocabulary_namespace_uri=prop['vocabulary_namespace_uri'],\n",
    "                resource_type='properties'\n",
    "            )\n",
    "            if prop_data:\n",
    "\n",
    "                # Add property id to payload\n",
    "                prop_payload['o:property'] = self.format_resource_id(prop_data['o:id'], 'properties')\n",
    "\n",
    "                # Add the property to the template\n",
    "                template_payload['o:resource_template_property'].append(prop_payload)\n",
    "            else:\n",
    "                print(f'Property \"{prop[\"label\"]}\" not found')\n",
    "  \n",
    "        return template_payload\n",
    "\n",
    "    def upload_template(self, template_payload):\n",
    "        '''\n",
    "        Upload a template exported from an instance of Omeka to the current local instance.\n",
    "        \n",
    "        Parameters:\n",
    "        * `template_payload` - dict payload generated by `prepare_template_payload`\n",
    "        \n",
    "        Return:\n",
    "        * dict containing a JSON-LD representation of the uploaded template\n",
    "        '''\n",
    "        # Upload the template payload\n",
    "        response = self.s.post(f'{self.api_url}/resource_templates/', params=self.credentials, json=template_payload)\n",
    "        data = self.process_response(response)\n",
    "        return data\n",
    "        \n",
    "    # MODULE RELATED METHODS\n",
    "\n",
    "    def add_marker_to_item(self, item_id, coords=None, terms=None, label=None, media_id=None):\n",
    "        '''\n",
    "        Add a map marker to an item.\n",
    "        Requires the `mapping` module to be installed.\n",
    "        \n",
    "        Parameters:\n",
    "        * `item_id` - identifier of item to add marker to\n",
    "        * `coords` - list with coordinates in longitude, latitude order eg [151.209900, -33.865143]\n",
    "        * `terms` - list with vocab terms containing longitude and latitude values eg ['schema:longitude', 'schema:latitude']\n",
    "        * `label` - label for marker (defaults to item title)\n",
    "        * `media_id` - identifier of media resource to display with marker\n",
    "        \n",
    "        Returns:\n",
    "        * dict providing JSON-LD representation of marker\n",
    "        '''\n",
    "        item = self.get_resource_by_id(item_id)\n",
    "        if coords:\n",
    "            lon, lat = coords\n",
    "        elif terms:\n",
    "            lon, lat = terms\n",
    "            lon = item[lon][0]['@value']\n",
    "            lat = item[lat][0]['@value']\n",
    "        else:\n",
    "            lon = item['schema:longitude'][0]['@value']\n",
    "            lat = item['schema:latitude'][0]['@value']\n",
    "        lon = float(lon)\n",
    "        lat = float(lat)\n",
    "        if not label:\n",
    "            label = item['o:title']\n",
    "        marker_payload = {\n",
    "            'o:item': {'o:id': item_id},\n",
    "            'o-module-mapping:lat': lat,\n",
    "            'o-module-mapping:lng': lon,\n",
    "            'o-module-mapping:label': label\n",
    "        }\n",
    "        if media_id:\n",
    "            marker_payload['o:media'] = {'o:id': media_id}\n",
    "        response = self.s.post(f'{self.api_url}/mapping_markers/', json=marker_payload, params=self.credentials)\n",
    "        data = self.process_response(response)\n",
    "        return data\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First import the `OmekaAPIClient` class.\n",
    "\n",
    "``` python\n",
    "from omeka_s_tools.api import OmekaAPIClient\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To initialise the `OmekaAPIClient` you need to provide the base url of your Omeka instance's API."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "omeka = OmekaAPIClient('http://timsherratt.org/collections/api')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will let you access details of all public resources provided by your Omeka instance. To access private resources, or create new resources, you'll have to authenticate your API requests by provide a `key_identity` and `key_credential`. See [Adding items](#Adding-items) for an example."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting resources\n",
    "\n",
    "You can find a [full list of Omeka's resources](https://omeka.org/s/docs/developer/api/#resources) in the API documentation. You're most likely to be interested in 'items', but accessing 'properties' and 'resource_templates' can be useful when you're creating new resources.\n",
    "\n",
    "You should be able to use `get_resources` with any of the resource types, though some of the parameters will be different. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.get_resources\" class=\"doc_header\"><code>OmekaAPIClient.get_resources</code><a href=\"__main__.py#L63\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.get_resources</code>(**`resource_type`**, **\\*\\*`kwargs`**)\n",
       "\n",
       "Get a list of resources matching the supplied parameters.\n",
       "This will return the first page of matching results. To retrieve additional pages, \n",
       "you can supply the `page` parameter to move through the full result set.\n",
       "\n",
       "Parameters:\n",
       "* `resource_type` - one of Omeka's resource types, eg: 'items', 'properties'\n",
       "* there are many additional parameters you can supply as kwargs, see the Omeka documention\n",
       "\n",
       "Returns a dict with the following values:\n",
       "* `total_results` - number of matching resources\n",
       "* `results` - a list of dicts, each containing a JSON-LD formatted representation of a resource"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.get_resources)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "120"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "data = omeka.get_resources('items')\n",
    "data['total_results']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert isinstance(data['total_results'], int)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a list of available resource templates\n",
    "data = omeka.get_resources('resource_templates')\n",
    "first_template = data['results'][0]\n",
    "assert first_template['@type'] == 'o:ResourceTemplate'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.get_resource_by_id\" class=\"doc_header\"><code>OmekaAPIClient.get_resource_by_id</code><a href=\"__main__.py#L101\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.get_resource_by_id</code>(**`resource_id`**, **`resource_type`**=*`'items'`*)\n",
       "\n",
       "Get a resource from its Omeka id.\n",
       "\n",
       "Parameters:\n",
       "* `resource_id` - numeric identifier used by Omeka for this resource\n",
       "* `resource_type` - one of Omeka's resource types, eg: 'items', 'properties'\n",
       "\n",
       "Returns\n",
       "* a dict containing a JSON-LD formatted representation of the resource"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.get_resource_by_id)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a random item from a list of items\n",
    "data = omeka.get_resources('items')\n",
    "random_item = random.choice(data['results'])\n",
    "item_id = random_item['o:id']\n",
    "\n",
    "# Get the same item using its id\n",
    "item_from_id = omeka.get_resource_by_id(item_id, 'items')\n",
    "\n",
    "# Check that they're the same\n",
    "assert random_item == item_from_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It can be difficult to remember all the available parameters and the differences between resource types, so I've created a number of more specialised methods that are really just wrappers around `get_resources`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.get_template_by_label\" class=\"doc_header\"><code>OmekaAPIClient.get_template_by_label</code><a href=\"__main__.py#L116\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.get_template_by_label</code>(**`label`**)\n",
       "\n",
       "Get a resource template from its Omeka label.\n",
       "\n",
       "Parameters:\n",
       "* `label` - the name of the resource template in Omeka (eg. 'NewspaperArticle')\n",
       "\n",
       "Returns:\n",
       "* dict containing representation of the template"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.get_template_by_label)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "newspaper_template = omeka.get_template_by_label('Newspaper')\n",
    "\n",
    "assert newspaper_template['@type'] == 'o:ResourceTemplate'\n",
    "assert newspaper_template['o:label'] == 'Newspaper'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a random template from list\n",
    "template_from_list = random.choice(omeka.get_resources('resource_templates')['results'])\n",
    "label = template_from_list['o:label']\n",
    "\n",
    "# Get the template using label\n",
    "template_from_label = omeka.get_template_by_label(label)\n",
    "\n",
    "# Check they're both the same\n",
    "assert template_from_list == template_from_label"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.get_resource_by_term\" class=\"doc_header\"><code>OmekaAPIClient.get_resource_by_term</code><a href=\"__main__.py#L128\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.get_resource_by_term</code>(**`term`**, **`resource_type`**=*`'properties'`*)\n",
       "\n",
       "Get the resource (property or class) associated with the suppied term.\n",
       "\n",
       "Parameters:\n",
       "* `term` - property label qualified with vocabulary prefix (eg: 'schema:name')\n",
       "\n",
       "Returns:\n",
       "* dict containing representation of the resource"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.get_resource_by_term)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'@context': 'http://timsherratt.org/collections/api-context',\n",
       " '@id': 'http://timsherratt.org/collections/api/properties/1116',\n",
       " '@type': 'o:Property',\n",
       " 'o:id': 1116,\n",
       " 'o:local_name': 'name',\n",
       " 'o:label': 'name',\n",
       " 'o:comment': 'The name of the item.',\n",
       " 'o:term': 'schema:name',\n",
       " 'o:vocabulary': {'@id': 'http://timsherratt.org/collections/api/vocabularies/5',\n",
       "  'o:id': 5}}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "prop = omeka.get_resource_by_term('schema:name')\n",
    "prop"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert prop['@type'] == 'o:Property'\n",
    "assert prop['o:term'] == 'schema:name'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.get_resource_from_vocab\" class=\"doc_header\"><code>OmekaAPIClient.get_resource_from_vocab</code><a href=\"__main__.py#L140\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.get_resource_from_vocab</code>(**`local_name`**, **`vocabulary_namespace_uri`**=*`'http://schema.org/'`*, **`resource_type`**=*`'properties'`*)\n",
       "\n",
       "Get the resource (property or class) associated with the suppied vocabulary and label.\n",
       "\n",
       "Parameters:\n",
       "* `local_name` - label of the property or class\n",
       "* `vocabulary_namespace_uri` - URI defining the vocab\n",
       "\n",
       "Returns:\n",
       "* dict containing representation of the resource"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.get_resource_from_vocab)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'@context': 'http://timsherratt.org/collections/api-context',\n",
       " '@id': 'http://timsherratt.org/collections/api/properties/1116',\n",
       " '@type': 'o:Property',\n",
       " 'o:id': 1116,\n",
       " 'o:local_name': 'name',\n",
       " 'o:label': 'name',\n",
       " 'o:comment': 'The name of the item.',\n",
       " 'o:term': 'schema:name',\n",
       " 'o:vocabulary': {'@id': 'http://timsherratt.org/collections/api/vocabularies/5',\n",
       "  'o:id': 5}}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "prop = omeka.get_resource_from_vocab(\n",
    "    'name', \n",
    "    vocabulary_namespace_uri='http://schema.org/',\n",
    "    resource_type='properties')\n",
    "prop"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "vocab = requests.get(prop['o:vocabulary']['@id'])\n",
    "namespace_uri = vocab.json()['o:namespace_uri']\n",
    "\n",
    "assert namespace_uri == 'http://schema.org/'\n",
    "assert prop['o:local_name'] == 'name'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.get_property_id\" class=\"doc_header\"><code>OmekaAPIClient.get_property_id</code><a href=\"__main__.py#L153\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.get_property_id</code>(**`term`**)\n",
       "\n",
       "Get the numeric identifier associated with the supplied property term.\n",
       "\n",
       "Parameters:\n",
       "* `term` - property label qualified with vocabulary prefix (eg: 'schema:name')\n",
       "\n",
       "Returns:\n",
       "* numeric identifier"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.get_property_id)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1116"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "prop_id = omeka.get_property_id('schema:name')\n",
    "prop_id"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert isinstance(prop_id, int)\n",
    "\n",
    "prop = omeka.get_resource_by_id(prop_id, 'properties')\n",
    "assert prop['o:term'] == 'schema:name'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.filter_items_by_property\" class=\"doc_header\"><code>OmekaAPIClient.filter_items_by_property</code><a href=\"__main__.py#L174\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.filter_items_by_property</code>(**`filter_property`**=*`'schema:name'`*, **`filter_value`**=*`''`*, **`filter_type`**=*`'eq'`*, **`page`**=*`1`*, **\\*\\*`extra_filters`**)\n",
       "\n",
       "Filter the list of items by searching for a value in a particular property.\n",
       "Additional filters can also limit to items associated with particular templates, classes, or item sets.\n",
       "\n",
       "Parameters:\n",
       "* `filter_property` - property term (eg: 'schema:name')\n",
       "* `filter_value` - the value you want to find\n",
       "* `filter_type` - how `filter_value` should be compared to the stored values (eg: 'eq')\n",
       "* `page` - number of results page\n",
       "\n",
       "Additional parameters:\n",
       "* `resource_template_id` - numeric identifier\n",
       "* `resource_class_id` - numeric identifier\n",
       "* `item_set_id` - numeric identifier\n",
       "* `is_public` - boolean, True or False\n",
       "\n",
       "Returns a dict with the following values:\n",
       "* `total_results` - number of matching resources\n",
       "* `results` - a list of dicts, each containing a JSON-LD formatted representation of a resource"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.filter_items_by_property)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "items = omeka.filter_items_by_property(filter_property='schema:name', filter_value='wragge', filter_type='in')\n",
    "\n",
    "assert len(items['results']) > 0\n",
    "assert 'wragge' in items['results'][0]['schema:name'][0]['@value'].lower()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Clement Wragge at Home. - UPDATED! - UPDATED!'"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "items['results'][0]['schema:name'][0]['@value']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.search_items\" class=\"doc_header\"><code>OmekaAPIClient.search_items</code><a href=\"__main__.py#L210\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.search_items</code>(**`query`**, **`search_type`**=*`'fulltext_search'`*, **`page`**=*`1`*, **\\*\\*`extra_filters`**)\n",
       "\n",
       "Search for matching items.\n",
       "Two search types are available:\n",
       "* 'search` - looks for an exact match of the query in a property value\n",
       "* 'fulltext_search` - looks for the occurance of the query anywhere\n",
       "\n",
       "Parameters:\n",
       "* `query` - the text you want to search for\n",
       "* `search_type` - one of 'fulltext_search' or 'search'\n",
       "* `page` - number of results page\n",
       "\n",
       "Additional parameters:\n",
       "* `resource_template_id` - numeric identifier\n",
       "* `resource_class_id` - numeric identifier\n",
       "* `item_set_id` - numeric identifier\n",
       "* `is_public` - boolean, True or False\n",
       "\n",
       "Returns a dict with the following values:\n",
       "* `total_results` - number of matching resources\n",
       "* `results` - a list of dicts, each containing a JSON-LD formatted representation of a resource"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.search_items)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "23"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "items = omeka.search_items('wragge')\n",
    "items['total_results']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert items['total_results'] >= len(items['results'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding items\n",
    "\n",
    "To add resources to Omeka you need authenticate your API requests by supplying `key_identity` and `key_credential` tokens as parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "omeka_auth = OmekaAPIClient(\n",
    "    api_url='https://timsherratt.org/collections/api',\n",
    "    key_identity=os.getenv('KEY_IDENTITY'), \n",
    "    key_credential=os.getenv('KEY_CREDENTIAL')\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are two stages in creating a new item:\n",
    "\n",
    "* prepare a payload containing the item data in the format expected by Omeka\n",
    "* upload the payload to Omeka\n",
    "\n",
    "### Prepare an item payload"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.prepare_item_payload\" class=\"doc_header\"><code>OmekaAPIClient.prepare_item_payload</code><a href=\"__main__.py#L336\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.prepare_item_payload</code>(**`terms`**)\n",
       "\n",
       "Prepare an item payload, ready for upload.\n",
       "\n",
       "Parameters:\n",
       "* `terms`: a dict of terms, values, and (optionally) data types\n",
       "\n",
       "Returns:\n",
       "* the payload dict"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.prepare_item_payload)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "test_item = {\n",
    "    'dcterms:title': [\n",
    "        {\n",
    "            'value': 'My first resource!'\n",
    "        }\n",
    "    ]\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'dcterms:title': [{'property_id': 1,\n",
       "   'type': 'literal',\n",
       "   '@value': 'My first resource!'}]}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "payload = omeka_auth.prepare_item_payload(test_item)\n",
    "payload"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each term in the payload should have values for `property_id` and `type`, and the property value should be included as either `@id` or `@value` depending on the data type."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "first_property = list(payload.values())[0][0]\n",
    "\n",
    "assert 'property_id' in first_property\n",
    "assert 'type' in first_property\n",
    "assert '@value' in first_property or '@id' in first_property"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One of the powerful features of Omeka S is the ability to create resource templates that define a set of properties for a particular type of item. We can use templates to help create our payload, ensuring that the terms and data types we supply match those expected by the template. This is useful for identifying potential problems before we upload to Omeka, especially as Omeka will sometimes just fail silently."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.prepare_item_payload_using_template\" class=\"doc_header\"><code>OmekaAPIClient.prepare_item_payload_using_template</code><a href=\"__main__.py#L360\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.prepare_item_payload_using_template</code>(**`terms`**, **`template_id`**)\n",
       "\n",
       "Prepare an item payload, checking the supplied terms and values against the specified template.\n",
       "Note:\n",
       "* terms that are not in the template will generate a warning and be dropped from the payload\n",
       "* data types that don't match the template definitions will generate a warning and the term will be dropped from the payload\n",
       "* if no data type is supplied, a type that conforms with the template definition will be used\n",
       "\n",
       "Parameters:\n",
       "* `terms`: a dict of terms, values, and (optionally) data types\n",
       "* `template_id`: Omeka's internal numeric identifier for the template\n",
       "\n",
       "Returns:\n",
       "* the payload dict"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.prepare_item_payload_using_template)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once you've created a payload, you can add paths to any media files that you want to be attached to the item."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "test_newspaper_item = {\n",
    "    'schema:name': [\n",
    "        {\n",
    "            'value': 'Wragge!'\n",
    "        }\n",
    "    ]\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'schema:name': [{'property_id': 1116,\n",
       "   'type': 'literal',\n",
       "   '@value': 'Wragge!'}]}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "test_newspaper_payload = omeka_auth.prepare_item_payload_using_template(test_newspaper_item, 5)\n",
    "test_newspaper_payload"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert test_newspaper_item['schema:name'][0]['value'] == test_newspaper_payload['schema:name'][0]['@value']\n",
    "assert test_newspaper_payload['schema:name'][0]['type'] == 'literal'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.add_media_to_payload\" class=\"doc_header\"><code>OmekaAPIClient.add_media_to_payload</code><a href=\"__main__.py#L406\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.add_media_to_payload</code>(**`payload`**, **`media_files`**)\n",
       "\n",
       "Add media files to the item payload.\n",
       "\n",
       "Parameters:\n",
       "* `payload` - the payload dict to be modified\n",
       "* `media_files` - media files to be uploaded\n",
       "\n",
       "The value of `media_files` can be either:\n",
       "* a list of paths to the image/media files (filename is used as title)\n",
       "* a list of dicts, each containing `title`, and `path` values\n",
       "\n",
       "The path values can either be strings or pathlib Paths.\n",
       "\n",
       "Returns: \n",
       "* the modified payload dict"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.add_media_to_payload)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "payload_with_media = omeka_auth.add_media_to_payload({}, media_files=['media/nla.news-article226799674-24144902.jpg'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert json.loads(payload_with_media['data'][1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Upload the payload to Omeka and create a new item"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.add_item\" class=\"doc_header\"><code>OmekaAPIClient.add_item</code><a href=\"__main__.py#L303\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.add_item</code>(**`payload`**, **`media_files`**=*`None`*, **`template_id`**=*`None`*, **`class_id`**=*`None`*, **`item_set_id`**=*`None`*)\n",
       "\n",
       "Create a new item from the supplied payload, optionally uploading attached media files.\n",
       "\n",
       "Parameters:\n",
       "* `payload` - a dict generated by `prepare_item_payload()` or `prepare_item_payload_using_template()`\n",
       "* `media_files` - a list of paths pointing to media files, or a list of dicts with `path` and `title` values\n",
       "* `template_id` - internal Omeka identifier of a resource template you want to attach to this item\n",
       "* `class_id` - internal Omeka identifier of a resource class you want to attach to this item\n",
       "* `item_set_id` - internal Omeka identifier for an item set you want to add this item to\n",
       "\n",
       "Returns:\n",
       "* a dict providing the JSON-LD representation of the new item from Omeka"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.add_item)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Add a simple item"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'@context': 'https://timsherratt.org/collections/api-context',\n",
       " '@id': 'https://timsherratt.org/collections/api/items/1038',\n",
       " '@type': 'o:Item',\n",
       " 'o:id': 1038,\n",
       " 'o:is_public': True,\n",
       " 'o:owner': {'@id': 'https://timsherratt.org/collections/api/users/1',\n",
       "  'o:id': 1},\n",
       " 'o:resource_class': None,\n",
       " 'o:resource_template': None,\n",
       " 'o:thumbnail': None,\n",
       " 'o:title': 'My first resource!',\n",
       " 'thumbnail_display_urls': {'large': None, 'medium': None, 'square': None},\n",
       " 'o:created': {'@value': '2022-04-04T00:47:02+00:00',\n",
       "  '@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},\n",
       " 'o:modified': {'@value': '2022-04-04T00:47:02+00:00',\n",
       "  '@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},\n",
       " 'o:media': [],\n",
       " 'o:item_set': [],\n",
       " 'o:site': [],\n",
       " 'dcterms:title': [{'type': 'literal',\n",
       "   'property_id': 1,\n",
       "   'property_label': 'Title',\n",
       "   'is_public': True,\n",
       "   '@value': 'My first resource!'}]}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "new_item = omeka_auth.add_item(payload)\n",
    "new_item"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert new_item['@type'] == 'o:Item'\n",
    "assert test_item['dcterms:title'][0]['value'] == new_item['dcterms:title'][0]['@value']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also add an item to an existing item set by supplying the `item_set_id` parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a random item set id\n",
    "random_item_set = random.choice(omeka_auth.get_resources('item_sets')['results'])\n",
    "item_set_id = random_item_set['o:id']\n",
    "\n",
    "# Create a new item using the item set id\n",
    "new_item_in_item_set = new_item = omeka_auth.add_item(payload, item_set_id=item_set_id)\n",
    "\n",
    "# Check that the ids match\n",
    "assert new_item_in_item_set['o:item_set'][0]['o:id'] == item_set_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Updating resources"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.delete_resource\" class=\"doc_header\"><code>OmekaAPIClient.delete_resource</code><a href=\"__main__.py#L440\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.delete_resource</code>(**`resource_id`**, **`resource_type`**)\n",
       "\n",
       "Deletes a resource. No confirmation is requested, so use carefully.\n",
       "\n",
       "Parameters:\n",
       "* `resource_id` - local Omeka identifier of the resource you want to delete\n",
       "* `resource_type` - type of the resource (eg 'items')\n",
       "\n",
       "Returns:\n",
       "* dict with JSON-LD representation of the deleted resource"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.delete_resource)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a random item from a list of items\n",
    "data = omeka.get_resources('items')\n",
    "random_item = random.choice(data['results'])\n",
    "\n",
    "deleted_resource = omeka_auth.delete_resource(random_item['o:id'], 'items')\n",
    "\n",
    "# The id of the deleted item should be None\n",
    "assert deleted_resource['o:id'] is None\n",
    "\n",
    "# The titles of the random and deleted items should be the same\n",
    "assert deleted_resource['o:title'] == random_item['o:title']\n",
    "\n",
    "# Trying to get the random item should now raise an HTTP 404 error\n",
    "with pytest.raises(requests.exceptions.HTTPError):\n",
    "    omeka_auth.get_resource_by_id(random_item['o:id'], 'items')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.update_resource\" class=\"doc_header\"><code>OmekaAPIClient.update_resource</code><a href=\"__main__.py#L455\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.update_resource</code>(**`payload`**, **`resource_type`**=*`'items'`*)\n",
       "\n",
       "Update an existing resource.\n",
       "\n",
       "Parameters:\n",
       "* `payload` - the updated resource data\n",
       "* `resource_type` - the type of resource\n",
       "\n",
       "To avoid problems, it's generally easiest to retrieve the resource first,\n",
       "make your desired changes to it, then submit the updated resource as your payload."
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.update_resource)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Wellington Times (NSW : 1899 - 1954) - UPDATED! - UPDATED! - UPDATED!\n"
     ]
    }
   ],
   "source": [
    "# Get a random item from a list of items\n",
    "data = omeka_auth.filter_items_by_property(filter_property='schema:name', filter_type='ex')\n",
    "random_item = random.choice(data['results'])\n",
    "# Original title\n",
    "title = random_item['schema:name'][0]['@value']\n",
    "\n",
    "# Copy and update the original item\n",
    "new_item = deepcopy(random_item)\n",
    "new_item['schema:name'][0]['@value'] = title + ' - UPDATED!'\n",
    "\n",
    "# Update the item \n",
    "updated_item = omeka_auth.update_resource(new_item, 'items')\n",
    "\n",
    "# Display the updated title\n",
    "updated_title = updated_item['schema:name'][0]['@value']\n",
    "print(updated_title)\n",
    "\n",
    "# The id of the original and upated items should be the same\n",
    "assert random_item['o:id'] == updated_item['o:id']\n",
    "\n",
    "# But the titles should be different\n",
    "assert title != updated_item['schema:name'][0]['@value']"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Adding a new property to an existing item.  \n",
    "It's easier to use `OmekaAPIClient.prepare_property_value`.  \n",
    "The existing payload should be kept.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a random item from a list of items\n",
    "data = omeka_auth.filter_items_by_property(filter_property='schema:name', filter_type='ex')\n",
    "random_item = random.choice(data['results'])\n",
    "\n",
    "# New property with URI data (label and URI, as proposed in omeka UI)\n",
    "new_propTerm = 'crm:P45_consists_of'\n",
    "new_propId = omeka_auth.get_property_id(new_propTerm)\n",
    "new_propValue = {'value': 'http://vocab.getty.edu/aat/300010814', 'type': 'uri', 'label': 'crystal (AAT)'}\n",
    "formatted_new_prop = omeka_auth.prepare_property_value(new_propValue, new_propId)\n",
    "\n",
    "# Copy and update the original item\n",
    "new_item = deepcopy(random_item)\n",
    "new_item[new_propTerm] = [formatted_new_prop,]\n",
    "# note: this overwrites values in `new_propTerm` if it already exists in item (manage exceptions by you own with tests)\n",
    "\n",
    "# Update the item \n",
    "updated_item = omeka_auth.update_resource(new_item, 'items')\n",
    "\n",
    "# The id of the original and upated items should be the same\n",
    "assert random_item['o:id'] == updated_item['o:id']\n",
    "\n",
    "# But the new property has been added to the updated item\n",
    "assert new_propTerm in updated_item"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.add_media_to_item\" class=\"doc_header\"><code>OmekaAPIClient.add_media_to_item</code><a href=\"__main__.py#L470\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.add_media_to_item</code>(**`item_id`**, **`media_file`**, **`payload`**=*`{}`*, **`template_id`**=*`None`*, **`class_id`**=*`None`*)\n",
       "\n",
       "Upload a media file and associate it with an existing item.\n",
       "\n",
       "Parameters:\n",
       "* `item_id` - the Omeka id of the item this media file should be added to\n",
       "* `media_path` - a path to an image/media file (string or pathlib Path)\n",
       "* `payload` (optional) - metadata to attach to media object, either \n",
       "   a dict generated by `prepare_item_payload()` or `prepare_item_payload_using_template()`,\n",
       "   or a string which is used as the value for `dcterms:title`.\n",
       "* `template_id` - internal Omeka identifier of a resource template you want to attach to this item\n",
       "* `class_id` - internal Omeka identifier of a resource class you want to attach to this item\n",
       "\n",
       "Returns: \n",
       "* a dict providing a JSON-LD representation of the new media object"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.add_media_to_item)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "omeka_auth = OmekaAPIClient(\n",
    "    api_url='https://timsherratt.org/collections/api',\n",
    "    key_identity=os.getenv('KEY_IDENTITY'), \n",
    "    key_credential=os.getenv('KEY_CREDENTIAL')\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Add a media file to an item without any additional metadata."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a random item from a list of items\n",
    "data = omeka_auth.get_resources('items')\n",
    "item = random.choice(data['results'])\n",
    "item_id = item['o:id']\n",
    "\n",
    "# Add a new media file to the item\n",
    "media_resource = omeka_auth.add_media_to_item(item_id, 'media/nla.news-article226799674-24144902.jpg')\n",
    "\n",
    "# Check that the media resource is the expected type\n",
    "assert media_resource['@type'] == 'o:Media'\n",
    "\n",
    "# Check that the media resource is linked to the item\n",
    "assert media_resource['o:item']['o:id'] == item_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Include a title for a new media item by supplying a string value to the `payload` parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Add a new media file with a title to the item\n",
    "media_resource = omeka_auth.add_media_to_item(item_id, 'media/nla.news-article226799674-24144902.jpg', payload='This has a title')\n",
    "\n",
    "# The title should be saved as dcterms:title\n",
    "assert media_resource['dcterms:title'][0]['@value'] == 'This has a title'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Include more detailed metadata with a new media item by generating a payload and supplying it using the `payload` parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define some metadata\n",
    "media_metadata = {\n",
    "    'schema:name': ['This is a different title'],\n",
    "    'schema:identifier': ['myidis3']\n",
    "}\n",
    "\n",
    "# Convert metadata into an Omeka payload\n",
    "media_payload = omeka_auth.prepare_item_payload(media_metadata)\n",
    "\n",
    "# Add a new media file with a metadata payload to the item\n",
    "media_resource = omeka_auth.add_media_to_item(item_id, 'media/nla.news-article226799674-24144902.jpg', payload=media_payload)\n",
    "\n",
    "assert media_resource['schema:name'][0]['@value'] == 'This is a different title'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use a specific resource template with the new media item by using the `template_id` parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a random template from a list of available templates for testing\n",
    "data = omeka_auth.get_resources('resource_templates')\n",
    "template = random.choice(data['results'])\n",
    "template_id = template['o:id']\n",
    "\n",
    "# Add a new media file and assign it to a template using the `template_id` parameter\n",
    "media_resource = omeka_auth.add_media_to_item(item_id, 'media/nla.news-article226799674-24144902.jpg', payload=media_payload, template_id=template_id)\n",
    "\n",
    "# Check the new media object has the correct template id\n",
    "assert media_resource['o:resource_template']['o:id'] == template_id"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.add_marker_to_item\" class=\"doc_header\"><code>OmekaAPIClient.add_marker_to_item</code><a href=\"__main__.py#L653\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.add_marker_to_item</code>(**`item_id`**, **`coords`**=*`None`*, **`terms`**=*`None`*, **`label`**=*`None`*, **`media_id`**=*`None`*)\n",
       "\n",
       "Add a map marker to an item.\n",
       "Requires the `mapping` module to be installed.\n",
       "\n",
       "Parameters:\n",
       "* `item_id` - identifier of item to add marker to\n",
       "* `coords` - list with coordinates in longitude, latitude order eg [151.209900, -33.865143]\n",
       "* `terms` - list with vocab terms containing longitude and latitude values eg ['schema:longitude', 'schema:latitude']\n",
       "* `label` - label for marker (defaults to item title)\n",
       "* `media_id` - identifier of media resource to display with marker\n",
       "\n",
       "Returns:\n",
       "* dict providing JSON-LD representation of marker"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.add_marker_to_item)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Omeka [Mapping](https://omeka.org/s/modules/Mapping/) module lets you associate an item with a location on a map. Once you have the module installed, you can use the Omeka API to add map markers to items."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a random item from a list of items\n",
    "data = omeka_auth.get_resources('items')\n",
    "item = random.choice(data['results'])\n",
    "item_id = item['o:id']\n",
    "\n",
    "# Add a marker using coords\n",
    "marker = omeka_auth.add_marker_to_item(item_id, coords=[151.209900, -33.865143])\n",
    "\n",
    "assert marker['@type'] == 'o-module-mapping:Marker'\n",
    "assert marker['o:item']['o:id'] == item_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also read the map coordinates from the item itself. By default `OmekaAPIClient.add_marker_to_item` will look for values in `schema:longitude` and `schema:latitude`, but you can specify the vocabulary terms that you want to look for.\n",
    "\n",
    "Here we'll create a simple item with values for `schema:longitude` and `schema:latitude`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "test_place = {\n",
    "    'schema:name': [\n",
    "        {\n",
    "            'value': 'Australia'\n",
    "        }\n",
    "    ],\n",
    "    'schema:longitude': [\n",
    "        {\n",
    "            'value': '151.209900'\n",
    "        }\n",
    "    ],\n",
    "    'schema:latitude': [\n",
    "        {\n",
    "            'value': '-33.865143'\n",
    "        }\n",
    "    ],\n",
    "    \n",
    "}\n",
    "\n",
    "payload = omeka_auth.prepare_item_payload(test_place)\n",
    "new_place = omeka_auth.add_item(payload)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can just call `OmekaAPIClient.add_marker_to_item` without any coordinates, and it will get them from `schema:longitude` and `schema:latitude`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_marker = omeka_auth.add_marker_to_item(new_place['o:id'])\n",
    "\n",
    "assert new_marker['@type'] == 'o-module-mapping:Marker'\n",
    "assert new_marker['o:item']['o:id'] == new_place['o:id']\n",
    "assert new_marker['o-module-mapping:lat'] == -33.865143"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Managing templates\n",
    "\n",
    "Resource templates can be exported from one Omeka instance and imported into another. This is a really useful way of sharing and resuing data structures. However, exported templates can't be uploaded via the API without some modification, as they don't include Omeka numeric identifiers for referenced classes and properties. Before uploading them, we need to find the referenced classes and properties in the local Omeka instance, and insert the local identifiers into the payload.\n",
    "\n",
    "Similarly, if custom vocabs are referenced in the exported template, they will need to be updated to include the vocab's identifier in the new Omeka instance. Of course, you'll need to make sure it's installed first.\n",
    "\n",
    "In general, you want to make sure that the any vocabs and data types referenced by the exported templates will be available in the new Omeka instance. So before you upload any templates you should check that:\n",
    "\n",
    "* referenced vocabularies are already installed\n",
    "* modules used in defining data types are installed ( eg the [Numeric Data Types](https://omeka.org/s/modules/NumericDataTypes/) module provides additional data types such as `Timestamp` for dates\n",
    "* any custom vocabularies (created using the [Custom Vocab](https://omeka.org/s/modules/CustomVocab/) are installed, along with the module itself of course\n",
    "* the [Value Suggest](https://omeka.org/s/modules/ValueSuggest/) module is installed if the template includes references to the controlled vocabs it provides"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.prepare_template_payload\" class=\"doc_header\"><code>OmekaAPIClient.prepare_template_payload</code><a href=\"__main__.py#L583\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.prepare_template_payload</code>(**`template_file`**)\n",
       "\n",
       "Insert local property, class, and vocab identifiers into a resource template\n",
       "exported from Omeka so that it can be uploaded to the local instance.\n",
       "\n",
       "Parameters:\n",
       "* `template_file` - path to a template exported from Omeka (str or pathlib Path)\n",
       "\n",
       "Returns:\n",
       "* template payload with local identifiers inserted"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.prepare_template_payload)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "omeka_auth = OmekaAPIClient(\n",
    "    api_url='https://timsherratt.org/collections/api',\n",
    "    key_identity=os.getenv('KEY_IDENTITY'), \n",
    "    key_credential=os.getenv('KEY_CREDENTIAL')\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "template_payload = omeka_auth.prepare_template_payload('templates/Person.json')\n",
    "\n",
    "# Check the label\n",
    "assert template_payload['o:label'] == 'Person'\n",
    "\n",
    "# Check that there is a list of properties\n",
    "assert len(template_payload['o:resource_template_property']) > 0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.upload_template\" class=\"doc_header\"><code>OmekaAPIClient.upload_template</code><a href=\"__main__.py#L636\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.upload_template</code>(**`template_payload`**)\n",
       "\n",
       "Upload a template exported from an instance of Omeka to the current local instance.\n",
       "\n",
       "Parameters:\n",
       "* `template_payload` - dict payload generated by `prepare_template_payload`\n",
       "\n",
       "Return:\n",
       "* dict containing a JSON-LD representation of the uploaded template"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.upload_template)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# First we'll check to see if there's already a template with the label 'Person'\n",
    "existing_template = omeka_auth.get_template_by_label('Person')\n",
    "\n",
    "# If there is we'll delete it\n",
    "# Trying to upload a template with the same label as an existing template will generate an error\n",
    "if existing_template:\n",
    "    deleted = omeka_auth.delete_resource(existing_template['o:id'], 'resource_templates')\n",
    "\n",
    "# Now we can add the new template\n",
    "template_payload = omeka_auth.prepare_template_payload('templates/Person.json')\n",
    "new_template = omeka_auth.upload_template(template_payload)\n",
    "\n",
    "# Result should be a 'ResourceTemplate\n",
    "assert new_template['@type'] == 'o:ResourceTemplate'\n",
    "\n",
    "# Label should be 'Person'\n",
    "assert new_template['o:label'] == 'Person'\n",
    "\n",
    "# It should have properties\n",
    "assert len(new_template['o:resource_template_property']) > 0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.localise_custom_vocabs\" class=\"doc_header\"><code>OmekaAPIClient.localise_custom_vocabs</code><a href=\"__main__.py#L517\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.localise_custom_vocabs</code>(**`data_types`**)\n",
       "\n",
       "Check a list of data types for references to custom vocabs.\n",
       "If found, look for the local identifier of the custom vocab, \n",
       "and insert it into the data type information.\n",
       "\n",
       "Parameters:\n",
       "* `data_types` - a list of data types from an exported template property\n",
       "\n",
       "Returns:\n",
       "* list of datatypes with local identifiers"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.localise_custom_vocabs)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['customvocab:1']\n"
     ]
    }
   ],
   "source": [
    "# Data type example with ridiculously high customvocab id value\n",
    "data_types = [{'name': 'customvocab:200000', 'label': \"Date qualifiers\"}]\n",
    "\n",
    "# Localise!\n",
    "localised_data_types = omeka_auth.localise_custom_vocabs(data_types)\n",
    "print(localised_data_types)\n",
    "\n",
    "# Localised data type should start with 'customvocab'\n",
    "assert localised_data_types[0].startswith('customvocab:')\n",
    "\n",
    "# The localised customvocab id should not be the same as the supplied one\n",
    "assert localised_data_types[0] != data_types[0]['name']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.get_template_class_id\" class=\"doc_header\"><code>OmekaAPIClient.get_template_class_id</code><a href=\"__main__.py#L542\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.get_template_class_id</code>(**`template`**)\n",
       "\n",
       "Get the local id of the resource class associated with the supplied template.\n",
       "\n",
       "Parameters:\n",
       "* `template` - dict from exported template\n",
       "\n",
       "Returns:\n",
       "* class identifier"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.get_template_class_id)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load template from filesystem\n",
    "template = json.loads(Path('templates/Person.json').read_bytes())\n",
    "\n",
    "person_class_id = omeka_auth.get_resource_by_term('schema:Person', 'resource_classes')['o:id']\n",
    "\n",
    "# Get resource id\n",
    "class_id = omeka_auth.get_template_class_id(template)\n",
    "\n",
    "assert class_id == person_class_id"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.get_template_property_id\" class=\"doc_header\"><code>OmekaAPIClient.get_template_property_id</code><a href=\"__main__.py#L562\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.get_template_property_id</code>(**`template`**, **`term`**)\n",
       "\n",
       "Get the local id of the property associated with the supplied template.\n",
       "\n",
       "Parameters:\n",
       "* `template` - dict from exported template\n",
       "* `term` - property term (eg 'o:title_property')\n",
       "\n",
       "Returns:\n",
       "* property identifier"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.get_template_property_id)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load template from filesystem\n",
    "template = json.loads(Path('templates/Person.json').read_bytes())\n",
    "\n",
    "# get the id of the schema:name property\n",
    "name_prop_id = omeka_auth.get_resource_by_term('schema:name', 'properties')['o:id']\n",
    "\n",
    "# Get id of template property used for title\n",
    "prop_id = omeka_auth.get_template_property_id(template, 'o:title_property')\n",
    "\n",
    "# The ids should be the same\n",
    "assert prop_id == name_prop_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Utilities"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.format_resource_id\" class=\"doc_header\"><code>OmekaAPIClient.format_resource_id</code><a href=\"__main__.py#L46\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.format_resource_id</code>(**`resource_id`**, **`resource_type`**)\n",
       "\n",
       "Generate a formatted id for the resource with the specified Omeka id number and resource type.\n",
       "\n",
       "Parameters:\n",
       "* `resource_id` - numeric identifier used by Omeka for this resource\n",
       "* `resource_type` - one of Omeka's resource types, eg: 'items', 'properties'\n",
       "\n",
       "Returns:\n",
       "* a dict with values for '@id' and 'o:id'"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.format_resource_id)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "id_url = omeka.format_resource_id(5, 'resource_templates')\n",
    "\n",
    "assert id_url == {\n",
    "    '@id': 'http://timsherratt.org/collections/api/resource_templates/5',\n",
    "    'o:id': 5\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.prepare_property_value\" class=\"doc_header\"><code>OmekaAPIClient.prepare_property_value</code><a href=\"__main__.py#L266\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.prepare_property_value</code>(**`value`**, **`property_id`**)\n",
       "\n",
       "Formats a property value according to its datatype as expected by Omeka. \n",
       "The formatted value can be used in a payload to create a new item.\n",
       "\n",
       "Parameters:\n",
       "* `value` - a dict containing a `value` and (optionally) a `type`\n",
       "* `property_id` - the numeric identifier of the property\n",
       "\n",
       "Note that is no `type` is supplied, 'literal' will be used by default.\n",
       "\n",
       "Returns:\n",
       "* a dict with values for `property_id`, `type`, and either `@id` or `@value`."
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.prepare_property_value)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'property_id': 393, 'type': 'uri', '@id': 'https://glam-workbench.net'}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "prop_id = omeka_auth.get_property_id('schema:url')\n",
    "prop_value = {'value': 'https://glam-workbench.net', 'type': 'uri'}\n",
    "\n",
    "formatted_prop = omeka_auth.prepare_property_value(prop_value, prop_id)\n",
    "formatted_prop"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert prop_id == formatted_prop['property_id']\n",
    "assert 'type' in formatted_prop\n",
    "assert formatted_prop['@id'] == 'https://glam-workbench.net'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"OmekaAPIClient.get_template_properties\" class=\"doc_header\"><code>OmekaAPIClient.get_template_properties</code><a href=\"__main__.py#L238\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>OmekaAPIClient.get_template_properties</code>(**`template_id`**)\n",
       "\n",
       "List properties used by the specified template.\n",
       "\n",
       "The resource template objects returned by the API don't include property terms.\n",
       "This function gets the additional details, and organises the properties in a dictionary, \n",
       "organised by term. This makes it easy to check if a particular term is used by a template.\n",
       "\n",
       "Parameters:\n",
       "* `template_id` - numeric identifier for a template\n",
       "\n",
       "Returns:\n",
       "* a dict organised by property terms, with values for `property_id` and `type`"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(OmekaAPIClient.get_template_properties)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "template_id = omeka_auth.get_template_by_label('Newspaper')['o:id']\n",
    "newspaper_properties = omeka_auth.get_template_properties(template_id)\n",
    "\n",
    "assert 'schema:name' in newspaper_properties"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example: adding a newspaper article from Trove"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the example below I'm going to manually step through the process of adding a new item to Omeka using the API in order to demonstrate the methods available. But of course the point of using the API is to automate such processes -- joining together the individual steps so they can be embedded into your own systems or workflows. For a more detailed example that uploads Trove newspaper articles from a variety of sources, including Trove searches, Trove lists, and Zotero libraries, see the [GLAM Workbench](https://glam-workbench.net/trove-newspapers/#upload-trove-newspaper-articles-to-omeka-s).\n",
    "\n",
    "Let's suppose we want to add [this newspaper article](http://nla.gov.au/nla.news-article226799674) in Trove to our Omeka instance. To take best advantage of Omeka's linked data infrastructure, we'll actually create two resources -- one for the article, and one for the newspaper it was published in.\n",
    "\n",
    "I've already created templates labelled 'Newspaper' and 'Newspaper article'.\n",
    "\n",
    "Let's start with the newspaper. First we need to find out the numeric identifier Omeka is using for the Newspaper template. We can use `OmekaAPIClient.get_template_by_label` to find out. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "omeka_auth = OmekaAPIClient(\n",
    "    api_url='http://timsherratt.org/collections/api',\n",
    "    key_identity=os.getenv('KEY_IDENTITY'), \n",
    "    key_credential=os.getenv('KEY_CREDENTIAL')\n",
    ")\n",
    "\n",
    "newspaper_template_id = omeka_auth.get_template_by_label('Newspaper')['o:id']\n",
    "newspaper_template_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For convenience, we can get a summary of the properties used in the Newspaper template using `OmekaAPIClient.get_template_properties`. This is useful if we want to check which properties are in use, and what data types are expected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'schema:name': {'property_id': 1116, 'type': ['literal']},\n",
       " 'schema:additionalType': {'property_id': 1199, 'type': ['uri']},\n",
       " 'schema:description': {'property_id': 528,\n",
       "  'type': ['literal', 'uri', 'resource:item']},\n",
       " 'schema:alternateName': {'property_id': 282,\n",
       "  'type': ['literal', 'uri', 'resource:item']},\n",
       " 'schema:editor': {'property_id': 752, 'type': ['resource:item']},\n",
       " 'schema:publisher': {'property_id': 967, 'type': ['resource:item']},\n",
       " 'schema:issn': {'property_id': 931,\n",
       "  'type': ['literal', 'uri', 'resource:item']},\n",
       " 'schema:startDate': {'property_id': 513, 'type': ['numeric:timestamp']},\n",
       " 'schema:endDate': {'property_id': 657, 'type': ['numeric:timestamp']},\n",
       " 'schema:locationCreated': {'property_id': 706, 'type': ['resource:item']},\n",
       " 'schema:hasPart': {'property_id': 1405, 'type': ['resource:item']},\n",
       " 'schema:about': {'property_id': 1392, 'type': ['resource:item']},\n",
       " 'schema:mentions': {'property_id': 747, 'type': ['resource:item']},\n",
       " 'schema:contentLocation': {'property_id': 1419, 'type': ['resource:item']},\n",
       " 'schema:temporalCoverage': {'property_id': 460,\n",
       "  'type': ['literal', 'uri', 'resource:item']},\n",
       " 'schema:subjectOf': {'property_id': 1391, 'type': ['resource:item']},\n",
       " 'schema:url': {'property_id': 393, 'type': ['uri']},\n",
       " 'schema:image': {'property_id': 742, 'type': ['resource:item']},\n",
       " 'schema:identifier': {'property_id': 190,\n",
       "  'type': ['literal', 'uri', 'resource:item']},\n",
       " 'schema:sameAs': {'property_id': 246, 'type': ['uri']}}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "omeka_auth.get_template_properties(newspaper_template_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first step in preparing our data for upload is to create a dictionary, using the required property terms as keys. In this case, we'll assign data about the newspaper to `schema.name` and `schema.url`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "newspaper = {\n",
    "    'schema.name': [\n",
    "        {\n",
    "            'type': 'literal',\n",
    "            'value': 'The Bendigo Independent (Vic. : 1891 - 1918)'\n",
    "        }\n",
    "    ],\n",
    "    'schema:url': [\n",
    "        {\n",
    "            'type': 'literal',\n",
    "            'value': 'http://nla.gov.au/nla.news-title806'\n",
    "        }\n",
    "    ]\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can use this data to create a payload for upload to Omeka. `OmekaAPIClient.prepare_item_payload_using_template` will check our data against the Newspaper template and build the payload."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Term schema.name not in template\n",
      "Data type \"literal\" for term \"schema:url\" not allowed by template\n"
     ]
    }
   ],
   "source": [
    "payload = omeka_auth.prepare_item_payload_using_template(newspaper, newspaper_template_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Whoops! It seems we have some problems with our data file! First of all we've used a full stop, rather than a colon in `schema:name`. Second, we've said the data type of `schema:url` is 'literal', but if we check the template properties we'll see it' should be 'uri'. Let's make these changes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "newspaper = {\n",
    "    'schema:name': [\n",
    "        {\n",
    "            'type': 'literal',\n",
    "            'value': 'The Bendigo Independent (Vic. : 1891 - 1918)'\n",
    "        }\n",
    "    ],\n",
    "    'schema:url': [\n",
    "        {\n",
    "            'type': 'uri',\n",
    "            'value': 'http://nla.gov.au/nla.news-title806'\n",
    "        }\n",
    "    ]\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "payload = omeka_auth.prepare_item_payload_using_template(newspaper, newspaper_template_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That seems better! Now we can examine the payload."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'schema:name': [{'property_id': 1116,\n",
       "   'type': 'literal',\n",
       "   '@value': 'The Bendigo Independent (Vic. : 1891 - 1918)'}],\n",
       " 'schema:url': [{'property_id': 393,\n",
       "   'type': 'uri',\n",
       "   '@id': 'http://nla.gov.au/nla.news-title806'}]}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "payload"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice how the values have been reformatted? They should now be ready to upload to Omeka using `OmekaAPIClient.add_item`. We'll supply both the payload and the newspaper template id."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "newspaper_item = omeka_auth.add_item(payload, template_id=newspaper_template_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can check the contents of `newspaper_item` to make sure it's been added succesfully."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'@context': 'http://timsherratt.org/collections/api-context',\n",
       " '@id': 'http://timsherratt.org/collections/api/items/1045',\n",
       " '@type': ['o:Item', 'schema:Newspaper'],\n",
       " 'o:id': 1045,\n",
       " 'o:is_public': True,\n",
       " 'o:owner': {'@id': 'http://timsherratt.org/collections/api/users/1',\n",
       "  'o:id': 1},\n",
       " 'o:resource_class': {'@id': 'http://timsherratt.org/collections/api/resource_classes/161',\n",
       "  'o:id': 161},\n",
       " 'o:resource_template': {'@id': 'http://timsherratt.org/collections/api/resource_templates/5',\n",
       "  'o:id': 5},\n",
       " 'o:thumbnail': None,\n",
       " 'o:title': 'The Bendigo Independent (Vic. : 1891 - 1918)',\n",
       " 'thumbnail_display_urls': {'large': None, 'medium': None, 'square': None},\n",
       " 'o:created': {'@value': '2022-04-04T00:48:33+00:00',\n",
       "  '@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},\n",
       " 'o:modified': {'@value': '2022-04-04T00:48:33+00:00',\n",
       "  '@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},\n",
       " 'o:media': [],\n",
       " 'o:item_set': [],\n",
       " 'o:site': [],\n",
       " 'schema:name': [{'type': 'literal',\n",
       "   'property_id': 1116,\n",
       "   'property_label': 'name',\n",
       "   'is_public': True,\n",
       "   '@value': 'The Bendigo Independent (Vic. : 1891 - 1918)'}],\n",
       " 'schema:url': [{'type': 'uri',\n",
       "   'property_id': 393,\n",
       "   'property_label': 'url',\n",
       "   'is_public': True,\n",
       "   '@id': 'http://nla.gov.au/nla.news-title806'}]}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "newspaper_item"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Great! Now what about the article? Again let's start by having a look at the 'Newspaper article' template."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'schema:name': {'property_id': 1116,\n",
       "  'type': ['literal', 'uri', 'resource:item']},\n",
       " 'schema:additionalType': {'property_id': 1199, 'type': ['uri']},\n",
       " 'schema:description': {'property_id': 528,\n",
       "  'type': ['literal', 'uri', 'resource:item']},\n",
       " 'schema:alternateName': {'property_id': 282,\n",
       "  'type': ['literal', 'uri', 'resource:item']},\n",
       " 'schema:datePublished': {'property_id': 928, 'type': ['numeric:timestamp']},\n",
       " 'schema:pagination': {'property_id': 376,\n",
       "  'type': ['literal', 'uri', 'resource:item']},\n",
       " 'schema:creator': {'property_id': 329, 'type': ['resource:item']},\n",
       " 'schema:contributor': {'property_id': 1303, 'type': ['resource:item']},\n",
       " 'schema:isPartOf': {'property_id': 736, 'type': ['resource:item']},\n",
       " 'schema:license': {'property_id': 1348,\n",
       "  'type': ['literal', 'uri', 'resource:item']},\n",
       " 'schema:about': {'property_id': 1392, 'type': ['resource:item']},\n",
       " 'schema:mentions': {'property_id': 747, 'type': ['resource:item']},\n",
       " 'schema:contentLocation': {'property_id': 1419, 'type': ['resource:item']},\n",
       " 'schema:temporalCoverage': {'property_id': 460,\n",
       "  'type': ['literal', 'uri', 'resource:item']},\n",
       " 'schema:subjectOf': {'property_id': 1391, 'type': ['resource:item']},\n",
       " 'schema:image': {'property_id': 742, 'type': ['resource:item']},\n",
       " 'schema:url': {'property_id': 393, 'type': ['uri']},\n",
       " 'schema:identifier': {'property_id': 190,\n",
       "  'type': ['literal', 'uri', 'resource:item']},\n",
       " 'schema:sameAs': {'property_id': 246, 'type': ['uri']},\n",
       " 'schema:text': {'property_id': 833,\n",
       "  'type': ['literal', 'uri', 'resource:item']}}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "article_template_id = omeka_auth.get_template_by_label('Newspaper article')['o:id']\n",
    "omeka_auth.get_template_properties(article_template_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This time we'll build our data file in stages."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create an empty dictionary\n",
    "article = {}\n",
    "\n",
    "# Add value for schema:name\n",
    "article['schema:name'] = [\"MR WRAGGE'S PREDICTION. RENEWAL OF CYCLONE FORETOLD.\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You'll notice that this time I've only included the value of the property, not the data type. This is because `OmekaAPIClient.prepare_item_payload_using_template` will insert default data types if they're not specified. The basic rules it uses if you don't supply a data type are:\n",
    "\n",
    "* if the template defines a default data type, use that\n",
    "* if 'literal' is in the template's list of expected data types, use that\n",
    "* if 'literal' is not in the template's list of expected data types print a warning asking the user to specify a data type and drop the property from the payload\n",
    "\n",
    "In the case above, the 'literal' data type will be assigned to the `schema:name` value.\n",
    "\n",
    "To create a link between the article and the newspaper it was published in, we can use `schema.isPartOf`. If we look in the list of template properties we see that this property expects a data type of 'resource:item'.\n",
    "\n",
    "```\n",
    "'schema:isPartOf': {'property_id': 736, 'type': ['resource:item']}\n",
    "```\n",
    "\n",
    "The 'resource:item' data type means that the value will be an identifier pointing to another Omeka item. So we include the identifier of the newly-created newspaper record. Once again, the data type will be automatically added when we generate the payload."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "article['schema:isPartOf'] = [newspaper_item['o:id']]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we'll add the publication date. To recognise dates as specific data types, you need to install the [Numeric Data Types](https://omeka.org/s/modules/NumericDataTypes/) module. Once that's done, you can set the 'numeric:timestamp' data type as the default for any date fields in your template. In the list of properties from the newspaper article template, you can see:\n",
    "\n",
    "```\n",
    "'schema:datePublished': {'property_id': 928, 'type': ['numeric:timestamp']}\n",
    "```\n",
    "\n",
    "The date value itself is supplied in a standard ISO format -- 'YYYY-MM-DD'."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "article['schema:datePublished'] = ['1918-03-14']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally we'll add a link to the article. Once again the template includes a default data type.\n",
    "\n",
    "```\n",
    "'schema:url': {'property_id': 393, 'type': ['uri']}\n",
    "```\n",
    "\n",
    "So we can just include the value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "article['schema:url'] = ['http://nla.gov.au/nla.news-article226799674']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we've assembled the article metadata, we can generate a payload."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "article_payload = omeka_auth.prepare_item_payload_using_template(article, article_template_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see below, the default data types have been inserted into the payload, and some additional fields have been added to define the link to the newspaper item."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'schema:name': [{'property_id': 1116,\n",
       "   'type': 'literal',\n",
       "   '@value': \"MR WRAGGE'S PREDICTION. RENEWAL OF CYCLONE FORETOLD.\"}],\n",
       " 'schema:isPartOf': [{'property_id': 736,\n",
       "   'type': 'resource:item',\n",
       "   '@id': 'http://timsherratt.org/collections/api/items/1045',\n",
       "   'value_resource_id': 1045,\n",
       "   'value_resource_name': 'items'}],\n",
       " 'schema:datePublished': [{'property_id': 928,\n",
       "   'type': 'numeric:timestamp',\n",
       "   '@value': '1918-03-14'}],\n",
       " 'schema:url': [{'property_id': 393,\n",
       "   'type': 'uri',\n",
       "   '@id': 'http://nla.gov.au/nla.news-article226799674'}]}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "article_payload"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We could now go ahead and upload the payload to Omeka, but what if we want to include media files? In this case I have a JPG image of the article I want to attach. All you need to do is supply a list of paths pointing to media files using the `media_files` parameter. The list can just include the paths as strings, in which case the file name will be used as the media object's title. Alternatively, you can supply a list of dicts, each containing a `path` and `title` value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create a list of paths pointing to media files\n",
    "# The paths can be strings or pathlib Paths\n",
    "media_files = ['media/nla.news-article226799674-24144902.jpg']\n",
    "\n",
    "# Include the media files when we upload the payload\n",
    "article_item = omeka_auth.add_item(article_payload, media_files=media_files, template_id=article_template_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we look at the uploaded item, we'll see that the media files have been processed and added to the record."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'@context': 'http://timsherratt.org/collections/api-context',\n",
       " '@id': 'http://timsherratt.org/collections/api/items/1046',\n",
       " '@type': ['o:Item', 'schema:NewsArticle'],\n",
       " 'o:id': 1046,\n",
       " 'o:is_public': True,\n",
       " 'o:owner': {'@id': 'http://timsherratt.org/collections/api/users/1',\n",
       "  'o:id': 1},\n",
       " 'o:resource_class': {'@id': 'http://timsherratt.org/collections/api/resource_classes/543',\n",
       "  'o:id': 543},\n",
       " 'o:resource_template': {'@id': 'http://timsherratt.org/collections/api/resource_templates/4',\n",
       "  'o:id': 4},\n",
       " 'o:thumbnail': None,\n",
       " 'o:title': \"MR WRAGGE'S PREDICTION. RENEWAL OF CYCLONE FORETOLD.\",\n",
       " 'thumbnail_display_urls': {'large': 'http://timsherratt.org/collections/files/large/c60918ee88cb729ae8803742bbbb185460700903.jpg',\n",
       "  'medium': 'http://timsherratt.org/collections/files/medium/c60918ee88cb729ae8803742bbbb185460700903.jpg',\n",
       "  'square': 'http://timsherratt.org/collections/files/square/c60918ee88cb729ae8803742bbbb185460700903.jpg'},\n",
       " 'o:created': {'@value': '2022-04-04T00:48:40+00:00',\n",
       "  '@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},\n",
       " 'o:modified': {'@value': '2022-04-04T00:48:40+00:00',\n",
       "  '@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},\n",
       " 'o:media': [{'@id': 'http://timsherratt.org/collections/api/media/1047',\n",
       "   'o:id': 1047}],\n",
       " 'o:item_set': [],\n",
       " 'o:site': [],\n",
       " 'schema:name': [{'type': 'literal',\n",
       "   'property_id': 1116,\n",
       "   'property_label': 'name',\n",
       "   'is_public': True,\n",
       "   '@value': \"MR WRAGGE'S PREDICTION. RENEWAL OF CYCLONE FORETOLD.\"}],\n",
       " 'schema:datePublished': [{'type': 'numeric:timestamp',\n",
       "   'property_id': 928,\n",
       "   'property_label': 'datePublished',\n",
       "   'is_public': True,\n",
       "   '@value': '1918-03-14',\n",
       "   '@type': 'http://www.w3.org/2001/XMLSchema#date'}],\n",
       " 'schema:isPartOf': [{'type': 'resource:item',\n",
       "   'property_id': 736,\n",
       "   'property_label': 'isPartOf',\n",
       "   'is_public': True,\n",
       "   '@id': 'http://timsherratt.org/collections/api/items/1045',\n",
       "   'value_resource_id': 1045,\n",
       "   'value_resource_name': 'items',\n",
       "   'url': None,\n",
       "   'display_title': 'The Bendigo Independent (Vic. : 1891 - 1918)'}],\n",
       " 'schema:url': [{'type': 'uri',\n",
       "   'property_id': 393,\n",
       "   'property_label': 'url',\n",
       "   'is_public': True,\n",
       "   '@id': 'http://nla.gov.au/nla.news-article226799674'}]}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "article_item"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}