Enhanced examples

.github/workflows/python.yml

@@ -67,6 +67,7 @@ jobs:
 
   verify-nbstripout:
     runs-on: [self-hosted, linux]
+    needs: changed-files
     if: needs.changed-files.outputs.any_python_changed == 'true'
     steps:
       - name: Checkout code

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Traktor config option `backup_before_write`, (true by default, creates a backup of the nml file before each write).
 - `pyproject.toml` information updated (readme, license, authors, urls, classifiers).
 - Added support for batched remote operations, should allow to minify expensive network request.
+- Improved examples. They now live in the docs under `docs/examples` (full-fledged notebooks by us) and `docs/examples/community` (less restrictive, also simple python scripts by the community)
 
 ### Changed
 

docs/contribution.md

@@ -45,6 +45,9 @@ mypy .
 
 # Strip output from notebooks (if modified)
 find . -name '*.ipynb' -exec nbstripout --keep-output {} +
+
+# Run mypy on notebooks
+./.github/workflows/mypy_notebooks.sh
 ```
 
 If this looks tedious you may alternatively install the

docs/examples

@@ -0,0 +1 @@
+../examples/

docs/getting-started.md

@@ -54,6 +54,8 @@ Understand the key abstractions and notation of `plistsync`. Learn about `Tracks
 ::::
 
 ::::{grid-item-card} Examples
+:link: examples/readme
+:link-type: doc
 
 Follow step-by-step guides to see `plistsync` in action. Great for hands-on learning and testing common workflows. TODO
 ::::

docs/index.md

@@ -37,6 +37,7 @@ getting-started.md
 details/core-concepts.md
 details/configuration.md
 details/advanced/index.md
+examples/readme.md
 ```
 
 ```{toctree}

docs/services/plex/collections.ipynb

