Welcome to ArchivesSnake’s documentation!

class asnake.aspace.ASpace(**config)

__getattr__(attr)

returns the JSONModelRelation representing the route with the same name as the attribute requested.

class asnake.jsonmodel.JSONModelObject(json_rep, client=None)

A wrapper over the JSONModel representation of a single object in ArchivesSpace.

property id

Return the id for the object if it has a useful ID, or else None.

Note: unlike uri, an id is Not fully unique within some collections returnable by API methods. For example, searches can return different types of objects, and agents have unique ids per agent_type, not across all agents.

json()

return safe-to-edit copy wrapped dict representing JSONModelObject contents.

reify()

Convert object from a ref into a realized object.

class asnake.jsonmodel.ComponentObject(json_rep, client=None)

Specialized JSONModel subclass representing Archival Objects. Mostly exists to provide a way to get TreeNodes from AOs rather than having to start at the resource.

property id

Return the id for the object if it has a useful ID, or else None.

Note: unlike uri, an id is Not fully unique within some collections returnable by API methods. For example, searches can return different types of objects, and agents have unique ids per agent_type, not across all agents.

json()

return safe-to-edit copy wrapped dict representing JSONModelObject contents.

reify()

Convert object from a ref into a realized object.

property tree

Returns a TreeNode object for children of archival objects

class asnake.jsonmodel.JSONModelRelation(uri, params={}, client=None)

A wrapper over index routes and other routes that represent groups of items in ASpace.

It provides two means of accessing objects in these collections:

• you can iterate over the relation to get all objects

• you can call the relation as a function with an id to get an object with a known id

e.g.

for repo in ASpace().repositories:
    # do stuff with repo here

ASpace.repositories(12) # object at uri /repositories/12

This object wraps the route and parameters, and does no caching - each iteration through a relation fetches data from ASpace fresh.

Additionally, JSONModelRelations implement __getattr__, in order to handle nested and subsidiary routes, such as the routes for individual types of agents.

__getattr__(key)

__call__(myid=None, **params)

Fetch a JSONModelObject from the relation by id.

with_params(**params)

Return JSONModelRelation with same uri and client, but add kwargs to params.

Usage:

for thing in ASpace().repositories(2).search.with_params(q="primary_type:resource"):
    # do something with the things

class asnake.aspace.AgentRelation(uri, params={}, client=None)

subtype of JSONModelRelation for handling the /agents route hierarchy.

Usage:

ASpace().agents                        # all agents of all types
ASpace().agents.corporate_entities     # JSONModelRelation of corporate entities
ASpace().agents["corporate_entities"]  # see above
ASpace().agents["people", "families"]  # Multiple types of agents

__getitem__(only)

filter the AgentRelation to only the type or types passed in

exception asnake.jsonmodel.ASNakeBadAgentType

class asnake.jsonmodel.AgentRelation(uri, params={}, client=None)

subtype of JSONModelRelation for handling the /agents route hierarchy.

Usage:

ASpace().agents                        # all agents of all types
ASpace().agents.corporate_entities     # JSONModelRelation of corporate entities
ASpace().agents["corporate_entities"]  # see above
ASpace().agents["people", "families"]  # Multiple types of agents

class asnake.jsonmodel.ComponentObject(json_rep, client=None)

Specialized JSONModel subclass representing Archival Objects. Mostly exists to provide a way to get TreeNodes from AOs rather than having to start at the resource.

property tree

Returns a TreeNode object for children of archival objects

class asnake.jsonmodel.JM

Helper class for creating hashes suitable for POSTing to ArchivesSpace.

Usage:

JM.resource(title="A Resource's Title", ...) == {"jsonmodel_type": "resource", "title": "A Resource's Title", ...}
JM.agent_software(name="ArchivesSnake") == {"jsonmodel_type": "agent_software", "name": "ArchivesSnake"}

class asnake.jsonmodel.JSONModel(name, parents, dct)

