vsdConnect.connect module

INFOS

  • connect 0.8.1
  • python version: 3.5
  • @author: Michael Kistler 2015, Livia B 2016

CHANGES

  • changed / added JwT auth
  • added models module
class connect.JWTAuth(enctoken)[source]

Bases: requests.auth.AuthBase

Attaches JMT to the given Request object. extends the request package auth class

class connect.SAMLAuth(enctoken)[source]

Bases: requests.auth.AuthBase

Attaches SMAL to the given Request object. extends the request package auth class

class connect.VSDConnecter(authtype='jwt', url='https://demo.virtualskeleton.ch/api/', username='demo@virtualskeleton.ch', password='demo', version='', token=None)[source]

Bases: object

add an object link

Parameters:
  • obj1 (APIBase) – a linked object with selfUrl
  • obj2 (APIBase) – a linked object with selfUrl
Returns:

the created object-link
Return type:

json
addObjectToFolder(target, obj)[source]

add an object to the folder

Parameters:
  • target (Folder) – the target folder
  • obj (Object) – the object to copy
Returns:

updated folder
Return type:

Folder
addOntologyToObject(obj, ontology, pos=0)[source]

add an ontoly term to an object

Parameters:
  • obj (APIBase) – basic object
  • ontology (Ontology) – ontology object
  • pos (int) – position of the ontology term, default = 1
Returns:

returns true if successfully added
Return type:

bool
checkFileInObject(obj, fp)[source]

check if a local file is part of an object

Parameters:
  • obj (APIObject) – API object
  • fp (Path) – file to test
Returns:

if contained or not
Return type:

bool
chunkFileUpload(fp, chunksize=4194304)[source]

upload large files in chunks of max 100 MB size

Parameters:
  • fp (Path) – the file to upload
  • chunksize (int) – size in bytes of the chunk parts, default is 4MB
Returns:

the generated object
Return type:

APIObject
chunkedread(fp, chunksize)[source]

breaks the file into chunks of chunksize

Parameters:
  • fp (Path) – the file to chunk
  • chunksize (int) – size in bytes of the chunk parts
Yields:

chunk
createFolderStructure(rootfolder, filepath, parents)[source]

creates the folders based on the filepath if not already existing, starting from the rootfolder

Parameters:
  • rootfolder (Folder) – the root folder object
  • filepath (Path) – filepath of the file
  • parents (int) – number of partent levels to create from file folder
Returns:

the last folder in the tree
Return type:

Folder
createObject(response=None, **kwargs)[source]

please describe the purpose here

convert fields to response dict how to use it?, cant we use: json.dumps(self.to_struct())

Parameters:
  • response (bool) –

    ???

  • **kwargs –

    ???
delObject(obj)[source]

delete an unvalidated object

Parameters:obj (APIObject) – the object to delete
Returns:status_code
Return type:int
delRequest(resource)[source]

generic delete request

Parameters:resource (str) – resource path
Returns:status_code
Return type:int
deleteFolder(folder, recursive=False)[source]

remove a folder (Folder)

Parameters:folder (Folder) – the folder object
Returns:True if deleted, False if not
Return type:bool
deleteFolderContent(folder)[source]

delete all content from a folder (Folder)

Parameters:folder (Folder) – a folder object
Return state:returns true if successful, else False
Return type:bool
downloadObject(obj, workingDir=None)[source]

download the object into a ZIP file based on the object name and the working directory

Parameters:
  • obj (APIObject) – object
  • workingDir (Path) – workpath, where to store the zip
Returns:

None or filename
Return type:

str
downloadObjectPreviewImages(object, thumbnail=True)[source]
downloadZip(resource, fp)[source]

download the zipfile into the given file (fp)

Parameters:
  • resource (str) – download URL
  • fp (Path) – filepath
Returns:

None or status_code ok (200)
Return type:

int
fileObjectVersion(data)[source]

Extract VSDID and selfUrl of the related Object Version of the file after file upload

Parameters:data (json) – file object data
Result:returns the id and the selfUrl of the Object Version
Return type:str
fullUrl(resource)[source]

