Package: treillage
Unofficial Wrapper library for the Filevine APITreillage (tre-ˈyäzh): A lattice or framework for supporting vines.Treillage is an unofficial wrapper library for the Filevine API written in python.
This library is neither supported by or maintained by Filevine, Inc.Filevine's API DocumentationKey FeaturesLeverages asyncio to speed up IO bound requestsAutomatically refreshes session authentication tokensBuilt-in token bucket rate limitingAPI endpoints with built-in paginationTable of contentsInstallationGetting StartedUsing built-in endpointsUsing raw HTTP methodsBase URLRate Limiting and Connection ManagementExceptionsTreillageHTTPExceptionTreillageRateLimitExceptionTreillageTypeErrorTreillageValueErrorExamplesLibrary InstallationpipinstalltreillageGetting StartedThe only required parameter is a path to a yaml credentials file with the following keys:key,secret,queueid.
It should look like this:key:"fvpk_************************"secret:"fvsk_***********************************"queueid:"***********"These values are obtained from theFilevine developer portal.
The treillage module uses these credentials to obtain the accessToken and refreshToken for the authorization header.
These tokens are refreshed as needed throughout script execution.Using built-in endpointsfromtreillageimportTreillagefromtreillage.endpointsimportget_contact_listasyncwithTreillage(credentials_file="creds.yml")astr:asyncforcontactinget_contact_list(tr.conn,fields=['fullName','personId'],first_name='James'):print(contact['fullName'])This will request thepersonIdandfullNamefields for all contacts with the first name of 'James'.Using raw HTTP methodsIf there isn't a function written for the built-in endpoint you need, you can still use the rate limiting
and credential rotation featuresfromtreillageimportTreillageasyncwithTreillage(credentials_file="creds.yml")astr:query_parameters={'requestedFields':['fullName, personId'],'firstName':'James','offset':0,'limit':50}contacts=awaittr.conn.get(endpoint='/core/contacts',params=query_parameters)forcontactincontacts:print(contact['fullName'])This will request thepersonIdandfullNamefields for the first 50 contacts with the first name of 'James'.POST and DELETE work similarlyfromtreillageimportTreillageasyncwithTreillage(credentials_file="creds.yml")astr:# POST Examplebody={'firstName':'John','lastName':'Doe','fullName':'John Doe','gender':'M','personTypes':['Client']}response=awaittr.conn.post(endpoint='/core/contacts',body=body)# DELETE Exampleawaittr.conn.delete(endpoint='/core/documents/1234')Base URLThe base url for the server defaults to United States server athttps://api.filevine.io.
To access the Canada specific server pass in the base_url parameterfromtreillageimportTreillage,BaseURL# Use the built-in EnumasyncwithTreillage(credentials_file="creds.yml",base_url=BaseURL.CANADA)astr:# Pass in a stringasyncwithTreillage(credentials_file="creds.yml",base_url='https://api.filevine.ca')astr:Rate Limiting and Connection ManagementThe built-in rate limiter uses a token bucket technique. Each  web request consumes a token,
and tokens regenerate at a set rate. The bucket has a fixed capacity to keep the initial burst of requests
from exceeding the rate-limit. To keep things simple, the maximum number of tokens is equal to the amount regenerated
in one second.To use the built-in rate limiter, one additional parameters must be passed to the treillage object:requests_per_secondsets how many tokens are regenerated per second.If this parameter is not set, no rate-limiting will occur.asyncwithTreillage(credentials_file="creds.yml",requests_per_second=10)astr:tr.do_something()Additionally, the rate limiter will use an exponential backoff algorithm to
temporarily slow down requests when the server returns a HTTP 429 error (Rate Limit Exceeded).Alternatively the total number of simultaneous connections to the server can limited by passing
themax_connectionsparameter. Ifmax_connectionsis not set, the default value of100will be used.If you want to automatically retry a rate limited call, use the@retry_on_rate_limitdecorator to wrap the function
you want to be retried.@retry_on_rate_limitasyncdefget_some_data(tr:Treillage,endpoint):returnawaittr.conn.get(endpoint)some_data=awaitget_some_data(tr,'/some_data')ExceptionsThe treillage module includes several exceptions to make error handling easier.
All exceptions inherit fromTreillageException.TreillageHTTPExceptionInherits fromTreillageExceptionThis exception is raised when the API returns any non 200 status code.Parameters:code - The HTTP error codeurl - The url accessedmsg - The body of the server response or"Received non-2xx HTTP Status Code {code}"TreillageRateLimitExceptionInherits fromTreillageHTTPExceptionThis exception is raised when the API returns a 429 status code (Rate Limit Exceeded).Parameters:code - The HTTP error code.It will always be 429url - The url accessedmsg - The body of the server response or"Received non-2xx HTTP Status Code 429"TreillageTypeErrorInherits fromTreillageExceptionandTypeErrorRaised when a parameter for an endpoint does not match the required typeParametersmsgTreillageValueErrorInherits fromTreillageExceptionandValueErrorRaised when a parameter for an endpoint does not meet the requirements in the endpoint specification.
For example, a contact's personTypes must be in the list['Adjuster', 'Attorney', 'Client', 'Court', 'Defendant', 'Plaintiff', 'Expert', 'Firm', 'Insurance Company', 'Involved Party', 'Judge', 'Medical Provider']Parameters:msgExamplesTheexamplesfolder contains complete non-trivial examples of this module in use.