Metadata-Version: 2.3
Name: msgspec-yaml
Version: 1.0.2
Summary: Simple YAML loader for msgspec.Struct
Author: Cryder
Author-email: Cryder <cronyx.developer@gmail.com>
Requires-Dist: msgspec>=0.21.1
Requires-Dist: pyyaml>=6.0.3
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# msgspec-yaml

Simple YAML loader for `msgspec.Struct`.

## Installation

### uv
```bash
uv add msgspec-yaml
```

### pip
```bash
pip install msgspec-yaml
```

### poetry
```bash
poetry add msgspec-yaml
```

## Usage

```python
import msgspec

import msgspec_yaml


class Config(msgspec.Struct):
    host: str
    port: int


config = msgspec_yaml.load("config.yml", Config)

print(config.host)
print(config.port)
```

Example YAML file:

```yaml
host: localhost
port: 8000
```

## API

### `msgspec_yaml.load(path, struct, encoding="utf-8")`

Load a YAML file and convert its contents into a `msgspec.Struct`.

#### Parameters

* `path` (`str | pathlib.Path`) — path to the YAML file.
* `struct` (`type[msgspec.Struct]`) — target structure class.
* `encoding` (`str`) — file encoding. Defaults to `utf-8`.

#### Returns

An instance of the provided `msgspec.Struct`.

#### Raises

* `FileNotFoundError` — file does not exist.
* `yaml.YAMLError` — invalid YAML file or unsupported file extension.
* `msgspec.ValidationError` — data validation failed during conversion.

## Why?

Instead of writing:

```python
import msgspec
import yaml


class Config:
    host: str
    port: int


with open("config.yml") as f:
    data = yaml.safe_load(f)

config = msgspec.convert(data, type=Config)
```

you can simply write:

```python
import msgspec_yaml


class Config:
    host: str
    port: int

config = msgspec_yaml.load("config.yml", Config)
```
