Feature/emerald/36/domain value view model

.github/workflows/_build.py

@@ -0,0 +1,54 @@
+from portray import config, render  # type: ignore
+from typing import Any
+import yaml
+
+# Note that this does not work for reloads.
+mkdocs = config.mkdocs
+
+
+def _mkdocs(directory: str, **overrides) -> dict:  # type: ignore
+    superfences = yaml.unsafe_load("""
+      preserve_tabs: true
+      custom_fences:
+        # Mermaid diagrams
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+    """)
+    overrides.setdefault("markdown_extensions", [])
+    for n, ext in enumerate(overrides["markdown_extensions"]):
+        if ext == "pymdownx.superfences":
+            ext = {"pymdownx.superfences": {}}
+        elif isinstance(ext, dict) and len(ext) == 1 and "pymdownx.superfences" in ext:
+            ...
+        else:
+            continue
+        ext["pymdownx.superfences"].update(superfences)
+        overrides["markdown_extensions"][n] = ext
+    res: dict[Any, Any] = mkdocs(directory, **overrides)
+    return res
+
+
+config.mkdocs = _mkdocs
+
+mkdocs_render = render.mkdocs
+
+
+def _mkdocs_render(config: dict[str, Any]) -> Any:
+    """Ensures the original config can be reused."""
+    original_config = list(config.get("markdown_extensions", []))
+    if original_config and "pymdownx.superfences" in original_config[0]:
+        original_config = original_config[0]["pymdownx.superfences"]
+        result = mkdocs_render(config)
+        config["markdown_extensions"][0]["pymdownx.superfences"] = original_config
+    else:
+        result = mkdocs_render(config)
+    return result
+
+
+render.mkdocs = _mkdocs_render
+
+if __name__ == "__main__":
+    from portray.cli import cli  # type: ignore
+
+    cli()

.github/workflows/docs.yml

@@ -0,0 +1,18 @@
+name: Docs
+on: 
+  push:
+    tags:
+      - 'release/v*' 
+  pull_request:
+jobs:
+  static:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+      - name: install
+        run: python -m pip install .\[docs\]
+      - name: portray
+        run: python .github/workflows/_build.py on-github-pages -f

.github/workflows/python-publish.yml

@@ -11,7 +11,11 @@ permissions:
 jobs:
   deploy:
 
+    name: upload release to PyPI
     runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
 
     steps:
     - uses: actions/checkout@v3
@@ -27,8 +31,6 @@ jobs:
       run: |
         python -m build
     - name: Publish package
-      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      uses: pypa/gh-action-pypi-publish@release/v1
       with:
-        user: __token__
-        password: ${{ secrets.PYPI_API_TOKEN }}
         packages_dir: dist/

README.md

@@ -4,6 +4,49 @@ 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. Note that this is only
+necessary if you do not already have Arches installed in the current environment.
+
+```
+pip install .[arches]
+```
+
+### Test
+
+Runs tests across the various backends.
+
+```
+pip install .[tests]
+python -m pytest
+```
+
 ## Well-known Resource Models
 
 To provide a partial boundary, this package expects a settings object called
@@ -39,11 +82,7 @@ extension loading:
 
 ## Documentation
 
