Skip to content

Code reference

AddImage

Source code in iiif_prezi3/helpers/add_image.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class AddImage:

    def add_image(self, image_url, anno_id=None, anno_page_id=None, **kwargs):
        """Adds an image to an existing canvas.

        Args:
            image_url (str): An HTTP URL which points to the image.
            anno_id (str): An HTTP URL for the annotation to which the image will be attached.
            anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.

        Returns:
            anno_page (AnnotationPage): the AnnotationPage with an Annotation and ResourceItem attached.
        """
        body = ResourceItem(id=image_url, type='Image', **kwargs)
        annotation = Annotation(id=anno_id, body=body, target=self.id, motivation='painting', type='Annotation')
        anno_page = AnnotationPage(id=anno_page_id, type='AnnotationPage', items=[annotation])
        if not self.items:
            self.items = list()
        self.items.append(anno_page)
        return anno_page

add_image(image_url, anno_id=None, anno_page_id=None, **kwargs)

Adds an image to an existing canvas.

Parameters:

Name Type Description Default
image_url str

An HTTP URL which points to the image.

 required
anno_id str

An HTTP URL for the annotation to which the image will be attached.

 None
anno_page_id str

An HTTP URL for the annotation page to which the annotation will be attached.

 None

Returns:

Name Type Description
anno_page AnnotationPage

the AnnotationPage with an Annotation and ResourceItem attached.
Source code in iiif_prezi3/helpers/add_image.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
def add_image(self, image_url, anno_id=None, anno_page_id=None, **kwargs):
    """Adds an image to an existing canvas.

    Args:
        image_url (str): An HTTP URL which points to the image.
        anno_id (str): An HTTP URL for the annotation to which the image will be attached.
        anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.

    Returns:
        anno_page (AnnotationPage): the AnnotationPage with an Annotation and ResourceItem attached.
    """
    body = ResourceItem(id=image_url, type='Image', **kwargs)
    annotation = Annotation(id=anno_id, body=body, target=self.id, motivation='painting', type='Annotation')
    anno_page = AnnotationPage(id=anno_page_id, type='AnnotationPage', items=[annotation])
    if not self.items:
        self.items = list()
    self.items.append(anno_page)
    return anno_page

AddItem

Source code in iiif_prezi3/helpers/add_item.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
class AddItem:
    def add_item(self, item):
        """Add a IIIF Prezi3 object to the items list, creating it if it doesn't exist.

        Args:
            item (Union[Collection, Manifest, Canvas, AnnotationPage, Annotation, Range, Reference, SpecificResource, Item])): The object to be added
        """
        if not self.items:
            self.items = []

        # If the item is a Manifest, and the target is a Collection, convert it to a reference
        if isinstance(item, Manifest) and isinstance(self, Collection):
            item = item.to_reference()

        self.items.append(item)
        self.items = self.items  # Force Pydantic to validate?

add_item(item)

Add a IIIF Prezi3 object to the items list, creating it if it doesn't exist.

Parameters:

Name Type Description Default
item Union[Collection, Manifest, Canvas, AnnotationPage, Annotation, Range, Reference, SpecificResource, Item]

The object to be added

 required
Source code in iiif_prezi3/helpers/add_item.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
def add_item(self, item):
    """Add a IIIF Prezi3 object to the items list, creating it if it doesn't exist.

    Args:
        item (Union[Collection, Manifest, Canvas, AnnotationPage, Annotation, Range, Reference, SpecificResource, Item])): The object to be added
    """
    if not self.items:
        self.items = []

    # If the item is a Manifest, and the target is a Collection, convert it to a reference
    if isinstance(item, Manifest) and isinstance(self, Collection):
        item = item.to_reference()

    self.items.append(item)
    self.items = self.items  # Force Pydantic to validate?

AddItemByReference

Source code in iiif_prezi3/helpers/add_item.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
class AddItemByReference:
    def add_item_by_reference(self, item):
        """Add a IIIF Prezi3 object by reference to the items list, creating it if it doesn't exist.

        Args:
            item (Union[Manifest, AnnotationPage, Collection, AnnotationCollection, Canvas])): The object to be added
        """
        if not self.items:
            self.items = []

        item = item.to_reference()

        self.items.append(item)
        self.items = self.items  # Force Pydantic to validate?

add_item_by_reference(item)

Add a IIIF Prezi3 object by reference to the items list, creating it if it doesn't exist.

Parameters:

Name Type Description Default
item Union[Manifest, AnnotationPage, Collection, AnnotationCollection, Canvas]

The object to be added

 required
Source code in iiif_prezi3/helpers/add_item.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
def add_item_by_reference(self, item):
    """Add a IIIF Prezi3 object by reference to the items list, creating it if it doesn't exist.

    Args:
        item (Union[Manifest, AnnotationPage, Collection, AnnotationCollection, Canvas])): The object to be added
    """
    if not self.items:
        self.items = []

    item = item.to_reference()

    self.items.append(item)
    self.items = self.items  # Force Pydantic to validate?

AddLabel

Source code in iiif_prezi3/helpers/add_label.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class AddLabel:

    def add_label(self, value, language=None):
        """Adds a label to an existing resource.

        Args:
            value (Union[str, list]): The label or labels to be added
            language (str): An optional language for the labels. If not provided it will default using the AutoLang configuration.
        """
        if not self.label:
            if not language:
                self.label = value
            else:
                if type(value) != list:
                    value = [value]
                self.label = {language: value}
        else:
            # fetch as dict not LngString
            curr = self.label
            if not language:
                language = configs['helpers.auto_fields.AutoLang'].auto_lang
            if language in curr:
                curr[language].append(value)
            else:
                if type(value) != list:
                    value = [value]
                curr[language] = value
            self.label = curr

add_label(value, language=None)

Adds a label to an existing resource.

Parameters:

Name Type Description Default
value Union[str, list]

The label or labels to be added

 required
language str

An optional language for the labels. If not provided it will default using the AutoLang configuration.

 None
Source code in iiif_prezi3/helpers/add_label.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def add_label(self, value, language=None):
    """Adds a label to an existing resource.

    Args:
        value (Union[str, list]): The label or labels to be added
        language (str): An optional language for the labels. If not provided it will default using the AutoLang configuration.
    """
    if not self.label:
        if not language:
            self.label = value
        else:
            if type(value) != list:
                value = [value]
            self.label = {language: value}
    else:
        # fetch as dict not LngString
        curr = self.label
        if not language:
            language = configs['helpers.auto_fields.AutoLang'].auto_lang
        if language in curr:
            curr[language].append(value)
        else:
            if type(value) != list:
                value = [value]
            curr[language] = value
        self.label = curr

AddService

Source code in iiif_prezi3/helpers/add_service.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
class AddService:
    def add_service(self, service):
        """Add a IIIF Prezi service to the service list.

        Args:
            service (ServiceItem,ServiceItem1,Service): A iiif-prezi ServiceItem.
        """
        if isinstance(service, (ServiceItem, ServiceItem1)):
            if not self.service:
                self.service = []
            self.service.append(service)
            self.service = self.service
        else:
            raise TypeError("Not a valid IIIF service.")

add_service(service)

Add a IIIF Prezi service to the service list.

Parameters:

Name Type Description Default
service (ServiceItem, ServiceItem1, Service)

A iiif-prezi ServiceItem.

 required
Source code in iiif_prezi3/helpers/add_service.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
def add_service(self, service):
    """Add a IIIF Prezi service to the service list.

    Args:
        service (ServiceItem,ServiceItem1,Service): A iiif-prezi ServiceItem.
    """
    if isinstance(service, (ServiceItem, ServiceItem1)):
        if not self.service:
            self.service = []
        self.service.append(service)
        self.service = self.service
    else:
        raise TypeError("Not a valid IIIF service.")

