Metadata-Version: 2.4
Name: StoryCADLib
Version: 4.1.0.dev1
Summary: Core library for StoryCAD, the outline creation and manipulation tool for fiction writers.
Project-URL: Homepage, https://github.com/storybuilder-org/StoryCAD
Project-URL: Issues, https://github.com/storybuilder-org/StoryCAD/issues
Author: StoryBuilder.org
License-Expression: GPL-3.0-or-later
License-File: ADDITIONAL-LICENSE-PERMISSIONS.TXT
License-File: LICENSE.TXT
Keywords: outline,pythonnet,story,storycad,writing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: pythonnet>=3.0.3
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# storycad

Python wrapper around the StoryCAD .NET API
(`StoryCADLib.Services.API.StoryCADApi`). Hosts the CLR in-process via
[`pythonnet`](https://pythonnet.github.io/) and exposes a Pythonic, snake_case
surface; errors surface as `StoryCADError` instead of `OperationResult<T>`
sentinels, and async (`Task<T>`) methods are joined inline.

The wheel bundles a published build of `StoryCADLib` under
`storycad/runtime/`, so end users do **not** need the .NET SDK — only the
.NET 10 runtime (the wheel is built with `--self-contained false`).

## Prerequisites

- Python 3.10+
- .NET 10 runtime installed on the host (https://dotnet.microsoft.com/download)
- A wheel matching your platform. Wheels are platform-specific; CI builds:
  Linux x64, Linux arm64, macOS arm64, Windows x64.

## Install

```bash
pip install storycadlib-<version>-<platform>.whl
```

## Quick example

```python
from storycad import StoryCAD

sc = StoryCAD()
guids = sc.create_empty_outline("My Story", "Author", "0")
overview = next(e for e in sc.get_all_elements() if e.element_type == "StoryOverview")
hero = sc.add_element(sc.item_type.Character, overview.uuid, "Hero")
sc.write_outline("/tmp/my_story.stbx")
```

## Building from source

```bash
git clone https://github.com/storybuilder-org/StoryCAD
cd StoryCAD/bindings/python
./build-wheel.sh   # runs dotnet publish, stages runtime, then python -m build
```

The script detects your host RID, publishes `StoryCADLib` for the matching
framework-dependent target, and produces a platform wheel under `dist/`.

## Known limitations

- Async methods are joined synchronously on the calling thread — no real
  asyncio integration yet.
- Wheels are platform-specific; you need a wheel built for your OS + arch.
- StoryCAD is GPL-3.0-or-later. Bundling its DLL into a wheel inherits that
  license; any project that ships this wheel must comply.
