Metadata-Version: 2.1
Name: arches-orm
Version: 0.4.2
Summary: Representation of Arches graphs for client and server side manipulation
Author-email: Phil Weir <phil.weir@flaxandteal.co.uk>
License-File: LICENSE.txt
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: edtf
Requires-Dist: eval-type-backport
Requires-Dist: geojson
Requires-Dist: lxml
Requires-Dist: pydantic
Requires-Dist: python-slugify
Requires-Dist: rdflib
Requires-Dist: tabulate
Requires-Dist: typing-extensions
Provides-Extra: arches
Requires-Dist: arches; extra == 'arches'
Provides-Extra: docs
Requires-Dist: mkdocs-material==7.0; extra == 'docs'
Requires-Dist: tmp-fat-portray>=v1.8.0; extra == 'docs'
Provides-Extra: graphql
Requires-Dist: aiodataloader; extra == 'graphql'
Requires-Dist: aiohttp; extra == 'graphql'
Requires-Dist: django-oauth2-provider; extra == 'graphql'
Requires-Dist: graphene; extra == 'graphql'
Requires-Dist: graphene-file-upload; extra == 'graphql'
Requires-Dist: oauth2-provider; extra == 'graphql'
Requires-Dist: starlette; extra == 'graphql'
Requires-Dist: starlette-context; extra == 'graphql'
Requires-Dist: starlette-graphene3; extra == 'graphql'
Requires-Dist: uvicorn[standard]; extra == 'graphql'
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: httpx; extra == 'test'
Requires-Dist: jsondiff; extra == 'test'
Requires-Dist: mypy; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-django; extra == 'test'
Requires-Dist: ruff; extra == 'test'
Requires-Dist: spatialite; extra == 'test'
Description-Content-Type: text/markdown

# (Unofficial) Arches ORM [EXPERIMENTAL]

This provides simple (server-side) access to Arches resources from Python
as Python objects. It makes no guarantees about efficiency or type-accuracy
but such issues raised will be addressed as far as possible.

## Installation

Basic installation can then happen as follows, _without_ Arches backend support:

```
pip install .
```

To run tests, make sure you have `libsqlite3-mod-spatialite`, or your distribution's equivalent
package for enabling Spatialite in Python. Instead of using a real Arches PostgreSQL database, we spin
a fresh test database up in memory.

**WARNING:** The mock DB behaviour for Python testing is not identical to a
real Arches database, but is adequately close for now, is fast and has no server dependency.

There are several sets of optional dependencies.

### GraphQL

Turns Arches ORM into an API server for Arches.

```
pip install .[graphql]
```

### Arches

Allows Arches ORM to directly manipulate the Arches database.

```
pip install .[arches]
```

### Test

Runs tests across the various backends.

```
pip install .[tests]
```

## Well-known Resource Models

To provide a partial boundary, this package expects a settings object called
`WELL_KNOWN_RESOURCE_MODELS` to list, at least, the models that should be
wrapped by this system.

It should be a list:

    WELL_KNOWN_RESOURCE_MODELS = [
        {
            "model_name": "Person",
            "graphid": "4110f743-1a44-11e9-9a37-000d3ab1e500",
            "nodes": {}, # optional additional configuration
            "to_string": lambda wkrm: str(wkrm) # optional callback for stringifying
        }
    ]

You must _not_ take this list as an exclusive boundary of data that can be accessed.

## Hooks

This package also contains experimental functionality for hooking tile saves,
so that client code can use the `MyModel.post_save` signal to get well-known
resource model events. To avoid any unintended overhead, it does not load
unless explicitly turned on with `arches_orm.add_hooks()`.

## Tests

Note that the tests require `spatialite` and so a Python that allows Sqlite3
extension loading:

    PYTHON_CONFIGURE_OPTS="--enable-loadable-sqlite-extensions" pyenv install 3.10.10

## Documentation

Documentation is available on [https://flaxandteal.github.io/arches-orm/](https://flaxandteal.github.io/arches-orm/).

## Thanks

Particular thanks to the funders of this work, and to the Arches community for
their work on which this builds. Particular thanks to Historic England's team
for the underlying resource models used in the test-cases.