Mixin providing functionality shared by JSONModel and JSONModelRelation classes.

default_client()

return existing ASnakeClient or create, store, and return a new ASnakeClient

class asnake.jsonmodel.JSONModelObject(json_rep, client=None)

A wrapper over the JSONModel representation of a single object in ArchivesSpace.

property id

Return the id for the object if it has a useful ID, or else None.

Note: unlike uri, an id is Not fully unique within some collections returnable by API methods. For example, searches can return different types of objects, and agents have unique ids per agent_type, not across all agents.

json()

return safe-to-edit copy wrapped dict representing JSONModelObject contents.

reify()

Convert object from a ref into a realized object.

class asnake.jsonmodel.JSONModelRelation(uri, params={}, client=None)

A wrapper over index routes and other routes that represent groups of items in ASpace.

It provides two means of accessing objects in these collections:

• you can iterate over the relation to get all objects

• you can call the relation as a function with an id to get an object with a known id

e.g.

for repo in ASpace().repositories:
    # do stuff with repo here

ASpace.repositories(12) # object at uri /repositories/12

This object wraps the route and parameters, and does no caching - each iteration through a relation fetches data from ASpace fresh.

Additionally, JSONModelRelations implement __getattr__, in order to handle nested and subsidiary routes, such as the routes for individual types of agents.

with_params(**params)

Return JSONModelRelation with same uri and client, but add kwargs to params.

Usage:

for thing in ASpace().repositories(2).search.with_params(q="primary_type:resource"):
    # do something with the things

class asnake.jsonmodel.ResourceRelation(params={}, client=None)

subtype of JSONModelRelation for returning all resources from every repository

Usage:

ASpace().resources      # all resources from every repository
ASpace().resources(42)  # resource with id=42, regardless of what repo it's in

with_params(**params)

Return JSONModelRelation with same uri and client, but add kwargs to params.

Usage:

for thing in ASpace().repositories(2).search.with_params(q="primary_type:resource"):
    # do something with the things

class asnake.jsonmodel.SolrRelation(uri, params={}, client=None)

Sometimes, the API returns solr responses, so we have to handle that. Facets are still tbd, but should be doable, but also I’m not sure if they’re widely used and thus need to be handled?.

class asnake.jsonmodel.TreeNode(json_rep, client=None)

Specialized JSONModel subclass representing nodes in trees, as returned from /repositories/:repo_id/resources/:id/tree.

node(node_uri)

A sub-route existing on resources, which returns info on the node passed in.

Returned as an instance of TreeNodeData.

property record

returns the full JSONModelObject for a node

property walk

Serial walk of all objects in tree and children (depth-first traversal)

class asnake.jsonmodel.TreeNodeData(json_rep, client=None)

Object representing data about a node in a tree.

class asnake.jsonmodel.UserRelation(uri, params={}, client=None)

“Custom” relation to deal with the API’s failure to properly populate permissions for the /users index route

property current_user

/users/current-user route.

asnake.jsonmodel.dispatch_type(obj)

Determines if object is JSON suitable for wrapping with a JSONModelObject, or a narrower subtype. Returns either the correct class or False if no class is suitable.

Note: IN GENERAL, it is safe to use this to test if a thing is a JSONModel subtype, but you should STRONGLY prefer wrap_json_object() for constructing objects, because some objects are wrapped, and would need to be manually unwrapped otherwise. So, usage like this:

jmtype = dispatch_type(obj, self.client)
if jmtype:
    return wrap_json_object(obj, self.client)

is fine and expected, but the following is dangerous:

jmtype = dispatch_type(obj, self.client)
if jmtype:
    return jmtype(obj, self.client)

because it will break on wrapped or otherwise odd objects.

asnake.jsonmodel.find_subtree(tree, uri)

Navigates a tree object to get a list of children of a specified archival object uri.

asnake.jsonmodel.wrap_json_object(obj, client=None)

