Public API¶

Models¶

Match-able & Hydrate-able Models¶

class digitalarchive.models.Document(id, uri, title, description, doc_date, frontend_doc_date, slug, source_created_at, source_updated_at, first_published_at, source, type, rights, pdf_generated_at, date_range_start, sort_string_by_coverage, main_src, model, donors, subjects, transcripts, translations, media_files, languages, contributors, creators, original_coverages, collections, attachments, links, repositories, publishers, classifications)¶

A Document corresponding to a single record page on digitalarchive.wilsoncenter.org.

Note

Avoid constructing Documents directly–use the match function to create Documents by keyword search or by ID.

Attributes present on all Documents:

id¶

The ID# of the record in the DA.

Type:	str

title¶

The title of a document.

Type:	str

description¶

A one-sentence description of the document’s content.

Type:	str

doc_date¶

The date of the document’s creation in YYYYMMDD format.

Type:	str

frontend_doc_date¶

How the date appears when presented on the DA website.

Type:	str

slug¶

A url-friendly name for the document. Not currently used.

Type:	str

source_created_at¶

Timestamp of when the Document was first added to the DA.

Type:	`datetime.datetime`

source_updated_at¶

Timestamp of when the Document was last edited.

Type:	`datetime.datetime`

first_published_at¶

Timestamp of when the document was first made publically accessible.

Type:	`datetime.datetime`

Attributes present only on hydrated Documents

These attributes are aliases of UnhydratedField until Document.hydrate() is called on the Document.

source¶

The archive where the document was retrieved from.

Type:	str

type¶

The type of the document (meeting minutes, report, etc.)

Type:	`digitalarchive.models.Type`

rights¶

A list of entities holding the copyright of the Document.

Type:	`list` of `digitalarchive.models.Right`

pdf_generated_at¶

The date that the combined source, translations, and transcriptions PDF. was generated.

Type:	str

date_range_start¶

A rounded-down date used to standardize approximate dates for date-range matching.

Type:	`datetime.date`

sort_string_by_coverage¶

An alphanumeric identifier used by the API to sort search results.

Type:	str

main_src¶

The original Source that a Document was retrieved from.

Type:	str

model¶

The model of a record, used to differentiate collections and keywords in searches.

Type:	str

donors¶

A list of donors whose funding make the acquisiton or translation of a document possible.

Type:	`list` of `digitalarchive.models.Donor`

subjects¶

A list of subjects that the document is tagged with.

Type:	`list` of `digitalarchive.models.Subject`

transcripts¶

A list of transcripts of the document’s contents.

Type:	`list` of `digitalarchive.models.Transcript`

translations¶

A list of translations of the original document.

Type:	`list` of `digitalarchive.models.Translation`

media_files¶

A list of attached original scans of the document.

Type:	`list` of `digitalarchive.models.MediaFile`

languages¶

A list of langauges contained in the document.

Type:	`list` of `digitalarchive.models.Language`

creators¶

A list of persons who authored the document.

Type:	`list` of `digitalarhive.models.Creator`

original_coverages¶

A list of geographic locations referenced in the document.

Type:	`list` of `digitalarchive.models.Coverage`

collections¶

A list of Collections that contain this document.

Type:	`list` of `digitalarchive.models.Collection`

attachments¶

A list of Documents that were attached to the Document.

Type:	`list` of `digitalarchive.models.Document`

links¶

A list of topically related documents.

Type:	`list` of `digitalarchive.models.Document`

respositories¶

A list of archives/libraries containing this document.

Type:	`list` of `digitalarchive.models.Repository`

publishers¶

A list of Publishers that released the document.

Type:	`list` of `digitalarchive.models.Publisher`

classifications¶

A list of security classification markings present on the document.

Type:	`list` of `digitalarchive.models.Publisher`

hydrate(recurse: bool = False)¶

Downloads the complete version of the Document with metadata for any related objects.

