piffle 0.5.1__py3-none-any.whl

piffle/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.5.1"

piffle/image.py

@@ -0,0 +1,746 @@
+# iiifclient
+# -*- coding: utf-8 -*-
+
+from collections import OrderedDict
+from urllib.parse import urlparse
+
+from cached_property import cached_property
+import requests
+
+
+class IIIFImageClientException(Exception):
+    """IIIFImageClient custom exception class"""
+
+
+class ParseError(IIIFImageClientException):
+    """Exception raised when an IIIF image could not be parsed"""
+
+
+# NOTE: possible image component base class?
+# commonalities so far: setting defaults on init / parse
+# handling exact matches like full/square? (but maybe only region/size),
+# validating options (and could add option type checking)
+
+
+class ImageRegion(object):
+    """IIIF Image region. Intended to be used with :class:`IIIFImageClient`.
+    Can be initialized with related image object and region options.
+
+    When associated with an image, region is callable and will return
+    an updated image object with the modified region options.
+
+    :param img: :class:`IIFImageClient`
+    :param full: full region, defaults to true
+    :param square: square region, defaults to false
+    :param x: x coordinate
+    :param y: y coordinate
+    :param width: region width
+    :param height: region height
+    :param percent: region is a percentage
+    """
+
+    # region options
+    options = OrderedDict(
+        [
+            ("full", False),
+            ("square", False),
+            ("x", None),
+            ("y", None),
+            ("width", None),
+            ("height", None),
+            ("percent", False),
+        ]
+    )
+
+    region_defaults = {
+        "full": True,
+        "square": False,
+        "x": None,
+        "y": None,
+        "width": None,
+        "height": None,
+        "percent": False,
+    }
+
+    coords = ["x", "y", "width", "height"]
+
+    def __init__(self, img=None, **options):
+        self.img = img
+        self.options = self.region_defaults.copy()
+        if options:
+            self.set_options(**options)
+
+    def __call__(self, **options):
+        if self.img is not None:
+            img = self.img.get_copy()
+            img.region.set_options(**options)
+            return img
+
+    def set_options(self, **options):
+        """Update region options.  Same parameters as initialiation."""
+        allowed_options = list(self.options.keys())
+        # error if an unrecoganized option is specified
+        for key in options:
+            if key not in allowed_options:
+                raise IIIFImageClientException("Unknown option: %s" % key)
+
+        # error if some but not all coordinates are specified
+        # or if percentage is specified but not all coordinates are present
+        if (
+            any([coord in options for coord in self.coords]) or "percent" in options
+        ) and not all([coord in options for coord in self.coords]):
+            # partial region specified
+            raise IIIFImageClientException("Incomplete region specified")
+
+        # TODO: do we need to type checking? bool/int/float?
+
+        self.options.update(**options)
+        # if any non-full value is specified, set full to false
+        # NOTE: if e.g. square is specified but false, this is wrong
+        allowed_options.remove("full")
+        if any([(key in allowed_options and options[key]) for key in options.keys()]):
+            self.options["full"] = False
+
+    def as_dict(self):
+        """Return region options as a dictionary"""
+        return self.options
+
+    def __str__(self):
+        """Render region information in IIIF region format"""
+        if self.options["full"]:
+            return "full"
+        if self.options["square"]:
+            return "square"
+
+        coords = "%(x)g,%(y)g,%(width)g,%(height)g" % self.options
+        if self.options["percent"]:
+            return "pct:%s" % coords
+
+        return coords
+
+    def parse(self, region):
+        """Parse an IIIF Image region string and update the current region"""
+
+        # reset to defaults before parsing
+        self.options = self.region_defaults.copy()
+
+        # full?
+        if region == "full":
+            self.options["full"] = True
+            # return immediately
+            return
+
+        self.options["full"] = False
+
+        if region == "square":
+            self.options["square"] = True
+            # return immediately
+            return self
+
+        # percent?
+        if "pct" in region:
+            self.options["percent"] = True
+            region = region.split("pct:")[1]
+
+        # split to dictionary
+        # if percentage type, cast to float
+        try:
+            if self.options["percent"]:
+                coords = [float(region_c) for region_c in region.split(",")]
+            # else, force int
+            else:
+                coords = [int(region_c) for region_c in region.split(",")]
+        except ValueError:
+            # failure converting to integer or float
+            raise ParseError("Invalid region coordinates: %s" % region)
+
+        if len(coords) != 4:
+            raise ParseError("Invalid region coordinates: %s" % region)
+
+        x, y, width, height = coords
+        self.options.update({"x": x, "y": y, "width": width, "height": height})
+
+    def canonicalize(self):
+        """Canonicalize the current region options so that
+        serialization results in canonical format."""
+        # From the spec:
+        #   “full” if the whole image is requested, (including a “square”
+        #    region of a square image), otherwise the x,y,w,h syntax.
+
+        if self.options["full"]:
+            # nothing to do
+            return
+
+        # if already in x,y,w,h format - nothing to do
+        if not any(
+            [self.options["full"], self.options["square"], self.options["percent"]]
+        ):
+            return
+
+        # possbly an error here for every other case if self.img is not set,
+        # since it's probably not possible to canonicalize without knowing
+        # image size  (any exceptions?)
+        if self.img is None:
+            raise IIIFImageClientException("Cannot canonicalize without image")
+
+        if self.options["square"]:
+            # if image is square, then return full
+            if self.img is not None and self.img.image_width == self.img.image_height:
+                self.options["full"] = True
+                self.options["square"] = False
+                return
+
+            # otherwise convert to x,y,w,h
+            # from the spec:
+            #  The region is defined as an area where the width and height
+            #  are both equal to the length of the shorter dimension of the
+            #  complete image. The region may be positioned anywhere in the
+            #  longer dimension of the image content at the server’s
+            #  discretion, and centered is often a reasonable default.
+
+            # determine size of the short edge
+            short_edge = min(self.img.image_width, self.img.image_height)
+            width = height = short_edge
+            # calculate starting long edge point to center the square
+            if self.img.image_height == short_edge:
+                y = 0
+                x = (self.img.image_width - short_edge) / 2
+            else:
+                x = 0
+                y = (self.img.image_height - short_edge) / 2
+
+            self.options.update(
+                {"x": x, "y": y, "width": width, "height": height, "square": False}
+            )
+
+        if self.options["percent"]:
+            # convert percentages to x,y,w,h
+            # From the spec:
+            #  The region to be returned is specified as a sequence of
+            #  percentages of the full image’s dimensions, as reported in
+            #  the image information document. Thus, x represents the number
+            #  of pixels from the 0 position on the horizontal axis, calculated
+            #  as a percentage of the reported width. w represents the width
+            #  of the region, also calculated as a percentage of the reported
+            #  width. The same applies to y and h respectively. These may be
+            #  floating point numbers.
+
+            # convert percentages to dimensions based on image size
+            self.options.update(
+                {
+                    "percent": False,
+                    "x": int((self.options["x"] / 100) * self.img.image_width),
+                    "y": int((self.options["y"] / 100) * self.img.image_height),
+                    "width": int((self.options["width"] / 100) * self.img.image_width),
+                    "height": int(
+                        (self.options["height"] / 100) * self.img.image_height
+                    ),
+                }
+            )
+            return
+
+
+class ImageSize(object):
+    """IIIF Image Size.  Intended to be used with :class:`IIIFImageClient`.
+    Can be initialized with related image object and size options.
+
+    When associated with an image, size is callable and will return
+    an updated image object with the modified size.
+
+    :param img: :class:`IIFImageClient`
+    :param width: optional width
+    :param height: optional height
+    :param percent: optional percent
+    :param exact: size should be exact (boolean, optional)
+    """
+
+    # size options
+    options = OrderedDict(
+        [
+            ("full", False),
+            ("max", False),
+            ("width", None),
+            ("height", None),
+            ("percent", None),
+            ("exact", False),
+        ]
+    )
+
+    # NOTE: full is being deprecated and replaced with max;
+    # full is deprecated in 2.1 and will be removed for 3.0
+    # Eventually piffle will need to address that, maybe with some kind of
+    # support for selecting a particular version of the IIIF image spec.
+    # For now, default size is still full, and max and full are treated as
+    # separate modes.  A parsed url with max will return max, and a parsed
+    # url with full will return full, but that will probably change
+    # once the deprecated full is handled properly.
+
+    size_defaults = {
+        "full": True,
+        "max": False,
+        "width": None,
+        "height": None,
+        "percent": None,
+        "exact": False,
+    }
+
+    def __init__(self, img=None, **options):
+        self.img = img
+        self.options = self.size_defaults.copy()
+        if options:
+            self.set_options(**options)
+
+    def __call__(self, **options):
+        if self.img is not None:
+            img = self.img.get_copy()
+            img.size.set_options(**options)
+            return img
+
+    def set_options(self, **options):
+        """Update size options.  Same parameters as initialiation."""
+        allowed_options = list(self.options.keys())
+        # error if an unrecoganized option is specified
+        for key in options:
+            if key not in allowed_options:
+                raise IIIFImageClientException("Unknown option: %s" % key)
+
+        # TODO: do we need to type checking? bool/int/float?
+
+        self.options.update(**options)
+        # if any non-full value is specified, set full to false
+        # NOTE: if e.g. square is specified but false, this is wrong
+        allowed_options.remove("full")
+        if any([key in allowed_options and options[key] for key in options.keys()]):
+            self.options["full"] = False
+
+    def as_dict(self):
+        """Return size options as a dictionary"""
+        return self.options
+
+    def __str__(self):
+        if self.options["full"]:
+            return "full"
+        if self.options["max"]:
+            return "max"
+        if self.options["percent"]:
+            return "pct:%g" % self.options["percent"]
+
+        size = "%s,%s" % (self.options["width"] or "", self.options["height"] or "")
+        if self.options["exact"]:
+            return "!%s" % size
+        return size
+
+    def parse(self, size):
+        # reset to defaults before parsing
+        self.options = self.size_defaults.copy()
+
+        # full?
+        if size == "full":
+            self.options["full"] = True
+            return
+
+        # for any other case, full should be false
+        self.options["full"] = False
+
+        # max?
+        if size == "max":
+            self.options["max"] = True
+            return
+
+        # percent?
+        if "pct" in size:
+            try:
+                self.options["percent"] = float(size.split(":")[1])
+                return
+            except ValueError:
+                raise ParseError("Error parsing size: %s" % size)
+
+        # exact?
+        if size.startswith("!"):
+            self.options["exact"] = True
+            size = size.lstrip("!")
+
+        # split width and height
+        width, height = size.split(",")
+        try:
+            if width != "":
+                self.options["width"] = int(width)
+            if height != "":
+                self.options["height"] = int(height)
+        except ValueError:
+            raise ParseError("Error parsing size: %s" % size)
+
+    def canonicalize(self):
+        """Canonicalize the current size options so that
+        serialization results in canonical format."""
+        # From the spec:
+        #   “full” if the default size is requested,
+        #   the w, syntax for images that should be scaled maintaining the
+        #   aspect ratio, and the w,h syntax for explicit sizes that change
+        #   the aspect ratio.
+        #   Note: The size keyword “full” will be replaced with “max” in
+        #   version 3.0
+
+        if self.options["full"]:
+            # nothing to do
+            return
+
+        # possbly an error here for every other case if self.img is not set,
+        # since it's probably not possible to canonicalize without knowing
+        # image size  (any exceptions?)
+        if self.img is None:
+            raise IIIFImageClientException("Cannot canonicalize without image")
+
+        if self.options["percent"]:
+            # convert percentage to w,h
+            scale = self.options["percent"] / 100
+            self.options.update(
+                {
+                    "height": int(self.img.image_height * scale),
+                    "width": int(self.img.image_width * scale),
+                    "percent": None,
+                }
+            )
+            return
+
+        if self.options["exact"]:
+            # from the spec:
+            #   The image content is scaled for the best fit such that the
+            #   resulting width and height are less than or equal to the
+            #   requested width and height. The exact scaling may be determined
+            #   by the service provider, based on characteristics including
+            #   image quality and system performance. The dimensions of the
+            #   returned image content are calculated to maintain the aspect
+            #   ratio of the extracted region.
+
+            # determine which edge results in a smaller scale
+            wscale = float(self.options["width"]) / float(self.img.image_width)
+            hscale = float(self.options["height"]) / float(self.img.image_height)
+            scale = min(wscale, hscale)
+            # use that scale on original image size, to preserve
+            # original aspect ratio
+            self.options.update(
+                {
+                    "exact": False,
+                    "height": int(scale * self.img.image_height),
+                    "width": int(scale * self.img.image_width),
+                }
+            )
+            return
+
+        # if height only is specified (,h), convert to width only (w,)
+        if self.options["height"] and self.options["width"] is None:
+            # determine the scale in use, and convert from
+            # height only to width only
+            scale = float(self.options["height"]) / float(self.img.image_height)
+            self.options.update(
+                {"height": None, "width": int(scale * self.img.image_width)}
+            )
+
+
+class ImageRotation(object):
+    """IIIF Image rotation Intended to be used with :class:`IIIFImageClient`.
+    Can be initialized with related image object and rotation options.
+
+    When associated with an image, rotation is callable and will return
+    an updated image object with the modified rotatoin options.
+
+    :param img: :class:`IIFImageClient`
+    :param degrees: degrees rotation, optional
+    :param mirrored: image should be mirrored (boolean, optional, default
+       is False)
+    """
+
+    # rotation options
+    options = OrderedDict(
+        [
+            ("degrees", None),
+            ("mirrored", False),
+        ]
+    )
+
+    rotation_defaults = {"degrees": 0, "mirrored": False}
+
+    def __init__(self, img=None, **options):
+        self.img = img
+        self.options = self.rotation_defaults.copy()
+        if options:
+            self.set_options(**options)
+
+    def __call__(self, **options):
+        if self.img is not None:
+            img = self.img.get_copy()
+            img.rotation.set_options(**options)
+            return img
+
+    def set_options(self, **options):
+        """Update size options.  Same parameters as initialiation."""
+        allowed_options = self.options.keys()
+        # error if an unrecoganized option is specified
+        for key in options:
+            if key not in allowed_options:
+                raise IIIFImageClientException("Unknown option: %s" % key)
+
+        # TODO: do we need to type checking? bool/int/float?
+
+        self.options.update(**options)
+
+    def as_dict(self):
+        """Return rotation options as a dictionary"""
+        return self.options
+
+    def __str__(self):
+        return "%s%g" % (
+            "!" if self.options["mirrored"] else "",
+            self.options["degrees"],
+        )
+
+    def parse(self, rotation):
+        # reset to defaults before parsing
+        self.options = self.rotation_defaults.copy()
+
+        if str(rotation).startswith("!"):
+            self.options["mirrored"] = True
+            rotation = rotation.lstrip("!")
+
+        # rotation allows float
+        self.options["degrees"] = float(rotation)
+
+    def canonicalize(self):
+        """Canonicalize the current region options so that
+        serialization results in canonical format."""
+        # NOTE: explicitly including a canonicalize as a method to make it
+        # clear that this field supports canonicalization, but no work
+        # is needed since the existing render does the right things:
+        # - trim any trailing zeros in a decimal value
+        # - leading zero if less than 1
+        # - ! if mirrored, followed by integer if possible
+        return
+
+
+class IIIFImageClient(object):
+    """Simple IIIF Image API client for generating IIIF image urls
+     in an object-oriented, pythonic fashion.  Can be extended,
+     when custom logic is needed to set the image id.  Provides
+     a fluid interface, so that IIIF methods can be chained, e.g.::
+
+         iiif_img.size(width=300).rotation(90).format('png')
+
+    Note that this returns a new image instance with the specified
+    options, and the original image will remain unchanged.
+
+     .. Note::
+
+         Method to set quality not yet available.
+    """
+
+    api_endpoint = None
+    image_id = None
+    default_format = "jpg"
+
+    # iiif defaults for each sections
+    image_defaults = {
+        "quality": "default",  # color, gray, bitonal, default
+        "fmt": default_format,
+    }
+    allowed_formats = ["jpg", "tif", "png", "gif", "jp2", "pdf", "webp"]
+
+    def __init__(
+        self,
+        api_endpoint=None,
+        image_id=None,
+        region=None,
+        size=None,
+        rotation=None,
+        quality=None,
+        fmt=None,
+    ):
+        self.image_options = self.image_defaults.copy()
+        # NOTE: using underscore to differenteate objects from methods
+        # but it could be reasonable to make objects public
+        self.region = ImageRegion(self)
+        self.size = ImageSize(self)
+        self.rotation = ImageRotation(self)
+
+        if api_endpoint is not None:
+            # remove any trailing slash to avoid duplicate slashes
+            self.api_endpoint = api_endpoint.rstrip("/")
+
+        # FIXME: image_id is not required on init to allow subclassing
+        # and customizing via get_image_id, but should probably cause
+        # an error if you attempt to serialize the url and it is not set
+        # (same for a few other options, probably, too...)
+        if image_id is not None:
+            self.image_id = image_id
+
+        # for now, if region option is specified parse as string
+        if region is not None:
+            self.region.parse(region)
+        if size is not None:
+            self.size.parse(size)
+        if rotation is not None:
+            self.rotation.parse(rotation)
+
+        if quality is not None:
+            self.image_options["quality"] = quality
+        if fmt is not None:
+            self.image_options["fmt"] = fmt
+
+    def get_image_id(self):
+        "Image id to be used in contructing urls"
+        return self.image_id
+
+    def __str__(self):
+        info = self.image_options.copy()
+        info.update(
+            {
+                "endpoint": self.api_endpoint,
+                "id": self.get_image_id(),
+                "region": str(self.region),
+                "size": str(self.size),
+                "rot": str(self.rotation),
+            }
+        )
+        return (
+            "%(endpoint)s/%(id)s/%(region)s/%(size)s/%(rot)s/%(quality)s.%(fmt)s" % info
+        )
+
+    def __repr__(self):
+        return "<IIIFImageClient %s>" % self.get_image_id()
+        # include non-defaults?
+
+    def info(self):
+        "JSON info url"
+        return "%(endpoint)s/%(id)s/info.json" % {
+            "endpoint": self.api_endpoint,
+            "id": self.get_image_id(),
+        }
+
+    @cached_property
+    def image_info(self):
+        "Retrieve image information provided as JSON at info url"
+        resp = requests.get(self.info())
+        if resp.status_code == requests.codes.ok:
+            return resp.json()
+
+        resp.raise_for_status()
+
+    @property
+    def image_width(self):
+        "Image width as reported in :attr:`image_info`"
+        return self.image_info["width"]
+
+    @property
+    def image_height(self):
+        "Image height as reported in :attr:`image_info`"
+        return self.image_info["height"]
+
+    def get_copy(self):
+        "Get a clone of the current settings for modification."
+        clone = self.__class__(self.api_endpoint, self.image_id, **self.image_options)
+        # copy region, size, and rotation - no longer included in
+        # image_options dict
+        clone.region.set_options(**self.region.as_dict())
+        clone.size.set_options(**self.size.as_dict())
+        clone.rotation.set_options(**self.rotation.as_dict())
+        return clone
+
+    # method to set quality not yet implemented
+
+    def format(self, image_format):
+        "Set output image format"
+        if image_format not in self.allowed_formats:
+            raise IIIFImageClientException("Image format %s unknown" % image_format)
+        img = self.get_copy()
+        img.image_options["fmt"] = image_format
+        return img
+
+    def canonicalize(self):
+        """Canonicalize the URI"""
+        img = self.get_copy()
+        img.region.canonicalize()
+        img.size.canonicalize()
+        img.rotation.canonicalize()
+        return img
+
+    @classmethod
+    def init_from_url(cls, url):
+        """Init ImageClient using Image API parameters from URI.  Detect
+        image vs. info request. Can count reliably from the end of the URI
+        backwards, but cannot assume how many slashes make up the api_endpoint.
+        Returns new instance of IIIFImageClient.
+        Per http://iiif.io/api/image/2.0/#image-request-uri-syntax, using
+        slashes to parse URI"""
+
+        # first parse as a url
+        parsed_url = urlparse(url)
+        # then split the path on slashes
+        # and remove any empty strings
+        path_components = [path for path in parsed_url.path.split("/") if path]
+        if not path_components:
+            raise ParseError("Invalid IIIF image url: %s" % url)
+        # pop off last portion of the url to determine if this is an info url
+        path_basename = path_components.pop()
+        opts = {}
+
+        # info request
+        if path_basename == "info.json":
+            # NOTE: this is unlikely to happen; more likely, if information is
+            # missing, we will misinterpret the api endpoint or the image id
+            if len(path_components) < 1:
+                raise ParseError("Invalid IIIF image information url: %s" % url)
+            image_id = path_components.pop()
+
+        # image request
+        else:
+            # check for enough IIIF parameters
+            if len(path_components) < 4:
+                raise ParseError("Invalid IIIF image request: %s" % url)
+
+            # pop off url portions as they are used so we can easily
+            # make use of leftover path to reconstruct the api endpoint
+            quality, fmt = path_basename.split(".")
+            rotation = path_components.pop()
+            size = path_components.pop()
+            region = path_components.pop()
+            image_id = path_components.pop()
+            opts.update(
+                {
+                    "region": region,
+                    "size": size,
+                    "rotation": rotation,
+                    "quality": quality,
+                    "fmt": fmt,
+                }
+            )
+
+        # construct the api endpoint url from the parsed url and whatever
+        # portions of the url path are leftover
+        # remove empty strings from the remaining path components
+        path_components = [p for p in path_components if p]
+        api_endpoint = "%s://%s/%s" % (
+            parsed_url.scheme,
+            parsed_url.netloc,
+            "/".join(path_components) if path_components else "",
+        )
+
+        # init and return instance
+        return cls(api_endpoint=api_endpoint, image_id=image_id, **opts)
+
+    def as_dict(self):
+        """
+        Dictionary of with all image request options.
+        request parameters. Returns a dictionary with all image request
+        parameters parsed to their most granular level. Can be helpful
+        for acting logically on particular request parameters like height,
+        width, mirroring, etc.
+        """
+        return OrderedDict(
+            [
+                ("region", self.region.as_dict()),
+                ("size", self.size.as_dict()),
+                ("rotation", self.rotation.as_dict()),
+                ("quality", self.image_options["quality"]),
+                ("format", self.image_options["fmt"]),
+            ]
+        )