AddThumbnail

Source code in iiif_prezi3/helpers/add_thumbnail.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
class AddThumbnail:
    def add_thumbnail(self, image_url, **kwargs):
        """Adds a thumbnail to an existing canvas.

        Args:
            image_url (str): An HTTP URL which points to the thumbnail.
            **kwargs (): see ResourceItem.

        Returns:
            new_thumbnail (ResourceItem): the newly-created thumbnail.
        """
        new_thumbnail = ResourceItem(id=image_url, type='Image', **kwargs)
        if not self.thumbnail:
            self.thumbnail = list()
        self.thumbnail.append(new_thumbnail)
        return new_thumbnail

add_thumbnail(image_url, **kwargs)

Adds a thumbnail to an existing canvas.

Parameters:

Name Type Description Default
image_url str

An HTTP URL which points to the thumbnail.

 required
**kwargs

see ResourceItem.

 {}

Returns:

Name Type Description
new_thumbnail ResourceItem

the newly-created thumbnail.
Source code in iiif_prezi3/helpers/add_thumbnail.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
def add_thumbnail(self, image_url, **kwargs):
    """Adds a thumbnail to an existing canvas.

    Args:
        image_url (str): An HTTP URL which points to the thumbnail.
        **kwargs (): see ResourceItem.

    Returns:
        new_thumbnail (ResourceItem): the newly-created thumbnail.
    """
    new_thumbnail = ResourceItem(id=image_url, type='Image', **kwargs)
    if not self.thumbnail:
        self.thumbnail = list()
    self.thumbnail.append(new_thumbnail)
    return new_thumbnail

AnnotationHelpers

Source code in iiif_prezi3/helpers/annotation_helpers.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
class AnnotationHelpers:

    def add_annotation(self, annotation, anno_page_id=None):
        """Adds the annotation object to the (AnnotationPage object in the) annotations property.

        Creates an AnnotationPage object if it doesn't exist.

        Args:
            annotation (Annotation): the Annotation to add
            anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.

        Returns:
            annotation (Annotation): the Annotation attached to the AnnotationPage.

        """
        if not self.annotations:
            self.annotations = list()

        if len(self.annotations) == 0:
            # add empty AnnotationPage
            anno_page = AnnotationPage(id=anno_page_id, items=[])
            self.annotations.append(anno_page)
        else:
            anno_page = self.annotations[0]

        anno_page.items.append(annotation)

        return annotation

    def make_annotation(self, anno_page_id=None, **kwargs):
        """Creates an annotation object and adds it to the annotations property using .add_annotation().

        Args:
            anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.
            **kwargs (): see Annotation.
        """
        annotation = Annotation(**kwargs)
        self.add_annotation(annotation, anno_page_id=anno_page_id)
        return annotation

add_annotation(annotation, anno_page_id=None)

Adds the annotation object to the (AnnotationPage object in the) annotations property.

Creates an AnnotationPage object if it doesn't exist.

Parameters:

Name Type Description Default
annotation Annotation

the Annotation to add

 required
anno_page_id str

An HTTP URL for the annotation page to which the annotation will be attached.

 None

Returns:

Name Type Description
annotation Annotation

the Annotation attached to the AnnotationPage.
Source code in iiif_prezi3/helpers/annotation_helpers.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
def add_annotation(self, annotation, anno_page_id=None):
    """Adds the annotation object to the (AnnotationPage object in the) annotations property.

    Creates an AnnotationPage object if it doesn't exist.

    Args:
        annotation (Annotation): the Annotation to add
        anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.

    Returns:
        annotation (Annotation): the Annotation attached to the AnnotationPage.

    """
    if not self.annotations:
        self.annotations = list()

    if len(self.annotations) == 0:
        # add empty AnnotationPage
        anno_page = AnnotationPage(id=anno_page_id, items=[])
        self.annotations.append(anno_page)
    else:
        anno_page = self.annotations[0]

    anno_page.items.append(annotation)

    return annotation

make_annotation(anno_page_id=None, **kwargs)

Creates an annotation object and adds it to the annotations property using .add_annotation().

Parameters:

Name Type Description Default
anno_page_id str

An HTTP URL for the annotation page to which the annotation will be attached.

 None
**kwargs

see Annotation.

 {}
Source code in iiif_prezi3/helpers/annotation_helpers.py 
35
36
37
38
39
40
41
42
43
44
def make_annotation(self, anno_page_id=None, **kwargs):
    """Creates an annotation object and adds it to the annotations property using .add_annotation().

    Args:
        anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.
        **kwargs (): see Annotation.
    """
    annotation = Annotation(**kwargs)
    self.add_annotation(annotation, anno_page_id=anno_page_id)
    return annotation

CreateCanvasFromIIIF

Source code in iiif_prezi3/helpers/create_canvas_from_iiif.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
class CreateCanvasFromIIIF:
    # should probably be added to canvas helpers

    def create_canvas_from_iiif(self, url, anno_id=None, anno_page_id=None, **kwargs):
        """Create a canvas from a IIIF Image URL.

        Creates a canvas from a IIIF Image service passing any kwargs to the Canvas.

        Args:
            url (str): An HTTP URL at which at a IIIF Image is available.
            anno_id (str): An HTTP URL for the annotation to which the image will be attached.
            anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.
            **kwargs (): see Canvas

        Returns:
            canvas (Canvas): the Canvas created from the IIIF Image.

        """
        canvas = Canvas(**kwargs)

        body = ResourceItem(id="http://example.com", type="Image")
        infoJson = body.set_hwd_from_iiif(url)

        # Will need to handle IIIF 2...
        if 'type' not in infoJson:
            # Assume v2

            # V2 profile contains profile URI plus extra features
            profile = ''
            for item in infoJson['profile']:
                if isinstance(item, str):
                    profile = item
                    break

            service = ServiceItem1(id=infoJson['@id'], profile=profile, type="ImageService2")
            body.service = [service]
            body.id = f'{infoJson["@id"]}/full/full/0/default.jpg'
            body.format = "image/jpeg"
        else:
            service = ServiceItem(id=infoJson['id'], profile=infoJson['profile'], type=infoJson['type'])
            body.service = [service]
            body.id = f'{infoJson["id"]}/full/max/0/default.jpg'
            body.format = "image/jpeg"

        annotation = Annotation(id=anno_id, motivation='painting', body=body, target=canvas.id)

        annotationPage = AnnotationPage(id=anno_page_id)
        annotationPage.add_item(annotation)

        canvas.add_item(annotationPage)
        canvas.set_hwd(infoJson['height'], infoJson['width'])

        return canvas

    def make_canvas_from_iiif(self, url, **kwargs):
        canvas = self.create_canvas_from_iiif(url, **kwargs)

        self.add_item(canvas)
        return canvas

create_canvas_from_iiif(url, anno_id=None, anno_page_id=None, **kwargs)

Create a canvas from a IIIF Image URL.

Creates a canvas from a IIIF Image service passing any kwargs to the Canvas.

Parameters:

Name Type Description Default
url str

An HTTP URL at which at a IIIF Image is available.

 required
anno_id str

An HTTP URL for the annotation to which the image will be attached.

 None
anno_page_id str

An HTTP URL for the annotation page to which the annotation will be attached.

 None
**kwargs

see Canvas

 {}

Returns:

Name Type Description
canvas Canvas

