Metadata-Version: 2.4
Name: idmap
Version: 0.1.0
Summary: idmap — a local identity-correlation store.
Keywords: identity,correlation,cli,sqlite,namespace
Author-email: Luiz Carvalho <lucarval@redhat.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
License-File: LICENSE
Project-URL: Homepage, https://github.com/lcarva/idmap
Project-URL: Issues, https://github.com/lcarva/idmap/issues
Project-URL: Repository, https://github.com/lcarva/idmap

# idmap

A local **identity-correlation** store: it maps identifiers from arbitrary
namespaces (services) to a single canonical person. Start from any identifier
and link more later — no service is special, and adding a new one is never a
schema change.

It knows nothing about LDAP, GitHub, or any specific service. It's a `set`/`get`
utility over an [identity graph](https://en.wikipedia.org/wiki/Identity_resolution),
backed by a single SQLite file. No network calls.

## Install

From PyPI (needs Python 3.10+):

```sh
pip install idmap
```

Or, since it's a single file using only the standard library, drop it on your
`$PATH` directly:

```sh
cp idmap.py ~/.local/bin/idmap    # anywhere on $PATH
```

The database is created on first use at `$IDMAP_DB`, or
`${XDG_DATA_HOME:-~/.local/share}/idmap/idmap.db`. Override per-invocation with
`--db PATH`.

## Development

The project uses only Python's standard library. Run the full local check with:

```sh
make ci
```

This compiles the Python files, runs the unit tests, and builds the
distribution artifacts, so a change that breaks packaging is caught early.
Individual checks are available with `make compile`, `make test`, and
`make build`; running `make` lists all targets.

The `build` step needs the [build](https://build.pypa.io/) package
(`pip install build`) and produces `dist/*.whl` and `dist/*.tar.gz`.

Releases are published to PyPI automatically by GitHub Actions when a GitHub
release is published (see `.github/workflows/publish.yml`), using PyPI
[Trusted Publishing](https://docs.pypi.org/trusted-publishers/).

## Concepts

- An **identifier** is `namespace:handle`, e.g. `github:alice`, `ldap:asmith`,
  `quay:alice-q`. The namespace is lowercased; the handle is kept verbatim.
- A **namespace** may have an associated URL, such as `github.com` or
  `foo.my.corp.com.br`. The URL is stored exactly as supplied; idmap never
  contacts it or otherwise interprets it.
- A **person** (entity) is a cluster of identifiers that all refer to the same
  human. You never create a person explicitly — it appears the first time you
  name an identifier, and clusters **merge** automatically when you link two
  that already exist.
- A person may hold **multiple handles in one namespace** (alt accounts,
  renamed users), so `get --ns` can return more than one line.

## Usage

```sh
# Assert that these identifiers name the same person (creates or merges).
idmap set github:alice ldap:asmith

# Attach more later, starting from any known identifier.
idmap set ldap:asmith quay:alice-q gitlab:alice-gl

# Resolve: all identifiers for the person, or just one namespace's handle(s).
idmap get ldap:asmith                 # github:alice, gitlab:alice-gl, ...
idmap get ldap:asmith --ns github     # alice
idmap get quay:alice-q --ns gitlab    # alice-gl
idmap get ldap:asmith --name          # Alice Smith

# Inspect.
idmap ls                              # every person and their identifiers
idmap ls --ns github                  # every github:* handle on record
idmap namespace set github github.com  # associate a URL with a namespace
idmap namespace get github             # print the stored URL
idmap namespace ls                     # list namespaces and URLs

# Labels and corrections.
idmap name github:alice "Alice Smith"
idmap unlink quay:alice-q             # split it off into its own person
idmap rm gitlab:alice-gl             # forget an identifier
```

`get` prints nothing and exits non-zero when the identifier (or requested
namespace, or a name that was never set) isn't known — convenient for shell
callers.

