GitHub : github_handler

The github_handler module handles all communications with the NeXus GitHub repository. The interaction is handled through the GitHub REST API. A token is needed to update the local cache of NeXus definitions. (See punx update -h for help on this command.)

GitHub requests use an access token. The token is unique to each user and may be generated by visiting the GitHub user’s token settings page. Without a token, the GitHub API Rate Limit allows unauthenticated access only a few downloads per hour.

These environment variables are searched (in order) for a token:

• GH_TOKEN

• GITHUB_TOKEN (searched in that order).

Here is an example of a GitHub token: ghp_AbcdEF0gHIJKlMNopqrs1tUvwXyzAb2CDEFg (N.B.: This is not a valid token; it is only an example. You must use your own token.)

To set the GH_TOKEN environment variable with this token:

export GH_TOKEN=ghp_AbcdEF0gHIJKlMNopqrs1tUvwXyzAb2CDEFg

For more details about tokens and authentication, please visit the GitHub documentation.

source code documentation

manages the communications with GitHub

GitHub_Repository_Reference()

all information necessary to describe and download a repository branch, release, tag, or SHA hash

USAGE:

grr = punx.github_handler.GitHub_Repository_Reference()
grr.connect_repo()
if grr.request_info(u'v3.2') is not None:
    d = grr.download()

class punx.github_handler.GitHub_Repository_Reference

all information necessary to describe and download a repository branch, release, tag, or SHA hash

ROUTINES

connect_repo([repo_name, token])	connect with the GitHub repository
request_info([ref])	request download information about ref
download()	download the NXDL definitions described by ref

See

https://github.com/PyGithub/PyGithub/tree/master/github

connect_repo(repo_name=None, token=None)

connect with the GitHub repository

Parameters

• repo_name (str) – name of repository in https://github.com/nexusformat (default: definitions)

• token (str or None) – GitHub access token or None

Returns bool

True if using GitHub credentials

download()

download the NXDL definitions described by ref

get_branch(ref='main')

learn the download information about the named branch

Parameters

ref (str) – name of branch in repository

get_commit(ref='a4fd52d')

learn the download information about the referenced commit

Parameters

ref (str) – name of SHA hash, first unique characters are sufficient, usually 7 or less

get_release(ref='v2018.5')

learn the download information about the named release

Parameters

ref (str) – name of release in repository

get_tag(ref='Schema-3.3')

learn the download information about the named tag

Parameters

ref (str) – name of tag in repository

request_info(ref=None)

request download information about ref

Parameters

ref (str) – name of branch, release, tag, or SHA hash (default: v3.2)

download URLs

• base: https://github.com

• master: https://github.com/nexusformat/definitions/archive/master.zip

• branch (www_page_486): https://github.com/nexusformat/definitions/archive/www_page_486.zip

• hash (83ce630): https://github.com/nexusformat/definitions/archive/83ce630.zip

• release (v3.2): see hash c0b9500

• tag (NXcanSAS-1.0): see hash 83ce630

punx.github_handler.get_GitHub_credentials()

Get the Github API token from a file or environment.

GitHub requests use an access token. The token is unique to a user and may be generated by visiting https://github.com/settings/tokens.

The token is provided in either of these environment variables: GH_TOKEN or GITHUB_TOKEN (searched in that order).

Issues a warning and returns None if credentials are not found per above search.