the Canvas created from the IIIF Image.
Source code in iiif_prezi3/helpers/create_canvas_from_iiif.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def create_canvas_from_iiif(self, url, anno_id=None, anno_page_id=None, **kwargs):
    """Create a canvas from a IIIF Image URL.

    Creates a canvas from a IIIF Image service passing any kwargs to the Canvas.

    Args:
        url (str): An HTTP URL at which at a IIIF Image is available.
        anno_id (str): An HTTP URL for the annotation to which the image will be attached.
        anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.
        **kwargs (): see Canvas

    Returns:
        canvas (Canvas): the Canvas created from the IIIF Image.

    """
    canvas = Canvas(**kwargs)

    body = ResourceItem(id="http://example.com", type="Image")
    infoJson = body.set_hwd_from_iiif(url)

    # Will need to handle IIIF 2...
    if 'type' not in infoJson:
        # Assume v2

        # V2 profile contains profile URI plus extra features
        profile = ''
        for item in infoJson['profile']:
            if isinstance(item, str):
                profile = item
                break

        service = ServiceItem1(id=infoJson['@id'], profile=profile, type="ImageService2")
        body.service = [service]
        body.id = f'{infoJson["@id"]}/full/full/0/default.jpg'
        body.format = "image/jpeg"
    else:
        service = ServiceItem(id=infoJson['id'], profile=infoJson['profile'], type=infoJson['type'])
        body.service = [service]
        body.id = f'{infoJson["id"]}/full/max/0/default.jpg'
        body.format = "image/jpeg"

    annotation = Annotation(id=anno_id, motivation='painting', body=body, target=canvas.id)

    annotationPage = AnnotationPage(id=anno_page_id)
    annotationPage.add_item(annotation)

    canvas.add_item(annotationPage)
    canvas.set_hwd(infoJson['height'], infoJson['width'])

    return canvas

MakeCanvas

Source code in iiif_prezi3/helpers/make_canvas.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
class MakeCanvas:

    def make_canvas(self, **kwargs):
        """Add a Canvas to a Manifest.

        Creates a new Canvas, appends it to the
        calling Manifest items and returns the newly created Canvas.
        Accepts keyword arguments to customize the resulting instance.
        """
        canvas = Canvas(**kwargs)
        self.add_item(canvas)
        return canvas

make_canvas(**kwargs)

Add a Canvas to a Manifest.

Creates a new Canvas, appends it to the calling Manifest items and returns the newly created Canvas. Accepts keyword arguments to customize the resulting instance.

Source code in iiif_prezi3/helpers/make_canvas.py 
 7
 8
 9
10
11
12
13
14
15
16
def make_canvas(self, **kwargs):
    """Add a Canvas to a Manifest.

    Creates a new Canvas, appends it to the
    calling Manifest items and returns the newly created Canvas.
    Accepts keyword arguments to customize the resulting instance.
    """
    canvas = Canvas(**kwargs)
    self.add_item(canvas)
    return canvas

MakeCollection

Source code in iiif_prezi3/helpers/make_collection.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
class MakeCollection:

    def make_collection(self, **kwargs):
        """Create a Collection.

        Creates a new collection, adds it to the calling Collection `items`
        and returns the newly created object. Accepts keyword arguments to
        customize the resulting instance.
        """
        child_collection = Collection(**kwargs)
        self.add_item(child_collection)
        return child_collection

make_collection(**kwargs)

Create a Collection.

Creates a new collection, adds it to the calling Collection items and returns the newly created object. Accepts keyword arguments to customize the resulting instance.

Source code in iiif_prezi3/helpers/make_collection.py 
 7
 8
 9
10
11
12
13
14
15
16
def make_collection(self, **kwargs):
    """Create a Collection.

    Creates a new collection, adds it to the calling Collection `items`
    and returns the newly created object. Accepts keyword arguments to
    customize the resulting instance.
    """
    child_collection = Collection(**kwargs)
    self.add_item(child_collection)
    return child_collection

MakeManifest

Source code in iiif_prezi3/helpers/make_manifest.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
class MakeManifest:

    def make_manifest(self, **kwargs):
        """Add a Manifest to a Collection.

        Creates a new Manifest, adds a Reference to it to the
        calling Collection items and returns the newly created Manifest.
        Accepts keyword arguments to customize the resulting instance.
        """
        manifest = Manifest(**kwargs)
        self.add_item(manifest)
        return manifest

make_manifest(**kwargs)

Add a Manifest to a Collection.

Creates a new Manifest, adds a Reference to it to the calling Collection items and returns the newly created Manifest. Accepts keyword arguments to customize the resulting instance.

Source code in iiif_prezi3/helpers/make_manifest.py 
 7
 8
 9
10
11
12
13
14
15
16
def make_manifest(self, **kwargs):
    """Add a Manifest to a Collection.

    Creates a new Manifest, adds a Reference to it to the
    calling Collection items and returns the newly created Manifest.
    Accepts keyword arguments to customize the resulting instance.
    """
    manifest = Manifest(**kwargs)
    self.add_item(manifest)
    return manifest

MakeRange

Source code in iiif_prezi3/helpers/make_range.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
class MakeRange:

    def make_range(self, **kwargs):
        """Create a Range and add it to the calling Collection or Range.

        Creates a new Range, adds it to the calling object and returns the newly created Range.
        Accepts keyword arguments to customize the resulting instance.
        """
        range = Range(**kwargs)
        if type(self) == Manifest:
            if self.structures:
                self.structures.append(range)
            else:
                self.structures = [range]
        elif type(self) == Range:
            self.add_item(range)
        return range

make_range(**kwargs)

Create a Range and add it to the calling Collection or Range.

Creates a new Range, adds it to the calling object and returns the newly created Range. Accepts keyword arguments to customize the resulting instance.

Source code in iiif_prezi3/helpers/make_range.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
def make_range(self, **kwargs):
    """Create a Range and add it to the calling Collection or Range.

    Creates a new Range, adds it to the calling object and returns the newly created Range.
    Accepts keyword arguments to customize the resulting instance.
    """
    range = Range(**kwargs)
    if type(self) == Manifest:
        if self.structures:
            self.structures.append(range)
        else:
            self.structures = [range]
    elif type(self) == Range:
        self.add_item(range)
    return range

MakeService

Source code in iiif_prezi3/helpers/make_service.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
class MakeService:
    def make_service(self, id, type, version=3, **kwargs):
        """Make a IIIF Prezi service of the desired IIIF API version and adds it to the service list.

        Args:
            id (AnyUrl): The id of the service.
            type (str): The type of the service.
            version (int): The API version of the service. Defaults to 3.
            **kwargs (): Arbitrary keyword arguments.

        Raises:
            ValueError: If an invalid IIIF API version is provided.

        Returns:
           service (Union[ServiceItem, ServiceItem1]): A service instance of the selected version.
        """
        serviceversions = {
            2: ServiceItem1,
            3: ServiceItem
        }
        if version not in serviceversions:
            raise ValueError(f"Version: {version} is not a valid IIIF API service version.")
        service = serviceversions[version](id=id, type=type, **kwargs)
        self.add_service(service)
        return service

make_service(id, type, version=3, **kwargs)

Make a IIIF Prezi service of the desired IIIF API version and adds it to the service list.

Parameters:

Name Type Description Default
id AnyUrl

The id of the service.

 required
type str

The type of the service.

 required
version int

The API version of the service. Defaults to 3.

 3
**kwargs

Arbitrary keyword arguments.

 {}

Raises:

Type Description
ValueError

If an invalid IIIF API version is provided.

Returns:

Name Type Description
service Union[ServiceItem, ServiceItem1]

A service instance of the selected version.
Source code in iiif_prezi3/helpers/make_service.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
def make_service(self, id, type, version=3, **kwargs):
    """Make a IIIF Prezi service of the desired IIIF API version and adds it to the service list.

    Args:
        id (AnyUrl): The id of the service.
        type (str): The type of the service.
        version (int): The API version of the service. Defaults to 3.
        **kwargs (): Arbitrary keyword arguments.

    Raises:
        ValueError: If an invalid IIIF API version is provided.

    Returns:
       service (Union[ServiceItem, ServiceItem1]): A service instance of the selected version.
    """
    serviceversions = {
        2: ServiceItem1,
        3: ServiceItem
    }
    if version not in serviceversions:
        raise ValueError(f"Version: {version} is not a valid IIIF API service version.")
    service = serviceversions[version](id=id, type=type, **kwargs)
    self.add_service(service)
    return service