piffle/presentation.py

@@ -0,0 +1,138 @@
+import json
+import os.path
+import urllib
+
+import addict
+
+import requests
+
+
+class IIIFException(Exception):
+    """Custom exception for IIIF errors"""
+
+
+def get_iiif_url(url):
+    """Wrapper around :meth:`requests.get` to support conditionally
+    adding an auth tokens or other parameters."""
+    request_options = {}
+    # TODO: need some way of configuring hooks for e.g. setting auth tokens
+    return requests.get(url, **request_options)
+
+
+class IIIFPresentation(addict.Dict):
+    """:class:`addict.Dict` subclass for read access to IIIF Presentation
+    content"""
+
+    # TODO: document sample use, e.g. @ fields
+
+    at_fields = ["type", "id", "context"]
+
+    @classmethod
+    def from_file(cls, path):
+        """Initialize :class:`IIIFPresentation` from a file."""
+        with open(path) as manifest:
+            data = json.loads(manifest.read())
+        return cls(data)
+
+    @classmethod
+    def from_url(cls, uri):
+        """Iniitialize :class:`IIIFPresentation` from a URL.
+
+        :raises: :class:`IIIFException` if URL is not retrieved successfully,
+            if the response is not JSON content, or if the JSON cannot be parsed.
+        """
+        response = get_iiif_url(uri)
+        if response.status_code == requests.codes.ok:
+            try:
+                return cls(response.json())
+            except json.decoder.JSONDecodeError as err:
+                # if json fails, two possibilities:
+                # - we didn't actually get json (e.g. redirect for auth)
+                if "application/json" not in response.headers["content-type"]:
+                    raise IIIFException("No JSON found at %s" % uri)
+                # - there is something wrong with the json
+                raise IIIFException("Error parsing JSON for %s: %s" % (uri, err))
+
+        raise IIIFException(
+            "Error retrieving manifest at %s: %s %s"
+            % (uri, response.status_code, response.reason)
+        )
+
+    @classmethod
+    def is_url(cls, url):
+        """Utility method to check if a path is a url or file"""
+        return urllib.parse.urlparse(url).scheme != ""
+
+    @classmethod
+    def from_file_or_url(cls, path):
+        """Iniitialize :class:`IIIFPresentation` from a file or a url."""
+        if os.path.isfile(path):
+            return cls.from_file(path)
+        elif cls.is_url(path):
+            return cls.from_url(path)
+        else:
+            raise IIIFException("File not found: %s" % path)
+
+    @classmethod
+    def short_id(cls, uri):
+        """Generate a short id from full manifest/canvas uri identifiers
+        for use in local urls.  Logic is based on the recommended
+        url pattern from the IIIF Presentation 2.0 specification."""
+
+        # shortening should work reliably for uris that follow
+        # recommended url patterns from the spec
+        # http://iiif.io/api/presentation/2.0/#a-summary-of-recommended-uri-patterns
+        #   manifest:  {scheme}://{host}/{prefix}/{identifier}/manifest
+        #   canvas: {scheme}://{host}/{prefix}/{identifier}/canvas/{name}
+
+        # remove trailing /manifest at the end of the url, if present
+        if uri.endswith("/manifest"):
+            uri = uri[: -len("/manifest")]
+        # split on slashes and return the last portion
+        return uri.split("/")[-1]
+
+    def __missing__(self, key):
+        raise KeyError(self._key(key))
+
+    def _key(self, key):
+        # convert key to @key if in the list of fields that requires it
+        if key in self.at_fields:
+            key = "@%s" % key
+        return key
+
+    def __getattr__(self, key):
+        try:
+            # addict getattr just calls getitem
+            return super().__getattr__(self._key(key))
+        except KeyError:
+            # python hasattr checks for attribute error
+            # translate key error to attribute error,
+            # since in an attr dict it's kind of both
+            raise AttributeError
+
+    def __getitem__(self, key):
+        """
+        Access a value associated with a key.
+        """
+        val = super().__getitem__(self._key(key))
+        return val
+
+    def __setitem__(self, key, value):
+        """
+        Add a key-value pair to the instance.
+        """
+        return super().__setitem__(self._key(key), value)
+
+    def __delitem__(self, key):
+        """
+        Delete a key-value pair
+        """
+        super().__delitem__(self._key(key))
+
+    @property
+    def first_label(self):
+        # label can be a string or list of strings
+        if isinstance(self.label, str):
+            return self.label
+        else:
+            return self.label[0]

