ged2doc.utils

Various utility methods.

Functions

embed_ref(xref_id, name)	Returns encoded person reference.
img_mime_type(img)	Returns image MIME type or None.
img_resize(img, size)	Resize image to fit given size.
img_save(img, file)	Save image into output file.
languages()	Returns list of supported languages.
person_image_file(person)	Finds primary person image file name.
resize(size, max_size[, reduce_only])	Resize a box so that it fits into other box and keeps aspect ratio.
split_refs(text)	Split text with embedded references into a sequence of text and references.
system_lang()	Try to guess system language.

ged2doc.utils.resize(size, max_size, reduce_only=True)

Resize a box so that it fits into other box and keeps aspect ratio.

Parameters

sizetuple

Box to resize, (width, height). Elements of tuple are either numbers or ged2doc.size.Size instances.

max_sizetuple

Box to fit new resized box into, (width, height).

reduce_onlybool

If True (default) and size is smaller than max_size then return original box.

Returns

width, height

Tuple (width, height) representing resized box. Type of the elements is the same as the type of the size elements.

ged2doc.utils.person_image_file(person)

Finds primary person image file name.

Scans INDI’s OBJE records and finds “best” FILE record from those.

Parameters

personged4py.model.Individual

INDI record representation.

Returns

file_namestr or None

String with file name or None.

Notes

OBJE record contains one (in 5.5) or few (in 5.5.1) related multimedia files. In 5.5 file contents can be embedded as BLOB record though we do not support this. In 5.5.1 file name is stored in a record.

In 5.5.1 OBJE record is supposed to have structure:

OBJE
  +1 FILE <MULTIMEDIA_FILE_REFN>    {1:M}
    +2 FORM <MULTIMEDIA_FORMAT>     {1:1}
        +3 MEDI <SOURCE_MEDIA_TYPE> {0:1}
  +1 TITL <DESCRIPTIVE_TITLE>       {0:1}
  +1 _PRIM {Y|N}                    {0:1}

Some applications which claim to be 5.5.1 version still store OBJE record in 5.5-like format:

OBJE
  +1 FILE <MULTIMEDIA_FILE_REFN>    {1:1}
  +1 FORM <MULTIMEDIA_FORMAT>       {1:1}
  +1 TITL <DESCRIPTIVE_TITLE>       {0:1}
  +1 _PRIM {Y|N}                    {0:1}

This method returns the name of the FILE corresponding to _PRIM=Y, or if there is no _PRIM record then the first FILE record. Potentially we also need to look at MEDI record to only chose image type, but I have not seen examples of MEDI use yet, so for now I only select FORM which correspond to images.

ged2doc.utils.languages()

Returns list of supported languages.

This should correspond to the existing translations and needs to be updated when new translation is added.

Returns

languageslist [ str ]

ged2doc.utils.system_lang()

Try to guess system language.

Returns

languagestr

Guessed system language, “en” is returned as a fallback.

ged2doc.utils.embed_ref(xref_id, name)

Returns encoded person reference.

Encoded reference consists of ASCII character SOH (0x01) followed by reference ID, STX (0x02), person name, and ETX (0x03).

Parameters

xref_idstr

Reference ID for a person.

namestr

Person name.

ged2doc.utils.split_refs(text)

Split text with embedded references into a sequence of text and references.

Reference is returned as tuple (id, name).

Yields

itemstr or tuple

Pieces of text and references.

ged2doc.utils.img_mime_type(img)

Returns image MIME type or None.

Parameters

img: `PIL.Image`

PIL Image object.

Returns

mime_typestr

MIME string like “image/jpg” or None.

ged2doc.utils.img_resize(img, size)

Resize image to fit given size.

Image is resized only if it is larger than size, otherwise unmodified image is returned.

Parameters

imgPIL.Image

PIL Image object.

sizetuple

Final image size (width, height)

Returns

imagePIL.Image

Resized image.

ged2doc.utils.img_save(img, file)

Save image into output file.

This method automatically chooses the best file format for output.

Parameters

imgPIL.Image

PIL Image object.

file

File object to write output to.

Returns

mime_typestr

MIME type of the output image.