SetHeightWidthDurationFileHelper

Source code in iiif_prezi3/helpers/set_hwd_from_file.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class SetHeightWidthDurationFileHelper:
    def set_hwd_from_file(self, file_path_or_object):
        """Introspect a file and set the height, width, and duration properties.

        Args:
            file_path_or_object (Union[str, fp]): the file path or file object to introspect
        """
        if isinstance(file_path_or_object, str) or isinstance(file_path_or_object, os.PathLike):
            filetype, _ = mimetypes.guess_type(file_path_or_object)
            if not filetype.startswith("image/"):
                raise NotImplementedError

        tmp_image = Image.open(file_path_or_object)
        w, h = tmp_image.size
        self.set_hwd(h, w, None)
        tmp_image.close()

set_hwd_from_file(file_path_or_object)

Introspect a file and set the height, width, and duration properties.

Parameters:

Name Type Description Default
file_path_or_object Union[str, fp]

the file path or file object to introspect

 required
Source code in iiif_prezi3/helpers/set_hwd_from_file.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
def set_hwd_from_file(self, file_path_or_object):
    """Introspect a file and set the height, width, and duration properties.

    Args:
        file_path_or_object (Union[str, fp]): the file path or file object to introspect
    """
    if isinstance(file_path_or_object, str) or isinstance(file_path_or_object, os.PathLike):
        filetype, _ = mimetypes.guess_type(file_path_or_object)
        if not filetype.startswith("image/"):
            raise NotImplementedError

    tmp_image = Image.open(file_path_or_object)
    w, h = tmp_image.size
    self.set_hwd(h, w, None)
    tmp_image.close()

SetHwd

Source code in iiif_prezi3/helpers/set_hwd.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
class SetHwd:
    def set_hwd(self, height=None, width=None, duration=None):
        """Set the height, width, and duration properties allowing nulls.

        Args:
            height (int): The height of the resource or the canvas
            width (int): The width of the resource or the canvas
            duration (float): The duration of the resource
        """
        if not (duration or height or width):
            raise TypeError("At least one of height, width, or duration must be set")
        if height and not width:
            raise TypeError("width must be set if height is set")
        if width and not height:
            raise TypeError("height must be set if width is set")
        self.height = height
        self.width = width
        self.duration = duration

set_hwd(height=None, width=None, duration=None)

Set the height, width, and duration properties allowing nulls.

Parameters:

Name Type Description Default
height int

The height of the resource or the canvas

 None
width int

The width of the resource or the canvas

 None
duration float

The duration of the resource

 None
Source code in iiif_prezi3/helpers/set_hwd.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
def set_hwd(self, height=None, width=None, duration=None):
    """Set the height, width, and duration properties allowing nulls.

    Args:
        height (int): The height of the resource or the canvas
        width (int): The width of the resource or the canvas
        duration (float): The duration of the resource
    """
    if not (duration or height or width):
        raise TypeError("At least one of height, width, or duration must be set")
    if height and not width:
        raise TypeError("width must be set if height is set")
    if width and not height:
        raise TypeError("height must be set if width is set")
    self.height = height
    self.width = width
    self.duration = duration

SetHwdFromIIIF

Source code in iiif_prezi3/helpers/set_hwd_from_iiif.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
class SetHwdFromIIIF:
    # should probably be added to canvas helpers

    def set_hwd_from_iiif(self, url):
        """Set height and width on a Canvas object.

        Requests IIIF Image information remotely for an
        image resource and sets resulting height and width.
        This method will return the info.json

        Args:
            url (str): An HTTP URL for the IIIF image endpoint.
        """
        # resource url may or may not end with info.json;
        # add if not present
        if not url.endswith("info.json"):
            url = f"{ url.rstrip('/') }/info.json"

        response = requests.get(url)
        # if response is not 200, raise exception
        if response.status_code != requests.codes.ok:
            response.raise_for_status()
        # if response is not valid json, request will raise
        # requests.exceptions.JSONDecodeError
        # — handle or document and let calling code handle?
        resource_info = response.json()
        self.set_hwd(resource_info.get("height"), resource_info.get("width"))

        return resource_info

set_hwd_from_iiif(url)

Set height and width on a Canvas object.

Requests IIIF Image information remotely for an image resource and sets resulting height and width. This method will return the info.json

Parameters:

Name Type Description Default
url str

An HTTP URL for the IIIF image endpoint.

 required
Source code in iiif_prezi3/helpers/set_hwd_from_iiif.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
def set_hwd_from_iiif(self, url):
    """Set height and width on a Canvas object.

    Requests IIIF Image information remotely for an
    image resource and sets resulting height and width.
    This method will return the info.json

    Args:
        url (str): An HTTP URL for the IIIF image endpoint.
    """
    # resource url may or may not end with info.json;
    # add if not present
    if not url.endswith("info.json"):
        url = f"{ url.rstrip('/') }/info.json"

    response = requests.get(url)
    # if response is not 200, raise exception
    if response.status_code != requests.codes.ok:
        response.raise_for_status()
    # if response is not valid json, request will raise
    # requests.exceptions.JSONDecodeError
    # — handle or document and let calling code handle?
    resource_info = response.json()
    self.set_hwd(resource_info.get("height"), resource_info.get("width"))

    return resource_info

ToReference

Source code in iiif_prezi3/helpers/to_reference.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class ToReference:

    def to_reference(self):
        """Returns a Reference object that points to the calling object."""
        # Only try to set thumbnail if it's a Class that can have one
        if isinstance(self, (Collection, Manifest, Canvas, AnnotationPage, Annotation, AnnotationCollection, Range)):
            thumbnail = self.thumbnail
        else:
            thumbnail = None

        # Currently the skeleton Reference requires a label, but some Referenceable objects may not have one (e.g AnnotationPage)
        # TODO: Remove this when the Schema is updated to have different reference types
        if not self.label:
            self.label = ""

        # Ensure that we use a specific Reference type if it exists
        if isinstance(self, Manifest):
            target_type = ManifestRef
        elif isinstance(self, Collection):
            target_type = CollectionRef
        elif isinstance(self, Canvas):
            target_type = CanvasRef
        elif isinstance(self, Range):
            target_type = RangeRef
        else:
            target_type = Reference

        return target_type(id=self.id, label=self.label, type=self.type, thumbnail=thumbnail)

to_reference()

Returns a Reference object that points to the calling object.

Source code in iiif_prezi3/helpers/to_reference.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def to_reference(self):
    """Returns a Reference object that points to the calling object."""
    # Only try to set thumbnail if it's a Class that can have one
    if isinstance(self, (Collection, Manifest, Canvas, AnnotationPage, Annotation, AnnotationCollection, Range)):
        thumbnail = self.thumbnail
    else:
        thumbnail = None

    # Currently the skeleton Reference requires a label, but some Referenceable objects may not have one (e.g AnnotationPage)
    # TODO: Remove this when the Schema is updated to have different reference types
    if not self.label:
        self.label = ""

    # Ensure that we use a specific Reference type if it exists
    if isinstance(self, Manifest):
        target_type = ManifestRef
    elif isinstance(self, Collection):
        target_type = CollectionRef
    elif isinstance(self, Canvas):
        target_type = CanvasRef
    elif isinstance(self, Range):
        target_type = RangeRef
    else:
        target_type = Reference

    return target_type(id=self.id, label=self.label, type=self.type, thumbnail=thumbnail)

helpers

add_image

AddImage

