algorithmia

package module
v0.0.0-...-be7b2c1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 1, 2016 License: MIT Imports: 15 Imported by: 0

README

Algorithmia Common Library (Golang)

Golang client library for accessing the Algorithmia API.

For detailed library documentation, see the Godoc.

Table Of Contents

Install

go get github.com/algebraic-brain/algorithmia-go

Authentication

First, create an Algorithmia client and authenticate with your API key:

import (
	algorithmia "github.com/algebraic-brain/algorithmia-go"
)

var apiKey = "{{Your API key here}}"
var client = algorithmia.NewClient(apiKey, "")

Now you're ready to call algorithms.

Calling algorithms

The following examples of calling algorithms are organized by type of input/output which vary between algorithms.

Note: a single algorithm may have different input and output types, or accept multiple types of input, so consult the algorithm's description for usage examples specific to that algorithm.

Text input/output

Call an algorithm with text input by simply passing a string into its Pipe method. If the algorithm output is text, then the Result field of the response will be a string.

algo, _ := client.Algo("demo/Hello/0.1.1")
resp, _ := algo.Pipe("Author")
response := resp.(*algorithmia.AlgoResponse)
fmt.Println(response.Result)            //Hello Author
fmt.Println(response.Metadata)          //Metadata(content_type='text',duration=0.0002127)
fmt.Println(response.Metadata.Duration) //0.0002127
JSON input/output

Call an algorithm with JSON input by simply passing in a type that can be serialized to JSON. For algorithms that return JSON, the Result field of the response will be the appropriate deserialized type.

algo, _ := client.Algo("WebPredict/ListAnagrams/0.1.0")
resp, _ := algo.Pipe([]string{"transformer", "terraforms", "retransform"})
response := resp.(*algorithmia.AlgoResponse)
fmt.Println(response.Result) //[transformer retransform]
Binary input/output

Call an algorithm with binary input by passing a byte array into the Pipe method. Similarly, if the algorithm response is binary data, then the Result field of the response will be a byte array.

input, _ := ioutil.ReadFile("/path/to/bender.png")
algo, _ := client.Algo("opencv/SmartThumbnail/0.1")
resp, _ := algo.Pipe(input)
response := resp.(*algorithmia.AlgoResponse)
ioutil.WriteFile("thumbnail.png", response.Result.([]byte), 0666)
fmt.Println(response.Result) //[binary byte sequence]
Error handling

API errors and Algorithm exceptions will result in calls to Pipe returning an error:

algo, _ := client.Algo("util/whoopsWrongAlgo")
_, err := algo.Pipe("Hello, World!")
fmt.Println(err) //algorithm algo://util/whoopsWrongAlgo not found
Request options

The client exposes options that can configure algorithm requests. This includes support for changing the timeout or indicating that the API should include stdout in the response.

algo, _ = client.Algo("util/echo")
algo.SetOptions(algorithmia.AlgoOptions{Timeout: 60, Stdout: false})

Working with data

Create directories

Create directories by instantiating a DataDirectory object and calling Create:

client.Dir("data://.my/foo").Create(nil) //nil for default access control (private)
Upload files to a directory

Upload files by calling Put on a DataFile object.

foo := client.Dir("data://.my/foo")
foo.File("sample.txt").Put("sample text contents")
foo.File("binary_file").Put([]byte{72, 101, 108, 108, 111})

Note: you can instantiate a DataFile by either client.File(filepath) or client.Dir(path).File(filename)

Download contents of file

Download files by calling StringContents, Bytes, Json, or File on a DataFile object:

foo := client.Dir("data://.my/foo")
sampleText, _ := foo.File("sample.txt").StringContents() //string object
fmt.Println(sampleText)                                  //"sample text contents"

binaryContent, _ := foo.File("binary_file").Bytes()      //binary data
fmt.Println(string(binaryContent))                       //"Hello"

tempFile, _ := foo.File("binary_file").File()            //Open file descriptor for read
defer tempFile.Close()
binaryContent, _ = ioutil.ReadAll(tempFile)
fmt.Println(string(binaryContent))                       //"Hello"
Delete files and directories

Delete files and directories by calling Delete on their respective DataFile or DataDirectory object. DataDirectories have ForceDelete method that deletes the directory even it contains files or other directories.

foo := client.Dir("data://.my/foo")
foo.File("sample.txt").Delete()
foo.ForceDelete() // force deleting the directory and its contents
List directory contents

Iterate over the contents of a directory using the channel returned by calling List, Files, or Dirs on a DataDirectory object:

foo := client.Dir("data://.my/foo")