check if resource is selfUrl or relative path. a correct full path will be returned

Parameters:resource (str) – the api resource path
Returns:the full resource path
Return type:str
getAllPaginated(resource, itemlist=[])[source]

returns all items as list

Parameters:
  • resource (str) – resource path
  • itemlist (list) – list of items
Returns:

list of items
Return type:

list of Pagination objects
getAllUnpublishedObjects(resource='objects/unpublished')[source]

retrieve the unpublished objects as list of APIObject

Parameters:
  • resource (str) – resource path (eg nextPageUrl) or default groups
  • rpp (int) – results per page
  • page (int) – page to display
Returns:

list of objects
Return type:

APIObjects
getContainedFolders(folder)[source]

return a list of folder object contained in a folder

Parameters:folder (APIFolder) – folder object
Return folderlist:
 a list of folder object (APIFolder) contained in the folder
Return type:list of APIFolder
getContainedObjects(folder)[source]

return a list of object contained in a folder

Parameters:folder (APIFolder) – folder object
Return objlist:a list of objects (APIFObject) contained in the folder
Return type:list of APIObject
getFile(resource)[source]

return a APIFile object

Parameters:resource (str) – resource path
Returns:api file object or status code
Return type:APIFile
getFolder(resource)[source]

retrieve an folder based on the folderID/selfUrl

Parameters:resource (int,str) – (str) selfUrl of the folder or the (int) folder ID
Returns:the folder
Return type:APIFolder
getFolderByName(search, mode='default', squeeze=True)[source]

get a list of folder(s) based on a search string

Parameters:
  • search (str) – term to search for
  • mode (str) – search for partial match (‘default’) or exact match (‘exact’)
  • squeeze (bool) – ???? what is squeeze
Returns:

list of folder objects APIFolders
Return type:

list of APIFolders
getFolderContent(folder, recursive=False, mode='d')[source]

get the objects and folder contained in the given folder. can be called recursive to travel and return all objects

Parameters:
  • folder (APIFolder) – the folder to be read
  • recursive (bool) – travel the folder structure recursively or not (default)
  • mode (str) – what to return: only objects (o), only folders (f) or default (d) folders and objects
Return content:

dictionary with folders (APIBase) and object (APIBase)
Return type:

dict of APIBase
getGroup(resource)[source]

retrieve a group object (Group)

Parameters:resource (int,str) – path to the group id (int) or selfUrl (str)
Returns:group object
Return type:Group
getGroups(resource='groups', rpp=None, page=None)[source]

get the list of groups

Parameters:
  • resource (str) – resource path (eg nextPageUrl) or default groups
  • rpp (int) – results per page
  • page (int) – page number to display
Returns:

list of group objects
Return type:

Group
Returns:

pagination object
Return type:

Pagination
getJWTtoken()[source]

request the JWT token from the server using Basic Auth

Returns:token - a authentication token or None
Return type:Token or None
getLatestUnpublishedObject()[source]

searches the list of unpublished objects and returns the newest object

Returns:last uploaded object
Return type:apiObject
getLicense(resource)[source]

retrieve a license (License)

Parameters:resource (int,str) – resource path to the of the license
Return license:the license object
Return type:License
getLicenseList()[source]

retrieve a list of the available licenses (License)

Returns:list of available license objects
Return type:list of License
getModality(resource)[source]

retrieve a modalities object (APIModality)

Parameters:resource (int,str) – resource path to the of the modality
Returns:the modality object
Return type:Modality
getModalityList()[source]

retrieve a list of modalities objects (APIModality)

Returns:list of available modalities
Return type:list of Modality
getOID(selfURL)[source]

extracts the last part of the selfURL, tests if it is a number

Parameters:selfURL – (str) url to the object
Returns:either None if not an ID or the object ID (int)
Raises:ValueError
getObject(resource)[source]

retrieve an object based on the objectID/selfUrl

Parameters:resource (int,str) – (str) selfUrl of the object or the (int) object ID
Returns:the object
Return type:APIObject
getObjectFiles(obj)[source]