Source code in iiif_prezi3/helpers/add_image.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class AddImage:

    def add_image(self, image_url, anno_id=None, anno_page_id=None, **kwargs):
        """Adds an image to an existing canvas.

        Args:
            image_url (str): An HTTP URL which points to the image.
            anno_id (str): An HTTP URL for the annotation to which the image will be attached.
            anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.

        Returns:
            anno_page (AnnotationPage): the AnnotationPage with an Annotation and ResourceItem attached.
        """
        body = ResourceItem(id=image_url, type='Image', **kwargs)
        annotation = Annotation(id=anno_id, body=body, target=self.id, motivation='painting', type='Annotation')
        anno_page = AnnotationPage(id=anno_page_id, type='AnnotationPage', items=[annotation])
        if not self.items:
            self.items = list()
        self.items.append(anno_page)
        return anno_page
add_image(image_url, anno_id=None, anno_page_id=None, **kwargs)

Adds an image to an existing canvas.

Parameters:

Name Type Description Default
image_url str

An HTTP URL which points to the image.

 required
anno_id str

An HTTP URL for the annotation to which the image will be attached.

 None
anno_page_id str

An HTTP URL for the annotation page to which the annotation will be attached.

 None

Returns:

Name Type Description
anno_page AnnotationPage

the AnnotationPage with an Annotation and ResourceItem attached.
Source code in iiif_prezi3/helpers/add_image.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
def add_image(self, image_url, anno_id=None, anno_page_id=None, **kwargs):
    """Adds an image to an existing canvas.

    Args:
        image_url (str): An HTTP URL which points to the image.
        anno_id (str): An HTTP URL for the annotation to which the image will be attached.
        anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.

    Returns:
        anno_page (AnnotationPage): the AnnotationPage with an Annotation and ResourceItem attached.
    """
    body = ResourceItem(id=image_url, type='Image', **kwargs)
    annotation = Annotation(id=anno_id, body=body, target=self.id, motivation='painting', type='Annotation')
    anno_page = AnnotationPage(id=anno_page_id, type='AnnotationPage', items=[annotation])
    if not self.items:
        self.items = list()
    self.items.append(anno_page)
    return anno_page

add_item

AddItem

Source code in iiif_prezi3/helpers/add_item.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
class AddItem:
    def add_item(self, item):
        """Add a IIIF Prezi3 object to the items list, creating it if it doesn't exist.

        Args:
            item (Union[Collection, Manifest, Canvas, AnnotationPage, Annotation, Range, Reference, SpecificResource, Item])): The object to be added
        """
        if not self.items:
            self.items = []

        # If the item is a Manifest, and the target is a Collection, convert it to a reference
        if isinstance(item, Manifest) and isinstance(self, Collection):
            item = item.to_reference()

        self.items.append(item)
        self.items = self.items  # Force Pydantic to validate?
add_item(item)

Add a IIIF Prezi3 object to the items list, creating it if it doesn't exist.

Parameters:

Name Type Description Default
item Union[Collection, Manifest, Canvas, AnnotationPage, Annotation, Range, Reference, SpecificResource, Item]

The object to be added

 required
Source code in iiif_prezi3/helpers/add_item.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
def add_item(self, item):
    """Add a IIIF Prezi3 object to the items list, creating it if it doesn't exist.

    Args:
        item (Union[Collection, Manifest, Canvas, AnnotationPage, Annotation, Range, Reference, SpecificResource, Item])): The object to be added
    """
    if not self.items:
        self.items = []

    # If the item is a Manifest, and the target is a Collection, convert it to a reference
    if isinstance(item, Manifest) and isinstance(self, Collection):
        item = item.to_reference()

    self.items.append(item)
    self.items = self.items  # Force Pydantic to validate?

AddItemByReference

Source code in iiif_prezi3/helpers/add_item.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
class AddItemByReference:
    def add_item_by_reference(self, item):
        """Add a IIIF Prezi3 object by reference to the items list, creating it if it doesn't exist.

        Args:
            item (Union[Manifest, AnnotationPage, Collection, AnnotationCollection, Canvas])): The object to be added
        """
        if not self.items:
            self.items = []

        item = item.to_reference()

        self.items.append(item)
        self.items = self.items  # Force Pydantic to validate?
add_item_by_reference(item)

Add a IIIF Prezi3 object by reference to the items list, creating it if it doesn't exist.

Parameters:

Name Type Description Default
item Union[Manifest, AnnotationPage, Collection, AnnotationCollection, Canvas]

The object to be added

 required
Source code in iiif_prezi3/helpers/add_item.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
def add_item_by_reference(self, item):
    """Add a IIIF Prezi3 object by reference to the items list, creating it if it doesn't exist.

    Args:
        item (Union[Manifest, AnnotationPage, Collection, AnnotationCollection, Canvas])): The object to be added
    """
    if not self.items:
        self.items = []

    item = item.to_reference()

    self.items.append(item)
    self.items = self.items  # Force Pydantic to validate?

add_label

AddLabel

Source code in iiif_prezi3/helpers/add_label.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class AddLabel:

    def add_label(self, value, language=None):
        """Adds a label to an existing resource.

        Args:
            value (Union[str, list]): The label or labels to be added
            language (str): An optional language for the labels. If not provided it will default using the AutoLang configuration.
        """
        if not self.label:
            if not language:
                self.label = value
            else:
                if type(value) != list:
                    value = [value]
                self.label = {language: value}
        else:
            # fetch as dict not LngString
            curr = self.label
            if not language:
                language = configs['helpers.auto_fields.AutoLang'].auto_lang
            if language in curr:
                curr[language].append(value)
            else:
                if type(value) != list:
                    value = [value]
                curr[language] = value
            self.label = curr
add_label(value, language=None)

Adds a label to an existing resource.

Parameters:

Name Type Description Default
value Union[str, list]

The label or labels to be added

 required
language str

An optional language for the labels. If not provided it will default using the AutoLang configuration.

 None
Source code in iiif_prezi3/helpers/add_label.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def add_label(self, value, language=None):
    """Adds a label to an existing resource.

    Args:
        value (Union[str, list]): The label or labels to be added
        language (str): An optional language for the labels. If not provided it will default using the AutoLang configuration.
    """
    if not self.label:
        if not language:
            self.label = value
        else:
            if type(value) != list:
                value = [value]
            self.label = {language: value}
    else:
        # fetch as dict not LngString
        curr = self.label
        if not language:
            language = configs['helpers.auto_fields.AutoLang'].auto_lang
        if language in curr:
            curr[language].append(value)
        else:
            if type(value) != list:
                value = [value]
            curr[language] = value
        self.label = curr

add_service

AddService

Source code in iiif_prezi3/helpers/add_service.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
class AddService:
    def add_service(self, service):
        """Add a IIIF Prezi service to the service list.

        Args:
            service (ServiceItem,ServiceItem1,Service): A iiif-prezi ServiceItem.
        """
        if isinstance(service, (ServiceItem, ServiceItem1)):
            if not self.service:
                self.service = []
            self.service.append(service)
            self.service = self.service
        else:
            raise TypeError("Not a valid IIIF service.")
add_service(service)

Add a IIIF Prezi service to the service list.

Parameters:

Name Type Description Default
service (ServiceItem, ServiceItem1, Service)

A iiif-prezi ServiceItem.

 required
Source code in iiif_prezi3/helpers/add_service.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
def add_service(self, service):
    """Add a IIIF Prezi service to the service list.

    Args:
        service (ServiceItem,ServiceItem1,Service): A iiif-prezi ServiceItem.
    """
    if isinstance(service, (ServiceItem, ServiceItem1)):
        if not self.service:
            self.service = []
        self.service.append(service)
        self.service = self.service
    else:
        raise TypeError("Not a valid IIIF service.")

add_thumbnail

AddThumbnail