Classify object, and either wrap it in the correct JSONModel type or return it as is.

Prefer this STRONGLY to directly using the output of dispatch_type()

class asnake.client.ASnakeClient(**config)

ArchivesSnake Web Client

authorize(username=None, password=None)

Authorizes the client against the configured archivesspace instance.

Parses the JSON response, and stores the returned session token in the session.headers for future requests. Asks for a “non-expiring” session, which isn’t truly immortal, just long-lived.

delete(url, *args, **kwargs)

Proxied requests.Session.delete() method from requests.Session

get(url, *args, **kwargs)

Proxied requests.Session.get() method from requests.Session

get_paged(url, *args, page_size=100, **kwargs)

get list of json objects from urls of paged items

head(url, *args, **kwargs)

Proxied requests.Session.head() method from requests.Session

options(url, *args, **kwargs)

Proxied requests.Session.options() method from requests.Session

post(url, *args, **kwargs)

Proxied requests.Session.post() method from requests.Session

put(url, *args, **kwargs)

Proxied requests.Session.put() method from requests.Session

exception asnake.client.web_client.ASnakeAuthError

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class asnake.client.web_client.ASnakeClient(**config)

ArchivesSnake Web Client

authorize(username=None, password=None)

Authorizes the client against the configured archivesspace instance.

Parses the JSON response, and stores the returned session token in the session.headers for future requests. Asks for a “non-expiring” session, which isn’t truly immortal, just long-lived.

delete(url, *args, **kwargs)

Proxied requests.Session.delete() method from requests.Session

get(url, *args, **kwargs)

Proxied requests.Session.get() method from requests.Session

get_paged(url, *args, page_size=100, **kwargs)

get list of json objects from urls of paged items

head(url, *args, **kwargs)

Proxied requests.Session.head() method from requests.Session

options(url, *args, **kwargs)

Proxied requests.Session.options() method from requests.Session

post(url, *args, **kwargs)

Proxied requests.Session.post() method from requests.Session

put(url, *args, **kwargs)

Proxied requests.Session.put() method from requests.Session

class asnake.client.web_client.ASnakeProxyMethods(name, parents, dct)

Metaclass to set up proxy methods for all requests-supported HTTP methods

mro()

Return a type’s method resolution order.

exception asnake.client.web_client.ASnakeWeirdReturnError

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

asnake.client.web_client.http_meth_factory(meth)

Utility method for producing HTTP proxy methods for ASnakeProxyMethods mixin class.

Urls are prefixed with the value of baseurl from the client’s ASnakeConfig. Arguments are passed unaltered to the matching requests.Session method.

asnake.client.web_client.listlike_seq(seq)

Determine if a thing is a list-like (sequence of values) sequence that’s not string-like.

class asnake.ASnakeConfig(config=NOTHING)

Configuration object. Essentially a convenience wrapper over an instance of boltons.dictutils.OrderedMultiDict

copy_config(config)

Copy relevant information from one config to another.

default_logging_conf(**overrides)

Generate a default stdlib logging configuration.

default_structlog_conf(**overrides)

Generate a default configuration for structlog

setup_logging(config=None, level=None, stream=None, filename=None, filemode=None)

sets up both logging and structlog.

update(*args, **kwargs)

adds a set of configuration values in ‘most preferred’ position (i.e. last updated wins). See boltons.dictutils.OrderedMultiDict.update_extend() in the OMD docs

asnake.utils.find_closest_value(archival_object, key, client)

Finds the closest value matching a key.

Starts with an archival object, and iterates up through its ancestors until it finds a match for a key that is not empty or null.

Parameters

• archival_object (JSONModelObject) – the URI for an archival object, a dict with a key ‘uri’ or ‘ref’ containing said URI, or an object responding to .json() returning such a dict

• key (str) – the key to match against.

Returns

The value of the key, which could be a str, list, or dict.

Return type

str, list, or key

asnake.utils.format_from_obj(obj, format_string, client)