return a list of file objects contained in an object

Parameters:obj (APIObject) – object
Returns:list of APIFile
Return type:list of APIFile
getObjectFilesHash(obj)[source]

retrieve the filehash and the anonymized file hash values of a file

Parameters:f (APIObject) – API object
Returns:list of fileHash (uppercase)
Return type:list of str
getObjectGroupRights(obj)[source]

get the list of attaced group rights of an object

Parameters:obj (APIObject) – the object
Return rights:a list of ObjectGroupRights
Return type:list of APIObjectGroupRight
getObjectRight(resource)[source]

retrieve a object rights object (ObjectRight)

Parameters:resource (int,str) – resource to the permission id (int) or selfurl (str)
Returns:perm object
Return type:ObjectRight
getObjectRightList()[source]

retrieve a list of the available base object rights (ObjectRight)

Returns:list of object rights
Return type:list of ObjectRight
getObjectType(response)[source]

create an APIObject depending on the type

Parameters:response (json) – object data
Returns:object
Return type:APIObject
getObjectUserRights(obj)[source]

get the list of attaced user rights of an object

Parameters:obj (APIObject) – the object
Returns:a list of ObjectUserRights
Return type:list APIObjectUserRight
getObjects(idList=None)[source]

please describe what you are doing

Parameters:idList (???) –

???
Returns:
Return type:
getOntologyItem(resource, oType=0)[source]

Retrieve an ontology item object (APIOntology)

Parameters:
  • resource (int,str) – resource path to the of the ontology item
  • oType (int) – ontology type
Return onto:

the ontology item object
Return type:

Ontology
getOntologyTermByID(oid, oType=0)[source]

Retrieve an ontology entry based on the IRI

Parameters:
  • oid (int) – Identifier of the entry
  • oType (int) – Resource type, available resources can be found using the OPTIONS on /api/ontologies). Default resouce is FMA (0)
Returns:

ontology term entry
Return type:

json
getPaginated(resource)[source]

get paginated object

getPermissionSets(permset='default')[source]

get the Object Rights for a permission set

Parameters:permset (str) – name of the permission set: available are private, protect, default, collaborate, full or a list of permission ids (list)
Return perms:list of object rights objects
Return type:OjectRight
getRequest(resource, rpp=None, page=None, include=None)[source]

generic get request function

Parameters:
  • resource (str) – resource path
  • rpp (int) – results per page to show
  • page (int) – page nr to show, starts with 0
  • include (str) – option to include more informations
Returns:

list of objects or None
Return type:

json or None
getResource(url)[source]

please describe what you are doing

Param:
Returns:
Return type:
getResourceTypeAndId(url)[source]

please describe what you are doing

Param:
Returns:
Return type:
getUser(resource)[source]

retrieve a user object (User)

Parameters:resource (int,str) – path to the user resource id (int) or selfUrl (str)
Returns:user object
Return type:User
iterateAllPaginated(resource, func=<class 'dict'>)[source]

returns all items as list

Parameters:
  • resource (str) – resource path
  • func – function for converting resource
Returns:

iterator of items
Return type:

list of dict or model object
iteratePageItems(page, func=<class 'dict'>)[source]

returns all items as list

Parameters:
  • resource (str) – resource path
  • func – function for converting resource
Returns:

iterator of items
Return type:

list of dict or model object
optionsRequest(resource)[source]

generic options request function

Parameters:resource (str) – the api resource path
Returns:json data result or None
Return type:json or None
parseUrl(resource, type)[source]

check if the resource is int (ID) or the selfURL

Parameters:
  • resource (str) – url to the resource
  • type (str) – type of the api resource (folders, objects etc)
postFolder(parent, name, check=True)[source]

creates the folder with a given name (name) inside a folder (parent) if not already exists

Parameters:
  • parent (Folder) – the root folder
  • name (str) – name of the folder which should be created
  • check (bool) – it we should check if already exist, default = True
Returns:

the folder object of the generated folder or the existing folder
Return type:

