Documentation ¶
Overview ¶
Package trending provides access to github`s trending repositories and developers. The data will be collected from githubs website at https://github.com/trending and https://github.com/trending/developers.
Construct a new trending client, then use the various functions on the client to access the trending content from GitHub. For example:
trend := trending.NewTrending() // Get trending projects of language "go" for today. projects, err := trend.GetProjects(trending.TimeToday, "go")
GitHub Enterprise ¶
If you are running a GitHub Enterprise yourself you can use this library as well. For such cases you can change the BaseURL of the library:
myURL, _ := url.Parse("https://my.github.enterprise.com") trend := trending.NewTrending() trend.BaseURL = myURL // Get trending projects of language "go" for today. projects, err := trend.GetProjects(trending.TimeToday, "go")
Index ¶
Examples ¶
Constants ¶
const ( // TimeToday is limit of the current day. TimeToday = "daily" // TimeWeek will focus on the complete week TimeWeek = "weekly" // TimeMonth include the complete month TimeMonth = "monthly" )
These are predefined constants to define the timerange of the requested repository or developer. If trending repositories or developer are requested, a timeframe has to be added. It is suggested to use this constants for this.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Developer ¶
type Developer struct { // ID is the github`s unique identifier of the user / organization like 1342004 (google) or 698437 (airbnb). ID int // DisplayName is the username of the developer / organization like "torvalds" or "apache". DisplayName string // FullName is the real name of the developer / organization like "Linus Torvalds" (for "torvalds") or "The Apache Software Foundation" (for "apache"). FullName string // URL is the http(s) address of the developer / organization reflected as url.URL datastructure like https://github.com/torvalds. URL *url.URL // Avatar is the http(s) address of the developer / organization avatar as url.URL datastructure like https://avatars1.githubusercontent.com/u/1024025?v=3&s=192. Avatar *url.URL }
Developer reflects a single trending developer / organization. It provides information as printed on the source website https://github.com/trending/developers.
type Language ¶
type Language struct { // Name is the human readable name of the language like "Go" or "Web Ontology Language" Name string // URLName is the machine readable / usable name of the language used for filtering / url parameters like "go" or "web-ontology-language". // Please use URLName if you want to filter your requests. URLName string // URL is the filter URL for the language like "https://github.com/trending?l=go" for "go" or "https://github.com/trending?l=unknown" or "unknown". URL *url.URL }
Language reflects a single (programing) language offered by github for filtering. If you call "GetProjects" you are able to filter by programing language. For filter input you should use the URLName of Language.
type Project ¶
type Project struct { // Name is the name of the repository including user / organization like "andygrunwald/go-trending" or "airbnb/javascript". Name string // Owner is the name of the user or organization. "andygrunwald" in "andygrunwald/go-trending" or "airbnb" in "airbnb/javascript". Owner string // RepositoryName is the name of therepository. "go-trending" in "andygrunwald/go-trending" or "javascript" in "airbnb/javascript". RepositoryName string // Description is the description of the repository like "JavaScript Style Guide" (for "airbnb/javascript"). Description string // Language is the determined programing language of the project (by Github). // Sometimes Language is an empty string, because Github can`t determine the (main) programing language (like for "google/deepdream"). Language string // Stars is the total number of github stars this project has received. Stars int // StarsPeriod is the number of github stars this project received in the given timeframe (see TimeToday / TimeWeek / TimeMonth constants). StarsPeriod int // URL is the http(s) address of the project reflected as url.URL datastructure like "https://github.com/Workiva/go-datastructures". URL *url.URL // ContributorURL is the http(s) address of the contributors page of the project reflected as url.URL datastructure like "https://github.com/Workiva/go-datastructures/graphs/contributors". ContributorURL *url.URL // Contributor are a collection of Developer. // Be aware that this collection don`t covers all contributor. // Only those who are mentioned at githubs trending page. Contributor []Developer }
Project reflects a single trending repository. It provides information as printed on the source website https://github.com/trending.
type Trending ¶
type Trending struct { // Base URL for requests. // Defaults to the public GitHub website, but can be set to a domain endpoint to use with GitHub Enterprise. // BaseURL should always be specified with a trailing slash. BaseURL *url.URL // Client to use for requests Client *http.Client }
Trending reflects the main datastructure of this package. It doesn`t provide an exported state, but based on this the methods are called. To receive a new instance just add
package main import ( "github.com/permafrost-dev/go-github-trending" ) func main() { trend := trending.NewTrending() ... }
func NewTrending ¶
func NewTrending() *Trending
NewTrending is the main entry point of the trending package. It provides access to the API of this package by returning a Trending datastructure. Usage:
trend := trending.NewTrending() projects, err := trend.GetProjects(trending.TimeToday, "") ...
func NewTrendingHttp11 ¶ added in v1.1.1
func NewTrendingHttp11() *Trending
func NewTrendingWithClient ¶
NewTrendingWithClient allows providing a custom http.Client to use for fetching trending items. It allows setting timeouts or using 3rd party http.Client implementations, such as Google App Engine urlfetch.Client.
func (*Trending) GetDevelopers ¶
GetDevelopers provides a slice of Developer filtered by the given time and language.
time can be filtered by applying by one of the Time* constants (e.g. TimeToday, TimeWeek, ...). If an empty string will be applied TimeToday will be the default (current default by Github).
language can be filtered by applying a programing language by your choice The input must be a known language by Github and be part of GetLanguages(). Further more it must be the Language.URLName and not the human readable Language.Name. If language is an empty string "All languages" will be applied (current default by Github).
Example ¶
package main import ( "fmt" "log" "net/http" "time" "golang.org/x/net/http2" trending "github.com/permafrost-dev/go-github-trending" ) func main() { client := &http.Client{ Timeout: 30 * time.Second, Transport: &http2.Transport{}, } trend := trending.NewTrendingWithClient(client) developers, err := trend.GetDevelopers(trending.TimeToday, "") if err != nil { log.Fatal(err) } if len(developers) > 0 { fmt.Println("Developers received.") } else { fmt.Printf("Number of developer received: %d", len(developers)) } }
Output: Developers received.
func (*Trending) GetLanguages ¶
GetLanguages will return a slice of Language known by gitub. With the Language.URLName you can filter your GetProjects / GetDevelopers calls.
Example ¶
package main import ( "fmt" "log" "net/http" "time" "golang.org/x/net/http2" trending "github.com/permafrost-dev/go-github-trending" ) func main() { client := &http.Client{ Timeout: 30 * time.Second, Transport: &http2.Transport{}, } trend := trending.NewTrendingWithClient(client) languages, err := trend.GetLanguages() if err != nil { log.Fatal(err) } // We need more as 15 languages, because 9 are trending languages if len(languages) > 15 { fmt.Println("Languages received.") } else { fmt.Printf("Number of languages received: %d", len(languages)) } }
Output: Languages received.
func (*Trending) GetProjects ¶
GetProjects provides a slice of Projects filtered by the given time and language.
time can be filtered by applying by one of the Time* constants (e.g. TimeToday, TimeWeek, ...). If an empty string will be applied TimeToday will be the default (current default by Github).
language can be filtered by applying a programing language by your choice. The input must be a known language by Github and be part of GetLanguages(). Further more it must be the Language.URLName and not the human readable Language.Name. If language is an empty string "All languages" will be applied (current default by Github).
Example ¶
package main import ( "fmt" "log" "net/http" "time" "golang.org/x/net/http2" trending "github.com/permafrost-dev/go-github-trending" ) func main() { client := &http.Client{ Timeout: 30 * time.Second, Transport: &http2.Transport{}, } trend := trending.NewTrendingWithClient(client) projects, err := trend.GetProjects(trending.TimeToday, "go") if err != nil { log.Fatal(err) } projectsNotInGo := 0 for _, project := range projects { if len(project.Language) > 0 && project.Language != "Go" { projectsNotInGo = projectsNotInGo + 1 } } // Sometimes we get projects where the main language is // not Go, but the repository contains a large amount of Go code. // Like https://github.com/codeedu/imersao-7-codepix // Main language TypeScript + 36% Go. // In this case, we calculate a threshold to tackle this situation, because // our code works as expected and GitHub is also returning projects with Go code. // But it might not be the (only) main language. onlyGoProjects := true if projectsNotInGo > 0 { // Threshold 10% if (projectsNotInGo / len(projects) * 100) > 10 { onlyGoProjects = false } } if len(projects) > 0 && onlyGoProjects { fmt.Println("Projects (filtered by Go) received.") } else { fmt.Printf("Number of projects received: %d / projects with a different main language than golang %d)", len(projects), projectsNotInGo) } }
Output: Projects (filtered by Go) received.