Upload Subject Attached Media

[yuenmichelle1]

Upload Subject attached media/ attached images/ancillary data for existing subjects

Example usages:

Without parallelism and multiple threads

subject = Subject(1234)
local_files = [...]

for file_location in local_files: 
  future_result = subject.save_attached_image(file_location)
  try:
    future_result.result()
  except Exception e:
    print(f"Upload failed for {file_location}")
    print(e)
   

Utilizing parallelism

from concurrent.futures import as_completed

subject = Subject(1234)
local_files = [...]

with Subject.async_saves():
    future_to_file = {subject.save_attached_image(file_location): file_location for file_location in local_files}
    for future in as_completed(future_to_file):
        local_file = future_to_file[future]
        try:
            future.result()
        except Exception as exc:
            print(f"Upload failed for {local_file}")

[yuenmichelle1]

@lcjohnso this is ready for review. Do you mind reading through the doc strings and examples to make sure wording makes sense?

Bonus: if you can run the examples and see what extra info is needed that I did not include in docs.

Maybe worth pinging @astrohayley after an initial run through from Cliff.

[lcjohnso]

I suggest a number of docs edits, and I have questions about how users are meant to use the new functions. It appears save_attached_image() is the primary interface, but the availability of add_attached_image() clouds this assumption.

[lcjohnso]

Please add in-line comments (with # mark)

[PmasonFF]

At one point you are stating:

 - **attached_media** can be an open :py:class:`file` object, a path to a
+          local file, or a :py:class:`dict` containing MIME types and URLs for
+          remote media.

This is no longer quite correct if the user has not installed libmagic and mime type detection is being handled by mimetypes - mimetypes does not handle all types of :py:class:file object, specifically BytesIO() file objects work with libmagic but not mimetypes.... This means one can no longer process an image (compress or crop, add captions etc) in memory and add the BytesIO() object as a attached image or location.

[lcjohnso]

This is no longer quite correct if the user has not installed libmagic and mime type detection is being handled by mimetypes - mimetypes does not handle all types of :py:class:file object, specifically BytesIO() file objects work with libmagic but not mimetypes.... This means one can no longer process an image (compress or crop, add captions etc) in memory and add the BytesIO() object as a attached image or location.

Hi @PmasonFF -- For the case where libmagic is not installed/available and the user wants to pass a BytesIO object, one can override and avoid any form of type sensing by using the manual_mimetype parameter.