velocity-python 0.4.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
velocity/__init__.py CHANGED
@@ -1,4 +1,4 @@
1
- __version__ = version = "0.4.2"
1
+ __version__ = version = "0.5.0"
2
2
 
3
3
  import importlib as _importlib
4
4
 
@@ -11,6 +11,14 @@ in ``client_actions`` (``client_actions = MINE | WORKFLOW_ACTIONS``)::
11
11
  workflow-claim {docket, position, release?} -> {ok, docket}
12
12
  workflow-notices {unread_only?, cursor?, limit?} -> {unread, rows, cursor?}
13
13
  workflow-notice-ack {notice} | {all: true} -> {ok, unread}
14
+ workflow-board {route, station, entity?, cursor?, limit?}
15
+ -> Board
16
+ workflow-assign {docket, position, to, comment?, request_key}
17
+ -> {ok, docket}
18
+ workflow-prioritize {docket, priority, request_key} -> {ok, docket}
19
+ workflow-handover {to, stations?, route?} -> {ok, moved, kept}
20
+ workflow-flow {route?, entity?} -> {flows, as_of}
21
+ workflow-graph {docket, depth?} -> Graph
14
22
 
15
23
  and :class:`WorkflowQueueMixin` to its queue handler (never reachable over
16
24
  HTTP): ``workflow-program`` (a program station's job), ``workflow-drain``
@@ -27,7 +35,19 @@ records it before it happens, and the engine then acts with ``override``.
27
35
  **Refusals** are ``{ok: false, reasons: [Reason]}`` with HTTP 403 (not
28
36
  yours) or 409 (the docket's state or a guard said no), or 400 for a
29
37
  malformed request. A docket the person may not see is refused exactly like
30
- one that does not exist.
38
+ one that does not exist; so is a board or a flow of a route or station that
39
+ does not exist.
40
+
41
+ **Boards, flows and graphs** (:mod:`velocity.workflow.views`): a board opens
42
+ for whoever sits at or oversees the station (``workflow.board``), a flow for
43
+ whoever owns the route or leads a station on it, or holds
44
+ ``workflow.flow.view`` (``workflow.flow``; counts only over the entities
45
+ :func:`velocity.workflow.access.flow_scope` gives), a graph for whoever may
46
+ see its root docket. Assigning and prioritizing need ``workflow.docket.view``
47
+ and ``workflow.docket.assign`` / ``workflow.docket.prioritize`` (a route
48
+ owner, the station's lead, or ``workflow.position.assign`` for the docket's
49
+ entity); a hand-over moves only the caller's own positions, to a receiver
50
+ seated at their stations.
31
51
  """
32
52
 
33
53
  from __future__ import annotations
@@ -46,6 +66,12 @@ CONFLICT = 409
46
66
  BAD_REQUEST = 400
47
67
 
48
68
 
69
+ def _now():
70
+ import datetime
71
+
72
+ return datetime.datetime.now(datetime.timezone.utc)
73
+
74
+
49
75
  def _workflow():
50
76
  # imported lazily: velocity.workflow pulls in the rules package
51
77
  from velocity import workflow
@@ -71,6 +97,7 @@ class WorkflowMixin:
71
97
  """See the module docstring."""
72
98
 
73
99
  workflow_tray_limit = 50
100
+ workflow_board_limit = 50
74
101
 
75
102
  # ── seams ──────────────────────────────────────────────────────────────
76
103
 
@@ -120,6 +147,63 @@ class WorkflowMixin:
120
147
  except AccessError:
121
148
  raise AccessError(authz.REFUSED) from None
122
149
 
150
+ def _wf_require_seat(self, tx, context, action, resource):
151
+ """``authz.require`` on a station- or route-scoped action, refused
152
+ with the same sentence as every other workflow refusal."""
153
+ try:
154
+ return authz.require(self, tx, context, action, resource)
155
+ except AccessError:
156
+ raise AccessError(authz.REFUSED) from None
157
+
158
+ def _wf_route(self, tx, code, entity, seats):
159
+ """The route a board or a flow draws (a missing one is refused like
160
+ one the person may not open)."""
161
+ wf = _workflow()
162
+ try:
163
+ return wf.views.route_for(tx, code, entity=entity, seats=seats)
164
+ except wf.WorkflowError:
165
+ raise AccessError(authz.REFUSED) from None
166
+
167
+ def _wf_entity(self, payload, seats):
168
+ """The payload's ``entity``: only one the person has seats in (any
169
+ other is refused like a board or flow not theirs, so another
170
+ entity's routes and people are never read)."""
171
+ entity = (payload or {}).get("entity")
172
+ if entity is None:
173
+ return None
174
+ if isinstance(entity, bool) or not isinstance(entity, (str, int)):
175
+ raise _Refusal(
176
+ BAD_REQUEST, [{"code": "entity", "text": "entity must be an id."}]
177
+ )
178
+ entity = str(entity)
179
+ if entity == "" or not seats.in_entity(entity):
180
+ raise AccessError(authz.REFUSED)
181
+ return entity
182
+
183
+ def _wf_request_key(self, payload):
184
+ request_key = (payload or {}).get("request_key")
185
+ if not isinstance(request_key, str) or not request_key.strip():
186
+ raise _Refusal(
187
+ BAD_REQUEST,
188
+ [{"code": "request_key", "text": "A request key is required."}],
189
+ )
190
+ return request_key
191
+
192
+ def _wf_can_board(self, context, route, seats):
193
+ wf = _workflow()
194
+
195
+ def can_board(station):
196
+ relations = wf.access.station_relations(seats, route, station)
197
+ decision = authz.decide(
198
+ self,
199
+ wf.access.BOARD,
200
+ wf.access.station_resource(route, station, relations),
201
+ context,
202
+ )
203
+ return decision.allowed and not decision.audit
204
+
205
+ return can_board
206
+
123
207
  def _wf_masquerading(self, principal) -> bool:
124
208
  return principal.real_user is not None
125
209
 
@@ -408,6 +492,304 @@ class WorkflowMixin:
408
492
 
409
493
  self._wf_guarded(tx, context, work)
410
494
 
495
+ # ── boards, flows, graphs ──────────────────────────────────────────────
496
+
497
+ def OnActionWorkflowBoard(self, tx, context):
498
+ wf = _workflow()
499
+ payload = context.payload() or {}
500
+ principal = self._wf_principal(context)
501
+ seats = self._wf_seats(tx, context, principal)
502
+
503
+ def work():
504
+ entity = self._wf_entity(payload, seats)
505
+ route = self._wf_route(tx, payload.get("route"), entity, seats)
506
+ try:
507
+ station = route.station(str(payload.get("station") or ""))
508
+ except wf.WorkflowError:
509
+ raise AccessError(authz.REFUSED) from None
510
+ relations = wf.access.station_relations(seats, route, station, entity)
511
+ self._wf_require_seat(
512
+ tx,
513
+ context,
514
+ wf.access.BOARD,
515
+ wf.access.station_resource(route, station, relations),
516
+ )
517
+ # what the board offers (display only: every write is decided
518
+ # per docket); nothing is offered under masquerade
519
+ writes = not self._wf_masquerading(principal)
520
+ assigns = writes and (
521
+ wf.access.OVERSEES in relations
522
+ or principal.holds_anywhere(wf.access.POSITION_ASSIGN)
523
+ )
524
+ viewer = wf.contract.Viewer(
525
+ seats=seats,
526
+ principal=principal,
527
+ view_decider=self._wf_decider(context),
528
+ )
529
+ body = wf.views.board(
530
+ tx,
531
+ viewer,
532
+ route,
533
+ station,
534
+ entity=entity,
535
+ cursor=payload.get("cursor"),
536
+ limit=payload.get("limit") or self.workflow_board_limit,
537
+ can={
538
+ "assign": assigns,
539
+ "prioritize": assigns,
540
+ "handover": writes and wf.access.SEATED in relations,
541
+ # the docket's can.flag, less what masquerade forbids
542
+ "flag": writes and bool(seats.person),
543
+ },
544
+ )
545
+ context.response().set_body(body)
546
+
547
+ self._wf_guarded(tx, context, work)
548
+
549
+ def OnActionWorkflowFlow(self, tx, context):
550
+ wf = _workflow()
551
+ payload = context.payload() or {}
552
+ principal = self._wf_principal(context)
553
+ seats = self._wf_seats(tx, context, principal)
554
+ viewer = wf.contract.Viewer(
555
+ seats=seats, principal=principal, view_decider=self._wf_decider(context)
556
+ )
557
+
558
+ def one(route, entity, required):
559
+ relations = wf.access.route_relations(seats, route, entity)
560
+ resource = wf.access.route_resource(route, relations)
561
+ if required:
562
+ self._wf_require_seat(tx, context, wf.access.FLOW, resource)
563
+ else:
564
+ decision = authz.decide(self, wf.access.FLOW, resource, context)
565
+ if not decision.allowed or decision.audit:
566
+ return None
567
+ scope = wf.access.flow_scope(seats, principal, route)
568
+ if entity is not None:
569
+ scope = scope.narrowed(entity)
570
+ if scope.empty:
571
+ # nothing this viewer may count: no flow (not a zeroed one)
572
+ if required:
573
+ raise AccessError(authz.REFUSED)
574
+ return None
575
+ return wf.views.flow(
576
+ tx,
577
+ viewer,
578
+ route,
579
+ scope,
580
+ can_board=self._wf_can_board(context, route, seats),
581
+ )
582
+
583
+ def work():
584
+ entity = self._wf_entity(payload, seats)
585
+ truncated = False
586
+ if payload.get("route") is not None:
587
+ route = self._wf_route(tx, payload.get("route"), entity, seats)
588
+ flows = [one(route, entity, True)]
589
+ else:
590
+ codes, truncated = wf.views.flow_route_codes(tx, seats, principal)
591
+ flows = []
592
+ for code in codes:
593
+ try:
594
+ route = wf.views.route_for(tx, code, entity=entity, seats=seats)
595
+ except wf.WorkflowError:
596
+ continue
597
+ found = one(route, entity, False)
598
+ if found is not None:
599
+ flows.append(found)
600
+ # nothing to show is an empty Business view (it names no route)
601
+ flows.sort(
602
+ key=lambda f: (f["route"]["label"].lower(), f["route"]["code"])
603
+ )
604
+ body = {"flows": flows, "as_of": wf.contract.iso(_now())}
605
+ if truncated:
606
+ body["truncated"] = True
607
+ context.response().set_body(body)
608
+
609
+ self._wf_guarded(tx, context, work)
610
+
611
+ def OnActionWorkflowGraph(self, tx, context):
612
+ wf = _workflow()
613
+ payload = context.payload() or {}
614
+ principal = self._wf_principal(context)
615
+ seats = self._wf_seats(tx, context, principal)
616
+
617
+ def work():
618
+ docket, route = self._wf_docket(tx, payload)
619
+ relations = wf.access.view_relations(tx, docket, route, seats)
620
+ self._wf_require(tx, context, wf.access.VIEW, docket, relations)
621
+ viewer = wf.contract.Viewer(
622
+ seats=seats,
623
+ principal=principal,
624
+ view_decider=self._wf_decider(context),
625
+ )
626
+ body = wf.views.graph(
627
+ tx, viewer, docket["sys_id"], depth=payload.get("depth")
628
+ )
629
+ context.response().set_body(body)
630
+
631
+ self._wf_guarded(tx, context, work)
632
+
633
+ # ── leading a station ──────────────────────────────────────────────────
634
+
635
+ def _wf_lead_write(self, tx, context, payload, principal, seats, kind, write):
636
+ """The shared path of assign and prioritize: the docket must be
637
+ visible; a retry of the person's own request answers with the
638
+ docket; then ``kind``'s authz action decides on the lead relations
639
+ (``position``: the target position, or None for the docket)."""
640
+ wf = _workflow()
641
+ docket, route = self._wf_docket(tx, payload)
642
+ position = None
643
+ if kind == "assign":
644
+ try:
645
+ position = wf.engine._position(tx, payload.get("position"))
646
+ except wf.WorkflowError:
647
+ raise AccessError(authz.REFUSED) from None
648
+ if position["docket_id"] != docket["sys_id"]:
649
+ raise AccessError(authz.REFUSED)
650
+ relations = wf.access.view_relations(tx, docket, route, seats)
651
+ self._wf_require(tx, context, wf.access.VIEW, docket, relations)
652
+ request_key = payload.get("request_key")
653
+ actor = wf.engine.Actor.person(seats)
654
+ if isinstance(request_key, str) and wf.engine.already_marked(
655
+ tx, kind, docket["sys_id"], actor, request_key
656
+ ):
657
+ body = self._wf_docket_body(tx, context, docket["sys_id"], principal, seats)
658
+ context.response().set_body({"ok": True, "docket": body})
659
+ return
660
+ action = wf.access.ASSIGN if kind == "assign" else wf.access.PRIORITIZE
661
+ lead = wf.access.lead_relations(tx, docket, route, seats, position)
662
+ self._wf_require(tx, context, action, docket, lead)
663
+ request_key = self._wf_request_key(payload)
664
+ write(docket, position, actor, request_key)
665
+ self._wf_after_change(tx, context, docket["sys_id"])
666
+ body = self._wf_docket_body(tx, context, docket["sys_id"], principal, seats)
667
+ context.response().set_body({"ok": True, "docket": body})
668
+
669
+ def OnActionWorkflowAssign(self, tx, context):
670
+ wf = _workflow()
671
+ payload = context.payload() or {}
672
+ principal = self._wf_principal(context)
673
+ seats = self._wf_seats(tx, context, principal)
674
+
675
+ def write(docket, position, actor, request_key):
676
+ to = payload.get("to")
677
+ if not isinstance(to, dict):
678
+ raise _Refusal(
679
+ BAD_REQUEST,
680
+ [{"code": "to", "text": "Say whom to assign it to."}],
681
+ )
682
+ comment = payload.get("comment")
683
+ if comment is not None and not isinstance(comment, str):
684
+ raise _Refusal(
685
+ BAD_REQUEST, [{"code": "comment", "text": "comment must be text."}]
686
+ )
687
+ person = to.get("id")
688
+ if to.get("kind") == "person" and (
689
+ isinstance(person, bool) or not isinstance(person, (str, int))
690
+ ):
691
+ raise _Refusal(
692
+ BAD_REQUEST,
693
+ [{"code": "to", "text": "Say whom to assign it to."}],
694
+ )
695
+ wf.engine.assign(
696
+ tx,
697
+ docket["sys_id"],
698
+ position["sys_id"],
699
+ {"kind": to.get("kind"), "id": None if person is None else str(person)},
700
+ actor,
701
+ request_key=request_key,
702
+ comment=comment,
703
+ )
704
+
705
+ self._wf_guarded(
706
+ tx,
707
+ context,
708
+ lambda: self._wf_lead_write(
709
+ tx, context, payload, principal, seats, "assign", write
710
+ ),
711
+ )
712
+
713
+ def OnActionWorkflowPrioritize(self, tx, context):
714
+ wf = _workflow()
715
+ payload = context.payload() or {}
716
+ principal = self._wf_principal(context)
717
+ seats = self._wf_seats(tx, context, principal)
718
+
719
+ def write(docket, position, actor, request_key):
720
+ wf.engine.prioritize(
721
+ tx,
722
+ docket["sys_id"],
723
+ payload.get("priority"),
724
+ actor,
725
+ request_key=request_key,
726
+ )
727
+
728
+ self._wf_guarded(
729
+ tx,
730
+ context,
731
+ lambda: self._wf_lead_write(
732
+ tx, context, payload, principal, seats, "prioritize", write
733
+ ),
734
+ )
735
+
736
+ def OnActionWorkflowHandover(self, tx, context):
737
+ wf = _workflow()
738
+ payload = context.payload() or {}
739
+ principal = self._wf_principal(context)
740
+ seats = self._wf_seats(tx, context, principal)
741
+
742
+ def bad(code, text):
743
+ return _Refusal(BAD_REQUEST, [{"code": code, "text": text}])
744
+
745
+ def work():
746
+ authz.require(self, tx, context, wf.access.HANDOVER)
747
+ to = payload.get("to")
748
+ if isinstance(to, bool) or not isinstance(to, (str, int)):
749
+ raise bad("to", "Say whom to hand over to.")
750
+ to = str(to).strip()
751
+ stations = payload.get("stations")
752
+ if stations is not None:
753
+ if not isinstance(stations, list) or not all(
754
+ isinstance(s, str) and wf.hooks.CODE.match(s) for s in stations
755
+ ):
756
+ raise bad("stations", "stations must be station codes.")
757
+ route = payload.get("route")
758
+ if route is not None and not (
759
+ isinstance(route, str) and wf.hooks.CODE.match(route)
760
+ ):
761
+ raise bad("route", "route must be a route code.")
762
+ if wf.hooks.hook("person_seats") is None:
763
+ raise wf.WorkflowError(
764
+ "Hand-overs need register_person_seats (the receiver's seats)."
765
+ )
766
+ receiver = wf.hooks.person_seats(tx, to) if to else None
767
+ if receiver is None or receiver.person != to:
768
+ raise _Refusal(
769
+ CONFLICT,
770
+ [{"code": "not_seated", "text": "They do not sit there."}],
771
+ )
772
+ row_id = wf.engine.handover(
773
+ tx,
774
+ seats.person,
775
+ to,
776
+ to_seats=receiver,
777
+ stations=stations or None,
778
+ route=route,
779
+ seated_only=True,
780
+ by=wf.engine.Actor.person(seats),
781
+ )
782
+ row = tx.table(wf.schema.HANDOVER).find({"sys_id": row_id})
783
+ context.response().set_body(
784
+ {
785
+ "ok": True,
786
+ "moved": int(row.get("moved") or 0),
787
+ "kept": int(row.get("kept") or 0),
788
+ }
789
+ )
790
+
791
+ self._wf_guarded(tx, context, work)
792
+
411
793
  # ── notices ────────────────────────────────────────────────────────────
412
794
 
413
795
  def OnActionWorkflowNotices(self, tx, context):
@@ -15,7 +15,9 @@ leaves the transaction. The handler actions live in
15
15
  An application supplies, in code: :func:`register_subject`,
16
16
  :func:`register_program`, :func:`register_sheet`, :func:`register_seats`
17
17
  (and optionally :func:`register_recipients`, :func:`register_contact`,
18
- :func:`register_person_label`). Nothing here names a business. See
18
+ :func:`register_person_label`, :func:`register_station_people`,
19
+ :func:`register_time_zone`). :mod:`.views` draws the Station Board, the
20
+ Flow map and the Dependency view. Nothing here names a business. See
19
21
  docs/workflow.md.
20
22
  """
21
23
 
@@ -29,6 +31,7 @@ from . import (
29
31
  outbox,
30
32
  points,
31
33
  schema,
34
+ views,
32
35
  ) # noqa: F401
33
36
  from .contract import Viewer, build_docket, tray # noqa: F401
34
37
  from .definitions import ( # noqa: F401
@@ -54,6 +57,7 @@ from .engine import ( # noqa: F401
54
57
  act,
55
58
  actions_for,
56
59
  advance,
60
+ assign,
57
61
  check_possession,
58
62
  claim,
59
63
  clear_flag,
@@ -63,6 +67,7 @@ from .engine import ( # noqa: F401
63
67
  link,
64
68
  open_docket,
65
69
  place_hold,
70
+ prioritize,
66
71
  release_hold,
67
72
  resume_wait,
68
73
  run_program,
@@ -91,7 +96,9 @@ from .hooks import ( # noqa: F401
91
96
  register_recipients,
92
97
  register_seats,
93
98
  register_sheet,
99
+ register_station_people,
94
100
  register_subject,
101
+ register_time_zone,
95
102
  )
96
103
  from .notices import Channel, EmailChannel, register_channel # noqa: F401
97
104
  from .schema import ensure_schema # noqa: F401
@@ -120,6 +127,7 @@ __all__ = [
120
127
  "act",
121
128
  "actions_for",
122
129
  "advance",
130
+ "assign",
123
131
  "build_docket",
124
132
  "check_possession",
125
133
  "claim",
@@ -134,6 +142,7 @@ __all__ = [
134
142
  "load_route_version",
135
143
  "open_docket",
136
144
  "place_hold",
145
+ "prioritize",
137
146
  "publish",
138
147
  "register_calendar",
139
148
  "register_channel",
@@ -145,7 +154,9 @@ __all__ = [
145
154
  "register_recipients",
146
155
  "register_seats",
147
156
  "register_sheet",
157
+ "register_station_people",
148
158
  "register_subject",
159
+ "register_time_zone",
149
160
  "release_hold",
150
161
  "resume_wait",
151
162
  "retire",