Merge fe96b7b into faaeb8e

README.md

@@ -8,7 +8,9 @@
 [![PyPI](https://img.shields.io/pypi/v/pyinaturalist?color=blue)](https://pypi.org/project/pyinaturalist)
 [![PyPI - Python Versions](https://img.shields.io/pypi/pyversions/pyinaturalist)](https://pypi.org/project/pyinaturalist)
 [![PyPI - Format](https://img.shields.io/pypi/format/pyinaturalist?color=blue)](https://pypi.org/project/pyinaturalist)
+
 [![Run with Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/niconoe/pyinaturalist/main?filepath=examples)
+[![Open in VSCode](https://open.vscode.dev/badges/open-in-vscode.svg)](https://open.vscode.dev/niconoe/pyinaturalist)
 
 <br/>
 

docker-compose.yml

@@ -0,0 +1,14 @@
+version: '3.7'
+
+services:
+  jupyter:
+    container_name: jupyter
+    image: jxcook/pyinaturalist-notebook
+    ports:
+      - 8888:8888
+    volumes:
+      - .:/home/jovyan/work
+    restart: unless-stopped
+    # environment:
+      # Set any value here to use as a token instead of generating one
+      # JUPYTER_TOKEN: 'token goes here'

docs/examples.rst

@@ -18,22 +18,19 @@ Docker image, which you can also use to run these examples on a local Jupyter se
 .. toctree::
     :maxdepth: 2
 
+    examples/Tutorial.ipynb
     examples/Data Visualizations - Regional Activity Report.ipynb
     examples/Data Visualizations - Regional Observation Stats.ipynb
     examples/Data Visualizations - Seaborn.ipynb
     examples/Data Visualizations - Matplotlib.ipynb
 
-.. examples/observations_to_gpx.py
-
-
 .. TODO: Can't generate thumbnails for Altair visualizations
 .. .. nbgallery::
 ..     :caption: This is a thumbnail gallery
 ..     :name: nb-gallery
 ..
 ..     ../examples/Data Visualizations - Regional Observation Stats.ipynb
 
-
 Scripts
 -------
 

docs/user_guide.md

@@ -87,8 +87,9 @@ See the {ref}`reference-docs` section for a complete list of functions available
 ## Responses
 API responses are returned as JSON, with some python type conversions applied (similar to the
 request type conversions mentioned above). Example response data is shown in the documentation for
-each request function, for example {py:func}`~pyinaturalist.v1.observations.get_observations`
+each request function, for example {py:func}`~pyinaturalist.v1.observations.get_observations`.
 
+### API Data vs Web UI
 Here is how some of those response fields correspond to observation details shown on
 iNaturalist.org:
 ```{figure} images/inat-observation-page-annotated.png

examples/Data Visualizations - Seaborn.ipynb

@@ -137,11 +137,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Reload from previously loaded results, if available\n",
+    "# TODO: This should be done with the /observations/histogram endpoint instead\n",
+    "\n",
+    "# Optional: reload from previously loaded results, if available\n",
     "#if exists(DATASET_FILENAME):\n",
     "#    with open(DATASET_FILENAME) as f:\n",
     "#        observations = json.load(f)\n",
     "#else:\n",
+    "\n",
     "observations = get_observations(\n",
     "    taxon_name='Danaus plexippus',\n",
     "    photos=True,\n",

pyinaturalist/models/photo.py

@@ -1,4 +1,7 @@
-from typing import Optional, Tuple
+from io import BytesIO
+from typing import BinaryIO, Optional, Tuple
+
+import requests
 
 from pyinaturalist.constants import ALL_LICENSES, CC_LICENSES, PHOTO_INFO_BASE_URL, PHOTO_SIZES, TableRow
 from pyinaturalist.converters import format_dimensions, format_license
@@ -86,17 +89,19 @@ def url_size(self, size: str) -> Optional[str]:
             return None
         return self._url_format.format(size=size)
 
-    def open(self, size: str = 'large'):
+    def open(self, size: str = 'large') -> BinaryIO:
+        """Download the image and return as a file-like object"""
+        url = self.url_size(size)
+        return requests.get(url, stream=True).raw if url else BytesIO()
+
+    def show(self, size: str = 'large'):
         """Download and display the image with the system's default image viewer.
-        Experimental / requires ``pillow``
+        Requires ``pillow``.
         """
-        import requests
         from PIL import Image
 
-        url = self.url_size(size)
-        if url:
-            img = Image.open(requests.get(url, stream=True).raw)
-            img.show()
+        img = Image.open(self.open(size=size))
+        img.show()
 
     @property
     def row(self) -> TableRow: