grequests

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

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

 Go to latest Published: Sep 28, 2019 License: MIT Imports: 22 Imported by: 0

README

grequests

A simple and user-friendly HTTP request library for Go, inspired by the well-known Python project requests.

Build Status Go Report Card GoDoc License

Features

  • GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, etc.
  • Easy set query params, headers and cookies.
  • Easy send form, JSON or files payload.
  • Easy set basic authentication or bearer token.
  • Easy customize root certificate authorities and client certificates.
  • Easy set proxy.
  • Automatic cookie management.
  • Customize HTTP client, transport, redirect policy, cookie jar and timeout.
  • Easy set context.
  • Easy serialize responses into JSON.
  • Concurrent safe.

Install

go get -u github.com/winterssy/grequests

Usage

import "github.com/winterssy/grequests"

Examples

Set Params
data, err := grequests.
    Get("http://httpbin.org/get").
    Params(grequests.Value{
        "key1": "value1",
        "key2": "value2",
    }).
    Send().
    Text()
if err != nil {
    panic(err)
}
fmt.Println(data)
Set Headers
data, err := grequests.
    Get("http://httpbin.org/get").
    Headers(grequests.Value{
        "Origin":  "http://httpbin.org",
        "Referer": "http://httpbin.org",
    }).
    Send().
    Text()
if err != nil {
    panic(err)
}
fmt.Println(data)
Set Cookies
data, err := grequests.
    Get("http://httpbin.org/cookies/set").
    Cookies(
        &http.Cookie{
            Name:  "name1",
            Value: "value1",
        },
        &http.Cookie{
            Name:  "name2",
            Value: "value2",
        },
    ).
    Send().
    Text()
if err != nil {
    panic(err)
}
fmt.Println(data)
Set Form Payload
data, err := grequests.
    Post("http://httpbin.org/post").
    Form(grequests.Value{
        "key1": "value1",
        "key2": "value2",
    }).
    Send().
    Text()
if err != nil {
    panic(err)
}
fmt.Println(data)
Set JSON Payload
data, err := grequests.
    Post("http://httpbin.org/post").
    JSON(grequests.Data{
        "msg": "hello world",
        "num": 2019,
    }).
    Send().
    Text()
if err != nil {
    panic(err)
}
fmt.Println(data)
Set Files Payload
data, err := grequests.
    Post("http://httpbin.org/post").
    Files(
        &grequests.File{
            FieldName: "testimage1",
            FileName:  "testimage1.jpg",
            FilePath:  "./testdata/testimage1.jpg",
        },
        &grequests.File{
            FieldName: "testimage2",
            FileName:  "testimage2.jpg",
            FilePath:  "./testdata/testimage2.jpg",
        },
    ).
    Send().
    Text()
if err != nil {
    panic(err)
}
fmt.Println(data)
Set Basic Authentication
data, err := grequests.
    Get("http://httpbin.org/basic-auth/admin/pass").
    BasicAuth("admin", "pass").
    Send().
    Text()
if err != nil {
    panic(err)
}
fmt.Println(data)
Set Bearer Token
data, err := grequests.
    Get("http://httpbin.org/bearer").
    BearerToken("grequests").
    Send().
    Text()
if err != nil {
    panic(err)
}
fmt.Println(data)
Customize HTTP Client
transport := &http.Transport{
    Proxy: http.ProxyFromEnvironment,
    DialContext: (&net.Dialer{
        Timeout:   30 * time.Second,
        KeepAlive: 30 * time.Second,
    }).DialContext,
    MaxIdleConns:          100,
    IdleConnTimeout:       90 * time.Second,
    TLSHandshakeTimeout:   10 * time.Second,
    ExpectContinueTimeout: 1 * time.Second,
}
redirectPolicy := func(req *http.Request, via []*http.Request) error {
    return http.ErrUseLastResponse
}
jar, _ := cookiejar.New(&cookiejar.Options{
    PublicSuffixList: publicsuffix.List,
})
timeout := 120 * time.Second

req := grequests.
    WithTransport(transport).
    WithRedirectPolicy(redirectPolicy).
    WithCookieJar(jar).
    WithTimeout(timeout)