piffle-0.5.1.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.3
+Name: piffle
+Version: 0.5.1
+Summary: Python library for working with IIIF Image and Presentation APIs
+Project-URL: Homepage, https://github.com/princeton-cdh/piffle
+Project-URL: Repository, https://github.com/princeton-cdh/piffle
+Project-URL: Changelog, https://github.com/Princeton-CDH/piffle/blob/main/README.md
+Author-email: The Center for Digital Humanities at Princeton <cdhdevteam@princeton.edu>
+License: Apache License, Version 2.0
+License-File: LICENSE
+Keywords: iiif
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: addict
+Requires-Dist: cached-property
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=3.6; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest>=3.6; extra == 'test'
+Description-Content-Type: text/markdown
+
+# piffle
+
+Python library for generating and parsing [IIIF Image API](http://iiif.io/api/image/2.1/) URLs in an
+object-oriented, pythonic fashion.
+
+[![unit tests](https://github.com/Princeton-CDH/piffle/actions/workflows/unit_tests.yml/badge.svg)](https://github.com/Princeton-CDH/piffle/actions/workflows/unit_tests.yml)
+[![codecov](https://codecov.io/gh/Princeton-CDH/piffle/branch/main/graph/badge.svg)](https://codecov.io/gh/Princeton-CDH/piffle)
+[![Maintainability](https://api.codeclimate.com/v1/badges/d37850d90592f9d628df/maintainability)](https://codeclimate.com/github/Princeton-CDH/piffle/maintainability)
+
+
+Piffle is tested on Python 3.8—3.12.
+
+Piffle was originally developed by Rebecca Sutton Koeser at Emory University as a part of [Readux](https://github.com/ecds/readux) and forked as a separate project under [emory-lits-labs](https://github.com/emory-lits-labs/). It was later transferred to Rebecca Sutton Koeser at the Center for Digital Humanities at Princeton.
+
+## Installation and example use:
+
+`pip install piffle`
+
+Example use for generating an IIIF image url:
+
+```
+>>> from piffle.image import IIIFImageClient
+>>> myimg = IIIFImageClient('http://image.server/path/', 'myimgid')
+>>> print myimg
+http://image.server/path/myimgid/full/full/0/default.jpg
+>>> print myimg.info()
+http://image.server/path/myimgid/info.json"
+>>> print myimg.size(width=120).format('png')
+http://image.server/path/myimgid/full/120,/0/default.png
+```
+
+Example use for parsing an IIIF image url:
+
+```
+>>> from piffle.image import IIIFImageClient
+>>> myimg = IIIFImageClient.init_from_url('http://www.example.org/image-service/abcd1234/full/full/0/default.jpg')
+>>> print myimg
+http://www.example.org/image-service/abcd1234/full/full/0/default.jpg
+>>> print myimg.info()
+http://www.example.org/image-service/abcd1234/info.json
+>>> myimg.as_dict()['size']['full']
+True
+>>> myimg.as_dict()['size']['exact']
+False
+>>> myimg.as_dict()['rotation']['degrees']
+0.0
+```
+
+Example use for reading a IIIF manifest:
+
+```
+>>> from piffle.image import IIIFImageClient
+>>> from piffle.presentation import IIIFPresentation
+>>>  manifest = IIIFPresentation.from_url('https://iiif.bodleian.ox.ac.uk/iiif/manifest/60834383-7146-41ab-bfe1-48ee97bc04be.json')
+>>> manifest.label
+'Bodleian Library MS. Bodl. 264'
+>>> manifest.id
+'https://iiif.bodleian.ox.ac.uk/iiif/manifest/60834383-7146-41ab-bfe1-48ee97bc04be.json'
+>>> manifest.type
+'sc:Manifest'
+>>> for canvas in manifest.sequences[0].canvases[:5]:
+...     image_id = canvas.images[0].resource.id
+...     iiif_img = IIIFImageClient(*image_id.rsplit('/', 1))
+...     print(str(iiif_img.size(height=250)))
+...
+https://iiif.bodleian.ox.ac.uk/iiif/image/90701d49-5e0c-4fb5-9c7d-45af96565468/full/,250/0/default.jpg
+https://iiif.bodleian.ox.ac.uk/iiif/image/e878cc78-acd3-43ca-ba6e-90a392f15891/full/,250/0/default.jpg
+https://iiif.bodleian.ox.ac.uk/iiif/image/0f1ed064-a972-4215-b884-d8d658acefc5/full/,250/0/default.jpg
+https://iiif.bodleian.ox.ac.uk/iiif/image/6fe52b9a-5bb7-4b5b-bbcd-ad0489fcad2a/full/,250/0/default.jpg
+https://iiif.bodleian.ox.ac.uk/iiif/image/483ff8ec-347d-4070-8442-dbc15bc7b4de/full/,250/0/default.jpg
+```
+
+## Development and Testing
+
+This project uses [git-flow](https://github.com/nvie/gitflow) branching conventions.
+
+Install locally for development (the use of a python virtualenv is recommended):
+
+`pip install -e .`
+
+Install test dependencies:
+
+`pip install -e ".[dev]"`
+
+Run unit tests: `py.test` or `python setup.py test`
+
+### Install pre-commit hooks
+
+Anyone who wants to contribute to this codebase should install the configured pre-commit hooks:
+
+```
+pre-commit install
+```
+
+This will configure a pre-commit hooks to automatically lint and format python code with [ruff](https://github.com/astral-sh/ruff) and [black](https://github.com/psf/black).
+
+Pre-commit hooks and formatting conventions were added at version 0.5, so ``git blame`` may not reflect the true author of a given change. To make ``git blame`` more accurate, ignore formatting revisions:
+
+```
+git blame <FILE> --ignore-revs-file .git-blame-ignore-revs
+```
+
+Or configure your git to always ignore styling revision commits:
+```
+git config blame.ignoreRevsFile .git-blame-ignore-revs
+```
+
+## Publishing python packages
+
+A new python package is automatically built and published to [PyPI](https://pypi.python.org/pypi) using a GitHub Actions workflow when a new release is created on GitHub.

piffle-0.5.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+piffle/__init__.py,sha256=eZ1bOun1DDVV0YLOBW4wj2FP1ajReLjbIrGmzN7ASBw,22
+piffle/image.py,sha256=bli2O_t4MMQmw9AF-W9mTLN_fFcx2LCoQIX95j-wB68,26486
+piffle/presentation.py,sha256=TAcNvfRbaggHsqp-RVX2yYaY4qcfqBEYov7bCE8OOpc,4591
+piffle-0.5.1.dist-info/METADATA,sha256=u8LR39DZT0PCJHNV09q2PQsmz79F1CuJWbAZ8fAxt3A,5968
+piffle-0.5.1.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+piffle-0.5.1.dist-info/licenses/LICENSE,sha256=tAkwu8-AdEyGxGoSvJ2gVmQdcicWw3j1ZZueVV74M-E,11357
+piffle-0.5.1.dist-info/RECORD,,

piffle-0.5.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

piffle-0.5.1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.