Parameters:	recurse (bool) – If true, also hydrate subordinate and related records.

classmethod match(**kwargs) → digitalarchive.matching.ResourceMatcher¶

Search for a Document by keyword, or fetch one by ID.

Matching on the Document model runs a full-text search using keywords passed via the title and description keywords. Results can also be limited by dates or by related records, as described below.

Note

Title and description keywords are not searched for individually. All non-date or child record searches are concatenated to single querystring.

Note

Collection and other related record searches use INNER JOIN logic when passed multiple related resources.

Allowed search fields:

Parameters:

title (str, optional) – Title search keywords.
description (str, optional) – Title search keywords.
start_date (datetime.date, optional) – Return only Documents with a doc_date after the passed start_date.
end_date (datetime.date, optional) – Return only Documents with a doc_date before the passed end_date.
collections (list of digitalarchive.models.Collection, optional) – Restrict results to Documents contained in all of the passed Collections.
publishers (list of digitalarchive.models.Publisher, optional) – Restrict results to Documents published by all of the passed Publishers.
repositories (list of digitalarchive.models.Repository, optional) – Documents contained in all of the passed Repositories.
coverages (list of digitalarchive.models.Coverage, optional) – relating to all of the passed geographical Coverages.
subjects (list of digitalarchive.models.Subject) – all of the passed subjects
contributors (list of :class:`digitalarchive.models.Contributor) – authors include all of the passed contributors.
donors (list(digitalarchive.models.Donor)) – translated with support from all of the passed donors.
languages (digitalarchive.models.Language or str) – original document. If passing a string, you must pass an ISO 639-2/B language code.
translation (digitalarchive.models.Translation) – is a translation available in the passed Language.
theme (digitalarchive.models.Theme) –

Returns:

An instance of (digitalarchive.matching.ResourceMatcher) containing any records responsive to the: search.

class digitalarchive.models.Collection(id, name, slug, uri, parent, model, value, description, short_description, main_src, no_of_documents, is_inactive, source_created_at, source_updated_at, first_published_at)¶

A collection of Documents on a single topic

name¶

The title of the collection.

Type:	str

slug¶

A url-friendly name of the collection.

Type:	str

uri¶

The URI of the record on the DA API.

Type:	str

parent¶

A Collection containing the Collection.

Type:	`digitalarchive.models.Collection`

model¶

A sting name of the model used to differentiate Collection and Document searches in the DA API.

Type:	str

value¶

A string identical to the title field.

Type:	str

description¶

A 1-2 sentence description of the Collection’s content.

Type:	str

short_description¶

A short description that appears in search views.

Type:	str

main_src¶

Placeholder

Type:	str

no_of_documents¶

The count of documents contained in the collection.

Type:	str

is_inactive¶

Whether the collection is displayed in the collections list.

Type:	str

source_created_at¶

Timestamp of when the Document was first added to the DA.

Type:	`datetime.datetime`

source_updated_at¶

Timestamp of when the Document was last edited.

Type:	`datetime.datetime`

first_published_at¶

Timestamp of when the document was first made publically accessible.

Type:	`datetime.datetime`

hydrate()¶: Populate all unhydrated fields of a resource.

classmethod match(**kwargs) → digitalarchive.matching.ResourceMatcher¶: Find a resource using passed keyword arguments.

Note

If called without arguments, returns all records in the DA .

class digitalarchive.models.Subject(id, name, uri, value)¶

A historical topic to which documents can be related.

id¶

The ID of the record.

Type:	str

name¶

The name of the subject.

Type:	str

value¶

An alias for name.

Type:	str

uri¶

The URI for the Subject in the API.

Type:	str

hydrate()¶: Populate all unhydrated fields of a resource.

classmethod match(**kwargs) → digitalarchive.matching.ResourceMatcher¶: Find a resource using passed keyword arguments.

Note

If called without arguments, returns all records in the DA .

class digitalarchive.models.Coverage(id, name, uri, value, parent, children)¶

A geographical area referenced by a Document.

id¶

The ID# of the geographic Coverage.

Type:	str

name¶

The name of geographic coverage area.

Type:	str

value¶

An alias to name.

Type:	str

uri¶

URI to the Coverage’s metadata on the DA API.

Type:	str

parent¶

The parent coverage, if any

Type:	`Coverage`

children¶: (list of Covereage): Subordinate geographical areas, if any.

hydrate()¶: Populate all unhydrated fields of a resource.

classmethod match(**kwargs) → digitalarchive.matching.ResourceMatcher¶: Find a resource using passed keyword arguments.

Note

If called without arguments, returns all records in the DA .

class digitalarchive.models.Contributor(id, name, value, uri)¶

An individual person or organization that contributed to the creation of the document.

Contributors are typically the Document’s author, but for meeting minutes and similar documents, a Contributor may simply be somebody who was in attendance at the meeting.

id¶

The ID# of the Contributor.

Type:	str

name¶

The name of the contributor.

Type:	str

uri¶

The URI of the contributor metadata on the DA API.

Type:	str

hydrate()¶: Populate all unhydrated fields of a resource.

classmethod match(**kwargs) → digitalarchive.matching.ResourceMatcher¶: Find a resource using passed keyword arguments.

Note

If called without arguments, returns all records in the DA .

class digitalarchive.models.Repository(id, name, value, uri)¶

The archive or library possessing the original, physical Document.

id¶

The ID# of the Repository.

Type:	str

name¶

The name of the repository

Type:	str

uri¶

The URI for the Repository’s metadata on the Digital Archive API.

Type:	str

value¶

An alias to name

Type:	str

hydrate()¶: Populate all unhydrated fields of a resource.

classmethod match(**kwargs) → digitalarchive.matching.ResourceMatcher¶: Find a resource using passed keyword arguments.

Note

If called without arguments, returns all records in the DA .

Hydrate-able Models¶

class digitalarchive.models.Transcript(id, filename, content_type, extension, asset_id, source_created_at, source_updated_at, url, html, pdf, raw)¶

A transcript of a document in its original language.

id¶

The ID# of the Transcript.

Type:	str

url¶

A URL to accessing the hydrated Transcript.

Type:	str

html¶

The html of of the Transcript.

Type:	str

pdf¶

A bytes object of the Transcript pdf content.

Type:	bytes

raw¶

The raw content recieved from the DA API for the Transcript.

Type:	str or bytes

filename¶

The filename of the Transcript on the content server.

Type:	str

content_type¶

The MIME type of the Transcript file.

Type:	str

extension¶

The file extension of the Transcript.

Type:	str

asset_id¶

The Transcript’s unique ID on the content server.

Type:	str

source_created_at¶

ISO 8601 timestamp of the first time the Translation was published.

Type:	str

source_updated_at¶

ISO 8601 timestamp of the last time the Translation was modified.

Type:	str

hydrate()¶: Populate all unhydrated fields of a digitalarchive.models._Asset.

class digitalarchive.models.Translation(id, filename, content_type, extension, asset_id, source_created_at, source_updated_at, url, html, pdf, raw, language)¶

A translation of a Document into a another language.

id¶

The ID# of the Translation.

Type:	str

language¶

Type:	`digitalarchive.models.Language`

html¶

The HTML-formatted text of the Translation.

Type:	str

pdf¶

A bytes object of the Translation pdf content.

Type:	bytes

raw¶

The raw content recieved from the DA API for the Translation.

Type:	str or bytes

filename¶

The filename of the Translation on the content server.

Type:	str

content_type¶

The MIME type of the Translation file.

Type:	str

extension¶

The file extension of the Translation.

Type:	str

asset_id¶

The Translation’s unique ID on the content server.

Type:	str

source_created_at¶

ISO 8601 timestamp of the first time the Translation was published.

Type:	str

source_updated_at¶

ISO 8601 timestamp of the last time the Translation was modified.

Type:	str

hydrate()¶: Populate all unhydrated fields of a digitalarchive.models._Asset.

class digitalarchive.models.MediaFile(id, filename, content_type, extension, asset_id, source_created_at, source_updated_at, path, html, pdf, raw)¶

An original scan of a Document.

id¶

The ID# of the MediaFile.

Type:	str

pdf¶

A bytes object of the MediaFile content.

Type:	bytes

raw¶

The raw content received from the DA API for the MediaFile.

Type:	str or bytes

filename¶

The filename of the MediaFile on the content server.

Type:	str

content_type¶

The MIME type of the MediaFile file.

Type:	str

extension¶

The file extension of the MediaFile.

Type:	str

asset_id¶

The MediaFile’s unique ID on the content server.

Type:	str

source_created_at¶

ISO 8601 timestamp of the first time the MediaFile was published.

Type:	str

source_updated_at¶

ISO 8601 timestamp of the last time the MediaFile was modified.

Type:	str

hydrate()¶: Populate all unhydrated fields of a digitalarchive.models._Asset.

class digitalarchive.models.Theme(id, slug, title, value, description, main_src, uri, featured_resources, has_map, has_timeline, featured_collections, dates_with_events)¶

A parent container for collections on a single geopolitical topic.

Note

Themes never appear on any record model, but can be passed as a search param to Document.

id¶

The ID# of the Theme.

Type:	str

slug¶

A url-friendly version of the theme title.

Type:	str

title¶

The name of the Theme.

Type:	str

description¶

A short description of the Theme contents.

Type:	str

main_src¶: A URI for the Theme’s banner image on the Digital Archive website.

has_map¶

A boolean value for whether the Theme has an accompanying map on the Digital Archive website.

Type:	str

has_timeline¶

A boolean value for whether the Theme has a Timeline on the Digital Archive website.

Type:	str

featured_collections¶

A list of related collections.

Type:	list of `Collection`

dates_with_events¶

A list of date ranges that the Theme has timeline entries for.

Type:	list

hydrate()¶: Populate all unhydrated fields of a resource.

Other Models¶

class digitalarchive.models.Language(id, name)¶

The original language of a resource.

id¶

An ISO 639-2/B language code.

Type:	str

name¶

The ISO language name for the language.

Type:	str

class digitalarchive.models.Donor(id, name)¶

An entity whose resources helped publish or translate a document.

id¶

The ID# of the Donor.

Type:	str

name¶

The name of the Donor.

Type:	str

class digitalarchive.models.Type(id, name)¶

The type of a document (memo, report, etc).

id¶

The ID# of the Type.

Type:	str

name¶

The name of the resource Type.

Type:	str

class digitalarchive.models.Right(id, name)¶

A copyright notice attached to the Document.

id¶

The ID# of the Copyright type.

Type:	str

name¶

The name of the Copyright type.

Type:	str

rights¶

A description of the copyright requirements.

Type:	str

class digitalarchive.models.Classification(id, name)¶

A classification marking applied to the original Document.

id¶

The ID# of the Classification type.

Type:	str

name¶

A description of the Classification type.

Type:	str

,,,

Matching¶

class digitalarchive.matching.ResourceMatcher(resource_model: digitalarchive.models.Resource, items_per_page=200, **kwargs)¶

Runs a search against the DA API for the provided DA model and keywords.

ResourceMatcher wraps search results and exposes methods for interacting with the resultant set of resources.

list¶

search results. Handles pagination of the DA API.

Type:	`Generator` of `digitalarchive.models.Resource`

count¶: The number of respondant records to the given search.

all() → List[digitalarchive.models.Resource]¶: Exhaust the results generator and return a list of all search results.

first() → digitalarchive.models.Resource¶: Return only the first record from a search result.

hydrate(recurse: bool = False)¶: Hydrate all of the resources in a search result.