writer

package module
v3.0.4 Latest Latest
Warning

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

 Go to latest Published: Oct 25, 2023 License: BSD-3-Clause Imports: 16 Imported by: 6

README

go-writer-github

GitHub API support for the go-writer Writer interface.

This package supersedes the go-whosonfirst-readwrite-github package.

Documentation

Documentation is incomplete.

Example

package main

import (
	"context"
	"flag"
	"fmt"	
	"github.com/whosonfirst/go-writer/v2"
	_ "github.com/whosonfirst/go-writer-github/v2"		
	"io/ioutil"
	"strings"
	"time"
)

func main() {

	owner := "example"
	repo := "example-repo"
	access_token := "s33kret"
	branch := "example"

	ctx := context.Background()
	
	source := fmt.Sprintf("githubapi://%s/%s?access_token=%s&branch=%s", owner, repo, access_token, branch)
			
	wr, _ := writer.NewWriter(ctx, source)

	now := time.Now()
	msg := fmt.Sprintf("This is a test: %v", now)
	
	br := strings.NewReader(msg)
	fh := ioutil.NopCloser(br)

	wr.Write(ctx, "TEST.md", fh)
}

Error handling has been omitted for brevity.

URIs

Note: The githubapi-pr, githubapi-tree and githubapi-branch URI schemes (and packages) developed independently to address specific needs. It is possible (desirable) that these three packages get merged in to a single scheme with specific query parameters. That has not happened yet.

githubapi

The githubapi scheme is used to publish individual documents to a Git repository using the GitHub API.

The URI structure for go-writer-github (API) writers is:

Component Value Notes
Scheme githubapi
Host string A valid GitHub owner or organization
Path string A valid GitHub respository
Query described below

The following query parameters are supported for go-writer-github writers:

Name Value Required Notes
access_token string yes A valid GitHub API access token
branch string no A valid Git repository branch. Default is main.
prefix string no An optional path to prepend URIs (for writing) with.
new string no A valid string for formatting new file commit messages. Default is Created %s.
update string no A valid string for formatting updated file commit messages. Default is Updated %s.
retry-on-ratelimit boolean (string) no If true and the writer encounters a GitHub rate-limit error trying to write data it will sleep until the "reset" time (published by GitHub) and retry the write operation.
retry-on-conflict boolean (string) no If true and the writer encounters a GitHub 409 Conflict error trying to write data it will keep trying (by refreshing the current hash) until it succeeds, with the limits of the ?max-retry-attempts flag.
max-retry-attempts int no Default is 10. If <=0 then checks on the maximum number of retry attempts will be disabled.

For example:

githubapi://whosonfirst-data/whosonfirst-data-admin-us \
	?access_token={access_token} \
	&branch=main
githubapi-pr

The githubapi-pr scheme is used to write documents to a GitHub pull request using the GitHub API. Records are commited when when the writer's Flush() or Close() methods are called. The PR is created when the writer's Close() method is called.

The URI structure for go-writer-github (API Pull Request) writers is:

Component Value Notes
Scheme githubapi-pr
Host string A valid GitHub owner or organization
Path string A valid GitHub respository
Query described below

The following query parameters are supported for githubapi-pr writers:

Name Value Required Notes
access_token string yes A valid GitHub API access token
branch string no A valid Git repository branch. Default is main.
prefix string no An optional path to prepend URIs (for writing) with.
pr-owner string no The user or organization name where the pull request will be created. If empty will default to GitHub owner or organization defined in URI host field.
pr-repo string no The repository name where the pull request will be created. If empty will default to GitHub owner or organization defined in URI path field.
pr-branch string yes The name of branch that the pull request will be created for.
pr-title string yes The title of the pull request being created.
pr-description string yes The description of the pull request being created.
pr-author string no The author of the pull request being created. If empty the name associated with the GitHub access token will be used (must not be empty).
pr-email string no The email address associated with the pull request being created. If empty the email address associated with the GitHub access token will be used (must not be empty).
pr-ensure-repo bool no If true then the existence of {pr_owner}/{pr_repo} will be checked. If it does not exist then it will be forked (and if necessary renamed) from the organization and repo defined in the URI Host and Path fields.

For example:

githubapi-pr://sfomuseum-data/sfomuseum-data-collection \
	?access_token={access_token} \
	&branch=main \
	&prefix=data/ \
	&pr-branch=aaronc \
	&pr-title=testing \
	&pr-description=testing \
	&pr-email=aaron@localhost \
	&pr-repo=sfomuseum-data-testing \
	&pr-owner=aaronland \
	&ensure-repo=true

Which might yield something like this:

githubapi-tree

The githubapi-tree scheme is used to write multiple documents to a GitHub tree commit using the GitHub API. Documents are written is created when the writer's Flush() or Close() methods are called.

The URI structure for go-writer-github (API Pull Request) writers is:

Component Value Notes
Scheme githubapi-tree
Host string A valid GitHub owner or organization
Path string A valid GitHub respository
Query described below

The following query parameters are supported for githubapi-tree writers:

Name Value Required Notes
access_token string yes A valid GitHub API access token
branch string no A valid Git repository branch. Default is main.
prefix string no An optional path to prepend URIs (for writing) with.
to-branch string yes The name of branch that the pull request will be created for.
description string yes The description of the pull request being created.
author string no The author of the pull request being created. If empty the name associated with the GitHub access token will be used (must not be empty).
email string no The email address associated with the pull request being created. If empty the email address associated with the GitHub access token will be used (must not be empty).

For example:

githubapi-tree://sfomuseum-data/sfomuseum-data-collection \
	?access_token={access_token} \
	&branch=main \
	&prefix=data/ \
	&to-branch=testing \
	&description=testing \
	&email=aaron@localhost
githubapi-branch

The githubapi-branch scheme is used to write multiple documents to a GitHub commit using the GitHub API, optionally merging and removing that branch when complete. Documents are written is created when the writer's Flush() or Close() methods are called. Branches are merged and removed when the writer's Close() method is called.

The URI structure for go-writer-github (API Pull Request) writers is:

Component Value Notes
Scheme githubapi-branch
Host string A valid GitHub owner or organization
Path string A valid GitHub respository
Query described below

The following query parameters are supported for githubapi-branch writers:

Name Value Required Notes
access_token string yes A valid GitHub API access token
branch string no A valid Git repository branch. Default is main.
prefix string no An optional path to prepend URIs (for writing) with.
to-branch string yes The name of branch that the pull request will be created for.
description string yes The description of the pull request being created.
author string no The author of the pull request being created. If empty the name associated with the GitHub access token will be used (must not be empty).
email string no The email address associated with the pull request being created. If empty the email address associated with the GitHub access token will be used (must not be empty).
merge bool no Merge commits made to to-branch in to the main branch when the writer's Close() method is invoked. Default is false.
remove-on-merge bool no Remove the to-branch branch when the writer's Close() method is invoked. Default is false.

For example:

githubapi-branch://sfomuseum-data/sfomuseum-data-collection \
	?access_token={access_token} \
	&branch=main \
	&prefix=data/ \
	&description=testing \
	&email=aaron@localhost \
	&to-commit=testing \
	&merge=true \
	&remove-on-merge=true

See also

Documentation

Overview

package writer

Index

Constants

View Source 
const DEFAULT_BRANCH string = "main"
View Source 
const GITHUBAPI_BRANCH_SCHEME string = "githubapi-branch"
View Source 
const GITHUBAPI_PR_SCHEME string = "githubapi-pr"
View Source 
const GITHUBAPI_SCHEME string = "githubapi"
View Source 
const GITHUBAPI_TREE_SCHEME string = "githubapi-tree"

Variables

This section is empty.

Functions

func EnsureGitHubAccessToken 

func EnsureGitHubAccessToken(ctx context.Context, writer_uri string, token_uri string) (string, error)

EnsureGitHubAccessToken ensures that 'writer_uri' contains a '?access_token=VALUE' parameter. This only applies if the scheme is `githubapi://`. If not the method returns the original 'writer_uri' value. If the 'writer_uri' contains an empty `access_token` parameter or the value is "{access_token}" then the method will replace parameter with the value derived from 'token_uri' which is expected to be a valid `gocloud.dev/runtimevar` URI.

func NewGitHubAPIBranchWriter 

func NewGitHubAPIBranchWriter(ctx context.Context, uri string) (wof_writer.Writer, error)

func NewGitHubAPIPullRequestWriter 

