Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
manual.py · 7.5 KB · 142 lines
1"""The manual carrier: the operator IS the integration.
2
3This is app-shipping's own carrier connector, declared in the manifest
4under `connectors` for the `shipments` collection and loaded at runtime by
5object_connectors.load_connector -- the mechanism the mail connector spec
6already established (plan/vocabulary/03-external-connectors-spec.md).
7Open core never imports it statically; a deployment that swaps in a real
8carrier installs a package declaring `connectors` for `shipments` too, and
9the private overlay's declaration wins for the whole box. That swap is the
10entire point of this file existing rather than the manual behaviour being
11welded into the two objects that use it: if the free path is not shaped
12exactly like the paid one, the paid one is a rewrite rather than a plug-in.
13
14THE CARRIER INTERFACE, in full, so an adapter author needs nothing else:
15
16 PROVIDER = "manual" the value of app_settings carrier.provider this
17 module answers to. The objects refuse to use a
18 module whose PROVIDER disagrees with the
19 setting rather than quietly doing something
20 other than what the shop configured.
21
22 track(shipment, *, base_dir) -> outcome
23 Ask the carrier where this parcel is.
24 {"ok": True, "status": "Out for delivery", "delivered": False}
25 {"ok": True, "status": "Delivered", "delivered": True,
26 "delivered_on": "2026-07-24"} -- moves the shipment to delivered
27
28 buy_label(shipment, *, base_dir, tracking_number="", label_bytes=None,
29 label_content_type="", label_filename="") -> outcome
30 Get a label for this parcel. Direction is on the shipment: an
31 INBOUND shipment is a return label, and there is deliberately no
32 second verb for it -- a return label is the same purchase with the
33 addresses the other way round, and two verbs would be two places
34 for the credentials, the errors and the file to drift.
35 {"ok": True, "tracking_number": "1Z...", "label_bytes": b"%PDF...",
36 "label_content_type": "application/pdf", "label_filename": "..."}
37
38 reconcile(record, *, base_dir) -> outcome
39 The entry object_daemon's connector pass calls. See below.
40
41Every one of them answers in the SAME vocabulary object_connectors already
42defines for reconcile, and reusing it is deliberate:
43
44 {"ok": True, ...} it worked; here is what we learned
45 {"skip": True, "reason": "..."} declined this tick -- the HOST is
46 not set up. The row is left exactly
47 as it is and NOTHING is counted
48 against it.
49 {"ok": False, "error": "..."} THIS parcel could not be read; count
50 the attempt against it.
51 {"ok": False, "error": "...",
52 "permanent": True} ...and do not bother asking again.
53
54That distinction is the one system_scan_processor spells `recoverable`, and
55it is the difference between "somebody has not pasted the API key in yet"
56and "this tracking number is nonsense". Spelling it a third way here would
57mean three subsystems that agree about the rule and disagree about the word,
58so this file borrows the connector contract's word and the poll borrows its
59meaning.
60
61WHAT `manual` ACTUALLY DOES:
62
63`track` always declines. There is no carrier to ask -- the operator is the
64one who reads the tracking page and types what it said, and a poll that
65"succeeded" every hour by writing back the status a human typed would burn
66tracking_checked_at into a timestamp that means nothing. Declining is the
67honest answer, and because it declines rather than fails, nothing is ever
68counted against a manually-tracked parcel.
69
70`buy_label` accepts what the operator brings back from the post office
71counter: the tracking number, and optionally the label PDF they were handed.
72It buys nothing and pretends to buy nothing. It is still worth routing
73through the connector interface, because it is what proves the interface
74covers the free path -- and because the day a real adapter lands, the
75operator-typed path is still there for the parcel the API refuses to quote.
76
77`reconcile` declines every tick, always, and that is not a stub. The
78daemon's connector pass converges an external system toward what our
79records DESIRE; a parcel is the opposite shape of fact. We cannot make a
80van arrive by wishing, the carrier's truth flows toward us rather than away,
81and reading it is time-driven work that belongs to a scheduled pass
82(docs/logic-decisions.md #2) -- system_tracking_poll, declared in this
83package's `schedules`. The declaration exists so that the module is
84DISCOVERABLE by the mechanism that already resolves connector modules
85safely (escape-checked, package-relative, dynamically loaded); implementing
86`reconcile` as an explicit decline is how it stays discoverable without the
87reconcile pass quietly acquiring a meaning nobody wanted.
88"""
89
90PROVIDER = "manual"
91
92# Kept short because it is written into a poll's report and read by somebody
93# scanning a list of skipped rows.
94_NO_CARRIER = ("carrier.provider is manual: tracking is whatever the operator "
95 "typed, so there is nobody to ask")
96
97
98def track(shipment, *, base_dir=None):
99 """Decline, always -- see the module docstring. Not an attempt, not a
100 failure: the row waits exactly as the operator left it."""
101 return {"skip": True, "reason": _NO_CARRIER}
102
103
104def buy_label(shipment, *, base_dir=None, tracking_number="",
105 label_bytes=None, label_content_type="", label_filename=""):
106 """Take what the human brings back from the counter.
107
108 The one refusal here is an empty tracking number, and it is a refusal
109 rather than a shrug because the whole reason to press this button
110 manually is to put a tracking number on the parcel -- stamping an empty
111 string would leave a shipment that claims to have a label and cannot be
112 followed. The label FILE is optional: plenty of shops print the label
113 from the carrier's own site and never hold the bytes, and refusing them
114 a tracking number over a missing PDF would be paperwork for its own
115 sake.
116 """
117 number = str(tracking_number or "").strip()
118 if not number:
119 return {"ok": False, "permanent": True,
120 "error": ("A manual label needs the tracking number the "
121 "carrier gave you -- that number is the whole "
122 "point of the button, and a label with no number "
123 "cannot be followed by anybody.")}
124 outcome = {"ok": True, "tracking_number": number,
125 "provider": PROVIDER,
126 "note": ("recorded from the counter; nothing was bought and "
127 "nothing pretended to be")}
128 if label_bytes:
129 outcome["label_bytes"] = label_bytes
130 outcome["label_content_type"] = (str(label_content_type or "").strip()
131 or "application/pdf")
132 outcome["label_filename"] = (str(label_filename or "").strip()
133 or f"label-{number}.pdf")
134 return outcome
135
136
137def reconcile(record, *, base_dir=None):
138 """The daemon's desired-state pass has nothing to converge here."""
139 return {"skip": True,
140 "reason": ("a shipment is not desired state: the carrier's truth "
141 "flows toward us, and reading it is system_tracking_"
142 "poll's scheduled job")}