From 5251112d7e256deb79c2ba0ecf1abf09b89a8fcf Mon Sep 17 00:00:00 2001 From: liron navon Date: Tue, 20 Mar 2018 01:43:56 +0200 Subject: [PATCH 1/4] added idea (goland) to gitignore and updated documentation #242 --- .gitignore | 1 + README | 141 +++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 117 insertions(+), 25 deletions(-) diff --git a/.gitignore b/.gitignore index db912a1..8cafa97 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,5 @@ *.swn conf.sh *.patch +.idea/ anaconda.test diff --git a/README b/README index 47200eb..3618687 100644 --- a/README +++ b/README @@ -1,28 +1,41 @@ Anaconda ======== + [![Build Status](https://travis-ci.org/ChimeraCoder/anaconda.svg?branch=master)](https://travis-ci.org/ChimeraCoder/anaconda) [![Build Status](https://ci.appveyor.com/api/projects/status/63pi6csod8bps80i/branch/master?svg=true)](https://ci.appveyor.com/project/ChimeraCoder/anaconda/branch/master) [![GoDoc](https://godoc.org/github.com/ChimeraCoder/anaconda?status.svg)](https://godoc.org/github.com/ChimeraCoder/anaconda) + Anaconda is a simple, transparent Go package for accessing version 1.1 of the Twitter API. + Successful API queries return native Go structs that can be used immediately, with no need for type assertions. +For more information and a complete api please see the [GoDoc.](https://godoc.org/github.com/ChimeraCoder/anaconda) + + Examples -------- + ### Authentication + If you already have the access token (and secret) for your user (Twitter provides this for your own account on the developer portal), creating the client is simple: + ```go -api := anaconda.NewTwitterApiWithCredentials("your-access-token", "your-access-token-secret", "your-consumer-key", "your-consumer-secret") +api := anaconda.NewTwitterApiWithCredentials("user-token", "user-token-secret", "your-consumer-key", "your-consumer-secret") ``` + ### Queries +Almost all of anaconda's methods require the Values struct from the ["net/url" package](https://golang.org/pkg/net/url/) + + +Queries are methods of an authenticated `TwitterApi` struct. In v1.1 of Twitter's API, all requests should be authenticated. -Queries are conducted using a pointer to an authenticated `TwitterApi` struct. In v1.1 of Twitter's API, all requests should be authenticated. ```go searchResult, _ := api.GetSearch("golang", nil) @@ -32,6 +45,7 @@ for _ , tweet := range searchResult.Statuses { ``` Certain endpoints allow separate optional parameter; if desired, these can be passed as the final parameter. + ```go //Perhaps we want 30 values instead of the default 15 v := url.Values{} @@ -39,95 +53,154 @@ v.Set("count", "30") result, err := api.GetSearch("golang", v) ``` + (Remember that `url.Values` is equivalent to a `map[string][]string`, if you find that more convenient notation when specifying values). Otherwise, `nil` suffices. + ### Streaming + Anaconda supports the Streaming APIs. You can use `PublicStream*` or `UserStream` API methods. -A go loop is started an gives you an stream that sends `interface{}` objects through it's `chan` `C` +A go loop is started and gives you a stream that sends `interface{}` objects through it's `chan` `C` Objects which you can cast into a tweet, event and more. +Some services like [FireHose](https://developer.twitter.com/en/docs/tweets/compliance/api-reference/compliance-firehose) and [Decahose](https://developer.twitter.com/en/docs/tweets/sample-realtime/overview/decahose) require enterprise access to the twitter api. + + +Example for the PublicStreamFilter ([statuses/filter](https://developer.twitter.com/en/docs/tweets/filter-realtime/overview)) ````go -v := url.Values{} -s := api.UserStream(v) - -for t := range s.C { - switch v := t.(type) { - case anaconda.Tweet: - fmt.Printf("%-15s: %s\n", v.User.ScreenName, v.Text) - case anaconda.EventTweet: - switch v.Event.Event { - case "favorite": - sn := v.Source.ScreenName - tw := v.TargetObject.Text - fmt.Printf("Favorited by %-15s: %s\n", sn, tw) - case "unfavorite": - sn := v.Source.ScreenName - tw := v.TargetObject.Text - fmt.Printf("UnFavorited by %-15s: %s\n", sn, tw) - } - } +values := url.Values{} +values.Set("track", "#golang,#go,#anaconda,#ChimeraCoder,#fakenews,#twitter-dev") +stream := api.UserStream(values) +counter := 0 + +for data := range s.C { + tweet, ok := data.(anaconda.Tweet) + if ok { + fmt.Println(tweet.Text) + counter += 1 + if(counter == 50) { + // close the channel and release resources of this stream + api.Close() + } + } +} +```` + + +Example for the UserStream +````go +values := url.Values{} +stream := api.UserStream(values) + + +for data := range stream.C { + switch tweet := data.(type) { + case anaconda.Tweet: + fmt.Printf("%-15s: %s\n", tweet.User.ScreenName, tweet.Text) + case anaconda.EventTweet: + switch tweet.Event.Event { + case "favorite": + screenName := tweet.Source.ScreenName + text := tweet.TargetObject.Text + fmt.Printf("Favorited by %-15s: %s\n", screenName, text) + case "unfavorite": + screenName := tweet.Source.ScreenName + text := tweet.TargetObject.Text + fmt.Printf("UnFavorited by %-15s: %s\n", screenName, text) + } + } } ```` +For more information about streaming and streaming parameter please view the [Standard streaming API request parameters](https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters) + + + Endpoints --------- + Anaconda implements most of the endpoints defined in the [Twitter API documentation](https://developer.twitter.com/en/docs). For clarity, in most cases, the function name is simply the name of the HTTP method and the endpoint (e.g., the endpoint `GET /friendships/incoming` is provided by the function `GetFriendshipsIncoming`). -In a few cases, a shortened form has been chosen to make life easier (for example, retweeting is simply the function `Retweet`) + +In a few cases, a shortened form has been chosen to make life easier (for example, retweeting is simply the function `Retweet`). + Error Handling, Rate Limiting, and Throttling --------------------------------------------- + ### Error Handling + Twitter errors are returned as an `ApiError`, which satisfies the `error` interface and can be treated as a vanilla `error`. However, it also contains the additional information returned by the Twitter API that may be useful in deciding how to proceed after encountering an error. + + If you make queries too quickly, you may bump against Twitter's [rate limits](https://developer.twitter.com/en/docs/basics/rate-limits). If this happens, `anaconda` automatically retries the query when the rate limit resets, using the `X-Rate-Limit-Reset` header that Twitter provides to determine how long to wait. + In other words, users of the `anaconda` library should not need to handle rate limiting errors themselves; this is handled seamlessly behind-the-scenes. If an error is returned by a function, another form of error must have occurred (which can be checked by using the fields provided by the `ApiError` struct). -(If desired, this feature can be turned off by calling `ReturnRateLimitError(true)`.) + + +(If desired, this feature can be turned off by calling `api.ReturnRateLimitError(true)`.) + + ### Throttling + Anaconda now supports automatic client-side throttling of queries to avoid hitting the Twitter rate-limit. + This is currently *off* by default; however, it may be turned on by default in future versions of the library, as the implementation is improved. + + To set a delay between queries, use the `SetDelay` method: + ```go api.SetDelay(10 * time.Second) ``` + Delays are set specific to each `TwitterApi` struct, so queries that use different users' access credentials are completely independent. + + To turn off automatic throttling, set the delay to `0`: + ```go api.SetDelay(0 * time.Second) ``` + ### Query Queue Persistence -If your code creates a NewTwitterApi in a regularly called function, you'll need to call `.Close()` on the API struct to clear the queryQueue and allow the goroutine to exit. Otherwise you could see goroutine and therefor heap memory leaks in long-running applications. + +If your code creates a NewTwitterApi in a regularly called function, you'll need to call `.Close()` on the API struct to clear the queryQueue and allow the goroutine to exit. Otherwise, you could see goroutine and therefor heap memory leaks in long-running applications. + ### Google App Engine + Since Google App Engine doesn't make the standard `http.Transport` available, it's necessary to tell Anaconda to use a different client context. + ```go api = anaconda.NewTwitterApi("", "") c := appengine.NewContext(r) @@ -135,6 +208,24 @@ api.HttpClient.Transport = &urlfetch.Transport{Context: c} ``` +### Twitter Media api + +Anaconda support the media api, currently file uploads to the new media api ([media/upload](https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload)) is available only in base64. + +```go +// this is a one pixel png image from: http://png-pixel.com/ +myBase64Image := "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==" + +media, err := api.UploadMedia(myBase64Image) +if(err == nil){ + // use this string id when referencing twitter media + fmt.Println(media.MediaIDString) +} +``` + +Video uploads can be made using the media api by calling UploadMedia, or by using the ``UploadVideoInit``, ``UploadVideoAppend`` and ``UploadVideoFinalize`` methods. + + License ------- Anaconda is free software licensed under the MIT/X11 license. Details provided in the LICENSE file. From 2669a3117dd75b59f8e6dc34af45b283b4ba8566 Mon Sep 17 00:00:00 2001 From: Liron Navon Date: Sun, 29 Apr 2018 12:24:01 +0300 Subject: [PATCH 2/4] Removed ide specific .gitignore --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 8cafa97..db912a1 100644 --- a/.gitignore +++ b/.gitignore @@ -3,5 +3,4 @@ *.swn conf.sh *.patch -.idea/ anaconda.test From 8c4a0e62f379d17b7c5cd611880f55fdce3b02df Mon Sep 17 00:00:00 2001 From: Liron Navon Date: Sun, 29 Apr 2018 12:26:02 +0300 Subject: [PATCH 3/4] Removed extra spaces --- README | 54 ------------------------------------------------------ 1 file changed, 54 deletions(-) diff --git a/README b/README index 3618687..820d044 100644 --- a/README +++ b/README @@ -1,42 +1,31 @@ Anaconda ======== - [![Build Status](https://travis-ci.org/ChimeraCoder/anaconda.svg?branch=master)](https://travis-ci.org/ChimeraCoder/anaconda) [![Build Status](https://ci.appveyor.com/api/projects/status/63pi6csod8bps80i/branch/master?svg=true)](https://ci.appveyor.com/project/ChimeraCoder/anaconda/branch/master) [![GoDoc](https://godoc.org/github.com/ChimeraCoder/anaconda?status.svg)](https://godoc.org/github.com/ChimeraCoder/anaconda) Anaconda is a simple, transparent Go package for accessing version 1.1 of the Twitter API. - Successful API queries return native Go structs that can be used immediately, with no need for type assertions. - For more information and a complete api please see the [GoDoc.](https://godoc.org/github.com/ChimeraCoder/anaconda) - - Examples -------- - ### Authentication - If you already have the access token (and secret) for your user (Twitter provides this for your own account on the developer portal), creating the client is simple: - ```go api := anaconda.NewTwitterApiWithCredentials("user-token", "user-token-secret", "your-consumer-key", "your-consumer-secret") ``` - ### Queries Almost all of anaconda's methods require the Values struct from the ["net/url" package](https://golang.org/pkg/net/url/) - Queries are methods of an authenticated `TwitterApi` struct. In v1.1 of Twitter's API, all requests should be authenticated. - ```go searchResult, _ := api.GetSearch("golang", nil) for _ , tweet := range searchResult.Statuses { @@ -45,7 +34,6 @@ for _ , tweet := range searchResult.Statuses { ``` Certain endpoints allow separate optional parameter; if desired, these can be passed as the final parameter. - ```go //Perhaps we want 30 values instead of the default 15 v := url.Values{} @@ -53,10 +41,8 @@ v.Set("count", "30") result, err := api.GetSearch("golang", v) ``` - (Remember that `url.Values` is equivalent to a `map[string][]string`, if you find that more convenient notation when specifying values). Otherwise, `nil` suffices. - ### Streaming @@ -64,10 +50,8 @@ Anaconda supports the Streaming APIs. You can use `PublicStream*` or `UserStream A go loop is started and gives you a stream that sends `interface{}` objects through it's `chan` `C` Objects which you can cast into a tweet, event and more. - Some services like [FireHose](https://developer.twitter.com/en/docs/tweets/compliance/api-reference/compliance-firehose) and [Decahose](https://developer.twitter.com/en/docs/tweets/sample-realtime/overview/decahose) require enterprise access to the twitter api. - Example for the PublicStreamFilter ([statuses/filter](https://developer.twitter.com/en/docs/tweets/filter-realtime/overview)) ````go values := url.Values{} @@ -88,7 +72,6 @@ for data := range s.C { } ```` - Example for the UserStream ````go values := url.Values{} @@ -114,87 +97,52 @@ for data := range stream.C { } ```` - For more information about streaming and streaming parameter please view the [Standard streaming API request parameters](https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters) - - - Endpoints --------- - Anaconda implements most of the endpoints defined in the [Twitter API documentation](https://developer.twitter.com/en/docs). For clarity, in most cases, the function name is simply the name of the HTTP method and the endpoint (e.g., the endpoint `GET /friendships/incoming` is provided by the function `GetFriendshipsIncoming`). - In a few cases, a shortened form has been chosen to make life easier (for example, retweeting is simply the function `Retweet`). - - - Error Handling, Rate Limiting, and Throttling --------------------------------------------- - ### Error Handling - Twitter errors are returned as an `ApiError`, which satisfies the `error` interface and can be treated as a vanilla `error`. However, it also contains the additional information returned by the Twitter API that may be useful in deciding how to proceed after encountering an error. - - - If you make queries too quickly, you may bump against Twitter's [rate limits](https://developer.twitter.com/en/docs/basics/rate-limits). If this happens, `anaconda` automatically retries the query when the rate limit resets, using the `X-Rate-Limit-Reset` header that Twitter provides to determine how long to wait. - In other words, users of the `anaconda` library should not need to handle rate limiting errors themselves; this is handled seamlessly behind-the-scenes. If an error is returned by a function, another form of error must have occurred (which can be checked by using the fields provided by the `ApiError` struct). - - - (If desired, this feature can be turned off by calling `api.ReturnRateLimitError(true)`.) - - - ### Throttling - Anaconda now supports automatic client-side throttling of queries to avoid hitting the Twitter rate-limit. - This is currently *off* by default; however, it may be turned on by default in future versions of the library, as the implementation is improved. - - - To set a delay between queries, use the `SetDelay` method: - ```go api.SetDelay(10 * time.Second) ``` - Delays are set specific to each `TwitterApi` struct, so queries that use different users' access credentials are completely independent. - - - To turn off automatic throttling, set the delay to `0`: - ```go api.SetDelay(0 * time.Second) ``` - ### Query Queue Persistence - If your code creates a NewTwitterApi in a regularly called function, you'll need to call `.Close()` on the API struct to clear the queryQueue and allow the goroutine to exit. Otherwise, you could see goroutine and therefor heap memory leaks in long-running applications. - ### Google App Engine @@ -207,7 +155,6 @@ c := appengine.NewContext(r) api.HttpClient.Transport = &urlfetch.Transport{Context: c} ``` - ### Twitter Media api Anaconda support the media api, currently file uploads to the new media api ([media/upload](https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload)) is available only in base64. @@ -225,7 +172,6 @@ if(err == nil){ Video uploads can be made using the media api by calling UploadMedia, or by using the ``UploadVideoInit``, ``UploadVideoAppend`` and ``UploadVideoFinalize`` methods. - License ------- Anaconda is free software licensed under the MIT/X11 license. Details provided in the LICENSE file. From a38ddee1c5f2f05e4d3ddfee42b7129bf954d574 Mon Sep 17 00:00:00 2001 From: Liron Navon Date: Sun, 29 Apr 2018 12:28:00 +0300 Subject: [PATCH 4/4] Removed more extra spaces --- README | 2 -- 1 file changed, 2 deletions(-) diff --git a/README b/README index 820d044..09081b2 100644 --- a/README +++ b/README @@ -3,7 +3,6 @@ Anaconda [![Build Status](https://travis-ci.org/ChimeraCoder/anaconda.svg?branch=master)](https://travis-ci.org/ChimeraCoder/anaconda) [![Build Status](https://ci.appveyor.com/api/projects/status/63pi6csod8bps80i/branch/master?svg=true)](https://ci.appveyor.com/project/ChimeraCoder/anaconda/branch/master) [![GoDoc](https://godoc.org/github.com/ChimeraCoder/anaconda?status.svg)](https://godoc.org/github.com/ChimeraCoder/anaconda) - Anaconda is a simple, transparent Go package for accessing version 1.1 of the Twitter API. Successful API queries return native Go structs that can be used immediately, with no need for type assertions. @@ -45,7 +44,6 @@ result, err := api.GetSearch("golang", v) ### Streaming - Anaconda supports the Streaming APIs. You can use `PublicStream*` or `UserStream` API methods. A go loop is started and gives you a stream that sends `interface{}` objects through it's `chan` `C` Objects which you can cast into a tweet, event and more.