Generates a human-readable string from an object.

Parameters

or dict (JSONModelObject) – an ArchivesSpace object.

Returns

a string in the chosen format.

Return type

str

asnake.utils.format_resource_id(resource, client, separator=':')

Concatenates the four-part ID for a resource record.

Parameters

• resource (dict) – an ArchivesSpace resource.

• separator (str) – a separator to insert between the id parts. Defaults to :.

Returns

a concatenated four-part ID for the resource record.

Return type

str

asnake.utils.get_date_display(date, client)

Returns a date expression for a date object.

Concatenates start and end dates if no date expression exists.

Parameters

date (dict) – an ArchivesSpace date

Returns

date expression for the date object.

Return type

str

asnake.utils.get_note_text(note, client)

Parses note content from different note types.

Parameters

dict – an ArchivesSpace note.

Returns

a list containing note content.

Return type

list

asnake.utils.get_object_locations(ao_uri, client)

Given any of: - the URI for an archival object - a dict with a key ‘uri’ or ‘ref’ containing said URI - an object responding to .json() returning such a dict

and an asnake.client.ASnakeClient, this method will return a generator which yields the JSON representation of any locations associated with the archival object.

asnake.utils.get_orphans(object_list, null_attribute, client)

Finds objects in a list which do not have a value in a specified field.

Parameters

• object_list (list) – a list of URIs for an archival object, dicts with a key ‘uri’ or ‘ref’ containing said URI, or objects responding to .json() returning such a dict

• null_attribute – an attribute which must be empty or null.

Yields

a list of ArchivesSpace objects.

Yield type

dict

asnake.utils.indicates_restriction(rights_statement, restriction_acts, client)

Parses a rights statement to determine if it indicates a restriction.

Parameters

rights_statement (dict) – an ArchivesSpace rights statement.

Returns

True if rights statement indicates a restriction, False if not.

Return type

bool

asnake.utils.is_expired(date_str)

Takes a date and then checks whether today’s date is before or after passed date. Will return a ValueError if passed date argument is an invalid date.

Parameters

date (string) – an ISO-formatted representation of a date

Returns

False if date argument is after today or True if

Return type

bool

asnake.utils.is_restricted(archival_object, query_string, restriction_acts, client)

Parses an archival object to determine if it is restricted.

Iterates through notes, looking for a conditions governing access note which contains a particular set of strings. Also looks for associated rights statements which indicate object may be restricted.

Parameters

• archival_object (dict) – an ArchivesSpace archival_object.

• restriction_acts (list) – a list of strings to match restriction act against.

Returns

True if archival object is restricted, False if not.

Return type

bool

asnake.utils.resolve_to_json(thingit, client)

Given any of: - the URI for an ArchivesSpace object - an object responding to .json() returning such a dict

this method will return a JSON representation of that object.

asnake.utils.resolve_to_uri(thingit)

Given any of: - the URI for an ArchivesSpace object - a dict with a key ‘uri’ or ‘ref’ containing said URI - an object responding to .json() returning such a dict

this method will return a string containing the URI for that resource.

asnake.utils.strip_html_tags(string)

Strips HTML tags from a string.

Parameters

string (str) – An input string from which to remove HTML tags.

asnake.utils.text_in_note(note, query_string, client, confidence=97)

Performs fuzzy searching against note text.

Parameters

• note (dict) – an ArchivesSpace note.

• query_string (str) – a string to match against.

• confidence (int) – minimum confidence ratio to match against.

Returns

True if a match is found for query_string, False if no match is found.

Return type

bool

asnake.utils.walk_tree(thingit, client)

Given any of: - the URI for a resource - the URI for an archival object - a Mapping containing such a URI under the key ‘uri’

and an asnake.client.ASnakeClient, this method will return a generator which yields the JSON representation of each successive element in the resource’s tree, in order.

Indices and tables

• Index

• Module Index

• Search Page