Metadata-Version: 2.4
Name: osp-provider-sdk
Version: 0.10.5
Summary: Optional declaration, planning and progress helpers for OSP providers.
Author: OSP Team
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: loguru<1,>=0.7
Requires-Dist: osp-provider-contracts==0.18.2
Requires-Dist: osp-provider-runtime==0.16.5
Requires-Dist: pika<2,>=1.3
Requires-Dist: pydantic<3,>=2.11.7
Requires-Dist: pyyaml<7,>=6.0.2
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: hatch<2,>=1.14; extra == 'dev'
Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Requires-Dist: ty>=0.0.89; extra == 'dev'
Requires-Dist: uv<0.14,>=0.13.4; extra == 'dev'
Description-Content-Type: text/markdown

# osp-provider-sdk

Write an OSP provider in plain Python. A provider connects OSP to your service:
it lists your resources and plans and applies the changes users request.
The SDK handles the wire protocol, input validation, approvals, ownership checks
and progress reporting, so your code only talks to your backend.

## Install

Requires Python 3.13 or newer.

```bash
uv pip install osp-provider-sdk
```

## A minimal provider

```python
from contextlib import contextmanager
from datetime import UTC, datetime

from pydantic import BaseModel, ConfigDict, Field

from osp_provider_sdk import App, Done, Page, Resource, ResourceOwnership


@contextmanager
def lifespan():
    yield {}  # your backend client; available as app.state while running


app = App("notes", description="Sticky notes", lifespan=lifespan)


class Create(BaseModel):
    model_config = ConfigDict(frozen=True)
    name: str = Field(title="Name")
    text: str = Field("", title="Text")


class Row(BaseModel):
    text: str = Field(title="Text")


@app.resource("note", fields=Row)
def notes(q, access) -> Page:
    rows = [
        Resource(target_ref=ref, display=ref, ownership=owner, fields={"text": text})
        for ref, (text, owner) in app.state.items()
    ]
    return Page(tuple(rows), observed_at=datetime.now(UTC).isoformat())


@app.action("create", inputs=Create)
def create(req, ctx) -> Done:
    owner = ResourceOwnership(contacts=frozenset(ctx.contacts))
    app.state[req.name] = (req.inputs.text, owner)
    ctx.created(req.name)
    return Done(f"Created note {req.name}")


if __name__ == "__main__":
    app.run()
```

The input model becomes the form users fill in, the resource becomes an
inventory list, and the runtime checks ownership and policy before your
handler runs. `app.state` is whatever `lifespan` yields, typed from it.

## Try it without OSP

Save the code as `notes.py`. These commands need no orchestrator or RabbitMQ:

```bash
python -m osp_provider_sdk manifest notes:app              # what OSP will see
python -m osp_provider_sdk doctor notes:app --offline      # declarations and policy
python -m osp_provider_sdk plan notes:app create '{"text": "buy milk"}' --name milk
```

`python notes.py` serves the provider over RabbitMQ; it reads `RABBITMQ_URL`
and `PROVIDER_INSTANCE`.

## Next steps

- **Build a real provider:** start from the
  [provider template](https://github.uio.no/IT-OPS/osp-provider-cookiecutter)
  and follow the [tutorial](https://github.uio.no/IT-OPS/osp-provider-tutorial).
- **Understand how it works:** [concepts](https://github.uio.no/IT-OPS/osp-provider-sdk/blob/main/docs/concepts.md)
  covers lifetime, ownership, planning and approval, progress and results.
- **Declare inputs and resources:** [manifest](https://github.uio.no/IT-OPS/osp-provider-sdk/blob/main/docs/manifest.md).
- **Approvals and policy:** [policy](https://github.uio.no/IT-OPS/osp-provider-sdk/blob/main/docs/policy.md).
- **Test locally:** [testing](https://github.uio.no/IT-OPS/osp-provider-sdk/blob/main/docs/testing.md).
- **API contracts:** [API reference](https://github.uio.no/IT-OPS/osp-provider-sdk/blob/main/docs/api.md).
- **Worked examples:** [bucket and sandwich shop providers](https://github.uio.no/IT-OPS/osp-provider-sdk/blob/main/examples/README.md).
- **Deploy to OSP dev and prod:** [provider onboarding](https://github.uio.no/IT-OPS/osp-deployment/blob/main/docs/PROVIDER_ONBOARDING.md).
- **Contribute:** [CONTRIBUTING.md](https://github.uio.no/IT-OPS/osp-provider-sdk/blob/main/CONTRIBUTING.md)
  and the [changelog](https://github.uio.no/IT-OPS/osp-provider-sdk/blob/main/CHANGELOG.md).
