Metadata-Version: 2.4
Name: dogwood-py
Version: 0.0.6
Classifier: Development Status :: 4 - Beta
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: Topic :: Security
Requires-Dist: maturin>=1.7,<2 ; extra == 'dev'
Requires-Dist: pytest>=8 ; extra == 'dev'
Requires-Dist: setuptools-scm[toml]>=8 ; extra == 'dev'
Requires-Dist: sphinx>=8 ; extra == 'dev'
Requires-Dist: sphinx-autobuild>=2024.10 ; extra == 'dev'
Requires-Dist: sphinx-book-theme>=1.1 ; extra == 'dev'
Requires-Dist: sphinx-copybutton>=0.5 ; extra == 'dev'
Requires-Dist: sphinx-sitemap>=2.6 ; extra == 'dev'
Requires-Dist: twine>=5 ; extra == 'dev'
Requires-Dist: fastapi>=0.115 ; extra == 'examples'
Requires-Dist: httpx2>=0.28 ; extra == 'examples'
Requires-Dist: uvicorn[standard]>=0.30 ; extra == 'examples'
Requires-Dist: strands-agents>=1 ; extra == 'strands'
Provides-Extra: dev
Provides-Extra: examples
Provides-Extra: strands
License-File: LICENSE
License-File: NOTICE
Summary: Python SDK and reference-compatible interpreter surface for Dogwood policies
Keywords: dogwood,policy,authorization,cedar,temporal-policy,pyo3,maturin,fastapi,strands-agents
Author-email: Abhishek Tiwari <abhishek@abhishek-tiwari.com>
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Reports, https://github.com/abhishektiwari/dogwood-py/issues
Project-URL: Documentation, https://dogwood-py.abhishek-tiwari.com/
Project-URL: Homepage, https://github.com/abhishektiwari/dogwood-py
Project-URL: Repository, https://github.com/abhishektiwari/dogwood-py
Project-URL: Source, https://github.com/abhishektiwari/dogwood-py

# Dogwood Policy Python SDK

Python SDK and PyO3 binding for the [Dogwood](https://github.com/dogwood-policy/dogwood) policy language. Dogwood supports fine-grained authorization decisions that depend on history or patterns of events over time, then lowers policies back to [Cedar](https://www.cedarpolicy.com/) for evaluation.

For full documentation, see **[dogwood-py.abhishek-tiwari.com](https://dogwood-py.abhishek-tiwari.com/)**.

> ⚠️⚠️⚠️ Current Dogwood reference interpreter is not intended for production use;
therefore, this Python SDK and PyO3 binding is experimental in nature.

> **Note:** This is an unofficial Python SDK and port for Dogwood Policy.
> Support is provided on a best effort basis with community help.

![GitHub Release](https://img.shields.io/github/v/release/abhishektiwari/dogwood-py)
![GitHub Actions Test Workflow Status](https://img.shields.io/github/actions/workflow/status/abhishektiwari/dogwood-py/test.yml?label=tests)
![PyPI - Version](https://img.shields.io/pypi/v/dogwood-py)
![Python Wheels](https://img.shields.io/pypi/wheel/dogwood-py)
![Python Versions](https://img.shields.io/pypi/pyversions/dogwood-py?logo=python&logoColor=white)
![GitHub last commit](https://img.shields.io/github/last-commit/abhishektiwari/dogwood-py)
![PyPI - Status](https://img.shields.io/pypi/status/dogwood-py)
![Conda Version](https://img.shields.io/conda/v/dogwood-py/dogwood-py)
![License](https://img.shields.io/github/license/abhishektiwari/dogwood-py)
![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/abhishektiwari/dogwood-py/total?label=GitHub%20Downloads)
![PyPI Downloads](https://img.shields.io/pepy/dt/dogwood-py?label=PyPI%20Downloads)

## Install

```bash
pip install dogwood-py
```

Optional extras:

```bash
pip install "dogwood-py[examples]"        # FastAPI and general examples
pip install "dogwood-py[strands]"         # Strands integration and shopping-agent example
pip install "dogwood-py[examples,strands]"
```

The package installs as `dogwood`:

```python
from dogwood import native

assert native.available()
```

## What It Provides

The public API follows the Rust `dogwood-language` lifecycle:

1. Build a `ServiceSchema` and `PolicySchema`.
2. Parse and lower policy source into a `LoweredPolicySet`.
3. Validate it.
4. Feed `Event` values to a stateful `Authorizer`.

The native path uses PyO3/maturin to call the Rust Dogwood reference implementation for schema-backed lowering, validation, trace replay, augmented Cedar schema export, and authorization. A temporary pure-Python fallback remains only for limited schema-less examples.

dogwood-py also provides optional Strands Agents support. Dogwood policies can be attached as Strands interventions so tool calls are checked before execution, with typed outcomes such as proceed, deny, guide, confirm, and transform.

## Documentation

- [Installation](https://dogwood-py.abhishek-tiwari.com/installation.html)
- [Getting Started](https://dogwood-py.abhishek-tiwari.com/getting-started.html)
- [Native Rust Binding](https://dogwood-py.abhishek-tiwari.com/native.html)
- [Strands Agents Integration](https://dogwood-py.abhishek-tiwari.com/strands.html)
- [Examples](https://dogwood-py.abhishek-tiwari.com/examples/index.html)
- [API Reference](https://dogwood-py.abhishek-tiwari.com/api.html)

Dogwood language documentation is available at [dogwood-policy.github.io/dogwood](https://dogwood-policy.github.io/dogwood/index.html).

## Examples

Checked-in examples are documented at [Examples](https://dogwood-py.abhishek-tiwari.com/examples/index.html).
After installing the package and optional dependencies, run examples directly:

```bash
python -m examples.api_usage

python -m examples.cli

python -m uvicorn examples.fastapi_simple.app:app --host 127.0.0.1 --port 8000

python -m examples.strands_shopping_agent.agent --user alice
```

## Development

```bash
make setup
make develop
make test
make docs
make build
```

Useful targets:

- `make docs-ci` installs docs-only dependencies and builds Sphinx HTML docs.
- `make docs-watch` serves live-reloading docs at `http://127.0.0.1:8001`.
- `make perf-test` runs the opt-in native-vs-Python replay regression check.

The docs-only Cloudflare Pages build command is:

```bash
make docs-ci PYTHON=python
```

Build output directory:

```text
docs/build/html
```

## Current Scope

Rust-backed operations cover schema-backed lowering, validation, authorization, and trace replay. The Python fallback is temporary and schema-less only. The intended end state is to remove it once the Rust-backed SDK objects cover the same ergonomic surface.

