GitHub data access

Read CSV resources from public or private GitHub repositories. Examples use the public salmon-data-mobilization/sdp-example-data repo, so every snippet is runnable.

Build a raw URL

from metasalmonpy import github_raw_url

url = github_raw_url(
    "data/escapement.csv",
    repo="salmon-data-mobilization/sdp-example-data",
    ref="v0.1.0",
)

Pin ref to a tag or commit when reproducibility matters. The default is main.

Read one CSV

from metasalmonpy import read_github_csv

escapement = read_github_csv(
    "data/escapement.csv",
    repo="salmon-data-mobilization/sdp-example-data",
    ref="v0.1.0",
)

Read a directory

from metasalmonpy import read_github_csv_dir

tables = read_github_csv_dir(
    "data",
    repo="salmon-data-mobilization/sdp-example-data",
    ref="v0.1.0",
)

Public repositories — including the example repo above — need no token at all: the readers send an Authorization header only when a token is discovered, mirroring metasalmon.

Private repositories

Token discovery checks GITHUB_PAT, GH_TOKEN, and the configured git credential store. Verify discovery without printing the token:

from metasalmonpy import ms_setup_github

ms_setup_github()  # token discovery only
ms_setup_github(repo="your-org/your-private-repo")  # also verify repo access

There is no default repository: a bare ms_setup_github() confirms token discovery, and repository verification happens only when you name one (mirroring metasalmon’s 0.2.3 fix for the same function).

Pass token= directly only when your application already manages credentials. Do not commit tokens to source, examples, notebooks, or .env files that are tracked by git.

Back to top