data, err := req.
    Get("http://httpbin.org/get").
    Send().
    Text()
if err != nil {
    panic(err)
}
fmt.Println(data)
Set Proxy
data, err := grequests.
    WithProxy("http://127.0.0.1:1081").
    Get("http://httpbin.org/get").
    Send().
    Text()
if err != nil {
    panic(err)
}
fmt.Println(data)
Concurrent Safe
const MaxWorker = 1000
wg := new(sync.WaitGroup)

for i := 0; i < MaxWorker; i += 1 {
    wg.Add(1)
    go func(i int) {
        defer wg.Done()

        params := grequests.Value{}
        params.Set(fmt.Sprintf("key%d", i), fmt.Sprintf("value%d", i))

        data, err := grequests.
            AcquireLock().
            Get("http://httpbin.org/get").
            Params(params).
            Send().
            Text()
        if err != nil {
            return
        }

        fmt.Println(data)
    }(i)
}

wg.Wait()

License

MIT.

Thanks

Documentation

Index

Constants

View Source 
const (
	// Version of grequests.
	Version = "0.1"

	// ContentType is the same as "Content-Type".
	ContentType = "Content-Type"

	// TypeForm is the same as "application/x-www-form-urlencoded".
	TypeForm = "application/x-www-form-urlencoded"

	// TypeJSON is the same as "application/json".
	TypeJSON = "application/json"

	// MethodGet represents GET HTTP method
	MethodGet = "GET"

	// MethodHead represents HEAD HTTP method
	MethodHead = "HEAD"

	// MethodPost represents POST HTTP method
	MethodPost = "POST"

	// MethodPut represents PUT HTTP method
	MethodPut = "PUT"

	// MethodPatch represents PATCH HTTP method
	MethodPatch = "PATCH"

	// MethodDelete represents DELETE HTTP method
	MethodDelete = "DELETE"

	// MethodConnect represents CONNECT HTTP method
	MethodConnect = "CONNECT"

	// MethodOptions represents OPTIONS HTTP method
	MethodOptions = "OPTIONS"

	// MethodTrace represents TRACE HTTP method
	MethodTrace = "TRACE"
)

Variables

This section is empty.

Functions

func Reset 

func Reset()

Reset resets state of the default client.

Types

type Client 

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

Client defines a client.

func AcquireLock 

func AcquireLock() *Client

AcquireLock locks the default client. Use grequests across goroutines you must call AcquireLock for each request in the beginning. Necessary, otherwise might cause data race.

func BasicAuth 

func BasicAuth(username, password string) *Client

BasicAuth sets basic authentication of the default client.

func BearerToken 

func BearerToken(token string) *Client

BearerToken sets bearer token of the default client.

func Connect 

func Connect(url string) *Client

Connect uses the default client to make CONNECT HTTP requests.

func Cookies 

func Cookies(cookies ...*http.Cookie) *Client

Cookies sets cookies of the default client.

func Delete 

func Delete(url string) *Client

Delete uses the default client to make DELETE HTTP requests.

func DisableKeepAlives 

func DisableKeepAlives() *Client

DisableKeepAlives disables HTTP keep-alives of the default client. HTTP keep-alives is enabled by default.

func DisableProxy 

func DisableProxy() *Client

DisableProxy lets the default client not use proxy. grequests uses proxy from environment by default.

func DisableRedirect 

func DisableRedirect() *Client

DisableRedirect lets the default client not redirect HTTP requests. HTTP requests redirection is enabled by default.

func DisableSession 

func DisableSession() *Client

DisableSession lets the default client not use cookie jar. Session is enabled by default, grequests use cookie jar to manage cookie automatically.

func DisableVerify 

func DisableVerify() *Client

DisableVerify lets the default client not verify the server's TLS certificate. TLS certificate verification is enabled by default.

func Files 

func Files(files ...*File) *Client

Files sets files payload of the default client.

func Form 

func Form(form Value) *Client

Form sets form payload of the default client.

func Get 

func Get(url string) *Client

Get uses the default client to make GET HTTP requests. 

func Head(url string) *Client

Head uses the default client to make HEAD HTTP requests.

func Headers 

func Headers(headers Value) *Client

