Initial commit

vendor/gopkg.in/masci/flickr.v3/README.md

@@ -0,0 +1,161 @@
+# flickr
+
+A go library to easily consume Flickr API.
+The project is currently under heavy development, so it hasn't a version number yet.
+
+[![GoDoc](https://godoc.org/gopkg.in/masci/flickr.v3?status.svg)](https://godoc.org/gopkg.in/masci/flickr.v3)
+[![build-test](https://github.com/masci/flickr/actions/workflows/test.yml/badge.svg)](https://github.com/masci/flickr/actions/workflows/test.yml)
+[![Coverage Status](https://coveralls.io/repos/masci/flickr/badge.svg)](https://coveralls.io/r/masci/flickr)
+
+## Usage
+
+`flickr` aims to expose a Go Api matching Flickr REST Api, so that you don't need
+to build HTTP requests and parse HTTP response manually. For example, the Flickr
+method `flickr.photosets.create` is implemented with the `Create` function in the `flickr/photosets`
+package:
+
+```go
+import "fmt"
+import "gopkg.in/masci/flickr.v3"
+import "gopkg.in/masci/flickr.v3/photosets"
+
+// create an API client with credentials
+client := flickr.NewFlickrClient("your_apikey", "your_apisecret")
+client.OAuthToken = "your_token"
+client.OAuthTokenSecret = "your_tokenSecret"
+
+response, _ := photosets.Create(client, "My Set", "Description", "primary_photo_id")
+fmt.Println("New photoset created:", response.Photoset.Id)
+```
+
+`flickr` responses implement `flickr.FlickrResponse` interface. A response contains error codes
+and error messages (if any) produced by Flickr or the specific data returned by the api call.
+Different methods may return different kind of responses.
+
+### Upload a photo
+
+There are a number of functions that don't map any actual Flickr Api method
+(see below for the detailed list). For example, to upload a photo, you call the
+`UploadFile` or `UploadReader` functions in the `flickr` package:
+
+```go
+import "gopkg.in/masci/flickr.v3"
+
+
+// upload the image file with default (nil) options
+resp, err := flickr.UploadFile(client, "/path/to/image", nil)
+```
+Files are uploaded through an io.Pipe fueled in a separate goroutine, so the process is pretty efficient.
+
+### Authentication (or how to retrieve OAuth credentials)
+
+Several api calls must be authenticated and authorized: `flickr` only supports
+OAuth since the original token-based method has been deprecated by Flickr. This
+is an example describing the OAuth worflow from a command line application:
+
+```go
+import "gopkg.in/masci/flickr.v3"
+
+client := flickr.NewFlickrClient("your_apikey", "your_apisecret")
+
+// first, get a request token
+requestTok, _ := flickr.GetRequestToken(client)
+
+// build the authorizatin URL
+url, _ := flickr.GetAuthorizeUrl(client, requestTok)
+
+// ask user to hit the authorization url with
+// their browser, authorize this application and coming
+// back with the confirmation token
+
+// finally, get the access token, setup the client and start making requests
+accessTok, err := flickr.GetAccessToken(client, requestTok, "oauth_confirmation_code")
+client.OAuthToken = accessTok.OAuthToken
+client.OAuthTokenSecret = accessTok.OAuthTokenSecret
+```
+
+### Api coverage
+
+Only a small part of the Flickr Api is implemented as Go functions: even if it's quite
+simple to write the code for the mapping, I only did it for methods I actually need in my projects
+(contributions well accepted). Anyway, if you need to call a Flickr Api method that wasn't
+already mapped, you can do it manually:
+
+```go
+import "fmt"
+import "gopkg.in/masci/flickr.v3"
+
+client := flickr.NewFlickrClient("your_apikey", "your_apisecret")
+client.Init()
+client.Args.Set("method", "flickr.cameras.getBrandModels")
+client.Args.Set("brand", "nikon")
+
+client.OAuthSign()
+response := &flickr.BasicResponse{}
+err := flickr.DoGet(client, response)
+
+if err != nil {
+    fmt.Printf("Error: %s", err)
+} else {
+    fmt.Println("Api response:", response.Extra)
+}
+```
+
+Checkout the `example` folder and the docs pages for more details.
+
+## Note on Go versions
+
+The latest version `v2` only supports go `1.6` and above, for Go `< 1.6` use the `v1` package:
+```
+go get gopkg.in/masci/flickr.v1
+```
+
+## API Methods
+
+### Extra-API Methods
+These are methods that are not actually part of the Flickr API
+
+ * Get OAuth request token
+ * Get OAuth authorize URL
+ * Get OAuth access token
+ * Upload photo
+
+### auth.oauth
+ * flickr.auth.oauth.checkToken
+
+### photos
+ * flickr.photos.delete
+ * flickr.photos.getInfo
+ * flickr.photos.setDates
+ * flickr.photos.setPerms
+ * flickr.photos.addTags
+ * flickr.photos.getSizes
+
+### photosets
+ * flickr.photosets.addPhoto
+ * flickr.photosets.create
+ * flickr.photosets.delete
+ * flickr.photosets.editMeta
+ * flickr.photosets.editPhotos
+ * flickr.photosets.getInfo
+ * flickr.photosets.getList
+ * flickr.photosets.getPhotos
+ * flickr.photosets.orderSets
+ * flickr.photosets.removePhoto
+ * flickr.photosets.removePhotos
+ * flickr.photosets.reorderPhotos
+ * flickr.photosets.setPrimaryPhoto
+
+### people
+ * flickr.people.getPhotos
+
+ ### Groups
+ * flickr.groups.pools.add
+ * flickr.groups.pools.getGroups
+ * flickr.groups.getInfo
+
+
+### test
+ * flickr.test.echo
+ * flickr.test.login
+ * flickr.test.null