Metadata-Version: 2.5
Name: uploadkit-office
Version: 0.1.0
Summary: Office document validators, policies, and metadata for UploadKit
Project-URL: Homepage, https://github.com/uploadkit/uploadkit-office
Project-URL: Repository, https://github.com/uploadkit/uploadkit-office
Author: UploadKit
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: docx,office,pptx,uploadkit,validation,xlsx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: uploadkit>=0.2.0
Provides-Extra: dev
Requires-Dist: coverage>=7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: uploadkit-testing>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# uploadkit-office

[![CI](https://github.com/uploadkit/uploadkit-office/actions/workflows/ci.yml/badge.svg)](https://github.com/uploadkit/uploadkit-office/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen)](https://github.com/uploadkit/uploadkit-office/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](pyproject.toml)

Office document validators, policies, and metadata for UploadKit.

## What problem does this solve?

OOXML/ODF structure and security checks (macros, external links, embeds) that
plug into `UploadPolicy.validators` without modifying UploadKit Core.

## When to use it

Use for DOCX, XLSX, PPTX, ODT, and ODS uploads that must stay macro-free by default.

## When not to use it

- Do not edit or convert office documents here.
- Do not put generic MIME/filename checks here (see `uploadkit-security`).

## Installation

Requires **Python 3.10+**. No extra native dependencies (stdlib `zipfile` + XML).

```bash
pip install uploadkit-office
```

## Quick Start

```python
from uploadkit import Uploader
from uploadkit_office import DocxPolicy, OfficePolicy, OfficeKind

uploader = Uploader(DocxPolicy(max_size=10 * 1024 * 1024), storage=my_storage)

# Or allow multiple kinds:
policy = OfficePolicy(kinds=frozenset({OfficeKind.DOCX, OfficeKind.XLSX}))
```

## Public API

| Symbol | Kind |
|--------|------|
| `OfficePolicy` / `DocxPolicy` / `XlsxPolicy` / `PptxPolicy` | Public |
| `OfficeKind` / `OfficeMetadata` / `inspect_office` | Public |
| `OfficeStructureValidator` / `OfficeSecurityValidator` / `OfficeSheetLimitValidator` | Public |
| `default_office_validators` / `default_async_office_validators` | Public |
| Async validator equivalents | Public |

## Coverage

The coverage badge is a **measured** total from
`coverage report --include='src/*'`, not an aspirational 100%. CI enforces
`--fail-under=80`.

Most of the remaining gap is defensive and format-variant code in `metadata.py`
(edge-case ZIP/ODF parsing, zip-bomb heuristics). Validators and policies are
fully covered. Unlike Core / framework adapters, this package does not claim
100% yet — fixtures for those branches are welcome.

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).