Headers sets headers of the default client.

func JSON 

func JSON(data Data) *Client

JSON sets JSON payload of the default client.

func New 

func New() *Client

New constructors and returns a new client.

func Options 

func Options(url string) *Client

Options uses the default client to make OPTIONS HTTP requests.

func Params 

func Params(params Value) *Client

Params sets query params of the default client.

func Patch 

func Patch(url string) *Client

Patch uses the default client to make PATCH HTTP requests.

func Post 

func Post(url string) *Client

Post uses the default client to make POST HTTP requests.

func Put 

func Put(url string) *Client

Put uses the default client to make PUT HTTP requests.

func Trace 

func Trace(url string) *Client

Trace uses the default client to make TRACE HTTP requests.

func WithClientCertificates 

func WithClientCertificates(certs ...tls.Certificate) *Client

WithClientCertificates appends client certificates of the default client.

func WithContext 

func WithContext(ctx context.Context) *Client

WithContext sets context of the default client.

func WithCookieJar 

func WithCookieJar(jar http.CookieJar) *Client

WithCookieJar sets cookie jar of the default client.

func WithProxy 

func WithProxy(url string) *Client

WithProxy sets proxy of the default client from a url.

func WithRedirectPolicy 

func WithRedirectPolicy(policy func(req *http.Request, via []*http.Request) error) *Client

WithRedirectPolicy sets redirect policy of the default client.

func WithRootCAs 

func WithRootCAs(pemFilePath string) *Client

WithRootCAs appends root certificate authorities of the default client.

func WithTimeout 

func WithTimeout(timeout time.Duration) *Client

WithTimeout sets timeout of the default client.

func WithTransport 

func WithTransport(transport http.RoundTripper) *Client

WithTransport sets transport of the default client.

func (*Client) AcquireLock 

func (c *Client) AcquireLock() *Client

AcquireLock locks c. Use grequests across goroutines you must call AcquireLock for each request in the beginning. Necessary, otherwise might cause data race.

func (*Client) BasicAuth 

func (c *Client) BasicAuth(username, password string) *Client

BasicAuth sets basic authentication of c.

func (*Client) BearerToken 

func (c *Client) BearerToken(token string) *Client

BearerToken sets bearer token of c.

func (*Client) Connect 

func (c *Client) Connect(url string) *Client

Connect uses c to make CONNECT HTTP requests.

func (*Client) Cookies 

func (c *Client) Cookies(cookies ...*http.Cookie) *Client

Cookies sets cookies of c.

func (*Client) Delete 

func (c *Client) Delete(url string) *Client

Delete uses c to make DELETE HTTP requests.

func (*Client) DisableKeepAlives 

func (c *Client) DisableKeepAlives() *Client

DisableKeepAlives disables HTTP keep-alives of c. HTTP keep-alives is enabled by default.

func (*Client) DisableProxy 

func (c *Client) DisableProxy() *Client

DisableProxy lets c not use proxy. grequests uses proxy from environment by default.

func (*Client) DisableRedirect 

func (c *Client) DisableRedirect() *Client

DisableRedirect lets c not redirect HTTP requests. HTTP requests redirection is enabled by default.

func (*Client) DisableSession 

func (c *Client) DisableSession() *Client

DisableSession lets c not use cookie jar. Session is enabled by default, grequests use cookie jar to manage cookie automatically.

func (*Client) DisableVerify 

func (c *Client) DisableVerify() *Client

DisableVerify lets c not verify the server's TLS certificate. TLS certificate verification enabled by default.

func (*Client) Files 

func (c *Client) Files(files ...*File) *Client

Files sets files payload of c.

func (*Client) Form 

func (c *Client) Form(form Value) *Client

Form sets form payload of c.

func (*Client) Get 

func (c *Client) Get(url string) *Client

Get uses c to make GET HTTP requests.

func (*Client) Head 

func (c *Client) Head(url string) *Client

Head uses c to make HEAD HTTP requests.

func (*Client) Headers 

func (c *Client) Headers(headers Value) *Client

Headers sets headers of c.

func (*Client) JSON 

func (c *Client) JSON(data Data) *Client