@@ -1,25 +1,8 @@
 {
  "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "0",
-   "metadata": {
-    "tags": [
-     "hide-cell"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "import os\n",
-    "\n",
-    "# Uremote_edite you config directory as needed\n",
-    "os.environ[\"PSYNC_CONFIG_DIR\"] = \"../../../config\""
-   ]
-  },
   {
    "cell_type": "markdown",
-   "id": "1",
+   "id": "0",
    "metadata": {},
    "source": [
     "# Collections\n",
@@ -34,7 +17,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "2",
+   "id": "1",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -45,7 +28,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "3",
+   "id": "2",
    "metadata": {},
    "source": [
     "### Iterating Tracks\n",
@@ -56,7 +39,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "4",
+   "id": "3",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -69,7 +52,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "5",
+   "id": "4",
    "metadata": {},
    "source": [
     "This can be a bit slow depending on the number of tracks you want to iterate. To speed things up you can consider preloading all tracks."
@@ -78,7 +61,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "6",
+   "id": "5",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -88,7 +71,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "7",
+   "id": "6",
    "metadata": {},
    "source": [
     "### Track Lookup\n",
@@ -103,7 +86,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "8",
+   "id": "7",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -114,7 +97,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "9",
+   "id": "8",
    "metadata": {},
    "source": [
     "Looking up tracks by `isrc` is currently a bit more involved.\n",
@@ -127,7 +110,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "10",
+   "id": "9",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -145,7 +128,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "11",
+   "id": "10",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -159,7 +142,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "12",
+   "id": "11",
    "metadata": {},
    "source": [
     ":::{note}\n",
@@ -172,7 +155,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "13",
+   "id": "12",
    "metadata": {},
    "source": [
     "## Playlist Collection\n",
@@ -187,7 +170,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "14",
+   "id": "13",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -199,43 +182,42 @@
   },
   {
    "cell_type": "markdown",
-   "id": "15",
+   "id": "14",
    "metadata": {},
    "source": [
-    "If you just want a specific playlist, you can use the library's {py:meth}`PlexLibraryCollection.get_playlist <plistsync.services.plex.PlexLibraryCollection.get_playlist>` method to retrieve a playlist."
+    "If you just want a specific playlist, you can use the library's {py:meth}`PlexLibraryCollection.get_playlist <plistsync.services.plex.PlexLibraryCollection.get_playlist>` or {py:meth}`PlexLibraryCollection.get_playlist_or_raise <plistsync.services.plex.PlexLibraryCollection.get_playlist_or_raise>` method to retrieve a playlist."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "16",
+   "id": "15",
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Can get via namer or id\n",
-    "if pl := library.get_playlist(\n",
+    "# Returns `PlexPlaylistCollection | None`\n",
+    "maybe_pl = library.get_playlist(\n",
     "    name=\"DnB Classics\"\n",
     "    # id = 108530\n",
-    "):\n",
-    "    print(f\"Found playlist: {pl.id} {pl.name} ({len(pl.tracks)} tracks)\")\n",
-    "else:\n",
-    "    print(\"Playlist not found.\")"
+    ")\n",
+    "\n",
+    "# Raises if not found\n",
+    "pl = library.get_playlist_or_raise(id=108530)"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "17",
+   "id": "16",
    "metadata": {},
    "source": [
     ":::{note}\n",
     "This method supports lookup by various identifiers, currently ``name=`` and ``id=``.\n",
-    "Lookup by name will return ``None`` if no matching playlist is found, while lookups by other identifiers will raise a ``ValueError`` if the playlist cannot be resolved.\n",
     ":::"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "18",
+   "id": "17",
    "metadata": {},
    "source": [
     "### Creating playlists\n",
@@ -246,14 +228,14 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "19",
+   "id": "18",
    "metadata": {},
    "outputs": [],
    "source": [
     "from plistsync.services.plex import PlexPlaylistCollection\n",
     "\n",
     "try:\n",
-    "    library.get_playlist(name=\"My New Playlist\").remote_delete()\n",
+    "    library.get_playlist_or_raise(name=\"My New Playlist\").remote_delete()\n",
     "except:\n",
     "    print(\"Playlist did not exist, no need to delete\")\n",
     "\n",
@@ -269,7 +251,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "20",
+   "id": "19",
    "metadata": {},
    "source": [
     "To remotly create the same playlist use the {py:meth}`PlexPlaylistCollection.remote_create <plistsync.services.plex.PlexPlaylistCollection.remote_create>` method."
@@ -278,7 +260,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "21",
+   "id": "20",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -288,7 +270,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "22",
+   "id": "21",
    "metadata": {},
    "source": [
     "### Updating a playlist\n",
@@ -299,7 +281,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "23",
+   "id": "22",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -313,31 +295,33 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "24",
+   "id": "23",
    "metadata": {},
    "outputs": [],
    "source": [
     "from plistsync.services.plex import PlexTrack\n",
     "\n",
     "# find some tracks to play around with\n",
     "new_tracks: list[PlexTrack] = list(\n",
-    "    library.find_many_by_local_ids(\n",
-    "        [\n",
-    "            {\"plex_id\": \"111017\"},\n",
-    "            {\"plex_id\": \"111018\"},\n",
-    "            {\"plex_id\": \"111023\"},\n",
-    "            {\"plex_id\": \"111024\"},\n",
-    "        ]\n",
+    "    filter(\n",
+    "        None,\n",
+    "        library.find_many_by_local_ids(\n",
+    "            [\n",
+    "                {\"plex_id\": \"111017\"},\n",
+    "                {\"plex_id\": \"111018\"},\n",
+    "                {\"plex_id\": \"111023\"},\n",
+    "                {\"plex_id\": \"111024\"},\n",
+    "            ]\n",
+    "        ),\n",
     "    )\n",
-    ")  # type: ignore # TODO: use generic type in ABC\n",
-    "new_tracks = list(filter(None, new_tracks))\n",
+    ")\n",
     "new_tracks"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "25",
+   "id": "24",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -351,7 +335,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "26",
+   "id": "25",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -365,7 +349,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "27",
+   "id": "26",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -393,7 +377,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.3"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,