Description

Retrieve the info.json for a resource, and add height, width, and duration properties to a Canvas or Content Resource object, allowing nulls

Function name / Parameters / Return

Function name: .set_hwd_from_iiif(url)

Parameters: url - the IIIF Image API URL for the resource

Returns: None

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

This will introduce a new dependency for retrieving the info.json file, probably requests. Please discuss before adding.

The URL provided by the user might already be the full path to the info.json file, so the helper should check this and not add it if unnecessary,

For Canvas objects, if height is present, then width must also be set, and vice-versa (https://iiif.io/api/presentation/3.0/#height / https://iiif.io/api/presentation/3.0/#width), Therefore the helper must be type aware, and raise an error if one is set without the other when the target is a Canvas object

Since this helper will be making a request to an external HTTP(S) resource, it should be prepared to gracefully handle errors and 404s etc, raising them to the main library as appropriate.

I've been looking at language strings particularly with labels e.g.:

manifest = Manifest(id='http://iiif.example.org/prezi/Manifest/0', type='Manifest', label={'en': 'label'})

print (manifest.label)

The problem is the label is empty. This is due to the LngString class in the skeleton only containing pass.

The relevant part of the schema is:

"lngString": {
      "title": "Language string, must have a language and value must be an array.",
      "type": "object",
      "patternProperties": {
                "^[a-zA-Z-][a-zA-Z-]*$": {
               "type": "array",
               "items": { "type": "string"}
            },
            "^none$": {
                "type": "array",
                "items": { "type": "string"}
            }
      },
     "additionalProperties": false
},

from IIIF Schema#L11 and it seems pydantic is struggling with patternProperties and how to convert them into python.

Relevant discussions on pydantics:

• JSON Schema patternProperties with Pydantic
• Support for dynamic fields equivalent to patternProperties in JSON Schema

Example lngStrings include:

# single language:
{
   'en': 'label'
}

# multiple languages: 
{
   'en': 'label',
   'cy': 'Welsh Label'
}

See #64 (comment)

Write a wrapper python script that generates the skeleton file using datamodel-codegen and then applies any necessary changes,

Changes so far:

• LngString fix
• Rename _id and _type to id and type in ServiceItem1

https://packaging.python.org/en/latest/guides/making-a-pypi-friendly-readme/

from setuptools import setup

# read the contents of your README file
from pathlib import Path
this_directory = Path(__file__).parent
long_description = (this_directory / "README.md").read_text()

setup(
    name='an_example_package',
    # other arguments omitted
    long_description=long_description,
    long_description_content_type='text/markdown'
)

We need easy ways to pass languages to things like labels and metadata

Add some validation, this may require changing the schema:

https://github.com/IIIF/presentation-validator/blob/183a373d89bc203f2b77b94fa43c1f890792a7ef/schema/iiif_3_0.json#L15

Seems that the construction of the LngString class did not produce the expected output.

from iiif_prezi3 import Manifest
man = Manifest(id="https://test.com",type="Manifest",label={"en": [ "A test" ]})
man.json(exclude_unset=True)

Description

Set the height, width, and duration properties of a Canvas or Content Resource object, allowing nulls

Function name / Parameters / Return

Function name: .set_hwd(height, width, duration)

Parameters:

• height - the height value for the object
• width - the width value for the object
• duration - the duration value for the object

Returns: None

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

For Canvas objects, if height is present, then width must also be set, and vice-versa (https://iiif.io/api/presentation/3.0/#height / https://iiif.io/api/presentation/3.0/#width), Therefore the helper must be type aware, and raise an error if one is set without the other when the target is a Canvas object

This is the warning I've seen in other projects when running python setup.py test:

WARNING: Testing via this command is deprecated and will be removed in a future version. Users looking for a generic test entry point independent of test runner are encouraged to use tox.

We need an easy way to create URIs for objects like Manifests and Canvases

• Config has default ID generation method
• It makes ID optional if supplied it is override otherwise it creates a default.
• Set base_uri

Our setup.py says that the library supports python2, but we don't actually test against it.

We should either add testing for Py2 or decide to support Py3 only and update setup,py accordingly

Description

It adds an accompanying canvas to a IIIF object.

Function name / Parameters / Return

Function name: .set_accompanying_canvas()

Parameters: canvas

Returns: canvas object

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

Note that in the description is written that the object is a special Canvas that:

The object must not have the placeholderCanvas property, nor the accompanyingCanvas property.

But below is also written:

*A Canvas that is the value of a placeholderCanvas or accompanyingCanvas property may not have either of those properties itself.

In case the first is the recommendation true we should create a Canvas class that does not have this method.

E.g the library version did not update, and it says the tests are failing.

If you look at the images, they are being served from camo.githubusercontent.com and not from the actual source of the images.

Potential fix: https://stackoverflow.com/a/66030456

Description

This helper will add an existing Annotation to the object's annotations key

Function name / Parameters / Return

Function name: .add_annotation(annotation)

Parameters: annotation - the Prezi3 Annotation object to be added

Returns: None

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

Annotations must exist within an AnnotationPage object, so the helper must create and add one if one is not already present. Otherwise the Annotation should be added to the first existing AnnotationPage

I open an issue to keep it tracked.
It seems that duration is forced to be a string while as @azaroth42 said it should be a float.

from iiif_prezi3 import Canvas
acanvas = Canvas(id=canvasid, type='Canvas', label={'en': ['default lab']})
duration = 300.23
acanvas.duration = duration
acanvas.duration == duration

Description

This helper takes a reference to an appropriate object (e.g for a Collection, it would accept a Collection or a Manifest) and adds it to the end of the items property

Function name / Parameters / Return

Function name: .add_item(item)

Parameters: item - the Prezi3 objetc to be added

Returns: None

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

Different objects will have different acceptable inputs (i.e you can't add a Manifest to a Canvas object's items), so this should be validated by the helper code.

Description

This helper will create a new Manifest object, add it by reference to the items property, and return it

Function name / Parameters / Return

Function name: make_manifest()

Parameters: None

Returns: A Manifest object

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

Manifests must not be embedded inline in a Collection (https://iiif.io/api/presentation/3.0/#51-collection) and therefore this helper must also create a ManifestReference and add that to the items property of the Collection object calling this helper.

We need helper methods to add canvases to a manifest handling creation of the items array if missing.

The default output includes every possible property with a null value if it is not set.

The presentation spec does not even acknowledge the existence of null (for JSON-LD reasons) and the pattern is to simply omit them.

.json() should be wrapped to strip out null values throughout the resulting structure.

e.g.

m = Manifest(label="Test Manifest")
c = Canvas()
m.items = [c]
m.json()
'{"id": "http://example.org/iiif/3", "type": "Manifest", "label": {"en": ["Test Manifest"]}, "metadata": null, "summary": null, "requiredStatement": null, "rendering": null, "service": null, "services": null, "viewingDirection": null, "rights": null, "start": null, "logo": null, "navDate": null, "provider": null, "seeAlso": null, "thumbnail": null, "homepage": null, "behavior": null, "partOf": null, "items": [{"id": "http://example.org/iiif/4", "type": "Canvas", "label": null, "height": null, "width": null, "duration": null, "metadata": null, "summary": null, "requiredStatement": null, "rights": null, "navDate": null, "provider": null, "seeAlso": null, "thumbnail": null, "homepage": null, "behavior": null, "partOf": null, "items": null, "annotations": null}], "structures": null, "annotations": null}'

Should instead just be

'{"id": "http://example.org/iiif/3", "type": "Manifest", "label": {"en": ["Test Manifest"]},  "items": [{"id": "http://example.org/iiif/4", "type": "Canvas"}]}'

Tox has started showing a deprecation warning for part of pydantic:

./home/mike/projects/iiif-prezi3/iiif_prezi3/base.py:35: DeprecationWarning: copy_on_model_validation should be a string: 'deep', 'shallow' or 'none'

However, changing this value to any from the list caused test failures. It turns out tox is installing the requirements each run in a temporary virtual environment, and thus was installing a newer version of Pydantic than my local virtualenv.

This leads to test inconsistencies etc and I think is best resolved by pinning dependency versions in setup.py

The documentation e.g. https://github.com/iiif-prezi/iiif-prezi3/blob/main/docs/getting-started-using-iiifprezi3-without-helpermethods.md uses label={'en': 'default label'} but that doesn't work. It should be label={'en': ['default label']}

Description

This helper will create a Canvas object, add it to the items property (by calling the add_item helper (#37)), and return it

Function name / Parameters / Return

Function name: .make_canvas()

Parameters: None

Returns: A Canvas object

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

Description

This helper will create a new Collection object, add it to the items property (by calling the add_item helper (#37)), and return the new object

Function name / Parameters / Return

Function name: .make_collection()

Parameters: None

Returns: a Collection object

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

We use a list to filter the kwargs into those that need to go to Pydantic, and those that need to go to the json module:
https://github.com/iiif-prezi/iiif-prezi3/blob/main/iiif_prezi3/base.py#L55-L57

        pydantic_args = ["include", "exclude", "by_alias", "encoder"]
        dict_kwargs = dict([(arg, kwargs[arg]) for arg in kwargs.keys() if arg in pydantic_args])
        json_kwargs = dict([(arg, kwargs[arg]) for arg in kwargs.keys() if arg not in pydantic_args])

This was fine when we were passing through all valid Pydantic options, but now that we explicitly set exclude_unset, exclude_defaults etc, they have been removed from the list used for filtering.

This means that they now get included on the json_kwargs list instead and thus get passed through to the underlying json.dumps call, causing an error if they are supplied:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/mike/projects/iiif-prezi3/iiif_prezi3/base.py", line 56, in jsonld
    dict_kwargs = dict([(arg, kwargs[arg]) for arg in kwargs.keys() if arg in pydantic_args])
  File "/usr/lib/python3.8/json/__init__.py", line 234, in dumps
    return cls(
TypeError: __init__() got an unexpected keyword argument 'exclude_unset'

This is easily solved by having an "excluded kwargs" list and ignoring anything on that list.

In order to have a Manifest in a Collection, the Collection should have a Reference to the Manifest, not the full Manifest resource.
This works as expected, hooray!

But ... if the referenced resource is modified, such as to change its label, then the Reference isn't updated.

e.g.

m = Manifest(label="1")
c = Collection()
c.items = [m]
m.label = {"en": ["2"]}
print(c.items[0].label) # --> 1
print(m.label) # --> 2

Populate Image resource with info from either a file or IIIF info.json:

https://github.com/iiif-prezi/iiif-prezi/blob/e5956d5ab929ff8149a6429c6145790bb4bd59e5/iiif_prezi/factory_11.py#L822

Would require PIL if we are going to open images.

Description

This helper adds an existing Range object to the structures key

Function name / Parameters / Return

Function name: .add_range(range)

Parameters: range - The Range object to be added

Returns: None

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

Discussed in meeting on the 25th of Feb. To help new users of library we should have code documentation. We should add a check to the CI.

@helrond to look at different options for python linters.

We can also look at configuring the data generator to add documentation from the JSON schema into the python files. We may need to add labels to the schema.

We need CI to do:

• Run tests on pull requests
• Create deployment to pip on tag creation
• Need to improve the documentation on pypi

Relates to: #9

Description

This helper adds key/value pairs to the metadata property of a Prezi3 object

Function name / Parameters / Return

Function name: .add_metadata(label, value)

Parameters:

• label - the key to be added the metadata property
• value - the value(s) for the key, either a string or an array of strings

Returns: None

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

Found by @p-galligan when testing the library. Example:

manifest = Manifest(id='http://iiif.example.org/prezi/Manifest/0', type='Manifest', label={'en': ['default label']})
        
canvas = Canvas(id='http://iiif.example.org/prezi/Canvas/0')
canvas.height = 100
canvas.width = 200

canvas2 = Canvas(id='http://iiif.example.org/prezi/Canvas/1')
canvas2.height = 100
canvas2.width = 100

manifest.items = [canvas, canvas2]

data =  json.loads(manifest.json(exclude_unset=True))
print (json.dumps(data, indent=4))

Which gives the following JSON:

{
    "id": "http://iiif.example.org/prezi/Manifest/0",
    "type": "Manifest",
    "label": {},
    "items": [
        {
            "id": "http://iiif.example.org/prezi/Canvas/0",
            "height": 100,
            "width": 200
        },
        {
            "id": "http://iiif.example.org/prezi/Canvas/1",
            "height": 100,
            "width": 100
        }
    ]
}

which is missing the @context (and label which is related to #23)

Description

This helper adds a new label to the language map of an existing object

Function name / Parameters / Return

Function name: .add_label(language, value)

Parameters:

• language - the language code of the new label
• value - the label string in that language

Returns: None

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

The helper should check if the object has a label property set, and either create a new dictionary with the the parameters as the first entry, or append to the existing dictionary

Currently the library works when you do a git clone but if you've installed it from pypi the directories will be different.

Description

This helper adds an existing Service object to the service key, creating the key if it does not exist

Function name / Parameters / Return

Function name: .add_service(service)

Parameters: service - The Service object to be added

Returns: None

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

This helper is designed to target the service key of an individual object, and does not cover the services object that can additionally exist on a Collection or Manifest object

Description

This helper creates a new Range object, adds it to structures or items as appropriate (via the add_range (#44) or add_item (#37) helpers), and returns it

Function name / Parameters / Return

Function name: .make_range()

Parameters: None

Returns: A Range object

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

The helper must be type-aware - Ranges can be added to Manifests, where they live in the structures property, or as part of other Ranges, where they live in the items property.

We need to have a way to do unit tests. I've made a start here:

https://github.com/iiif-prezi/iiif-prezi3/tree/main/tests

Like setting the id and label.

See the testNewManifest method:

from iiif_prezi3 import Collection
col = Collection(id="https://test.com")

result in :

ValidationError: 1 validation error for Collection
type
  field required (type=value_error.missing)

Which is correct but requires the user to set the type of object which by default should have the type assigned.
For instance, a Manifest has always type equal to Manifest the same for collection and many other types.

This issue could be solved using the default keyword of JSON shema and then generating the class model using --use-default flag:

datamodel-codegen --input ../generatecodefromschema/iiif_3_0.json --input-file-type jsonschema --use-default --base-class .base.Base --output skeleton.py

Description

This helper will create an Annotation and add it to the object's annotations key (via the add_annotation (#40) helper), and returns it.

Function name / Parameters / Return

Function name: .make_annotation()

Parameters: None

Returns: An Annotation object

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

Annotations must exist within an AnnotationPage object, so the helper must create and add one if one is not already present. Otherwise the Annotation should be added to the first existing AnnotationPage

When I try to import iiif_prezi3 I get the error:

ModuleNotFoundError: No module named 'iiif_prezi3.helpers'

Python 3.9.9 on macOS 12.1 (M1)

Description

This helper creates a new Service object, adds it to service (via the add_service (#57) helper), and returns it

Function name / Parameters / Return

Function name: .make_service()

Parameters: None

Returns: A Service object

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

The following warning showed up in the logs for the last action that made a release to PyPi:

Warning: You are using "pypa/gh-action-pypi-publish@master". The "master" branch of this project has been sunset and will not receive any updates, not even security bug fixes. Please, make sure to use a supported version. If you want to pin to v1 major version, use "pypa/gh-action-pypi-publish@release/v1". If you feel adventurous, you may opt to use use "pypa/gh-action-pypi-publish@unstable/v1" instead. A more general recommendation is to pin to exact tags or commit shas.

Description

It adds a placeholder canvas to a IIIF object.

Function name / Parameters / Return

Function name: .set_placeholder_canvas()

Parameters: canvas

Returns: canvas object

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

Note that in the description is written that the object is a special Canvas that:

The object must not have the placeholderCanvas property, nor the accompanyingCanvas property.

But below is also written:

*A Canvas that is the value of a placeholderCanvas or accompanyingCanvas property may not have either of those properties itself.

In case the first is the recommendation true we should create a Canvas class that does not have this method.

Would be nice to have developer docs for people getting started with contributing.

For my local setup, I initially ran:

pip install -e .
pip install tox

but later figured out I should maybe have installed from requirements.dev.txt

Also worth documenting that doc strings should follow google format

Description

Introspect a file and set the height, width, and duration properties of a Canvas or Content Resource object, allowing nulls

Function name / Parameters / Return

Function name: .set_hwd_from_file(file)

Parameters: file - the file path or file object to introspect

Returns: None

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations

The helper should be able to work with either a file path or an already open file object, so type checking on the parameter will be required.
This helper will introduce new dependencies - probably Pillow for Images and ??? for Audio and Video resources. Please discuss in the ticket or Slack before adding.

For Canvas objects, if height is present, then width must also be set, and vice-versa (https://iiif.io/api/presentation/3.0/#height / https://iiif.io/api/presentation/3.0/#width), Therefore the helper must be type aware, and raise an error if one is set without the other when the target is a Canvas object

Description

This helper takes a Manifest and returns a Reference that points to it

Function name / Parameters / Return

Function name: .get_reference()

Parameters: None

Returns: A Reference object

Objects

• Base Object (all Prezi3 Classes)
• Collection
• Manifest
• Canvas
• Range
• AnnotationCollection
• AnnotationPage
• Annotation
• Content Resource - Image
• Content Resource - Video
• Content Resource - Text
• Service
• Provider
• Other - please list below

Considerations