JSON sets JSON payload of c.

func (*Client) Options 

func (c *Client) Options(url string) *Client

Options uses c to make OPTIONS HTTP requests.

func (*Client) Params 

func (c *Client) Params(params Value) *Client

Params sets query params of c.

func (*Client) Patch 

func (c *Client) Patch(url string) *Client

Patch uses c to make PATCH HTTP requests.

func (*Client) Post 

func (c *Client) Post(url string) *Client

Post uses c to make POST HTTP requests.

func (*Client) Put 

func (c *Client) Put(url string) *Client

Put uses c to make PUT HTTP requests.

func (*Client) Reset 

func (c *Client) Reset()

Reset resets state of c so that other requests can acquire lock.

func (*Client) Send 

func (c *Client) Send() *Response

Send uses c to send the HTTP request and returns the response.

func (*Client) Trace 

func (c *Client) Trace(url string) *Client

Trace uses c to make TRACE HTTP requests.

func (*Client) WithClientCertificates 

func (c *Client) WithClientCertificates(certs ...tls.Certificate) *Client

WithClientCertificates appends client certificates of c.

func (*Client) WithContext 

func (c *Client) WithContext(ctx context.Context) *Client

WithContext sets context of c.

func (*Client) WithCookieJar 

func (c *Client) WithCookieJar(jar http.CookieJar) *Client

WithCookieJar sets cookie jar of c.

func (*Client) WithProxy 

func (c *Client) WithProxy(url string) *Client

WithProxy sets proxy of c from a url.

func (*Client) WithRedirectPolicy 

func (c *Client) WithRedirectPolicy(policy func(req *http.Request, via []*http.Request) error) *Client

WithRedirectPolicy sets redirect policy of c.

func (*Client) WithRootCAs 

func (c *Client) WithRootCAs(pemFilePath string) *Client

WithRootCAs appends root certificate authorities of c.

func (*Client) WithTimeout 

func (c *Client) WithTimeout(timeout time.Duration) *Client

WithTimeout sets timeout of c.

func (*Client) WithTransport 

func (c *Client) WithTransport(transport http.RoundTripper) *Client

WithTransport sets transport of c.

type Data 

type Data map[string]interface{}

Data is the same as map[string]interface{}, used for JSON payload.

func (Data) Del 

func (d Data) Del(key string)

Del deletes the value related to the given key from a map.

func (Data) Get 

func (d Data) Get(key string) interface{}

Get gets the value from a map by the given key.

func (Data) Set 

func (d Data) Set(key string, value interface{})

Set sets a kv pair into a map.

type File 

type File struct {
	FieldName string
	FileName  string
	FilePath  string
}

File defines a multipart-data.

type Response 

type Response struct {
	R   *http.Response
	Err error
}

Response wrap HTTP response and request error.

func Send 

func Send() *Response

Send uses the default client to send the HTTP request and returns the response.

func (*Response) EnsureStatus2xx 

func (r *Response) EnsureStatus2xx(httpResp *http.Response) *Response

EnsureStatus2xx ensures the HTTP response status code of r must be 2xx.

func (*Response) EnsureStatusOk 

func (r *Response) EnsureStatusOk() *Response

EnsureStatusOk ensures the HTTP response status code of r must be 200.

func (*Response) JSON 

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

JSON reads the HTTP response of r and unmarshals it.

func (*Response) Raw 

func (r *Response) Raw() ([]byte, error)

Raw reads the HTTP response of r and returns a []byte.

func (*Response) Resolve 

func (r *Response) Resolve() (*http.Response, error)

Resolve resolves r and returns the original HTTP response.

func (*Response) Text 

func (r *Response) Text() (string, error)

Text reads the HTTP response of r and returns a string.

type Value 

type Value map[string]string

Value is the same as map[string]string, used for params, headers, form-data, etc.

func (Value) Del 

func (v Value) Del(key string)

Del deletes the value related to the given key from a map.

func (Value) Get 

func (v Value) Get(key string) string

Get gets the value from a map by the given key.

func (Value) Set 

func (v Value) Set(key string, value string)

Set sets a kv pair into a map.

Source Files

View all Source files

Directories

Path Synopsis

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.