collection-maker.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "02cabb72-dffe-48a9-a1d3-2d5ac4677a9a",
   "metadata": {},
   "source": [
    "Make a New Media Collection\n",
    "==========================="
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e869145-c027-4408-84fe-5260f3353754",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Setup\n",
    "\n",
    "The first time you run this, you need to run the below cell to install libraries this relies on"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ab4263b2-5458-4097-82be-19eaafe62930",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Install a pip package in the current Jupyter kernel\n",
    "import sys\n",
    "!{sys.executable} -m pip install mediacloud==3.13.0"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c4b35929-a92d-4682-b2be-0d893f05ce12",
   "metadata": {},
   "source": [
    "## Configuration"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "004909eb-3ec4-4409-afce-bb74b7267b22",
   "metadata": {},
   "source": [
    "Paste in your Media Cloud API key, which you can get from the profile page in any of our web apps."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cc15ef5d-a112-4112-b2b9-cba4e1d487aa",
   "metadata": {},
   "outputs": [],
   "source": [
    "my_api_key = \"YOUR_API_KEY\"\n",
    "\n",
    "# setup the library to make calls to our API with your key\n",
    "import mediacloud.api\n",
    "mc = mediacloud.api.AdminMediaCloud(my_api_key)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3386dfd9-a01c-42bd-88fa-baec067db769",
   "metadata": {},
   "source": [
    "Now setup the details about your collection. Edit the stuff in quotes below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b44c5553-c527-4b06-b4a7-3d55eb5a96e8",
   "metadata": {},
   "outputs": [],
   "source": [
    "collection_name = \"My Awesome Collection3\"  # what do you want users to see as the name for this collection?\n",
    "collection_computer_name = \"my_awesome_collection3\"  # give us a \"computery\" version of the collection name too\n",
    "collection_description = \"Explain the purpose, and credit people who helped\"\n",
    "is_it_static = False # set this to \"True\" if this is a collection that is a one-time snapshot and won't change, \"False\" otherwise"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cab1fa28-1a16-4077-8f8d-ef256558f51d",
   "metadata": {},
   "source": [
    "Now we need to check if this is a new collection or not, based on the `collection_name` you picked. If it is an existing one, we will update the collectioon to match your spreadsheet."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "29d87caa-84ab-4fe0-b818-0867c7ee7c16",
   "metadata": {},
   "outputs": [],
   "source": [
    "COLLECTION_TAG_SET = 5  # the id of the collection of collections (yes, this is confusing)\n",
    "similar_collections = mc.tagList(tag_sets_id=COLLECTION_TAG_SET, name_like=collection_name)\n",
    "existing_collection_id = None\n",
    "for c in similar_collections:\n",
    "    if c['label'].lower() == collection_name.lower():\n",
    "        existing_collection_id = c['tags_id']\n",
    "        print(\"This collection already exists, with id {}. We will update it, and NOT create a new one\".format(existing_collection_id))\n",
    "if existing_collection_id is None:\n",
    "    print(\"We will make a new collection for you.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ef63799-c87b-401e-98cb-37e3b41dbe53",
   "metadata": {},
   "source": [
    "## Make the Thing!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b5ecb38e-7485-40be-a799-c314d162560c",
   "metadata": {},
   "outputs": [],
   "source": [
    "# is it public?\n",
    "show_on_stories = True\n",
    "show_on_media = True"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b04db8a9-336a-4cb8-9224-d8cef8b64ef3",
   "metadata": {},
   "source": [
    "### Make/Find Media Sources"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9cc8a76-a14e-48ec-8361-2986a8772f14",
   "metadata": {},
   "source": [
    "First we iterate over all the media sources to find them or create them as needed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0594af7e-28c1-4d34-8602-e9b3776da1cf",
   "metadata": {},
   "outputs": [],
   "source": [
    "# read in the list of media\n",
    "import csv\n",
    "from requests.exceptions import ConnectionError\n",
    "INPUT_FILE = 'collection.csv'\n",
    "media_list = []\n",
    "with open(INPUT_FILE) as csvfile:\n",
    "    reader = csv.DictReader(csvfile)\n",
    "    for row in reader:\n",
    "        media_list.append(row)\n",
    "print(\"Loaded {} media from {}:\".format(len(media_list), INPUT_FILE))\n",
    "# This step check each one - it might take a while, but you'll see one row printed out below for each item,\n",
    "# so at least you can track the progress.\n",
    "import json\n",
    "media_ids = []\n",
    "start_index = 0\n",
    "for idx, m in enumerate(media_list[start_index:]):\n",
    "    if len(m['media_id'])==0:\n",
    "        params = m.copy()\n",
    "        valid_params = ['url', 'name', 'foreign_rss_links', 'content_delay', 'feeds', 'tags_ids', 'editor_notes',\n",
    "                        'public_notes', 'is_monitored', 'foreign_rss_links', 'is_monitored']\n",
    "        invalid_params = [k for k in params if k not in valid_params]\n",
    "        for p in invalid_params:\n",
    "            del params[p]\n",
    "        try:\n",
    "            results = mc.mediaCreate([params])[0]\n",
    "            if 'media_id' in results:\n",
    "                if results['status'] == 'existing':\n",
    "                    print(\"  Row {}: {} - found existing source media_id {}\".format(idx+start_index, m['url'], results['media_id']))\n",
    "                else:\n",
    "                    print(\"  Row {}: {} - created new source media_id {}\".format(idx+start_index, m['url'], results['media_id']))\n",
    "                media_ids.append(results['media_id'])\n",
    "            else:\n",
    "                print(\"  Row {}: {} -  ⚠️ no media id returned {}\".format(idx, m['url'], json.dumps(results)))\n",
    "        except ConnectionError:\n",
    "            print(\"  Row {}: {} - timeout ⚠️ won't get added\".format(idx, m['url'], m['media_id']))\n",
    "    else:\n",
    "        print(\"  Row {}: {} - using media_id {}\".format(idx, m['url'], m['media_id']))\n",
    "        media_ids.append(m['media_id'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ed8508a2-eb1c-43da-a25c-f5026273dbc6",
   "metadata": {},
   "outputs": [],
   "source": [
    "# now make the new collection, if needed\n",
    "collection_id = None\n",
    "if existing_collection_id is None:\n",
    "    new_collection = mc.createTag(COLLECTION_TAG_SET, collection_computer_name, collection_name, collection_description,\n",
    "                                  is_static=is_it_static, show_on_stories=show_on_stories, show_on_media=show_on_media)\n",
    "    collection_id = new_collection['tag']['tags_id']\n",
    "else:\n",
    "    collection_id = existing_collection_id\n",
    "print(\"We'll have a collection id - {}\".format(collection_id))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "73b58540-ae99-44e2-8e91-86d7ae1479a1",
   "metadata": {},
   "outputs": [],
   "source": [
    "import mediacloud.tags\n",
    "# Now we tag all the media so they show up as part of the new collection\n",
    "tags_to_create = [mediacloud.tags.MediaTag(mid, tags_id=collection_id, action=mediacloud.tags.TAG_ACTION_ADD) for mid in set(media_ids)]\n",
    "if len(tags_to_create) > 0:\n",
    "    mc.tagMedia(tags_to_create)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "298412d4-17d7-4c2e-b22a-2681abbeead5",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Checkout the collection now, at https://sources.mediacloud.org/#collections/{}\".format(collection_id))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b24535f0-7c6b-45d3-b6c7-ac34ae9105df",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}