Metadata-Version: 2.4
Name: parsled
Version: 0.2.0
Summary: Parser and serializer for Sled, a serialization language for developer-friendly reading and writing
Keywords: sled,parse,serialize,deserialize,readable,language,format
Author: Kawin
Author-email: Kawin <kawin.open@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: Topic :: File Formats
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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
Maintainer: Kawin
Maintainer-email: Kawin <kawin.open@gmail.com>
Requires-Python: >=3.8
Project-URL: Homepage, https://github.com/kawindex/sled/python
Project-URL: Source, https://github.com/kawindex/sled.git
Project-URL: Issues, https://github.com/kawindex/sled/issues
Description-Content-Type: text/markdown

# `parsled`

Python package for parsing Sled and serializing Python objects as Sled.

Sled is a serialization language for developer-friendly reading and writing.


## Parse: Sled to Python `dict`

To parse Sled into a Python `dict`, call `from_sled()`.

```python
from parsled import from_sled

with open("path/to/my_file.sled", mode="r") as f:
    data = from_sled(f.read())
```


## Serialize: Python to Sled

This package provides 2 ways to serialize Python objects.
1. Call `to_sled()`.
2. Instantiate a `SledSerializer` and call its `to_sled()` method.

Both have the same configuration options and defaults.
For details, refer to the `SledSerializer` documentation.

Approach #1 simply does approach #2 under the hood.
Approach #2 may be useful if you want to set a configuration once
and reuse that for serialization multiple times.

```python
from parsled import SledSerializer, to_sled

data = {}
other_data = {}

# Approach #1
sled = to_sled(data)

# Approach #2
sled_serializer = SledSerializer()
sled = sled_serializer.to_sled(data)
other_sled = sled_serializer.to_sled(other_data)
```

### Default serialization

Instances of the following Python data types (on the left) will be serialized
as the associated Sled data type (on the right).
- `None`: `nil`
- `bool`: `boolean`
- `bytes`: `hex`
- `int`: `integer`
- `float`: `float`
- `str`: `identity`, `quote`, or `concat`
- `Mapping[str, Entity]`: `smap`
- `Mapping[int, Entity]`: `imap`
- `Iterable` that is not a `Mapping`: `list`
- dataclass: `smap`

For an object to be serialized as a standalone Sled document,
it should be a `Mapping[str, Entity]` or dataclass instance,
since the top level of a Sled document is always a `smap`.

A dataclass instance is implicitly converted into a `Mapping`
by calling `dataclasses.fields()` (unless the original instance is itself
also a `Mapping`, in which case that takes precedence).
