whose-name API client

This is a client for the whose-name API.

It answers questions of the following form:

For one that calls themselves test@example.org on jira, what is their username on Slack? (Answer: U123456).

Installation

To install the code globally, use:

sudo pip3 install .

To add this to pip requirements.txt file, use:

-e git+ssh://git@github.com:makimo/whose-name-client.git#egg=whosename-main

To add this to setup.py, try this answer:

install_requires = [
  'whosename @ git+ssh://git@github.com/makimo/whose-name-client@v1.3#egg=whosename-main',
]

Console usage

There are two commands that can be used in shell: whosename and whosename-login. When used on your own machine, you can simply issue the following command:

whosename user service askedService

First time, you'll be asked interactively for email and password to the whose-name API in order to get a token. Subsequent calls will make use of the saved token.

If you would only want to issue a token, you can do that with the whosename-login command. This comes in useful on servers that need access to the API.

whosename (1.3)

Whose name client.

Usage:
    whosename [options] USERNAME SERVICE ASKED_SERVICE

Options:
    -a, --all   Print every matching name, one per line.
    -n          Non-interactive mode.
    -t, --token TOKEN  Use authorization token.
    --version   Show version information.
    -h, --help  Show this message.

whosename-login (1.3)

Get token for whosename

Usage:
    whosename-login [options] [EMAIL]

Options:
    -n          Non-interactive mode.
    -t TITLE    Set title for a token.
    -o OUTPUT   Save token to a specific file.
    --password PASS  Use specific password
    --version   Show version information.
    -h, --help  Show this message.

whosename-pool (1.3)

Whose name pool client.

Usage:
    whosename-pool [options] [NAME]

Options:
    -f, --field FIELD  Asked service to map the pool into.
    -m, --mapping      Print a JSON object mapping each member's original
                       value to its name(s) on the field, instead of a plain
                       line-by-line list.
    -n          Non-interactive mode.
    -t, --token TOKEN  Use authorization token.
    --version   Show version information.
    -h, --help  Show this message.

Python usage

This package defines the following function:

def name_of(
    username: str,
    service: str,
    askedService: str,
    authToken: Optional[str] = None,
    interactive: bool = False,
    accept: MultipleNames = MultipleNames.FIRST,
) -> Union[str, List[str], None]:

where:

• username and service match one's username on a known service
• askedService is the service on which we want to know one's username
• authToken can be given explicitely (for example if you want to get the value from a database or another specific place)
• interactive will ask for whosename API login and password to request a token if not found
• accept controls how a match is returned (see below)

The asked service may hold no name, exactly one name, or several. The accept keyword decides the shape of the result:

from whosename.query_service import MultipleNames

MultipleNames.FIRST    # the first name as a str, or None if there is no match (default)
MultipleNames.MIXED    # a str for a single name, a list for several, None if no match
MultipleNames.AS_LIST  # always a list: [] when there is no match, otherwise [name, ...]

Batch lookups

To resolve many identities in a single authenticated request, use:

def names_of(
    queries: Iterable[Tuple[str, str, str]],
    authToken: Optional[str] = None,
    interactive: bool = False,
    accept: MultipleNames = MultipleNames.FIRST,
) -> List[Union[str, List[str], None]]:

where each item in queries is a (username, service, askedService) triple with the same meaning as in name_of. authToken, interactive and accept behave identically.

The result is a list in the same order as queries, where each position is shaped according to accept (MultipleNames.FIRST by default). For example:

from whosename import names_of

names_of([
    ("test@example.org", "jira", "slack"),
    ("nobody@example.org", "jira", "slack"),
])
# => ["U123456", None]

Pools

A pool is a named, server-side group of members. Both pool functions take the pool name and the field (asked service) to resolve every member into, plus the usual authToken and interactive arguments.

def pool_mapping(
    pool: str,
    field: str,
    authToken: Optional[str] = None,
    interactive: bool = False,
    accept: MultipleNames = MultipleNames.FIRST,
) -> Dict[str, Union[str, List[str], None]]:

pool_mapping maps each member's original value to its name(s) on field. The value side is shaped by accept exactly like name_of (MultipleNames.FIRST by default); the key is always the member's original value. An unknown or empty pool yields {}.

from whosename import pool_mapping
from whosename.query_service import MultipleNames

pool_mapping("Slackers", "email", accept=MultipleNames.MIXED)
# => {
#      "U123456": "single@example.org",
#      "U234567": ["other@example.org", "new@example.org"],
#    }

def pool_names(
    pool: str,
    field: str,
    authToken: Optional[str] = None,
    interactive: bool = False,
) -> List[str]:

pool_names returns the flattened, distinct list of every member's name(s) on field, or [] when nothing was found.

from whosename import pool_names

pool_names("Slackers", "email")
# => ["single@example.org", "other@example.org", "new@example.org"]

Tokens

whosename will try to find the token in the following places:

1. --token console option or authToken argument
2. WHOSENAME_TOKEN in the environment
3. WHOSENAME_TOKEN_FILE in the environment
4. .whosename.token in current directory and upwards
5. ~/.whosename/token in user's home directory
6. /etc/whosename/token

If token cannot be found in any of these places, the application will ask for it interactively.