Giftless Client

A Git LFS client library implemented in Python, compatible with Git LFS servers in general and specifically Giftless Git LFS server.

giftless-client is tested on Python 2.7 and 3.6+.

Installation

You can install this library directly from pypi:

(venv) $ pip install giftless-client

API

This module exposes one main class: LfsClient. Typically, you only need to use this class to perform most Git LFS operations. The client provides both a wrapper around the low-level LFS API commands e.g. batch as well as higher level methods to upload and download files.

Instantiating a Client

from giftless_client import LfsClient

client = LfsClient(
    lfs_server_url='https://git-lfs.example.com', # Git LFS server URL
    auth_token='somer4nd0mT0ken==',               # Bearer token if required by the server (optional)
    transfer_adapters=['basic']                   # Enabled transfer adapters (optional)
)

The transfer_adapters parameter is optional, and represents a list of supported transfer adapters by priority to negotiate with the server; Typically, there is no reason to provide this parameter.

Downloading a File from LFS storage

Download a file and save it to file like object.

download(file_obj, object_sha256, object_size, organization, repo, **extras)

file_obj is expected to be an file-like object open for writing in binary mode
object_sha256: sha256 of the object you wish to download
object_size: size of the object you wish to download
organization, repo: used to generate the prefix for the batch request in form organization/repo
extras are added to the batch request attributes dict prefixed with x-. This is largely Giftless specific.

Note that the download itself is performed by the selected Transfer Adapter.

Uploading a File to LFS storage

Upload a file to LFS storage

upload(file_obj, organization, repo, **extras)

file_obj: a readable, seekable file-like object
Other arguments as per download

Note that the upload itself is performed by the selected Transfer Adapter.

Sending an LFS `batch` API request

Send a batch request to the LFS server:

batch(prefix, operation, objects, ref=None, transfers=None)

prefix: add to LFS server url e.g. if prefix=abc and client was created with server url of https://git-lfs.example.com then batch request is made by POST to https://git-lfs.example.com/abc/objects/batch
All other arguments: see batch command for definitions

Example:

client.batch(
  prefix='myorg/myrepo',
  operation='download',
  objects={
      "oid": "12345678",
      "size": 123
    }
)

Usage in Command Line

While the main use for giftless-client is as a client library for other projects, this module does include some command line functionality.

Run the following command to get more information:

(venv) $ giftless-client --help

License

Giftless Client is free software distributed under the terms of the MIT license. See LICENSE for details.

datopian/giftless-client