Source code in iiif_prezi3/helpers/add_thumbnail.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
class AddThumbnail:
    def add_thumbnail(self, image_url, **kwargs):
        """Adds a thumbnail to an existing canvas.

        Args:
            image_url (str): An HTTP URL which points to the thumbnail.
            **kwargs (): see ResourceItem.

        Returns:
            new_thumbnail (ResourceItem): the newly-created thumbnail.
        """
        new_thumbnail = ResourceItem(id=image_url, type='Image', **kwargs)
        if not self.thumbnail:
            self.thumbnail = list()
        self.thumbnail.append(new_thumbnail)
        return new_thumbnail
add_thumbnail(image_url, **kwargs)

Adds a thumbnail to an existing canvas.

Parameters:

Name Type Description Default
image_url str

An HTTP URL which points to the thumbnail.

 required
**kwargs

see ResourceItem.

 {}

Returns:

Name Type Description
new_thumbnail ResourceItem

the newly-created thumbnail.
Source code in iiif_prezi3/helpers/add_thumbnail.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
def add_thumbnail(self, image_url, **kwargs):
    """Adds a thumbnail to an existing canvas.

    Args:
        image_url (str): An HTTP URL which points to the thumbnail.
        **kwargs (): see ResourceItem.

    Returns:
        new_thumbnail (ResourceItem): the newly-created thumbnail.
    """
    new_thumbnail = ResourceItem(id=image_url, type='Image', **kwargs)
    if not self.thumbnail:
        self.thumbnail = list()
    self.thumbnail.append(new_thumbnail)
    return new_thumbnail

annotation_helpers

AnnotationHelpers

Source code in iiif_prezi3/helpers/annotation_helpers.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
class AnnotationHelpers:

    def add_annotation(self, annotation, anno_page_id=None):
        """Adds the annotation object to the (AnnotationPage object in the) annotations property.

        Creates an AnnotationPage object if it doesn't exist.

        Args:
            annotation (Annotation): the Annotation to add
            anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.

        Returns:
            annotation (Annotation): the Annotation attached to the AnnotationPage.

        """
        if not self.annotations:
            self.annotations = list()

        if len(self.annotations) == 0:
            # add empty AnnotationPage
            anno_page = AnnotationPage(id=anno_page_id, items=[])
            self.annotations.append(anno_page)
        else:
            anno_page = self.annotations[0]

        anno_page.items.append(annotation)

        return annotation

    def make_annotation(self, anno_page_id=None, **kwargs):
        """Creates an annotation object and adds it to the annotations property using .add_annotation().

        Args:
            anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.
            **kwargs (): see Annotation.
        """
        annotation = Annotation(**kwargs)
        self.add_annotation(annotation, anno_page_id=anno_page_id)
        return annotation
add_annotation(annotation, anno_page_id=None)

Adds the annotation object to the (AnnotationPage object in the) annotations property.

Creates an AnnotationPage object if it doesn't exist.

Parameters:

Name Type Description Default
annotation Annotation

the Annotation to add

 required
anno_page_id str

An HTTP URL for the annotation page to which the annotation will be attached.

 None

Returns:

Name Type Description
annotation Annotation

the Annotation attached to the AnnotationPage.
Source code in iiif_prezi3/helpers/annotation_helpers.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
def add_annotation(self, annotation, anno_page_id=None):
    """Adds the annotation object to the (AnnotationPage object in the) annotations property.

    Creates an AnnotationPage object if it doesn't exist.

    Args:
        annotation (Annotation): the Annotation to add
        anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.

    Returns:
        annotation (Annotation): the Annotation attached to the AnnotationPage.

    """
    if not self.annotations:
        self.annotations = list()

    if len(self.annotations) == 0:
        # add empty AnnotationPage
        anno_page = AnnotationPage(id=anno_page_id, items=[])
        self.annotations.append(anno_page)
    else:
        anno_page = self.annotations[0]

    anno_page.items.append(annotation)

    return annotation
make_annotation(anno_page_id=None, **kwargs)

Creates an annotation object and adds it to the annotations property using .add_annotation().

Parameters:

Name Type Description Default
anno_page_id str

An HTTP URL for the annotation page to which the annotation will be attached.

 None
**kwargs

see Annotation.

 {}
Source code in iiif_prezi3/helpers/annotation_helpers.py 
35
36
37
38
39
40
41
42
43
44
def make_annotation(self, anno_page_id=None, **kwargs):
    """Creates an annotation object and adds it to the annotations property using .add_annotation().

    Args:
        anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.
        **kwargs (): see Annotation.
    """
    annotation = Annotation(**kwargs)
    self.add_annotation(annotation, anno_page_id=anno_page_id)
    return annotation

create_canvas_from_iiif

CreateCanvasFromIIIF

Source code in iiif_prezi3/helpers/create_canvas_from_iiif.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
class CreateCanvasFromIIIF:
    # should probably be added to canvas helpers

    def create_canvas_from_iiif(self, url, anno_id=None, anno_page_id=None, **kwargs):
        """Create a canvas from a IIIF Image URL.

        Creates a canvas from a IIIF Image service passing any kwargs to the Canvas.

        Args:
            url (str): An HTTP URL at which at a IIIF Image is available.
            anno_id (str): An HTTP URL for the annotation to which the image will be attached.
            anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.
            **kwargs (): see Canvas

        Returns:
            canvas (Canvas): the Canvas created from the IIIF Image.

        """
        canvas = Canvas(**kwargs)

        body = ResourceItem(id="http://example.com", type="Image")
        infoJson = body.set_hwd_from_iiif(url)

        # Will need to handle IIIF 2...
        if 'type' not in infoJson:
            # Assume v2

            # V2 profile contains profile URI plus extra features
            profile = ''
            for item in infoJson['profile']:
                if isinstance(item, str):
                    profile = item
                    break

            service = ServiceItem1(id=infoJson['@id'], profile=profile, type="ImageService2")
            body.service = [service]
            body.id = f'{infoJson["@id"]}/full/full/0/default.jpg'
            body.format = "image/jpeg"
        else:
            service = ServiceItem(id=infoJson['id'], profile=infoJson['profile'], type=infoJson['type'])
            body.service = [service]
            body.id = f'{infoJson["id"]}/full/max/0/default.jpg'
            body.format = "image/jpeg"

        annotation = Annotation(id=anno_id, motivation='painting', body=body, target=canvas.id)

        annotationPage = AnnotationPage(id=anno_page_id)
        annotationPage.add_item(annotation)

        canvas.add_item(annotationPage)
        canvas.set_hwd(infoJson['height'], infoJson['width'])

        return canvas

    def make_canvas_from_iiif(self, url, **kwargs):
        canvas = self.create_canvas_from_iiif(url, **kwargs)

        self.add_item(canvas)
        return canvas
create_canvas_from_iiif(url, anno_id=None, anno_page_id=None, **kwargs)

Create a canvas from a IIIF Image URL.

Creates a canvas from a IIIF Image service passing any kwargs to the Canvas.

Parameters:

Name Type Description Default
url str

An HTTP URL at which at a IIIF Image is available.

 required
anno_id str

An HTTP URL for the annotation to which the image will be attached.

 None
anno_page_id str

An HTTP URL for the annotation page to which the annotation will be attached.

 None
**kwargs

see Canvas

 {}

Returns:

Name Type Description
canvas Canvas

