Metadata-Version: 2.4
Name: endec
Version: 0.3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Utilities
License-File: LICENSE
Summary: Web-compatible encoding and decoding library
Keywords: encoding_rs,web,codec
Author-email: Thitat Auareesuksakul <flux@thitat.net>
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/fluxth/endec
Project-URL: Source, https://github.com/fluxth/endec
Project-URL: Changelog, https://github.com/fluxth/endec/releases

# endec

[![PyPI - Version](https://img.shields.io/pypi/v/endec)](https://pypi.org/project/endec/)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/endec)
![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/fluxth/endec/build.yml)
![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/fluxth/endec/test.yml?label=tests)

Web-compatible **en**coding and **dec**oding library

**endec** uses [`encoding_rs`](https://github.com/hsivonen/encoding_rs) (which powers Firefox) under the hood.

## Installation

Requires Python 3.8+

```
$ pip install endec
```

## Examples

### Codecs

Please refer to [WHATWG Web Encoding Standard](https://encoding.spec.whatwg.org/#concept-encoding-get) for available codecs.

### Encode

```python
import endec

utf8_bytes = endec.encode("こんにちは")
assert utf8_bytes == b"\xe3\x81\x93\xe3\x82\x93\xe3\x81\xab\xe3\x81\xa1\xe3\x81\xaf"

iso2022jp_bytes = endec.encode("㊤㊥㊦", "iso-2022-jp")
assert iso2022jp_bytes == b"\x1b$B-e-f-g\x1b(B"

"㊤㊥㊦".encode("iso-2022-jp")  # Standard Library `encode`
# UnicodeEncodeError: 'iso2022_jp' codec can't encode character '\u32a4' in position 0: illegal multibyte sequence
```

### Decode

```python
import endec

utf8_str = endec.decode(b"\xe3\x81\x93\xe3\x82\x93\xe3\x81\xab\xe3\x81\xa1\xe3\x81\xaf")
assert utf8_str == "こんにちは"

iso2022jp_str = endec.decode(b"\x1b$B-e-f-g\x1b(B", "iso-2022-jp")
assert iso2022jp_str == "㊤㊥㊦"

b"\x1b$B-e-f-g\x1b(B".decode("iso-2022-jp")  # Standard Library `decode`
# UnicodeDecodeError: 'iso2022_jp' codec can't decode bytes in position 3-4: illegal multibyte sequence
```

### Error Handling

```python
import endec
from endec.exceptions import EncodeError, DecodeError

try:
    invalid_encode = endec.encode("漢字", "ascii")
except EncodeError as exc:
    # endec.exceptions.EncodeError: encoding with 'windows-1252' codec failed
    raise exc

try:
    invalid_decode = endec.decode(b"\x42\xff\x42", "iso-2022-jp")
except DecodeError as exc:
    # endec.exceptions.DecodeError: decoding with 'ISO-2022-JP' codec failed
    raise exc
```

## License

This project is licensed under the terms of the [MIT license](https://github.com/fluxth/endec/blob/main/LICENSE).

