# objectstore.path

> A module of objectstore's API.

`objectstore.path` — URI parsing and location handling.

Iceberg stores **absolute** locations everywhere: a table's `location`, a
snapshot's `manifest-list`, a manifest entry's `file_path`. Those strings are
the only addressing this stack has, so parsing them precisely — and rewriting
them when a warehouse is copied somewhere else — is a first-class concern
rather than string fiddling scattered across call sites.

Grammar handled here:

    s3://bucket/key/parts        object stores (s3, s3a, s3n, gs, gcs, abfs*, wasb*)
    https://host/path?query      HTTP(S), including presigned URLs
    file:///abs/path             a local file, RFC 8089 style
    file://host/abs/path         tolerated; the host is ignored
    /abs/path or rel/path        a bare filesystem path, scheme `file`

## Structs

### `Uri`

```mojo
struct Uri
```

A parsed location.

`bucket` is the authority: an S3/GCS bucket, an Azure container's account
host, or an HTTP host[:port]. `key` is everything after it with no leading
slash — which is exactly what an S3 request needs, and exactly what a
filesystem path needs once the leading slash is put back for `file`.

Implements: `Copyable`, `Movable`, `Writable`

Fields:

- `scheme: String`
- `bucket: String`
- `key: String`
- `query: String`
- `raw: String`

#### `__init__`

```mojo
def __init__(out self, var scheme: String, var bucket: String, var key: String, var query: String, var raw: String)
```

#### `is_local`

```mojo
def is_local(self) -> Bool
```

#### `is_object_store`

```mojo
def is_object_store(self) -> Bool
```

#### `local_path`

```mojo
def local_path(self) -> String
```

The filesystem path for a `file:` URI.

`file:///a/b` and `/a/b` both give `/a/b`; a relative bare path is
returned unchanged so `tests/fixtures/x` keeps working.

#### `canonical`

```mojo
def canonical(self) -> String
```

The location rebuilt from its parts — round-trips `parse_uri`.

#### `write_to`

```mojo
def write_to(self, mut writer: T)
```

## Functions

### `parse_uri`

```mojo
def parse_uri(location: String) -> Uri
```

### `join`

```mojo
def join(base: String, child: String) -> String
```

Joins a location with a relative child. An absolute `child` wins.

### `basename`

```mojo
def basename(location: String) -> String
```

### `parent`

```mojo
def parent(location: String) -> String
```

The containing directory/prefix, with no trailing slash.

`s3://b/a/b/c` -> `s3://b/a/b`; `s3://b/c` -> `s3://b`; a bare name with
no slash has no parent and yields `""`.

### `strip_scheme`

```mojo
def strip_scheme(location: String) -> String
```

`file:///a/b` -> `/a/b`; other schemes are returned unchanged.

Kept byte-compatible with `iceberg.io.strip_scheme` so iceberg.mojo can
swap its copy for this one.

### `url_encode`

```mojo
def url_encode(s: String, encode_slash: Bool = True) -> String
```

RFC 3986 percent-encoding of everything outside the unreserved set.

SigV4 needs both variants: path segments keep `/` literal, query keys and
values do not (SigV4 §canonical query string).

## Aliases

### `SCHEME_FILE`

```mojo
comptime SCHEME_FILE = String("file")
```

### `SCHEME_S3`

```mojo
comptime SCHEME_S3 = String("s3")
```

### `SCHEME_HTTP`

```mojo
comptime SCHEME_HTTP = String("http")
```

### `SCHEME_HTTPS`

```mojo
comptime SCHEME_HTTPS = String("https")
```

### `SCHEME_GS`

```mojo
comptime SCHEME_GS = String("gs")
```

### `SCHEME_ABFS`

```mojo
comptime SCHEME_ABFS = String("abfs")
```