Metadata-Version: 2.4
Name: uuid58
Version: 0.1.0
Summary: Encode UUIDs as 22-character, order-preserving Base58 strings (uuid58)
Keywords: uuid,base58,uuid58,short-id,encoding
Author: Nakano as a Service
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/nakanoasaservice/uuid58/tree/main/python
Project-URL: Repository, https://github.com/nakanoasaservice/uuid58
Project-URL: Specification, https://github.com/nakanoasaservice/uuid58/blob/main/spec/SPEC.md
Project-URL: Issues, https://github.com/nakanoasaservice/uuid58/issues
Description-Content-Type: text/markdown

# uuid58 (Python)

Encode UUIDs as 22-character Base58 strings, and back.

```text
f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf  <->  XDY9dmBbcMBXqcRvYw8xJ2
```

- Always exactly 22 characters, using the Bitcoin Base58 alphabet (no `0`,
  `O`, `I`, `l`).
- Order-preserving: sorting uuid58 strings by code point sorts the UUIDs
  numerically (useful with UUIDv7).
- Strict: implements the [uuid58 specification](https://github.com/nakanoasaservice/uuid58/blob/main/spec/SPEC.md)
  and passes its [test vectors](https://github.com/nakanoasaservice/uuid58/blob/main/spec/vectors.json).
- No dependencies, fully typed (`py.typed`), CPython 3.10+.

## Install

```bash
pip install uuid58
```

or `uv add uuid58`.

## Usage

```python
import uuid
import uuid58

s = "XDY9dmBbcMBXqcRvYw8xJ2"

# All of these return s:
uuid58.encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf")
uuid58.encode("F4B247FD1F8745D4AA061C6FC0A8DFAF")  # plain hex, any case
uuid58.encode(uuid.UUID("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"))
uuid58.encode(bytes.fromhex("f4b247fd1f8745d4aa061c6fc0a8dfaf"))
uuid58.encode(0xF4B247FD1F8745D4AA061C6FC0A8DFAF)

uuid58.decode(s)  # 'f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf'
uuid58.decode_uuid(s)  # UUID('f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf')
uuid58.decode_bytes(s)  # b'\xf4\xb2G\xfd\x1f\x87E\xd4...'
uuid58.decode_int(s)  # 325257319917903217740243107280071483311

uuid58.is_uuid58("XDY9dmBbcMBXqcRvYw8xJ2")  # True
uuid58.is_uuid58("zzzzzzzzzzzzzzzzzzzzzz")  # False: exceeds 128 bits

uuid58.uuid58()  # a random UUIDv4, encoded, e.g. 'Tj5D5H2Bc1LcPjwNNhH4xS'
```

### Errors

All invalid-input errors subclass `uuid58.Uuid58Error`, which subclasses
`ValueError`. Each carries the spec error kind (SPEC.md Section 7) in `kind`,
an `ErrorKind` that compares equal to its spec name:

| Exception               | `kind`                | Raised when                                                      |
| ----------------------- | --------------------- | ---------------------------------------------------------------- |
| `InvalidLengthError`    | `"invalid_length"`    | a string of the wrong length, or bytes whose length is not 16    |
| `InvalidCharacterError` | `"invalid_character"` | a character not allowed in its position (incl. any non-ASCII)    |
| `ValueOverflowError`    | `"overflow"`          | a value outside `0..2**128 - 1` (decoded string or encoded `int`) |

```python
try:
    uuid58.decode(user_input)
except uuid58.InvalidCharacterError:
    ...
except uuid58.Uuid58Error as e:
    print(e.kind)  # invalid_length / overflow
```

Passing an unsupported type (for example `bool`, `float` or `None`) raises
`TypeError`. Error messages are not part of the specification and may change.

## API

| Name                                     | Description                                                                       |
| ---------------------------------------- | --------------------------------------------------------------------------------- |
| `encode(value: UUIDLike) -> str`         | Encode a UUID string, `uuid.UUID`, 16 `bytes`/`bytearray`, or `int`.               |
| `decode(s: str) -> str`                  | Decode to the lowercase hyphenated UUID string.                                   |
| `decode_uuid(s: str) -> uuid.UUID`       | Decode to a `uuid.UUID`.                                                          |
| `decode_bytes(s: str) -> bytes`          | Decode to 16 big-endian bytes (`uuid.UUID.bytes` order).                          |
| `decode_int(s: str) -> int`              | Decode to an `int` in `0..2**128 - 1`.                                            |
| `is_uuid58(s: object) -> bool`           | `True` exactly when `decode(s)` would succeed. Never raises.                      |
| `uuid58() -> str`                        | Generate a random UUIDv4 and return its encoding.                                 |
| `ALPHABET`, `MAX_UUID58`                 | The Base58 alphabet and the largest valid uuid58 string.                          |
| `Uuid58Error`, `ErrorKind`, …            | See [Errors](#errors).                                                            |

### Accepted UUID strings

`encode` accepts exactly two textual forms, in any letter case (SPEC.md
Section 5.1):

- hyphenated, 36 characters: `f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf`
- plain, 32 hex digits: `f4b247fd1f8745d4aa061c6fc0a8dfaf`

Everything else is rejected, including forms that `uuid.UUID()` accepts:
braces, the `urn:uuid:` prefix, misplaced hyphens and surrounding
whitespace. To encode those, parse them with `uuid.UUID(...)` first and pass
the resulting object.

`bytes` passed to `encode` are the 16 raw bytes of the UUID, never the ASCII
text of a UUID string.

## Development

Uses [uv](https://docs.astral.sh/uv/) (pinned via `mise.toml`).

```bash
uv run pytest            # tests, including spec/vectors.json conformance
uv run ruff check        # lint
uv run ruff format       # format
uv run mypy              # type check (strict)
```

The conformance tests read `../spec/vectors.json`, so run them from a
checkout of the repository.

## License

MIT