Folder
postObjectGroupRights(obj, group, perms)[source]

translate a set of permissions and a group into the appropriate format and add it to the object

Parameters:
  • obj (Object) – the object you want to add the permissions to
  • group (Group) – group object
  • perms (list) – list of Object Rights (APIObjectRight), use getPermissionSet to retrive the ObjectRights based on the permission sets
Returns:

group rights object
Return type:

ObjectGroupRight
postObjectRights(obj, group, perms, isuser=False)[source]

translate a set of permissions and a group into the appropriate format and add it to the object

Warning

DEPRECATED: use postObjectGroupRights or postObjectUserRights!

Parameters:
  • obj (APIObject) – () the object you want to add the permissions to
  • group (APIGroup/APIUser) – group object or user object
  • perms (list) – list of Object Rights (APIObjectRight), use getPermissionSet to retrive the ObjectRights based on the permission sets
  • isuser (bool) – set True if the groups variable is a user. Default is False
Returns:

a group or user rights object
Return type:

APIObjectGroupRight,APIObjectUserRight
postObjectUserRights(obj, user, perms)[source]

translate a set of permissions and a user into the appropriate format and add it to the object

Parameters:
  • obj (Object) – the object you want to add the permissions to
  • user (User) – user object
  • perms (list) – list of Object Rights (APIObjectRight), use getPermissionSet to retrive the ObjectRights based on the permission sets
Returns:

user rights object
Return type:

ObjectUserRight
postRequest(resource, data)[source]

add data to an object

Parameters:
  • resource (str) – relative path of the resource or selfUrl
  • data (json) – data to be added to the resource
Returns:

the resource object
Return type:

json
Raises:

RequestException
postRequestSimple(resource)[source]

post (create) a resource

Parameters:resource (str) – resource path
Returns:the resource object
Return type:json
publishObject(obj)[source]

publisch an unvalidated object

Parameters:obj (APIObject) – the object to publish
Returns:returns the object
Return type:APIObject
putObject(obj)[source]

update an objects information

Parameters:obj (APIObject) – an APIObject
Returns:the updated object
Return type:APIObject
putRequest(resource, data)[source]

update data of an object

Parameters:
  • resource (str) – defines the relative path to the api resource
  • data (json) – data to be added to the object
Returns:

the updated object
Return type:

json
putRequestSimple(resource)[source]

put (update) a resource

Parameters:resource (str) – resource path
Returns:the resource object
Return type:json

removes all related item from an object

Parameters:resource (str) – resouce path url
Returns:True if successful or False if failed
Return type:bool
removeObjectFromFolder(target, obj)[source]

remove an object from the folder

Parameters:
  • target (APIFolder) – the target folder
  • obj (APIObject) – the object to remove
Returns:

updated folder
Return type:

APIFolder
searchOntologyTerm(search, oType='0', mode='default')[source]

Search ontology term in a single ontology resource. Two modes are available to either find the exact term or based on a partial match

Parameters:
  • search (str) – string to be searched
  • oType (int) – ontlogy resouce code, default is FMA (0)
  • mode (str) – find exact term (exact) or partial match (default)
Returns:

a list of ontology objects or a single ontology item
Return type:

APIOntolgy
searchTerm(resource, search, mode='default')[source]

search a resource using oAuths

Parameters:
  • resouce (str) – resource path
  • search (str) – term to search for
  • mode (str) – search for partial match (default) or exact match (exact)
Returns:

list of folder objects
Return type:

json
uploadFile(filename)[source]

push (post) a file to the server

Parameters:filename (Path) – the file to be uploaded
Returns:the file object containing the related object selfUrl
Return type:APIObject
walkFolder(folderUrl, topdown=True)[source]

please describe here

Param:
Returns:
Return type:
connect.samltoken(fp, stsurl='https://ciam-dev-chic.custodix.com/sts/services/STS')[source]

generates the saml auth token from a credentials file

Parameters:
  • fp (Path) – file with the credentials (xml file)
  • stsurl (str) – url to the STS authority
Returns:

enctoken - the encoded token
Return type:

byte