Metadata-Version: 2.5
Name: framework-py
Version: 0.1.0.dev25
Summary: Structured data science projects: a data catalog, integrity tracking, caching, outputs, and AI guardrails
Project-URL: Homepage, https://framework.pub
Project-URL: Source, https://github.com/frameworktools/framework-py
Project-URL: Issues, https://github.com/frameworktools/framework-py/issues
Author-email: Erik Westlund <erik@table1.org>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: jsonschema>=4.18
Requires-Dist: keyring>=25
Requires-Dist: pandas>=2.2
Requires-Dist: pyarrow>=16
Requires-Dist: pyyaml>=6.0
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: secretstorage>=3.2; sys_platform == 'linux'
Provides-Extra: duckdb
Requires-Dist: duckdb>=1.0; extra == 'duckdb'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == 'excel'
Provides-Extra: mysql
Requires-Dist: pymysql>=1.1; extra == 'mysql'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Provides-Extra: rds
Requires-Dist: pyreadr>=0.5; extra == 'rds'
Provides-Extra: s3
Requires-Dist: boto3>=1.34; extra == 's3'
Provides-Extra: sas
Requires-Dist: pyreadstat>=1.2; extra == 'sas'
Provides-Extra: spss
Requires-Dist: pyreadstat>=1.2; extra == 'spss'
Provides-Extra: sqlserver
Requires-Dist: pyodbc>=5.0; extra == 'sqlserver'
Description-Content-Type: text/markdown

# framework-py

Framework for Python provides structured data science projects with a data catalog, integrity tracking, caching, saved outputs, and AI coding assistant guardrails.

`framework-py` is the Python implementation of [Framework](https://framework.pub) ([documentation](https://py.framework.pub)). It reads and writes the same project files as the R package (`settings.yml`, the data catalog, and `framework.db`), so either language can read and verify a project's data. It runs standalone without Framework Cloud or the `fw` CLI.

Status: in development. See [docs/plan.md](docs/plan.md) for the implementation plan.

## Installation

```sh
uv add framework-py
# or
pip install framework-py
```

Optional extras install database drivers, S3 storage, and additional file formats: `postgres`, `mysql`, `duckdb`, `sqlserver`, `s3`, `excel`, `spss`, `sas` (version 8 SAS transport files), and `rds` (R `.rds` data frames).

```sh
uv add "framework-py[postgres,s3]"
```

GitHub Actions builds releases with signed build provenance. Verify that a wheel or sdist came from this repository:

```sh
gh attestation verify framework_py-<version>-py3-none-any.whl --repo frameworktools/framework-py
```

## Quick start

```python
import framework as fw

fw.settings("directories.notebooks")
info = fw.data_info("inputs.raw.survey")
fw.data_list()
```

Prepare a cloned project:

```sh
uv run python -m framework bootstrap
```

## Framework Cloud sync

Pull or push packages, skills, and the data registry for a linked Framework Cloud project. Each call lists changes by section and asks once before applying them.

```python
fw.pull_all(dry_run=True)
fw.pull_all()
fw.push_all()
```

`pull_skills()`, `push_skills()`, `pull_data_registry()`, and `push_data_registry()` sync individual sections.

## Skill sync

Sync a local skill and its companion files with your Framework Cloud account:

```python
fw.skills_sync(".agents/skills/my-skill", dry_run=True)
fw.skills_sync(".agents/skills/my-skill")
```

Local edits create account versions. Edited Framework skills become private forks pinned to an exact source version. Concurrent edits stop for reconciliation. See the [Skill sync guide](https://framework.pub/docs/skill-sync).

## Development

```sh
uv sync
uv run pytest
uv run ruff check && uv run ruff format --check
uv run mypy
uv run python scripts/check_parity.py
uv run python scripts/sync_assets.py --check
```

`scripts/sync_assets.py` copies shared files (JSON Schemas, the `framework.db` schema, conformance fixtures, and the R export list) from the R package. Edit shared assets in the R repository, then run `scripts/sync_assets.py` here.

`parity.toml` maps every exported R function to its Python equivalent or records why none exists.