the Canvas created from the IIIF Image.
Source code in iiif_prezi3/helpers/create_canvas_from_iiif.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def create_canvas_from_iiif(self, url, anno_id=None, anno_page_id=None, **kwargs):
    """Create a canvas from a IIIF Image URL.

    Creates a canvas from a IIIF Image service passing any kwargs to the Canvas.

    Args:
        url (str): An HTTP URL at which at a IIIF Image is available.
        anno_id (str): An HTTP URL for the annotation to which the image will be attached.
        anno_page_id (str): An HTTP URL for the annotation page to which the annotation will be attached.
        **kwargs (): see Canvas

    Returns:
        canvas (Canvas): the Canvas created from the IIIF Image.

    """
    canvas = Canvas(**kwargs)

    body = ResourceItem(id="http://example.com", type="Image")
    infoJson = body.set_hwd_from_iiif(url)

    # Will need to handle IIIF 2...
    if 'type' not in infoJson:
        # Assume v2

        # V2 profile contains profile URI plus extra features
        profile = ''
        for item in infoJson['profile']:
            if isinstance(item, str):
                profile = item
                break

        service = ServiceItem1(id=infoJson['@id'], profile=profile, type="ImageService2")
        body.service = [service]
        body.id = f'{infoJson["@id"]}/full/full/0/default.jpg'
        body.format = "image/jpeg"
    else:
        service = ServiceItem(id=infoJson['id'], profile=infoJson['profile'], type=infoJson['type'])
        body.service = [service]
        body.id = f'{infoJson["id"]}/full/max/0/default.jpg'
        body.format = "image/jpeg"

    annotation = Annotation(id=anno_id, motivation='painting', body=body, target=canvas.id)

    annotationPage = AnnotationPage(id=anno_page_id)
    annotationPage.add_item(annotation)

    canvas.add_item(annotationPage)
    canvas.set_hwd(infoJson['height'], infoJson['width'])

    return canvas

make_canvas

MakeCanvas

Source code in iiif_prezi3/helpers/make_canvas.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
class MakeCanvas:

    def make_canvas(self, **kwargs):
        """Add a Canvas to a Manifest.

        Creates a new Canvas, appends it to the
        calling Manifest items and returns the newly created Canvas.
        Accepts keyword arguments to customize the resulting instance.
        """
        canvas = Canvas(**kwargs)
        self.add_item(canvas)
        return canvas
make_canvas(**kwargs)

Add a Canvas to a Manifest.

Creates a new Canvas, appends it to the calling Manifest items and returns the newly created Canvas. Accepts keyword arguments to customize the resulting instance.

Source code in iiif_prezi3/helpers/make_canvas.py 
 7
 8
 9
10
11
12
13
14
15
16
def make_canvas(self, **kwargs):
    """Add a Canvas to a Manifest.

    Creates a new Canvas, appends it to the
    calling Manifest items and returns the newly created Canvas.
    Accepts keyword arguments to customize the resulting instance.
    """
    canvas = Canvas(**kwargs)
    self.add_item(canvas)
    return canvas

make_collection

MakeCollection

Source code in iiif_prezi3/helpers/make_collection.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
class MakeCollection:

    def make_collection(self, **kwargs):
        """Create a Collection.

        Creates a new collection, adds it to the calling Collection `items`
        and returns the newly created object. Accepts keyword arguments to
        customize the resulting instance.
        """
        child_collection = Collection(**kwargs)
        self.add_item(child_collection)
        return child_collection
make_collection(**kwargs)

Create a Collection.

Creates a new collection, adds it to the calling Collection items and returns the newly created object. Accepts keyword arguments to customize the resulting instance.

Source code in iiif_prezi3/helpers/make_collection.py 
 7
 8
 9
10
11
12
13
14
15
16
def make_collection(self, **kwargs):
    """Create a Collection.

    Creates a new collection, adds it to the calling Collection `items`
    and returns the newly created object. Accepts keyword arguments to
    customize the resulting instance.
    """
    child_collection = Collection(**kwargs)
    self.add_item(child_collection)
    return child_collection

make_manifest

MakeManifest

Source code in iiif_prezi3/helpers/make_manifest.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
class MakeManifest:

    def make_manifest(self, **kwargs):
        """Add a Manifest to a Collection.

        Creates a new Manifest, adds a Reference to it to the
        calling Collection items and returns the newly created Manifest.
        Accepts keyword arguments to customize the resulting instance.
        """
        manifest = Manifest(**kwargs)
        self.add_item(manifest)
        return manifest
make_manifest(**kwargs)

Add a Manifest to a Collection.

Creates a new Manifest, adds a Reference to it to the calling Collection items and returns the newly created Manifest. Accepts keyword arguments to customize the resulting instance.

Source code in iiif_prezi3/helpers/make_manifest.py 
 7
 8
 9
10
11
12
13
14
15
16
def make_manifest(self, **kwargs):
    """Add a Manifest to a Collection.

    Creates a new Manifest, adds a Reference to it to the
    calling Collection items and returns the newly created Manifest.
    Accepts keyword arguments to customize the resulting instance.
    """
    manifest = Manifest(**kwargs)
    self.add_item(manifest)
    return manifest

make_range

MakeRange

Source code in iiif_prezi3/helpers/make_range.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
class MakeRange:

    def make_range(self, **kwargs):
        """Create a Range and add it to the calling Collection or Range.

        Creates a new Range, adds it to the calling object and returns the newly created Range.
        Accepts keyword arguments to customize the resulting instance.
        """
        range = Range(**kwargs)
        if type(self) == Manifest:
            if self.structures:
                self.structures.append(range)
            else:
                self.structures = [range]
        elif type(self) == Range:
            self.add_item(range)
        return range
make_range(**kwargs)

Create a Range and add it to the calling Collection or Range.

Creates a new Range, adds it to the calling object and returns the newly created Range. Accepts keyword arguments to customize the resulting instance.

Source code in iiif_prezi3/helpers/make_range.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
def make_range(self, **kwargs):
    """Create a Range and add it to the calling Collection or Range.

    Creates a new Range, adds it to the calling object and returns the newly created Range.
    Accepts keyword arguments to customize the resulting instance.
    """
    range = Range(**kwargs)
    if type(self) == Manifest:
        if self.structures:
            self.structures.append(range)
        else:
            self.structures = [range]
    elif type(self) == Range:
        self.add_item(range)
    return range

make_service

MakeService

Source code in iiif_prezi3/helpers/make_service.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
class MakeService:
    def make_service(self, id, type, version=3, **kwargs):
        """Make a IIIF Prezi service of the desired IIIF API version and adds it to the service list.

        Args:
            id (AnyUrl): The id of the service.
            type (str): The type of the service.
            version (int): The API version of the service. Defaults to 3.
            **kwargs (): Arbitrary keyword arguments.

        Raises:
            ValueError: If an invalid IIIF API version is provided.

        Returns:
           service (Union[ServiceItem, ServiceItem1]): A service instance of the selected version.
        """
        serviceversions = {
            2: ServiceItem1,
            3: ServiceItem
        }
        if version not in serviceversions:
            raise ValueError(f"Version: {version} is not a valid IIIF API service version.")
        service = serviceversions[version](id=id, type=type, **kwargs)
        self.add_service(service)
        return service
make_service(id, type, version=3, **kwargs)

Make a IIIF Prezi service of the desired IIIF API version and adds it to the service list.

Parameters:

Name Type Description Default
id AnyUrl

The id of the service.

 required
type str

The type of the service.

 required
version int

The API version of the service. Defaults to 3.

 3
**kwargs

Arbitrary keyword arguments.

 {}

Raises:

Type Description
ValueError

If an invalid IIIF API version is provided.

Returns:

Name Type Description
service Union[ServiceItem, ServiceItem1]

A service instance of the selected version.
Source code in iiif_prezi3/helpers/make_service.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
def make_service(self, id, type, version=3, **kwargs):
    """Make a IIIF Prezi service of the desired IIIF API version and adds it to the service list.

    Args:
        id (AnyUrl): The id of the service.
        type (str): The type of the service.
        version (int): The API version of the service. Defaults to 3.
        **kwargs (): Arbitrary keyword arguments.

    Raises:
        ValueError: If an invalid IIIF API version is provided.

    Returns:
       service (Union[ServiceItem, ServiceItem1]): A service instance of the selected version.
    """
    serviceversions = {
        2: ServiceItem1,
        3: ServiceItem
    }
    if version not in serviceversions:
        raise ValueError(f"Version: {version} is not a valid IIIF API service version.")
    service = serviceversions[version](id=id, type=type, **kwargs)
    self.add_service(service)
    return service

