files

Classes for representing and resolving file references.

FileReference

Base class for all references to local or remote files in the XML data.

Do not instantiate directly; use the sub-classes instead.

Attributes:

Name	Type	Description
content_type	Optional[str]	The expected content type of the file. Set by some sub-classes.
template_field	str	The URL formatting template to use. Set by the sub-classes.
name	str	The file reference (as found in the XML), typically a URL or an internal filename.
checksum	Optional[str]	The CRC32 checksum for the file. Only specified for internal filenames.

is_local property

is_local

Whether this is a local filename.

url property

url

The URL at which this file can be accessed.

download

download(filename, timeout=10)

Download this file from its remote URL.

Parameters:

Name	Type	Description	Default
filename	StrPath	The path to the local file to write to.	required
timeout	float	The timeout in seconds for the GET request.	10

Note

If filename already exists and has the expected checksum for this file, this function will do nothing. Otherwise, this will attempt to (re)download the file, and filename will get overwritten.

Raises:

Type	Description
ChecksumMismatchWarning	If the downloaded file's checksum doesn't match the expected one.
ValueError	If the response does not have the expected Content-Type (e.g. application/pdf for PDFs).

from_file classmethod

from_file(filename)

Instantiate a new file reference from a file.

This automatically computes the checksum for the file and determines its name.

The name of the returned reference will depend on the configured template string; for example, if this function is called on the PDFReference class and given a filename ending in ".pdf", and config.pdf_location_template ends in ".pdf", this means the filename should and will be stored without the ".pdf" suffix.

Parameters:

Name	Type	Description	Default
filename	StrPath	The path to the file.	required

Returns:

Type	Description
Self	A file reference for the given file.

Raises:

Type	Description
FileNotFoundError	If filename does not point to an existing file.

from_xml classmethod

from_xml(elem)

Instantiate a new file reference from a corresponding XML element.

to_xml

to_xml(tag='url')

Parameters:

Name	Type	Description	Default
tag	str	Name of outer tag in which this file reference should be wrapped. Defaults to "url".	'url'

Returns:

Type	Description
_Element	A serialization of this file reference in Anthology XML format.

Classes for representing and resolving file references.

AttachmentReference

Bases: FileReference

Reference to an attachment.

EventFileReference

Bases: FileReference

Reference to an event-related file.

PDFReference

Bases: FileReference

Reference to a PDF file.

PDFThumbnailReference

Bases: FileReference

Reference to a PDF thumbnail image.

VideoReference

Bases: FileReference

Reference to a video.

compute_checksum

compute_checksum(value)

Compute the checksum of a byte string.

Parameters:

Name	Type	Description	Default
value	bytes	Any byte string.	required

Returns:

Type	Description
str	The checksum of the byte string as an eight-character, hex-formatted string.

compute_checksum_from_file

compute_checksum_from_file(path)

Compute the checksum of a file.

Parameters:

Name	Type	Description	Default
path	StrPath	The path to a file.	required

Returns:

Type	Description
str	The checksum of the file's contents.