grequests: github.com/levigross/grequests Index | Examples | Files

package grequests

import "github.com/levigross/grequests"

Package grequests implements a friendly API over Go's existing net/http library

Code:

ro := &grequests.RequestOptions{InsecureSkipVerify: true}
resp, err := grequests.Get("https://www.pcwebshop.co.uk/", ro)

if err != nil {
    log.Println("Unable to make request", err)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

Code:

ro := &grequests.RequestOptions{Auth: []string{"Levi", "Bot"}}
resp, err := grequests.Get("http://httpbin.org/get", ro)
// Not the usual JSON so copy and paste from below

if err != nil {
    log.Println("Unable to make request", err)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

Code:

// This is a very basic GET request
resp, err := grequests.Get("http://httpbin.org/get", nil)

if err != nil {
    log.Println(err)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

log.Println(resp.String())

Code:

// This is a very basic GET request
resp, err := grequests.Get("http://httpbin.org/get", &grequests.RequestOptions{HTTPClient: http.DefaultClient})

if err != nil {
    log.Println(err)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

log.Println(resp.String())

Code:

resp, err := grequests.Get("http://httpbin.org/cookies",
    &grequests.RequestOptions{
        Cookies: []*http.Cookie{
            {
                Name:     "TestCookie",
                Value:    "Random Value",
                HttpOnly: true,
                Secure:   false,
            }, {
                Name:     "AnotherCookie",
                Value:    "Some Value",
                HttpOnly: true,
                Secure:   false,
            },
        },
    })

if err != nil {
    log.Println("Unable to make request", err)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

log.Println(resp.String())

Code:

ro := &grequests.RequestOptions{UserAgent: "LeviBot 0.1",
    Headers: map[string]string{"X-Wonderful-Header": "1"}}
resp, err := grequests.Get("http://httpbin.org/get", ro)
// Not the usual JSON so copy and paste from below

if err != nil {
    log.Println("Unable to make request", err)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

Code:

ro := &grequests.RequestOptions{UserAgent: "LeviBot 0.1"}
resp, err := grequests.Get("http://httpbin.org/get", ro)

if err != nil {
    log.Fatal("Oops something went wrong: ", err)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

log.Println(resp.String())

Code:

resp, err := grequests.Get("http://httpbin.org/get", nil)

if err != nil {
    log.Println("Unable to make request", err)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

if err := resp.DownloadToFile("randomFile"); err != nil {
    log.Println("Unable to download to file: ", err)
}

if err != nil {
    log.Println("Unable to download file", err)
}

Code:


fd, err := grequests.FileUploadFromDisk("test_files/mypassword")

if err != nil {
    log.Println("Unable to open file: ", err)
}

// This will upload the file as a multipart mime request
resp, err := grequests.Post("http://httpbin.org/post",
    &grequests.RequestOptions{
        Files: fd,
        Data:  map[string]string{"One": "Two"},
    })

if err != nil {
    log.Println("Unable to make request", resp.Error)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

Code:

resp, err := grequests.Post("http://httpbin.org/post",
    &grequests.RequestOptions{Data: map[string]string{"One": "Two"}})

// This is the basic form POST. The request body will be `one=two`

if err != nil {
    log.Println("Cannot post: ", err)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

Code:

resp, err := grequests.Post("http://httpbin.org/post",
    &grequests.RequestOptions{
        JSON:   map[string]string{"One": "Two"},
        IsAjax: true, // this adds the X-Requested-With: XMLHttpRequest header
    })

if err != nil {
    log.Println("Unable to make request", resp.Error)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

Code:


type XMLPostMessage struct {
    Name   string
    Age    int
    Height int
}

resp, err := grequests.Post("http://httpbin.org/post",
    &grequests.RequestOptions{XML: XMLPostMessage{Name: "Human", Age: 1, Height: 1}})
// The request body will contain the XML generated by the `XMLPostMessage` struct

if err != nil {
    log.Println("Unable to make request", resp.Error)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

Code:

proxyURL, err := url.Parse("http://127.0.0.1:8080") // Proxy URL
if err != nil {
    log.Panicln(err)
}

resp, err := grequests.Get("http://www.levigross.com/",
    &grequests.RequestOptions{Proxies: map[string]*url.URL{proxyURL.Scheme: proxyURL}})

if err != nil {
    log.Println(err)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

log.Println(resp)

Code:

session := grequests.NewSession(nil)

resp, err := session.Get("http://httpbin.org/cookies/set", &grequests.RequestOptions{Params: map[string]string{"one": "two"}})

if err != nil {
    log.Fatal("Cannot set cookie: ", err)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

log.Println(resp.String())

Code:

ro := &grequests.RequestOptions{
    Params: map[string]string{"Hello": "World", "Goodbye": "World"},
}
resp, err := grequests.Get("http://httpbin.org/get", ro)
// url will now be http://httpbin.org/get?hello=world&goodbye=world

if err != nil {
    log.Println("Unable to make request", err)
}

if resp.Ok != true {
    log.Println("Request did not return OK")
}

Index

Examples

Package Files

base.go file_upload.go request.go response.go session.go utils.go

Variables

var (
    // ErrRedirectLimitExceeded is the error returned when the request responded
    // with too many redirects
    ErrRedirectLimitExceeded = errors.New("grequests: Request exceeded redirect count")

    // RedirectLimit is a tunable variable that specifies how many times we can
    // redirect in response to a redirect. This is the global variable, if you
    // wish to set this on a request by request basis, set it within the
    // `RequestOptions` structure
    RedirectLimit = 30

    // SensitiveHTTPHeaders is a map of sensitive HTTP headers that a user
    // doesn't want passed on a redirect. This is the global variable, if you
    // wish to set this on a request by request basis, set it within the
    // `RequestOptions` structure
    SensitiveHTTPHeaders = map[string]struct{}{
        "Www-Authenticate":    {},
        "Authorization":       {},
        "Proxy-Authorization": {},
    }
)

func BuildHTTPClient Uses

func BuildHTTPClient(ro RequestOptions) *http.Client

BuildHTTPClient is a function that will return a custom HTTP client based on the request options provided the check is in UseDefaultClient

func EnsureTransporterFinalized Uses

func EnsureTransporterFinalized(httpTransport *http.Transport)

EnsureTransporterFinalized will ensure that when the HTTP client is GCed the runtime will close the idle connections (so that they won't leak) this function was adopted from Hashicorp's go-cleanhttp package

type FileUpload Uses

type FileUpload struct {
    // Filename is the name of the file that you wish to upload. We use this to guess the mimetype as well as pass it onto the server
    FileName string

    // FileContents is happy as long as you pass it a io.ReadCloser (which most file use anyways)
    FileContents io.ReadCloser

    // FieldName is form field name
    FieldName string

    // FileMime represents which mimetime should be sent along with the file.
    // When empty, defaults to application/octet-stream
    FileMime string
}

FileUpload is a struct that is used to specify the file that a User wishes to upload.

func FileUploadFromDisk Uses

func FileUploadFromDisk(fileName string) ([]FileUpload, error)

FileUploadFromDisk allows you to create a FileUpload struct slice by just specifying a location on the disk

func FileUploadFromGlob Uses

func FileUploadFromGlob(fileSystemGlob string) ([]FileUpload, error)

FileUploadFromGlob allows you to create a FileUpload struct slice by just specifying a glob location on the disk this function will gloss over all errors in the files and only upload the files that don't return errors from the glob

type RequestOptions Uses

type RequestOptions struct {

    // Data is a map of key values that will eventually convert into the
    // the body of a POST request.
    Data map[string]string

    // Params is a map of query strings that may be used within a GET request
    Params map[string]string

    // QueryStruct is a struct that encapsulates a set of URL query params
    // this paramter is mutually exclusive with `Params map[string]string` (they cannot be combined)
    // for more information please see https://godoc.org/github.com/google/go-querystring/query
    QueryStruct interface{}

    // Files is where you can include files to upload. The use of this data
    // structure is limited to POST requests
    Files []FileUpload

    // JSON can be used when you wish to send JSON within the request body
    JSON interface{}

    // XML can be used if you wish to send XML within the request body
    XML interface{}

    // Headers if you want to add custom HTTP headers to the request,
    // this is your friend
    Headers map[string]string

    // InsecureSkipVerify is a flag that specifies if we should validate the
    // server's TLS certificate. It should be noted that Go's TLS verify mechanism
    // doesn't validate if a certificate has been revoked
    InsecureSkipVerify bool

    // DisableCompression will disable gzip compression on requests
    DisableCompression bool

    // UserAgent allows you to set an arbitrary custom user agent
    UserAgent string

    // Host allows you to set an arbitrary custom host
    Host string

    // Auth allows you to specify a user name and password that you wish to
    // use when requesting the URL. It will use basic HTTP authentication
    // formatting the username and password in base64 the format is:
    // []string{username, password}
    Auth []string

    // IsAjax is a flag that can be set to make the request appear
    // to be generated by browser Javascript
    IsAjax bool

    // Cookies is an array of `http.Cookie` that allows you to attach
    // cookies to your request
    Cookies []*http.Cookie

    // UseCookieJar will create a custom HTTP client that will
    // process and store HTTP cookies when they are sent down
    UseCookieJar bool

    // Proxies is a map in the following format
    // *protocol* => proxy address e.g http => http://127.0.0.1:8080
    Proxies map[string]*url.URL

    // TLSHandshakeTimeout specifies the maximum amount of time waiting to
    // wait for a TLS handshake. Zero means no timeout.
    TLSHandshakeTimeout time.Duration

    // DialTimeout is the maximum amount of time a dial will wait for
    // a connect to complete.
    DialTimeout time.Duration

    // KeepAlive specifies the keep-alive period for an active
    // network connection. If zero, keep-alive are not enabled.
    DialKeepAlive time.Duration

    // RequestTimeout is the maximum amount of time a whole request(include dial / request / redirect)
    // will wait.
    RequestTimeout time.Duration

    // HTTPClient can be provided if you wish to supply a custom HTTP client
    // this is useful if you want to use an OAUTH client with your request.
    HTTPClient *http.Client

    // SensitiveHTTPHeaders is a map of sensitive HTTP headers that a user
    // doesn't want passed on a redirect.
    SensitiveHTTPHeaders map[string]struct{}

    // RedirectLimit is the acceptable amount of redirects that we should expect
    // before returning an error be default this is set to 30. You can change this
    // globally by modifying the `RedirectLimit` variable.
    RedirectLimit int

    // RequestBody allows you to put anything matching an `io.Reader` into the request
    // this option will take precedence over any other request option specified
    RequestBody io.Reader

    // CookieJar allows you to specify a special cookiejar to use with your request.
    // this option will take precedence over the `UseCookieJar` option above.
    CookieJar http.CookieJar

    // Context can be used to maintain state between requests https://golang.org/pkg/context/#Context
    Context context.Context

    // BeforeRequest is a hook that can be used to modify the request object
    // before the request has been fired. This is useful for adding authentication
    // and other functionality not provided in this library
    BeforeRequest func(req *http.Request) error

    // LocalAddr allows you to send the request on any local interface
    LocalAddr *net.TCPAddr
}

RequestOptions is the location that of where the data

type Response Uses

type Response struct {

    // Ok is a boolean flag that validates that the server returned a 2xx code
    Ok  bool

    // This is the Go error flag – if something went wrong within the request, this flag will be set.
    Error error

    // We want to abstract (at least at the moment) the Go http.Response object away. So we are going to make use of it
    // internal but not give the user access
    RawResponse *http.Response

    // StatusCode is the HTTP Status Code returned by the HTTP Response. Taken from resp.StatusCode
    StatusCode int

    // Header is a net/http/Header structure
    Header http.Header
    // contains filtered or unexported fields
}

Response is what is returned to a user when they fire off a request

func Delete Uses

func Delete(url string, ro *RequestOptions) (*Response, error)

Delete takes 2 parameters and returns a Response struct. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil

func DoRegularRequest Uses

func DoRegularRequest(requestVerb, url string, ro *RequestOptions) (*Response, error)

DoRegularRequest adds generic test functionality

func Get Uses

func Get(url string, ro *RequestOptions) (*Response, error)

Get takes 2 parameters and returns a Response Struct. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil

func Head(url string, ro *RequestOptions) (*Response, error)

Head takes 2 parameters and returns a Response channel. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil

func Options Uses

func Options(url string, ro *RequestOptions) (*Response, error)

Options takes 2 parameters and returns a Response struct. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil

func Patch Uses

func Patch(url string, ro *RequestOptions) (*Response, error)

Patch takes 2 parameters and returns a Response struct. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil

func Post Uses

func Post(url string, ro *RequestOptions) (*Response, error)

Post takes 2 parameters and returns a Response channel. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil

func Put Uses

func Put(url string, ro *RequestOptions) (*Response, error)

Put takes 2 parameters and returns a Response struct. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil

func Req Uses

func Req(verb string, url string, ro *RequestOptions) (*Response, error)

Req takes 3 parameters and returns a Response Struct. These three options are:

1. A verb
2. A URL
3. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil

func (*Response) Bytes Uses

func (r *Response) Bytes() []byte

Bytes returns the response as a byte array

func (*Response) ClearInternalBuffer Uses

func (r *Response) ClearInternalBuffer()

ClearInternalBuffer is a function that will clear the internal buffer that we use to hold the .String() and .Bytes() data. Once you have used these functions – you may want to free up the memory.

func (*Response) Close Uses

func (r *Response) Close() error

Close is part of our ability to support io.ReadCloser if someone wants to make use of the raw body

func (*Response) DownloadToFile Uses

func (r *Response) DownloadToFile(fileName string) error

DownloadToFile allows you to download the contents of the response to a file

func (*Response) JSON Uses

func (r *Response) JSON(userStruct interface{}) error

JSON is a method that will populate a struct that is provided `userStruct` with the JSON returned within the response body

func (*Response) Read Uses

func (r *Response) Read(p []byte) (n int, err error)

Read is part of our ability to support io.ReadCloser if someone wants to make use of the raw body

func (*Response) String Uses

func (r *Response) String() string

String returns the response as a string

func (*Response) XML Uses

func (r *Response) XML(userStruct interface{}, charsetReader XMLCharDecoder) error

XML is a method that will populate a struct that is provided `userStruct` with the XML returned within the response body

type Session Uses

type Session struct {
    // RequestOptions is global options
    RequestOptions *RequestOptions

    // HTTPClient is the client that we will use to request the resources
    HTTPClient *http.Client
}

Session allows a user to make use of persistent cookies in between HTTP requests

func NewSession Uses

func NewSession(ro *RequestOptions) *Session

NewSession returns a session struct which enables can be used to maintain establish a persistent state with the server This function will set UseCookieJar to true as that is the purpose of using the session

func (*Session) CloseIdleConnections Uses

func (s *Session) CloseIdleConnections()

CloseIdleConnections closes the idle connections that a session client may make use of

func (*Session) Delete Uses

func (s *Session) Delete(url string, ro *RequestOptions) (*Response, error)

Delete takes 2 parameters and returns a Response struct. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct

func (*Session) Get Uses

func (s *Session) Get(url string, ro *RequestOptions) (*Response, error)

Get takes 2 parameters and returns a Response Struct. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct

func (*Session) Head Uses

func (s *Session) Head(url string, ro *RequestOptions) (*Response, error)

Head takes 2 parameters and returns a Response channel. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct

func (*Session) Options Uses

func (s *Session) Options(url string, ro *RequestOptions) (*Response, error)

Options takes 2 parameters and returns a Response struct. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct

func (*Session) Patch Uses

func (s *Session) Patch(url string, ro *RequestOptions) (*Response, error)

Patch takes 2 parameters and returns a Response struct. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct

func (*Session) Post Uses

func (s *Session) Post(url string, ro *RequestOptions) (*Response, error)

Post takes 2 parameters and returns a Response channel. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct

func (*Session) Put Uses

func (s *Session) Put(url string, ro *RequestOptions) (*Response, error)

Put takes 2 parameters and returns a Response struct. These two options are:

1. A URL
2. A RequestOptions struct

If you do not intend to use the `RequestOptions` you can just pass nil A new session is created by calling NewSession with a request options struct

type XMLCharDecoder Uses

type XMLCharDecoder func(charset string, input io.Reader) (io.Reader, error)

XMLCharDecoder is a helper type that takes a stream of bytes (not encoded in UTF-8) and returns a reader that encodes the bytes into UTF-8. This is done because Go's XML library only supports XML encoded in UTF-8

Package grequests imports 24 packages (graph) and is imported by 64 packages. Updated 2019-01-30. Refresh now. Tools for package owners.