Skip to main content

OArepo FSM library for record state transitions

Project description

https://img.shields.io/travis/oarepo/oarepo-fsm.svg https://img.shields.io/coveralls/oarepo/oarepo-fsm.svg https://img.shields.io/github/tag/oarepo/oarepo-fsm.svg https://img.shields.io/pypi/dm/oarepo-fsm.svg https://img.shields.io/github/license/oarepo/oarepo-fsm.svg

OArepo FSM library for record state transitions built on top of the https://pypi.org/project/sqlalchemy-fsm/ library.

Quickstart

Run the following commands to bootstrap your environment

git clone https://github.com/oarepo/oarepo-fsm
cd oarepo-fsm
pip install -e .[devel]

Configuration

Check that correct record_class is being used on the RECORDS_REST_ENDPOINT’s item_route

item_route='/records/<pid(recid,record_class="yourapp.models:RecordModelFSM"):pid_value>',

To automatically add a link to the FSM endpoint to your record links, use the following links_factory_imp in your RECORDS_REST_ENDPOINTS config

links_factory_imp='oarepo_fsm.links:record_fsm_links_factory',

If you wish to activate FSM on a certain Record enpoints only, put in your config

OAREPO_FSM_ENABLED_REST_ENDPOINTS = ['recid']

Where recid is the prefix key into your RECORDS_REST_ENDPOINTS configuration. This library activates FSM on all endpoints using record_class inherited from FSMMixin otherwise.

Usage

In order to use this library, you need to define a Record model in your app, that inherits from a FSMMixin column

from invenio_records import Record
from oarepo_fsm.mixins import FSMMixin

class RecordModelFSM(FSMMixin, Record):
...

To define FSM transitions on this class, create methods decorated with @transition(..) e.g.

@transition(
    src=['open', 'archived'],
    dest='published',
    required=['id'],
    permissions=[editor_permission],
    commit_record=True)
def publish(self, **kwargs):
    print('record published')

Where decorator parameters mean:

  • src: record must be in one of the source states before transition could happen

  • dest: target state of the transition

  • required: a list of required **kwargs that must be passed to the @transition decorated function

  • permissions: currently logged user must have at least one of the permissions to execute the transition

  • commit_record: should the changes made in a record be commited after the function returns?

A transition-decorated function can optionally return a custom flask Response or a JSON-serializable dict to be provided to user in a JSON response.

REST API Usage

To get current record state and possible transitions (only transitions that you have permission to invoke will be returned)

GET <record_rest_item_endpoint>
>>>
{
    metadata: {
        state: <current state of the record>
        ... other record metadata
    }
    links: {
        self: ...,
        "transitions": {
            <fsm_transition1_name>: <transition_url>,
            <fsm_transition2_name>: <transition_url>,
        },
        ...
    }
}

To invoke a specific transition transition, do

POST <record_rest_endpoint>/<fsm_transition_name>

Further documentation is available on https://oarepo-fsm.readthedocs.io/

Permission factories

Sometimes access to records should be governed by the state of the record. For example, if the record is in state=editing, any editor can make changes. If it is state=approving, only the curator can modify the record.

On REST level, modification permissions are governed by permission factories

from invenio_records_rest.utils import allow_all, deny_all
RECORDS_REST_ENDPOINTS = dict(
    recid=dict(
       create_permission_factory_imp=deny_all,
       delete_permission_factory_imp=deny_all,
       update_permission_factory_imp=deny_all,
       read_permission_factory_imp=allow_all,
   )
)

This library provides the following factories and helpers:

  • transition_required(*transitions) allows user if he is entitled to perform any of the transitions ( method names) on the current record

  • states_required(*states, state_field="state" allows anyone if the record is in any of the states mentioned

  • require_all(*perms_or_factories) allows user only if all permissions allow. Use it with states_required as follows

    require_all(
        states_required('editing'),
        editing_user_permission_factory
    )

    where editing_user_permission_factory is a permission factory allowing only editing users.

  • require_any(*perms_or_factories) allows user if any of the permissions allow. Example

    require_any(
        require_all(
            states_required('editing'),
            editing_user_permission_factory
        ),
        require_all(
            states_required('editing', 'approving),
            curator_user_permission_factory
        ),
    )

Changes

Version 0.1.0 (released TBD)

  • Initial public release.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

oarepo-fsm-1.5.1.tar.gz (19.5 kB view details)

Uploaded Source

Built Distribution

oarepo_fsm-1.5.1-py2.py3-none-any.whl (26.1 kB view details)

Uploaded Python 2Python 3

File details

Details for the file oarepo-fsm-1.5.1.tar.gz.

File metadata

  • Download URL: oarepo-fsm-1.5.1.tar.gz
  • Upload date:
  • Size: 19.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/3.10.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.59.0 CPython/3.9.2

File hashes

Hashes for oarepo-fsm-1.5.1.tar.gz
Algorithm Hash digest
SHA256 96b8c02a68e8052593eb8b58d2ef2658ba2887a9e4d34ec501656fdb8d6d2c61
MD5 f6c13c1928e40e075a62c0fcd98b2c92
BLAKE2b-256 0217784c44ff5673d79908653b66cfe5bddd394914c56253f054500662efd139

See more details on using hashes here.

File details

Details for the file oarepo_fsm-1.5.1-py2.py3-none-any.whl.

File metadata

  • Download URL: oarepo_fsm-1.5.1-py2.py3-none-any.whl
  • Upload date:
  • Size: 26.1 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/3.10.0 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.59.0 CPython/3.9.2

File hashes

Hashes for oarepo_fsm-1.5.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 07105435afb23c60d740ae6bbe2caee11d2460d7bebfc7831ea5c154d82e7047
MD5 346cc323355e1573ca131f89990c2a41
BLAKE2b-256 0d45f6707335be2cbb0b2b40d06c7796a067acf02f51622847d0ac57a9c86d04

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page