// List files in "foo"
for entry := range foo.Files() {
	if entry.Err == nil {
		file := entry.Object.(*algorithmia.DataFile)
		fmt.Println(file.Path(), "at URL:", file.Url(), "last modified:", file.LastModified())
	}
}

// List directories in "foo"
for entry := range foo.Dirs() {
	if entry.Err == nil {
		dir := entry.Object.(*algorithmia.DataDirectory)
		fmt.Println(dir.Path(), "at URL:", dir.Url())
	}
}

// List everything in "foo"
for entry := range foo.List() {
	if entry.Err == nil {
		fmt.Println(entry.Object.Path(), "at URL:", entry.Object.Url())
	}
}
Manage directory permissions

Directory permissions may be set when creating a directory, or may be updated on already existing directories.

foo := client.Dir("data://.my/foo")

//ReadAclPublic is a wrapper for &Acl{AclTypePublic} to make things easier
foo.Create(algorithmia.ReadAclPublic)

acl, _ := foo.Permissions()                             //Acl object
fmt.Println(acl.ReadAcl() == algorithmia.AclTypePublic) //true

foo.UpdatePermissions(algorithmia.ReadAclPrivate)
acl, _ = foo.Permissions()                               //Acl object
fmt.Println(acl.ReadAcl() == algorithmia.AclTypePrivate) //true

Running tests

To run all test files:

export ALGORITHMIA_API_KEY={{Your API key here}}
cd test
go test -v

To run particular test:

export ALGORITHMIA_API_KEY={{Your API key here}}
cd test
go test datadirlarge_test.go -v

Documentation

Overview

Algorithmia API Client (Go)

Index

Constants

This section is empty.

Variables

View Source 
var InvalidPath = errors.New("Invalid path")
View Source 
var NoAclProvided = errors.New("Response does not contain read ACL")
View Source 
var ReadAclMyAlgos = &Acl{AclTypeMyAlgos}
View Source 
var ReadAclPrivate = &Acl{AclTypePrivate}
View Source 
var ReadAclPublic = &Acl{AclTypePublic}

Functions

func PathJoin 

func PathJoin(parent, base string) string

Types

type Acl 

type Acl struct {
	// contains filtered or unexported fields
}

func (*Acl) ReadAcl 

func (a *Acl) ReadAcl() AclType

type AclType 

type AclType int
const (
	AclTypePublic AclType = iota
	AclTypeMyAlgos
	AclTypePrivate
	AclTypeDefault = AclTypeMyAlgos
)

func (AclType) AclString 

func (t AclType) AclString() string

func (AclType) Pseudonym 

func (t AclType) Pseudonym() string

func (AclType) String 

func (t AclType) String() string

type AlgoOptions 

type AlgoOptions struct {
	Timeout         int
	Stdout          bool
	Output          OutputType
	QueryParameters url.Values
}

type AlgoResponse 

type AlgoResponse struct {
	Result   interface{} `json:"result"`
	Metadata *Metadata   `json:"metadata"`
	Error    *Err        `json:"error"` //never set!
}

func (*AlgoResponse) String 

func (resp *AlgoResponse) String() string

type Algorithm 

type Algorithm struct {
	// contains filtered or unexported fields
}

func NewAlgorithm 

func NewAlgorithm(client *Client, ref string) (*Algorithm, error)

func (*Algorithm) Path 

func (algo *Algorithm) Path() string

func (*Algorithm) Pipe 

func (algo *Algorithm) Pipe(input1 interface{}) (interface{}, error)

Pipe an input into this algorithm

func (*Algorithm) SetOptions 

func (algo *Algorithm) SetOptions(opt AlgoOptions)

func (*Algorithm) Url 

func (algo *Algorithm) Url() string

type AsyncResponse 

type AsyncResponse struct {
	AsyncProtocol string `json:"async_protocol"`
	RequestId     string `json:"request_id"`
	Error         *Err   `json:"error"` //never set!
}

Response from the API for an asynchronous request (output=void)

func (*AsyncResponse) String 

func (resp *AsyncResponse) String() string

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(apiKey, apiAddress string) *Client

func (*Client) Algo 

func (c *Client) Algo(ref string) (*Algorithm, error)

func (*Client) Dir 

func (c *Client) Dir(dataUrl string) *DataDirectory

func (*Client) File 

func (c *Client) File(dataUrl string) *DataFile

type DataDirectory 

type DataDirectory struct {
	DataObjectType
	// contains filtered or unexported fields
}

func NewDataDirectory 

func NewDataDirectory(client *Client, dataUrl string) *DataDirectory

func (*DataDirectory) Create 

func (f *DataDirectory) Create(acl *Acl) error

Creates a directory, optionally include non-nil Acl argument to set permissions

func (*DataDirectory) Delete 

func (f *DataDirectory) Delete() error

