Metadata-Version: 2.4
Name: kokomikke
Version: 0.1.3
Summary: Look up GitHub tokens from various sources
Project-URL: Repository, https://github.com/celsiusnarhwal/kokomikke
Project-URL: Issues, https://github.com/celsiusnarhwal/kokomikke/issues
Project-URL: Changelog, https://github.com/celsiusnarhwal/kokomikke/blob/main/CHANGELOG.md
Author-email: celsius narhwal <hello@celsiusnarhwal.dev>
License-File: LICENSE.md
Requires-Python: >=3.10
Requires-Dist: platformdirs>=4.10.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyyaml>=6.0.3
Description-Content-Type: text/markdown

# Kokomikke

Kokomikke (*koh•koh•mi•ke*) is a Python library that looks up GitHub access tokens from various sources.

## Installation

```shell
pip install kokomikke
```

## Usage

Basic usage is as simple as:

```python
import kokomikke

token = kokomikke.search()
```

By default, this will look for a GitHub token in the following locations, in order, returning as soon as one is found:

1. The `GITHUB_API_TOKEN` environment variable
2. The `GITHUB_TOKEN` environment variable
3. The `GH_TOKEN` environment variable
4. The `GITHUB_PAT` environment variable
5. The `GH_PAT` environment variable
6. GitHub CLI via [`gh auth token`](https://cli.github.com/manual/gh_auth_token)
7. GitHub CLI via `hosts.yml`

If no token is found, `kokomikke.search()` will return `None`.

### Sources

In order to search for token, Kokomikke needs sources. A source is an object of a class that inherits from
`kokomikke.sources.Source` and implements the `lookup()` method:

```python
from kokomikke.sources import Source

class MySource(Source):
    def lookup(self) -> str | None:
        # lookup logic goes here
```

Kokomikke comes with the following sources built-in:

#### `kokomikke.sources.EnvironmentVariableSource`

Searches a list of environment variables, in order, for a non-empty value.

It takes the following arguments:

- `variables` (`list[str]`, keyword-only, default: [`GITHUB_API_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_PAT`, `GH_PAT`]): The variables to search.

#### `kokomikke.sources.GitHubCLISource`

Runs [`gh auth token`](https://cli.github.com/manual/gh_auth_token) and, if there is no error, returns its output.

It takes the following arguments:

- `hostname` (`str`, keyword-only, default: `github.com`): The hostname of the GitHub instance to get a token for.

#### `kokomikke.sources.GitHubCLIYamlSource`

Reads GitHub CLI's `hosts.yml` file and returns a token if one is present.

It takes the following arguments:

- `hostname` (`str`, keyword-only, default: `github.com`): The hostname of the GitHub instance to get a token for.

#### `kokomikke.sources.GitSource`

Calls [`git credential fill`](https://git-scm.com/docs/git-credential) and returns a token if one is present
in the output.

It takes the following arguments:

- `hostname` (`str`, keyword-only, default: `github.com`): The hostname of the GitHub instance to get a token for.

#### ``kokomikke.sources.CommandSource``

Runs an arbitrary command and, if there is no error, returns its output.

It takes the folowing arguments:

- command: (`list`, keyword-only): Command arguments.

<hr/>

`kokomikke.search()` takes an optional `sources` argument, which expects a list of sources, each of which will
be evaluated in order. For example, to first look for a token via `gh auth token`, but fall back to [`pass`](https://passwordstore.org)
if that fails:

```python
import kokomikke
from kokomikke.sources import CommandSource, GitHubCLISource

pass_source = CommandSource(command=["pass", "github.com/mona"])

token = kokomikke.search([GitHubCLISource, pass_source])
```