Skip to content

Getting Started Guide

Jump to bottom
Gregory Wiedeman edited this page Aug 7, 2018 · 11 revisions

Setup Credentials

  • Make a .archivessnake.yml file in your home directory
    • For OS X and Linux this is usually /home/[my user name]/.archivessnake.yml
    • For Windows, its usually C:\Users\[my user name]\.archivessnake.yml
    • A basic .archivessnake.yml looks like this, with the URL/IP to your ASpace API as baseurl and theusername and password for a User with API access.
baseurl: http://localhost:8089
username: admin
password: admin
  • YML files optionally might also have more advanced configuration, such as logging.

Setup a Script and Repositories

Importing and Initializing

from asnake.aspace import ASpace

AS = ASpace()

ASpace() is the abstraction layer, which will likely be the default way you will use ArchivesSnake. If you need to use additional endpoints which available or useful in the abstraction layer, you can make individual API calls with ASpace().client(), such as ASpace().client('/repositories/2/my_endpoint').

Right now, the abstraction layer is incomplete and read-only, but soon we hope it will cover most basic uses. It might take awhile for some endpoints to be included, and some might not ever be. Typically, we expect that you make the most use of the abstraction layer, and call ASpace().client() within that as needed.

Getting a Repository

from asnake.aspace import ASpace

# change '2' to any repository ID
repo = ASpace().repositories(2)
print (repo.title)

>> My Awesome ArchivesSpace Repository

Looping through multiple repositories

from asnake.aspace import ASpace

for repo in ASpace().repositories:
	print (repo.name)
	print (repo.resource(1).title)
	
>> My Awesome ArchivesSpace Repository
>> A Unique Group of Useful Records
>> M.E. Grenander Department of Special Collections & Archives
>> Murder Victims' Families for Reconciliation Records

The Basics

Getting Resources

from asnake.aspace import ASpace

repo = ASpace().repositories(2)

# change '1' to any resource :id
collection = repo.resources(1)
print (collection.title)

>> Murder Victims' Families for Reconciliation Records

Getting Archival Objects

from asnake.aspace import ASpace

repo = ASpace().repositories(2)

# change '1' to any archival_object :id
file = repo.archival_objects(1)
print (file.title)

>> Minutes

How about Accessions?

from asnake.aspace import ASpace

repo = ASpace().repositories(2)

# change '1' to any accession :id
transfer = repo.accessions(155)
print (transfer.accession_date)

>>> 2018-06-20

I have something, what do I do with it?

List all the Keys

from asnake.aspace import ASpace

repo = ASpace().repositories(2)

collection = repo.resources(1)
print (dir(collection))

>>> ['_client', '_json', 'classifications', 'create_time', 'created_by', 'dates', 'deaccessions', 'ead_id', 'ead_location', 'extents', 'external_documents', 'external_ids', 'finding_aid_author', 'finding_aid_date', 'finding_aid_language', 'finding_aid_sponsor', 'finding_aid_status', 'finding_aid_title', 'id_0', 'instances', 'is_ref', 'jsonmodel_type', 'language', 'last_modified_by', 'level', 'linked_agents', 'linked_events', 'lock_version', 'notes', 'publish', 'related_accessions', 'repository', 'restrictions', 'revision_statements', 'rights_statements', 'subjects', 'suppressed', 'system_mtime', 'title', 'tree', 'uri', 'user_mtime']

Just Print() it to Pretty Print the JSON

from asnake.aspace import ASpace

repo = ASpace().repositories(2)

collection = repo.resources(1)
print (collection)