Delete directory if it's empty

func (*DataDirectory) Dir 

func (f *DataDirectory) Dir(name string) *DataDirectory

func (*DataDirectory) Dirs 

func (f *DataDirectory) Dirs() <-chan SubobjectResult

func (*DataDirectory) Exists 

func (f *DataDirectory) Exists() (bool, error)

func (*DataDirectory) File 

func (f *DataDirectory) File(name string) *DataFile

func (*DataDirectory) Files 

func (f *DataDirectory) Files() <-chan SubobjectResult

func (*DataDirectory) ForceDelete 

func (f *DataDirectory) ForceDelete() error

Forcibly delete directory (even non-empty)

func (*DataDirectory) List 

func (f *DataDirectory) List() <-chan SubobjectResult

func (*DataDirectory) Name 

func (f *DataDirectory) Name() (string, error)

func (*DataDirectory) Path 

func (f *DataDirectory) Path() string

func (*DataDirectory) Permissions 

func (f *DataDirectory) Permissions() (*Acl, error)

Returns permissions for this directory or None if it's a special collection such as 

.session or .algo

func (*DataDirectory) SetAttributes 

func (f *DataDirectory) SetAttributes(attr *DirAttributes) error

func (*DataDirectory) UpdatePermissions 

func (f *DataDirectory) UpdatePermissions(acl *Acl) error

func (*DataDirectory) Url 

func (f *DataDirectory) Url() string

type DataFile 

type DataFile struct {
	DataObjectType
	// contains filtered or unexported fields
}

func NewDataFile 

func NewDataFile(client *Client, dataUrl string) *DataFile

func (*DataFile) Bytes 

func (f *DataFile) Bytes() ([]byte, error)

func (*DataFile) Delete 

func (f *DataFile) Delete() error

Delete from data api

func (*DataFile) Exists 

func (f *DataFile) Exists() (bool, error)

func (*DataFile) File 

func (f *DataFile) File() (*os.File, error)

Get file from the data api

func (*DataFile) Json 

func (f *DataFile) Json(x interface{}) error

func (*DataFile) LastModified 

func (f *DataFile) LastModified() time.Time

func (*DataFile) Name 

func (f *DataFile) Name() (string, error)

func (*DataFile) Path 

func (f *DataFile) Path() string

func (*DataFile) Put 

func (f *DataFile) Put(data interface{}) error

Post to data api

func (*DataFile) PutBytes 

func (f *DataFile) PutBytes(data []byte) error

func (*DataFile) PutFile 

func (f *DataFile) PutFile(fpath string) error

Post file to data api

func (*DataFile) PutJson 

func (f *DataFile) PutJson(data interface{}) error

Post json to data api

func (*DataFile) SetAttributes 

func (f *DataFile) SetAttributes(attr *FileAttributes) error

func (*DataFile) Size 

func (f *DataFile) Size() int64

func (*DataFile) StringContents 

func (f *DataFile) StringContents() (string, error)

func (*DataFile) Url 

func (f *DataFile) Url() string

type DataObject 

type DataObject interface {
	IsFile() bool         //Returns whether object is a file
	IsDir() bool          //Returns whether object is a directory
	Type() DataObjectType //Returns type of this DataObject
	Path() string
	Url() string
}

type DataObjectType 

type DataObjectType int
const (
	File DataObjectType = iota
	Directory
)
const DataObjectNone DataObjectType = -1

func (DataObjectType) IsDir 

func (obj DataObjectType) IsDir() bool

Returns whether object is a directory

func (DataObjectType) IsFile 

func (obj DataObjectType) IsFile() bool

Returns whether object is a file

func (DataObjectType) Type 

func (obj DataObjectType) Type() DataObjectType

Returns type of DataObject

type DirAttributes 

type DirAttributes struct {
	Name string `json:"name" mapstructure:"name"`
}

type Err 

type Err struct {
	Message    string `json:"message" mapstructure:"message"`
	Stacktrace string `json:"stacktrace" mapstructure:"stacktrace"`
}

func (*Err) Error 

func (e *Err) Error() string

type FileAttributes 

type FileAttributes struct {
	FileName     string `json:"filename"`
	LastModified string `json:"last_modified"`
	Size         int64  `json:"size"`
}

type Metadata 

type Metadata struct {
	ContentType string  `json:"content_type"`
	Duration    float64 `json:"duration"`
	Stdout      bool    `json:"stdout"`
}

func (*Metadata) String 

func (d *Metadata) String() string

type OutputType 

type OutputType int
const (
	Default OutputType = iota
	Raw
	Void
)

type SubobjectResult 

type SubobjectResult struct {
	Object DataObject
	Err    error
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.