Metadata-Version: 2.4
Name: vcti-app-data
Version: 1.0.0
Summary: Application data directory management and user profile storage with Pydantic models and filesystem-based persistence
Author: Visual Collaboration Technologies Inc.
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy; extra == "typecheck"
Dynamic: license-file

# App Data

Application data directory management and user profile storage with Pydantic models and filesystem-based persistence.

## Overview

vcti-app-data provides two components for managing application state on disk.
`AppDataDirectory` is a context manager that creates and scopes operations to
an application data directory. `ProfileManager` handles CRUD operations for
named user profiles, each stored as a JSON file in its own directory, with
active profile tracking and a default profile that cannot be deleted.

## Installation

```bash
pip install vcti-app-data>=1.0.0
```

---

## Quick Start

### Application data directory

```python
from vcti.app_data import AppDataDirectory

with AppDataDirectory("~/.config/my_app").context() as ctx:
    # Working directory is now ~/.config/my_app (created if needed)
    (ctx.path / "config.json").write_text('{"theme": "dark"}')
# Original working directory restored on exit
```

### Profile management

```python
from vcti.app_data import ProfileManager

mgr = ProfileManager("~/.config/my_app/profiles")

# Default profile created automatically
mgr.create_profile("dev", name="Development", tags=["dev"])
mgr.create_profile("prod", name="Production", attributes={"region": "us-east"})

mgr.set_active_profile("dev")
print(mgr.get_active_profile())  # "dev"

for profile in mgr.list_profiles():
    print(f"{profile.id}: {profile.info.name}")

mgr.delete_profile("prod")
# Deleting the active profile resets to default
```

---

## Core API

### AppDataDirectory

| Method | Description |
|--------|-------------|
| `context()` | Context manager — creates dir, changes CWD, restores on exit |
| `path` | The directory path |

### ProfileManager

| Method | Description |
|--------|-------------|
| `create_profile(profile_id, name, ...)` | Create a new profile |
| `get_profile(profile_id)` | Get profile by ID |
| `update_profile_info(profile_id, **kwargs)` | Update profile fields |
| `delete_profile(profile_id)` | Delete profile (not default) |
| `list_profiles()` | List all profiles (sorted by ID) |
| `set_active_profile(profile_id)` | Set the active profile |
| `get_active_profile()` | Get active profile ID |
| `profile_exists(profile_id)` | Check if profile exists |

### Pydantic Models

| Model | Purpose |
|-------|---------|
| `ProfileInfo` | name, description, avatar, tags, attributes |
| `Profile` | id + ProfileInfo |
| `ProfileList` | Collection of profiles (RootModel) |

---

## Dependencies

- [pydantic](https://docs.pydantic.dev/) (>=2.0) — data validation and JSON serialization
