Unofficial Wrapper library for the Filevine API

Treillage (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 Documentation

Key Features

• Leverages asyncio to speed up IO bound requests
• Automatically refreshes session authentication tokens
• Built-in token bucket rate limiting
• API endpoints with built-in pagination

Table of contents

• Installation
• Getting Started
  • Using built-in endpoints
  • Using raw HTTP methods
  • Base URL
• Rate Limiting and Connection Management
• Exceptions
  • TreillageHTTPException
  • TreillageRateLimitException
  • TreillageTypeError
  • TreillageValueError
• Examples

Library Installation

pip install treillage

Getting Started

The 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 the Filevine 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 endpoints

from treillage import Treillage
from treillage.endpoints import get_contact_list

async with Treillage(credentials_file="creds.yml") as tr:
    async for contact in get_contact_list(tr.conn, fields=['fullName', 'personId'], first_name='James'):
        print(contact['fullName'])

This will request the personId and fullName fields for all contacts with the first name of 'James'.

Using raw HTTP methods

If there isn't a function written for the built-in endpoint you need, you can still use the rate limiting and credential rotation features

from treillage import Treillage

async with Treillage(credentials_file="creds.yml") as tr:
    query_parameters = {'requestedFields': ['fullName, personId'], 'firstName': 'James', 'offset': 0, 'limit': 50}
    contacts = await tr.conn.get(endpoint='/core/contacts', params=query_parameters)
    for contact in contacts:
        print(contact['fullName'])

This will request the personId and fullName fields for the first 50 contacts with the first name of 'James'.

POST and DELETE work similarly

from treillage import Treillage

async with Treillage(credentials_file="creds.yml") as tr:
    # POST Example
    body = {
        'firstName' : 'John',
        'lastName' : 'Doe',
        'fullName' : 'John Doe',
        'gender': 'M',
        'personTypes': ['Client'] 
    }
    response = await tr.conn.post(endpoint='/core/contacts', json=body)
    # DELETE Example
    await tr.conn.delete(endpoint='/core/documents/1234')

Base URL

The base url for the server defaults to United States server at https://api.filevine.io. To access the Canada specific server pass in the base_url parameter

from treillage import Treillage, BaseURL

# Use the built-in Enum
async with Treillage(credentials_file="creds.yml", base_url=BaseURL.CANADA) as tr:

# Pass in a string
async with Treillage(credentials_file="creds.yml", base_url='https://api.filevine.ca') as tr:

Rate Limiting and Connection Management

The 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 use the built-in rate limiter, two parameters must be passed to the filevine object:

• rate_limit_max_tokens sets the capacity of the token bucket
• rate_limit_token_regen_rate sets how many tokens are regenerated per second.

If either one of the parameters is not set, no rate-limiting will occur.

async with Treillage(credentials_file="creds.yml", rate_limit_max_tokens=10, rate_limit_token_regen_rate=10) as tr:
    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 the max_connections parameter. If max_connections is not set, the default value of 100 will be used.

Exceptions

The treillage module includes several exceptions to make error handling easier. All exceptions inherit from TreillageException.

TreillageHTTPException

• Inherits from TreillageException
• This exception is raised when the API returns any non 200 status code.
• Parameters:
  • code - The HTTP error code
  • url - The url accessed
  • msg - The body of the server response or "Received non-2xx HTTP Status Code {code}"

TreillageRateLimitException

• Inherits from TreillageHTTPException
• This exception is raised when the API returns a 429 status code (Rate Limit Exceeded).
• Parameters:
  • code - The HTTP error code. It will always be 429
  • url - The url accessed
  • msg - The body of the server response or "Received non-2xx HTTP Status Code 429"

TreillageTypeError

• Inherits from TreillageException and TypeError
• Raised when a parameter for an endpoint does not match the required type
• Parameters
  • msg

TreillageValueError

• Inherits from TreillageException and ValueError
• Raised 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:
  • msg

Examples

The examples folder contains complete non-trivial examples of this module in use.