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. |
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.
Note
Some elements (e.g. a paper's or volume's own <pdf> element) carry no name at all, only a checksum -- the name is instead derived from the full_id of the object the file belongs to. In that case, this returns a reference with an empty placeholder name that callers are expected to replace (e.g. via attrs.evolve) before use.
Classes for representing and resolving file references.
AttachmentReference ¶
PDFReference ¶
PDFThumbnailReference ¶
URLReference ¶
Bases: FileReference
Reference to an external URL, e.g. for supplementary materials hosted elsewhere.
Used for <url> elements, which -- unlike PDFReference and its siblings -- carry no checksum and are (almost always) not locally hosted. An optional type attribute distinguishing multiple <url> elements (e.g. "video", "website") is not stored on this class; callers are expected to track it alongside the reference, e.g. as tuple[str, URLReference] (see validate_url_tuple).
VideoReference ¶
compute_checksum ¶
compute_checksum(value)
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. |
validate_url_tuple ¶
validate_url_tuple(instance, attribute, value)
Validator for tuple[tuple[str, URLReference], ...]-shaped attrs fields.
Intended to be used as the member_validator of a v.deep_iterable validator, e.g. for Paper.urls and Volume.urls. Since <url> elements are, by construction, never locally hosted (unlike <pdf>), this also rejects a local URLReference.