Metadata-Version: 2.4
Name: mailparse-mailkite
Version: 0.1.0
Summary: Python port of @mailkite/mail-parse — MIME parser + cross-language failure-signature primitive.
License: MIT
Project-URL: Homepage, https://mailkite.dev
Project-URL: Repository, https://github.com/mailkite/mail-parse
Keywords: mime,email,parser,mailkite
Requires-Python: >=3.8
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://mailkite.dev">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://mailkite.dev/brand/logo-email-dark.png">
      <img src="https://mailkite.dev/brand/logo-email.png" alt="MailKite" height="56">
    </picture>
  </a>
</p>

<h1 align="center">MailKite mail-parse (Python)</h1>

<p align="center">
  <b>Streaming, memory-efficient MIME email parser</b> — the Python port of <a href="https://github.com/mailkite/mail-parse"><code>@mailkite/mail-parse</code></a>.
  <br>Same parsed <code>Message</code> shape, and a failure-signature primitive whose hashes match the TypeScript package byte-for-byte.
</p>

<p align="center">
  <a href="https://mailkite.dev/docs">Docs</a> ·
  <a href="https://mailkite.dev/docs/libraries">Libraries</a> ·
  <a href="https://github.com/mailkite/mail-parse">Node / TypeScript</a> ·
  <a href="https://mailkite.dev">mailkite.dev</a>
</p>
<p align="center"><img src="https://img.shields.io/badge/license-MIT-2563eb" alt="MIT"> · <img src="https://img.shields.io/badge/python-3.8%2B-2563eb" alt="Python 3.8+"></p>

> Maintained in the MailKite monorepo; this is the public home for the Python port. The TypeScript package ([`mail-parse`](https://github.com/mailkite/mail-parse)) is the reference implementation.

## Why

- **Cross-language SSOT** — `compute_signature()` produces the **same failure-signature hash** as the TypeScript package for the same failure (conformance-tested against hashes captured from TS).
- **Same `Message` shape** — `parse()` returns the same structured fields, so payloads are consistent across your stack.
- **Tolerant** — malformed input never raises.

## Install

```bash
pip install mailparse-mailkite
```

## Quickstart

```python
from mailparse import parse, compute_signature

msg = parse(raw_bytes)
msg.from_        # Address(address=..., name=...)
msg.subject
msg.text; msg.html
msg.attachments  # [Attachment(filename, mimeType, content: bytes, size, ...)]

# Deterministic, PII-free fingerprint of a parse failure — identical hash to the TS package.
sig = compute_signature({"scope": "part", "diagnosticCodes": ["UNKNOWN_CHARSET"],
                         "contentType": "text/plain"})
sig["hash"]
```

## Status

The **failure-signature primitive** is fully ported and cross-language conformance-tested. `parse()` is
built on the stdlib `email` package (the documented `ContentManager` precedent) — the buffered path.
Porting the *streaming splitter + middleware registry* to Python is in progress; the
[TypeScript package](https://github.com/mailkite/mail-parse) is the reference.

## Develop

```bash
python3 -m unittest discover -s tests
```

## All MailKite libraries

| Library | Repo | Distribution |
| --- | --- | --- |
| mail-parse (Node / TypeScript) | [`mail-parse`](https://github.com/mailkite/mail-parse) | npm |
| mail-parse (Python) **(this repo)** | [`mail-parse-py`](https://github.com/mailkite/mail-parse-py) | PyPI |
| MailKite for Python | [`mailkite-python`](https://github.com/mailkite/mailkite-python) | PyPI |
| MailKite for Node.js | [`mailkite-node`](https://github.com/mailkite/mailkite-node) | npm |

Full list: [https://mailkite.dev/docs/libraries](https://mailkite.dev/docs/libraries).

## Docs & links

- 📚 **Documentation:** https://mailkite.dev/docs
- 🟦 **TypeScript reference:** https://github.com/mailkite/mail-parse
- 🌐 **Website:** https://mailkite.dev

<sub>MIT licensed. © MailKite.</sub>