-Documentation is generated using [pdocs](https://github.com/timothycrosley/pdocs) but,
-as the `arches_django` subpackage expects a running Arches instance to be importable
-(a side-effect of Django), we add an initialization routine.
-
-    python docs/make_doc.py
+Documentation is available on [https://flaxandteal.github.io/arches-orm/](https://flaxandteal.github.io/arches-orm/).
 
 ## Thanks
 

arches_orm/adapter.py

@@ -1,10 +1,21 @@
+from __future__ import annotations
+
+import logging
+from uuid import UUID
+from enum import Enum
 from typing import Any, Generator, Callable, Literal
 from inspect import isgenerator, isgeneratorfunction
 from functools import partial, wraps
 from contextlib import contextmanager
 from contextvars import ContextVar
+from abc import ABC, abstractmethod
+
+from .view_models._base import ResourceInstanceViewModel
+from .view_models.concepts import ConceptValueViewModel
 
-class Adapter:
+logger = logging.getLogger(__name__)
+
+class Adapter(ABC):
     config: dict[str, Any]
     _context: ContextVar[dict[str, Any] | None]
 
@@ -15,9 +26,45 @@ def __init__(self, key):
     def __init_subclass__(cls):
         ADAPTER_MANAGER.register_adapter(cls)
 
+    def __str__(self):
+        return self.key
+
+    def __repr__(self):
+        return f"<AORA:{self.key}>"
+
+    @property
+    @abstractmethod
+    def key(self):
+        ...
+
     def set_context_free(self):
         self._context.set(None)
 
+    def get_rdm(self):
+        from .collection import ReferenceDataManager
+        return ReferenceDataManager(self)
+
+    @abstractmethod
+    def retrieve_concept(self, concept_id: str | UUID) -> ConceptValueViewModel:
+        ...
+
+    @abstractmethod
+    def make_concept(self, concept_id: str | UUID, values: dict[UUID, tuple[str, str]], children: list[UUID] | None) -> ConceptValueViewModel:
+        ...
+
+    @abstractmethod
+    def get_collection(self, collection_id: str | UUID) -> type[Enum]:
+        ...
+
+    @abstractmethod
+    def derive_collection(self, collection_id: str | UUID, include: list[UUID] | None, exclude: list[UUID] | None, language: str | None=None) -> type[Enum]:
+        """Note that include and exclude should be lists of concept, not value, IDs."""
+        ...
+
+    @abstractmethod
+    def load_from_id(self, resource_id: str, from_prefetch: Callable[[str], Any] | None=None, lazy: bool=False) -> ResourceInstanceViewModel:
+        ...
+
     def get_context(self):
         return self._context
 
@@ -113,13 +160,13 @@ def wrapper(adapter_key: str | None, f: Callable[[Any], Any]) -> Callable[[Any],
         @wraps(f)
         def _g(*args, **kwargs):
             adapter = get_adapter(adapter_key)
-            with adapter.context(_ctx=ctx, _override=True) as cvar:
+            with adapter.context(_ctx=ctx, _override=True) as _:
                 yield from f(*args, **kwargs)
 
         @wraps(f)
         def _f(*args, **kwargs):
             adapter = get_adapter(adapter_key)
-            with adapter.context(_ctx=ctx, _override=True) as cvar:
+            with adapter.context(_ctx=ctx, _override=True) as _:
                 return f(*args, **kwargs)
         return _g if isgenerator(f) or isgeneratorfunction(f) else _f
 
@@ -130,5 +177,13 @@ def admin(adapter_key: str | None=None):
     with get_adapter(adapter_key).context(None, _override=True) as cvar:
         yield cvar
 
+def admin_everywhere(key=None):
+    get_adapter(key=key).set_context_free()
+    logger.warning(
+        "ARCHES ORM ADMINISTRATION MODE ON: use for debugging only, "
+        "otherwise use the `context_free` or `context` decorator/with statement to "
+        "achieve this result safely."
+    )
+
 ADAPTER_MANAGER = AdapterManager()
 get_adapter = ADAPTER_MANAGER.get_adapter

arches_orm/arches_django/adapter.py

@@ -1,4 +1,5 @@
 import logging
+from enum import Enum
 from arches_orm.adapter import Adapter
 
 logger = logging.getLogger(__name__)
@@ -21,6 +22,10 @@ def get_wrapper(self):
 
         return ArchesDjangoResourceWrapper
 
+    def get_collection(self, collection_id: str) -> type[Enum]:
+        from .datatypes.concepts import retrieve_collection
+        return retrieve_collection(collection_id)
+
     def load_from_id(self, resource_id, from_prefetch=None, lazy=False):
         from arches_orm.wkrm import get_resource_models_for_adapter
         from arches.app.models.resource import Resource

arches_orm/arches_django/datatypes/__init__.py

@@ -1,5 +1,5 @@
 from ._register import get_view_model_for_datatype
-from . import concepts, semantic, resource_instances, string, user, django_group
+from . import concepts, semantic, resource_instances, string, user, django_group, geojson_feature_collection
 
 __all__ = [
     "get_view_model_for_datatype",
@@ -9,4 +9,5 @@
     "string",
     "user",
     "django_group",
+    "geojson_feature_collection"
 ]