Skip to content

added idea (goland) to gitignore and updated documentation #242 #243

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

added idea (goland) to gitignore and updated documentation #242 #243

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5251112
added idea (goland) to gitignore and updated documentation #242
Mar 19, 2018
2669a31
Removed ide specific .gitignore
liron-navon Apr 29, 2018
8c4a0e6
Removed extra spaces
liron-navon Apr 29, 2018
a38ddee
Removed more extra spaces
liron-navon Apr 29, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 68 additions & 33 deletions README
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Anaconda is a simple, transparent Go package for accessing version 1.1 of the Tw

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
--------
Expand All @@ -17,12 +17,13 @@ Examples
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 conducted using a pointer to an authenticated `TwitterApi` struct. In v1.1 of Twitter's API, all requests should be authenticated.
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)
Expand All @@ -44,43 +45,64 @@ 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 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
---------------------------------------------
Expand All @@ -89,22 +111,18 @@ Error Handling, Rate Limiting, and Throttling

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
Expand All @@ -113,7 +131,6 @@ 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
Expand All @@ -122,18 +139,36 @@ 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)
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
-------
Expand Down