func NewGitHubAPIPullRequestWriter(ctx context.Context, uri string) (wof_writer.Writer, error)

func NewGitHubAPITreeWriter 

func NewGitHubAPITreeWriter(ctx context.Context, uri string) (wof_writer.Writer, error)

func NewGitHubAPIWriter 

func NewGitHubAPIWriter(ctx context.Context, uri string) (wof_writer.Writer, error)

Types

type GitHubAPIBranchWriter 

type GitHubAPIBranchWriter struct {
	wof_writer.Writer
	// contains filtered or unexported fields
}

func (*GitHubAPIBranchWriter) Close 

func (wr *GitHubAPIBranchWriter) Close(ctx context.Context) error

func (*GitHubAPIBranchWriter) Flush 

func (wr *GitHubAPIBranchWriter) Flush(ctx context.Context) error

func (*GitHubAPIBranchWriter) SetLogger 

func (wr *GitHubAPIBranchWriter) SetLogger(ctx context.Context, logger *log.Logger) error

func (*GitHubAPIBranchWriter) Write 

func (wr *GitHubAPIBranchWriter) Write(ctx context.Context, uri string, r io.ReadSeeker) (int64, error)

func (*GitHubAPIBranchWriter) WriterURI 

func (wr *GitHubAPIBranchWriter) WriterURI(ctx context.Context, key string) string

type GitHubAPIPullRequestWriter 

type GitHubAPIPullRequestWriter struct {
	wof_writer.Writer
	// contains filtered or unexported fields
}

func (*GitHubAPIPullRequestWriter) Close 

func (wr *GitHubAPIPullRequestWriter) Close(ctx context.Context) error

func (*GitHubAPIPullRequestWriter) Flush 

func (wr *GitHubAPIPullRequestWriter) Flush(ctx context.Context) error

func (*GitHubAPIPullRequestWriter) SetLogger 

func (wr *GitHubAPIPullRequestWriter) SetLogger(ctx context.Context, logger *log.Logger) error

func (*GitHubAPIPullRequestWriter) Write 

func (wr *GitHubAPIPullRequestWriter) Write(ctx context.Context, uri string, r io.ReadSeeker) (int64, error)

func (*GitHubAPIPullRequestWriter) WriterURI 

func (wr *GitHubAPIPullRequestWriter) WriterURI(ctx context.Context, key string) string

type GitHubAPITreeWriter 

type GitHubAPITreeWriter struct {
	wof_writer.Writer
	// contains filtered or unexported fields
}

func (*GitHubAPITreeWriter) Close 

func (wr *GitHubAPITreeWriter) Close(ctx context.Context) error

func (*GitHubAPITreeWriter) Flush 

func (wr *GitHubAPITreeWriter) Flush(ctx context.Context) error

func (*GitHubAPITreeWriter) SetLogger 

func (wr *GitHubAPITreeWriter) SetLogger(ctx context.Context, logger *log.Logger) error

func (*GitHubAPITreeWriter) Write 

func (wr *GitHubAPITreeWriter) Write(ctx context.Context, uri string, r io.ReadSeeker) (int64, error)

func (*GitHubAPITreeWriter) WriterURI 

func (wr *GitHubAPITreeWriter) WriterURI(ctx context.Context, key string) string

type GitHubAPIWriter 

type GitHubAPIWriter struct {
	wof_writer.Writer
	// contains filtered or unexported fields
}

func (*GitHubAPIWriter) Close 

func (wr *GitHubAPIWriter) Close(ctx context.Context) error

func (*GitHubAPIWriter) Flush 

func (wr *GitHubAPIWriter) Flush(ctx context.Context) error

func (*GitHubAPIWriter) SetLogger 

func (wr *GitHubAPIWriter) SetLogger(ctx context.Context, logger *log.Logger) error

func (*GitHubAPIWriter) Write 

func (wr *GitHubAPIWriter) Write(ctx context.Context, uri string, fh io.ReadSeeker) (int64, error)

func (*GitHubAPIWriter) WriterURI 

func (wr *GitHubAPIWriter) WriterURI(ctx context.Context, key string) string

type GitHubAPIWriterCommitTemplates 

type GitHubAPIWriterCommitTemplates struct {
	New    string
	Update string
}

Source Files

View all Source files

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.