set_hwd

SetHwd

Source code in iiif_prezi3/helpers/set_hwd.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
class SetHwd:
    def set_hwd(self, height=None, width=None, duration=None):
        """Set the height, width, and duration properties allowing nulls.

        Args:
            height (int): The height of the resource or the canvas
            width (int): The width of the resource or the canvas
            duration (float): The duration of the resource
        """
        if not (duration or height or width):
            raise TypeError("At least one of height, width, or duration must be set")
        if height and not width:
            raise TypeError("width must be set if height is set")
        if width and not height:
            raise TypeError("height must be set if width is set")
        self.height = height
        self.width = width
        self.duration = duration
set_hwd(height=None, width=None, duration=None)

Set the height, width, and duration properties allowing nulls.

Parameters:

Name Type Description Default
height int

The height of the resource or the canvas

 None
width int

The width of the resource or the canvas

 None
duration float

The duration of the resource

 None
Source code in iiif_prezi3/helpers/set_hwd.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
def set_hwd(self, height=None, width=None, duration=None):
    """Set the height, width, and duration properties allowing nulls.

    Args:
        height (int): The height of the resource or the canvas
        width (int): The width of the resource or the canvas
        duration (float): The duration of the resource
    """
    if not (duration or height or width):
        raise TypeError("At least one of height, width, or duration must be set")
    if height and not width:
        raise TypeError("width must be set if height is set")
    if width and not height:
        raise TypeError("height must be set if width is set")
    self.height = height
    self.width = width
    self.duration = duration

set_hwd_from_file

SetHeightWidthDurationFileHelper

Source code in iiif_prezi3/helpers/set_hwd_from_file.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
class SetHeightWidthDurationFileHelper:
    def set_hwd_from_file(self, file_path_or_object):
        """Introspect a file and set the height, width, and duration properties.

        Args:
            file_path_or_object (Union[str, fp]): the file path or file object to introspect
        """
        if isinstance(file_path_or_object, str) or isinstance(file_path_or_object, os.PathLike):
            filetype, _ = mimetypes.guess_type(file_path_or_object)
            if not filetype.startswith("image/"):
                raise NotImplementedError

        tmp_image = Image.open(file_path_or_object)
        w, h = tmp_image.size
        self.set_hwd(h, w, None)
        tmp_image.close()
set_hwd_from_file(file_path_or_object)

Introspect a file and set the height, width, and duration properties.

Parameters:

Name Type Description Default
file_path_or_object Union[str, fp]

the file path or file object to introspect

 required
Source code in iiif_prezi3/helpers/set_hwd_from_file.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
def set_hwd_from_file(self, file_path_or_object):
    """Introspect a file and set the height, width, and duration properties.

    Args:
        file_path_or_object (Union[str, fp]): the file path or file object to introspect
    """
    if isinstance(file_path_or_object, str) or isinstance(file_path_or_object, os.PathLike):
        filetype, _ = mimetypes.guess_type(file_path_or_object)
        if not filetype.startswith("image/"):
            raise NotImplementedError

    tmp_image = Image.open(file_path_or_object)
    w, h = tmp_image.size
    self.set_hwd(h, w, None)
    tmp_image.close()

set_hwd_from_iiif

SetHwdFromIIIF

Source code in iiif_prezi3/helpers/set_hwd_from_iiif.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
class SetHwdFromIIIF:
    # should probably be added to canvas helpers

    def set_hwd_from_iiif(self, url):
        """Set height and width on a Canvas object.

        Requests IIIF Image information remotely for an
        image resource and sets resulting height and width.
        This method will return the info.json

        Args:
            url (str): An HTTP URL for the IIIF image endpoint.
        """
        # resource url may or may not end with info.json;
        # add if not present
        if not url.endswith("info.json"):
            url = f"{ url.rstrip('/') }/info.json"

        response = requests.get(url)
        # if response is not 200, raise exception
        if response.status_code != requests.codes.ok:
            response.raise_for_status()
        # if response is not valid json, request will raise
        # requests.exceptions.JSONDecodeError
        # — handle or document and let calling code handle?
        resource_info = response.json()
        self.set_hwd(resource_info.get("height"), resource_info.get("width"))

        return resource_info
set_hwd_from_iiif(url)

Set height and width on a Canvas object.

Requests IIIF Image information remotely for an image resource and sets resulting height and width. This method will return the info.json

Parameters:

Name Type Description Default
url str

An HTTP URL for the IIIF image endpoint.

 required
Source code in iiif_prezi3/helpers/set_hwd_from_iiif.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
def set_hwd_from_iiif(self, url):
    """Set height and width on a Canvas object.

    Requests IIIF Image information remotely for an
    image resource and sets resulting height and width.
    This method will return the info.json

    Args:
        url (str): An HTTP URL for the IIIF image endpoint.
    """
    # resource url may or may not end with info.json;
    # add if not present
    if not url.endswith("info.json"):
        url = f"{ url.rstrip('/') }/info.json"

    response = requests.get(url)
    # if response is not 200, raise exception
    if response.status_code != requests.codes.ok:
        response.raise_for_status()
    # if response is not valid json, request will raise
    # requests.exceptions.JSONDecodeError
    # — handle or document and let calling code handle?
    resource_info = response.json()
    self.set_hwd(resource_info.get("height"), resource_info.get("width"))

    return resource_info

to_reference

ToReference

Source code in iiif_prezi3/helpers/to_reference.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class ToReference:

    def to_reference(self):
        """Returns a Reference object that points to the calling object."""
        # Only try to set thumbnail if it's a Class that can have one
        if isinstance(self, (Collection, Manifest, Canvas, AnnotationPage, Annotation, AnnotationCollection, Range)):
            thumbnail = self.thumbnail
        else:
            thumbnail = None

        # Currently the skeleton Reference requires a label, but some Referenceable objects may not have one (e.g AnnotationPage)
        # TODO: Remove this when the Schema is updated to have different reference types
        if not self.label:
            self.label = ""

        # Ensure that we use a specific Reference type if it exists
        if isinstance(self, Manifest):
            target_type = ManifestRef
        elif isinstance(self, Collection):
            target_type = CollectionRef
        elif isinstance(self, Canvas):
            target_type = CanvasRef
        elif isinstance(self, Range):
            target_type = RangeRef
        else:
            target_type = Reference

        return target_type(id=self.id, label=self.label, type=self.type, thumbnail=thumbnail)
to_reference()

Returns a Reference object that points to the calling object.

Source code in iiif_prezi3/helpers/to_reference.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def to_reference(self):
    """Returns a Reference object that points to the calling object."""
    # Only try to set thumbnail if it's a Class that can have one
    if isinstance(self, (Collection, Manifest, Canvas, AnnotationPage, Annotation, AnnotationCollection, Range)):
        thumbnail = self.thumbnail
    else:
        thumbnail = None

    # Currently the skeleton Reference requires a label, but some Referenceable objects may not have one (e.g AnnotationPage)
    # TODO: Remove this when the Schema is updated to have different reference types
    if not self.label:
        self.label = ""

    # Ensure that we use a specific Reference type if it exists
    if isinstance(self, Manifest):
        target_type = ManifestRef
    elif isinstance(self, Collection):
        target_type = CollectionRef
    elif isinstance(self, Canvas):
        target_type = CanvasRef
    elif isinstance(self, Range):
        target_type = RangeRef
    else:
        target_type = Reference

    return target_type(id=self.id, label=self.label, type=self.type, thumbnail=thumbnail)