>>>{
>>>  "lock_version": 3,
>>>  "title": "Murder Victims' Families for Reconciliation Records",
>>>  "publish": true,
>>>  "restrictions": false,
>>>  "ead_id": "apap313",
>>>  "ead_location": "http://meg.library.albany.edu:8080/archive/view?docId=apap313.xml",
>>>  "finding_aid_title": "Murder Victims Families for Reconciliation; Records",
>>>  "finding_aid_date": "2015",
>>>  "finding_aid_author": "Samantha Brown",
>>>  "finding_aid_language": "English",
>>>  "finding_aid_sponsor": "This project was made possible by a grant from the Council on Library and Information Resources (CLIR)",
>>>  "created_by": "greg",
>>>  "last_modified_by": "robotimporter",
>>>  "create_time": "2017-04-05T20:04:07Z",
>>>  "system_mtime": "2017-05-04T13:45:17Z",
>>>  "user_mtime": "2017-04-06T19:40:15Z",
>>>  "suppressed": false,
>>>  "id_0": "apap313",
>>>  "language": "eng",
>>>  "level": "collection",
>>>  "finding_aid_status": "new",
>>>  "jsonmodel_type": "resource",
>>>  "external_ids": [],
>>>  "subjects": [
>>>    {
>>>      "ref": "/subjects/91"
>>>    },
>>>    {
>>>      "ref": "/subjects/1029"
>>>    },
>>>    {
>>>      "ref": "/subjects/1030"
>>>    },
...
...

Just Get the JSON

from asnake.aspace import ASpace

repo = ASpace().repositories(2)

collection = repo.resources(1)
myJSON = collection.json()
print (myJSON['uri'])

>>> /repositories/2/resources/1

Getting All The Things

Listing resources

from asnake.aspace import ASpace

repo = ASpace().repositories(2)

for resource in repo.resources:
	print (resource.id_0 + ' ' + resource.title)

>>> apap001 American Association of University Professors, Albany Chapter Records
>>> apap002 American Association of University Women, Albany Branch Records
>>> apap003 Association of Colleges and Universities of the State of New York (ACUSNY) Records
...
...

Listing Children of Resources

from asnake.aspace import ASpace

repo = ASpace().repositories(2)
collection = repo.resources(231)

for child in collection.tree.children:
	print (child.level + " - " + child.title)

>>> series - Administrative Files, 1977-2005, Undated
>>> series - Correspondence, 1994-2005, Undated
>>> series - Outreach and Publications, 1994-2004, Undated
>>> series - Events, 1992-2003, Undated
>>> series - Subject Files, 1981-2007, Undated

Children from Trees are not full archival objects

from asnake.aspace import ASpace

repo = ASpace().repositories(2)
collection = repo.resources(231)

for child in collection.tree.children:
	print (child)
	
>>>{
>>>  "title": "Office of Equal Employment Opportunity , 1973 - 1974",
>>>  "id": 223023,
>>>  "record_uri": "/repositories/2/archival_objects/223023",
>>>  "publish": true,
>>>  "suppressed": false,
>>>  "node_type": "archival_object",
>>>  "level": "series",
>>>  "instance_types": [],
>>>  "containers": [],
>>>  "has_children": false,
>>>  "children": []
>>>}

Get Full Archival Objects from Trees

from asnake.aspace import ASpace

repo = ASpace().repositories(2)
collection = repo.resources(231)

for child in collection.tree.children:
	series = child.record
	print (series)
	
>>>{
>>>  "lock_version": 2,
>>>  "position": 9,
>>>  "publish": false,
>>>  "ref_id": "03199a7f042cc5cc1a1da3e707e70759",
>>>  "title": "Office of Diversity and Inclusion",
>>>  "display_string": "Office of Diversity and Inclusion, 2015",
>>>  "restrictions_apply": false,
>>>  "created_by": "miles",
>>>  "last_modified_by": "miles",
>>>  "create_time": "2018-07-09T14:57:50Z",
>>>  "system_mtime": "2018-07-26T13:45:24Z",
>>>  "user_mtime": "2018-07-20T20:08:13Z",
>>>  "suppressed": false,
>>>  "level": "series",
>>>  "jsonmodel_type": "archival_object",
>>>  "external_ids": [],
>>>  "subjects": [],
>>>  "linked_events": [],
>>>  "extents": [
>>>    {
>>>      "lock_version": 0,
>>>      "number": "0.17",
...
...

Looping down the Hierarchy

from asnake.aspace import ASpace

repo = ASpace().repositories(2)
collection = repo.resources(102)

for series in collection.tree.children:
	for folder in series.children:
		print (folder.title)
		
>>> General Activism, 1975-2000, Undated
>>> National Gay and Lesbian Task Force, 1985-1998, Undated
>>> National March on Washington, 1993, 1987-1994, Undated
>>> Seneca Women's Encampment for a Future of Peace and Justice (1983-1988), 1982-1991, Undated
...
...

Gotchas with Trees

Just remember, when you use .tree on a resource or an archival_object, you're getting part of a TreeObject with is different than a complete archival_object. Use .record to call the full archival_object, but then you need to call .tree.children again which is inefficient.

from asnake.aspace import ASpace

repo = ASpace().repositories(2)
collection = repo.resources(102)

for child in collection.tree.children:
	# child here is only a node of a tree object
	# tree nodes have things like .level, .id, .record_uri, .title, and .has_children
	if child.title == "General Activism":
		print (child.record_uri)
		
		series = child.record
		# Now series is the full archival_object
		# archival_objects have additional things like .uri, .dates, .extents, .subjects
		print (series.uri)
		
>>> /repositories/2/archival_objects/26792
>>> /repositories/2/archival_objects/26792

Dates and Extents

Remember, dates and extents are typically lists, so you want to make sure to loop though them or call them by index like resource.extents[0].

Dates

from asnake.aspace import ASpace

repo = ASpace().repositories(2)
collection = repo.resources(102)

print (collection.dates[0].date_type)
print (collection.dates[0].begin)
print (collection.dates[0].end)
print (collection.dates[0].expression)
print (collection.dates[0])

>>> inclusive
>>> 1927
>>> 2000
>>> 1927-2000
>>> {
>>>   "lock_version": 0,
>>>   "expression": "1927-2000",
>>>   "begin": "1927",
>>>   "end": "2000",
>>>   "created_by": "greg",
>>>   "last_modified_by": "greg",
>>>   "create_time": "2017-08-08T21:11:46Z",
>>>   "system_mtime": "2017-08-08T21:11:46Z",
>>>   "user_mtime": "2017-08-08T21:11:46Z",
>>>   "date_type": "inclusive",
>>>   "label": "creation",
>>>   "jsonmodel_type": "date"
>>> }

Looping through Dates

from asnake.aspace import ASpace

repo = ASpace().repositories(2)
collection = repo.resources(102)

for date in collection.dates:
	print (date.date_type + ": " + date.expression)
	
>>> inclusive: 1927-2000
>>> bulk: 1982-1995

Extents work the same way

from asnake.aspace import ASpace

repo = ASpace().repositories(2)
collection = repo.resources(102)

print (collection.extents[0].number)

for extent in collection.extents:
	print (extent)

>>> 44.4
>>> {
>>>   "lock_version": 0,
>>>   "number": "44.4",
>>>   "created_by": "greg",
>>>   "last_modified_by": "greg",
>>>   "create_time": "2017-08-08T21:11:46Z",
>>>   "system_mtime": "2017-08-08T21:11:46Z",
>>>   "user_mtime": "2017-08-08T21:11:46Z",
>>>   "portion": "whole",
>>>   "extent_type": "cubic ft.",
>>>   "jsonmodel_type": "extent"
>>> }

Updating Things

Using ASpace().client() for Additional Endpoints

Clone this wiki locally