From 5c1f5861b64adc8ae3a077de7ce5b056d3157cfa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mike=20F=C3=A4hrmann?= <mike_faehrmann@web.de>
Date: Mon, 18 Mar 2024 00:01:27 +0100
Subject: [PATCH] [flickr] add 'contexts' option (#5324)

---
 docs/configuration.rst         | 20 ++++++++++++++++++--
 gallery_dl/extractor/flickr.py | 13 +++++++++++++
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/docs/configuration.rst b/docs/configuration.rst
index 29578019..7ab9e1c2 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -1872,6 +1872,20 @@ Description
     from `linking your Flickr account to gallery-dl <OAuth_>`__.
 
 
+extractor.flickr.contexts
+-------------------------
+Type
+    ``bool``
+Default
+    ``false``
+Description
+    For each photo, return the albums and pools it belongs to
+    as ``set`` and ``pool`` metadata.
+
+    Note: This requires 1 additional API call per photo.
+    See `flickr.photos.getAllContexts <https://www.flickr.com/services/api/flickr.photos.getAllContexts.html>`__ for details.
+
+
 extractor.flickr.exif
 ---------------------
 Type
@@ -1879,9 +1893,11 @@ Type
 Default
     ``false``
 Description
-    Fetch `exif` and `camera` metadata for each photo.
+    For each photo, return its EXIF/TIFF/GPS tags
+    as ``exif`` and ``camera`` metadata.
 
     Note: This requires 1 additional API call per photo.
+    See `flickr.photos.getExif <https://www.flickr.com/services/api/flickr.photos.getExif.html>`__ for details.
 
 
 extractor.flickr.metadata
@@ -1901,7 +1917,7 @@ Description
 
     It is possible to specify a custom list of metadata includes.
     See `the extras parameter <https://www.flickr.com/services/api/flickr.people.getPhotos.html>`__
-    in `Flickr API docs <https://www.flickr.com/services/api/>`__
+    in `Flickr's API docs <https://www.flickr.com/services/api/>`__
     for possible field names.
 
 
diff --git a/gallery_dl/extractor/flickr.py b/gallery_dl/extractor/flickr.py
index f7dc3cc2..c94a110a 100644
--- a/gallery_dl/extractor/flickr.py
+++ b/gallery_dl/extractor/flickr.py
@@ -77,6 +77,8 @@ class FlickrImageExtractor(FlickrExtractor):
         photo = self.api.photos_getInfo(self.item_id)
         if self.api.exif:
             photo.update(self.api.photos_getExif(self.item_id))
+        if self.api.contexts:
+            photo.update(self.api.photos_getAllContexts(self.item_id))
 
         if photo["media"] == "video" and self.api.videos:
             self.api._extract_video(photo)
@@ -268,6 +270,8 @@ class FlickrAPI(oauth.OAuth1API):
 
         self.exif = extractor.config("exif", False)
         self.videos = extractor.config("videos", True)
+        self.contexts = extractor.config("contexts", False)
+
         self.maxsize = extractor.config("size-max")
         if isinstance(self.maxsize, str):
             for fmt, fmtname, fmtwidth in self.FORMATS:
@@ -311,6 +315,13 @@ class FlickrAPI(oauth.OAuth1API):
         params = {"user_id": user_id}
         return self._pagination("people.getPhotos", params)
 
+    def photos_getAllContexts(self, photo_id):
+        """Returns all visible sets and pools the photo belongs to."""
+        params = {"photo_id": photo_id}
+        data = self._call("photos.getAllContexts", params)
+        del data["stat"]
+        return data
+
     def photos_getExif(self, photo_id):
         """Retrieves a list of EXIF/TIFF/GPS tags for a given photo."""
         params = {"photo_id": photo_id}
@@ -444,6 +455,8 @@ class FlickrAPI(oauth.OAuth1API):
 
         if self.exif:
             photo.update(self.photos_getExif(photo["id"]))
+        if self.contexts:
+            photo.update(self.photos_getAllContexts(photo["id"]))
         photo["id"] = text.parse_int(photo["id"])
 
         if "owner" in photo: