A beta/hyper-prototypical/incomplete/work-in-progress Python package that uses CSVs to interact with the ArchivesSpace API.
NOTE: Use at your own risk. Much of this is still unfinished, but the description functions have been tested. Further additions to the code and more documentation is coming soon.
- Python 3.4+
requestsmodulepymysqlmodule- Access to ArchivesSpace API
- Access to ArchivesSpace Database
In Terminal, clone repository and cd to top-level apispace directory, then enter
pip install apispace
To enter login settings into the console:
>>> import apispace
>>> config.api_settings(url, username, password, nickname)
>>> print(api_url)
url
>>> config.db_settings(name, host, port, un, pw)
>>> print(db_name)
name
To download a configuration JSON file template:
>>> import apispace
>>> templates.write_config()
Please enter path to output folder:
>>> All Done!
To load a configuration JSON file:
>>> import apispace
>>> config.loadconfig()
Please enter the path to your config file: /Users/user/Desktop/confix.json
>>> Thank you, config file is loaded.
All functions will work without entering credentials, but users must enter credentials each time a function is called.
To clear login settings, run:
>>> config.clear_settings(api)
>>> print(password)
>>> config.clear_settings(db)
>>> print(db_name)
>>>
A variety of CSV templates are available for use with apispace functions. To download all templates, do:
>>> import apispace
>>> templates.download_templates()
>>> Please enter path to output folder: Users/username/Desktop/templates
>>>
To download a single template, do:
>>> import apispace
>>> templates.download_template('accessions')
>>> Please enter path to output folder: Users/username/Desktop/templates
>>>
Users may find it beneficial to create a separate directory to store template files.
This submodule includes basic login and file handling functions. It also includes a few basic ArchivesSpace functions, including functions to retrieve and update set default values and to update enumeration value positions.
admin.login()
Log in to the ArchivesSpace API. Uses optional config file to retrieve login information. See instructions above to set up config file.
To log in and perform a test GET request, try the following:
>>> import apispace
>>> values = admin.login()
Login successful! Connected to ArchivesSpace TEST
>>> example = requests.get(values[0] + '/repositories, headers=values[1]).json()
>>> print(example)
[List of repositories]
If the config file is not set, a call to the login function will prompt the user for credentials.
admin.login_db()
Log in to the ArchivesSpace database. Uses optional config file to retrieve login information. See instructions above to set up config file.
If the config file is not set, a call to the login_db function will prompt the user for credentials.
admin.opencsv()
Opens an input CSV file. This function is called in nearly every other function in this package.
admin.opencsvdict()
Opens an input CSV file in DictReader mode. This function is used in functions which allow for variable numbers of record updates.
admin.opencsvout()
Open an output CSV file. This function is used in other functions to store output data.
admin.opentxt()
Open an output text file. This function is used in other functions to store log data.
admin.writetxt(f, j)
Write to an output text file. This function is used in other functions to store JSON data for individual records.
admin.writealltxt(f, j)
Write to an output text file. This function is used in other functions to store JSON data for a batch of records.
admin.setdefaultvalues()
admin.update_enum_val_positions()
Updates the position of enumeration values, using a CSV as input. To use the CSV output from getdata.get_enumerations(enumeration) as input
for this function, simply change the position values to whatever is desired.
To use, do the following:
>>> import apispace
>>> admin.update_enum_val_positions()
Login Successful! Connected to ArchivesSpace TEST
Please enter path to input CSV: /Users/username/Desktop/updated_enum_positions.csv
<Enumeration_Value xxxxx>
<Enumeration_Value xxxxx>
>>>
This submodule takes the JSONModel schemas for ArchivesSpace and manipulates them into a format in which they can be easily accessed by the description functions in this module. The goal is to abstract the description functions - especially the record creation functions - as much as possible, and to pull in data directly from the schema.
This portion of the module is not fully fleshed out yet, so other functions in the description submodule for record creation are still available.
This submodule includes a variety of functions which create, update, and delete descriptive records and subrecords.
Use template functions to download CSV templates for use with description functions
description.**create_records(jsonmodel_type, subrecords)
Creates one or more records of any type, with any number of record and subrecord fields. This function pulls in data from the ArchivesSpace schema via a request to the API. Gien the record type and any subrecords as arguments, it matches the record type, the properties of each record type, and any subrecord fields with the data in the schema, and then constructs a JSON object based on the column headers of the input CSV.
This function enables users to create any kind of record, with any number of fields, using a single function. Because the schema is pulled in from the API, users will be able to utilize the schema which corresponds to their version of ArchivesSpace.
description.repositories()
Creates one or more minimally-populated repository records using repositories.csv as input.
To use, do the following:
Complete repositories.csv template, i.e.:
| repo_name | repo_code |
|---|---|
| Manuscripts and Archives | mssa |
| Arts Library | arts |
| Medical Library | med |
Run repositories() function:
>>> import apispace
>>> description.repositories()
Login Successful! Connected to ArchivesSpace TEST
Please enter path to input CSV: /Users/username/Desktop/repositories.csv
{Status: Updated...}
{Status: Updated...}
{Status: Updated...}
description.accessions()
Creates one or more minimally-populated repository record using accessions.csv as input.
description.resources()
Creates one or more minimally-populated resource records using resources.csv as input
description.archival_objects()
Creates one or more minimally-populated archival object records using archival_objects.csv as input
description.digital_objects()
Creates one or more minimally-populated digital object records using digital_objects.csv as input
description.dig_object_components()
Creates one or more minimally-populated digital object records using dig_obj_components.csv as input
description.dates()
Creates dates to be added to existing descriptive records, using dates.csv as input
description.extents()
Creates extents to be added to existing descriptive records, using extents.csv as input
description.external_docs()
Creates external documents to be added to existing descriptive records, using external_docs.csv as input
description.external_ids()
Creates external IDs to be added to existing descriptive records, using external_ids.csv as input
description.file_versions()
Creates file versions to be added to existing descriptive records, using file_versions.csv as input
description.revision_statements()
Creates finding aid revision statements to be added to existing descriptive records, using revision_statements.csv as input
description.singlepart_notes()
Creates singlepart notes to be added to existing descriptive records, using a CSV as input
description.multipart_notes()
Creates multipart notes to be added to existing descriptive records, using a CSV as input
description.rights_restrictions()
Creates rights restrictions to be added to existing conditions governing access or conditions governing use notes, using a CSV as input
description.note_bioghist()
Creates a biographical history note to be added to an existing descriptive record, using a CSV as input
description.note_abstract()
Creates an abstract note to be added to an existing descriptive record, using a CSV as input
description.note_bibliography()
Creates a bibliography to be added to an existing descriptive record, using a CSV as input
description.update_record_component()
Updates any single top-level (string) record component, using a CSV as input
description.update_record_components(**args)
Updates one or more top-level record components, using a CSV as input
description.update_record_pub_status()
Updates the publication status of one or more descriptive records, using a CSV as input
description.update_subrecord_component()
Updates any single sub-record (module) component, using a CSV as input
description.update_subrecord_components(**args)
Updates one or more sub-record (module) components, using a CSV as input
description.update_note_component()
Update any single note component, using a CSV as input
description.update_note_components(**args) - NOT YET WRITTEN
Update one or more note components, using a CSV as input
description.update_note_pub_status()
Update the publication status of one or more notes, using a CSV as input
description.replace_note_by_id()
Replace the text of an existing note using its persistent ID
description.delete_notes()
Delete one or more notes
description.delete_subrecords()
Delete one or more subrecords (modules) from a descriptive record
description.delete_subrecord_components()
Delete a given number of components from a subrecord
description.delete_do_instance()
Delete a digital object instance. NOTE: Always delete a digital object instance before deleting the digital object itself.
description.delete_records()
Delete one or more descriptive records.
classification.create_top_level()
classification.create_sub_level()
classification.create_sub_sub_level()
classification.link_records()
classification.get_class_uris()
classification.get_class_rec_links()
agent.create_agent()
Create one or more agent records using a CSV as input
agent.update_agent_component() - NOT YET WRITTEN
agent.update_agent_components() - NOT YET WRITTEN
agent.link_agent()
Link one or more agent records to existing descriptive records, using a CSV as input
agent.merge_agents() = NOT YET WRITTEN
subject.create_subject()
Create one or more subjects using a CSV as input
subject.update_subject_component()
subject.update_subject_components()
subject.link_subject() - NOT YET WRITTEN
subject.delete_subject() - NOT YET WRITTEN
container.create_top_container()
Creates one or more top containers using a CSV as input
container.update_tc_components()
container.create_instances()
Links top containers to descriptive records, using a CSV as input
container.create_do_instances()
container.update_sc_components()
Updates subcontainer types and indicators, using a CSV as input. Ideal for making batch updates/corrections to folder numbers
container.create_container_profiles()
Creates container profiles using a CSV as input
location.create_location()
Creates one or more locations using a CSV as input
location.update_location(**args)
Updates a given number of location components using a CSV as imput
event.create_event()
schema.schema()
Prints the ArchivesSpace schema
datatypes submodule
getdata.get_enumerations()
Database query to return the uri, name, and position of all enumeration values in a given enumeration.
getdata.get_repo_json()
getdata.get_global_json()
getdata.get_repo_ids()
getdata.get_global_ids()
getdata.get_note_ids()
getdata.get_uris()
getdata.extent_calculator() - NEED TO MOVE
Retrieves calculated extent values for a list of resources, using a CSV of ArchivesSpace URIs as input
getdata.get_tree(repo, resource) - NEED TO MOVE
Retrieves the record tree for a resource