Metadata-Version: 2.4
Name: outline-python
Version: 0.1.0
Summary: Python client and CLI for the Outline API.
Project-URL: Homepage, https://github.com/singularcurio/outline-py
Project-URL: Repository, https://github.com/singularcurio/outline-py
Project-URL: Issues, https://github.com/singularcurio/outline-py/issues
Author: Singular Curiosity
Keywords: api,cli,client,knowledge-base,markdown,outline
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx<0.29,>=0.28.1
Requires-Dist: pydantic<3,>=2.11.3
Requires-Dist: rich<15,>=14.3.0
Requires-Dist: typer<0.17,>=0.16.0
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.3.5; extra == 'dev'
Requires-Dist: ruff<0.12,>=0.11.5; extra == 'dev'
Description-Content-Type: text/markdown

# outline-py

Python client and CLI for the Outline API.

PyPI distribution: `outline-python`
Import package: `outline_py`
CLI command: `outline-py`

`outline-py` provides:

- A typed synchronous Python client
- A typed asynchronous Python client
- A Typer-based CLI
- Full current Outline API surface coverage, plus typed convenience commands for common workflows

## Install

```bash
uv sync --extra dev
```

For consumers:

```bash
pip install outline-python
```

## Setup

```bash
uv venv .venv
uv sync --extra dev
source .venv/bin/activate
```

## Python usage

```python
from outline_py import OutlineClient

with OutlineClient(api_key="ol_api_...", base_url="https://app.getoutline.com/api") as client:
    response = client.documents.search(query="hiring", limit=10)
    print(response.data)
```

## Async Python usage

```python
import asyncio

from outline_py import AsyncOutlineClient


async def main() -> None:
    async with AsyncOutlineClient(api_key="ol_api_...") as client:
        response = await client.documents.search(query="hiring", limit=10)
        print(response.data)


asyncio.run(main())
```

## CLI usage

The CLI exposes two layers:

1. Typed commands for common workflows
2. Full API coverage through grouped `--payload` commands

```bash
outline-py common whoami
outline-py common search "hiring" --limit 10
outline-py common doc-info hDYep1TPAM
outline-py common doc-show hDYep1TPAM
outline-py common collection-create Engineering
outline-py common share-create 3b6d8f9a-...
```

The grouped commands remain available for the full surface:

```bash
outline-py auth info
outline-py documents search --payload '{"query":"hiring","limit":10}'
outline-py collections create --payload '{"name":"Engineering"}'
```

Configuration can be provided through flags or environment variables:

```bash
export OUTLINE_API_KEY="ol_api_..."
export OUTLINE_BASE_URL="https://app.getoutline.com/api"
outline-py documents info --payload '{"id":"doc_123"}'
outline-py common doc-info doc_123
```

The `--payload` value uses the Python client's snake_case parameter names.

## Development

```bash
uv run ruff check .
uv run pytest
uv build
```

## Release

The repository includes a GitHub Actions workflow at `.github/workflows/workflow.yaml`
that publishes to PyPI when you push a tag matching `v*`.

Example:

```bash
git tag v0.1.0
git push origin v0.1.0
```

For publishing to work, configure PyPI Trusted Publishing for the
`singularcurio/outline-py` GitHub repository.
