mock-einvoice 0.3.0__tar.gz → 0.4.0__tar.gz

{mock_einvoice-0.3.0 → mock_einvoice-0.4.0}/CHANGELOG.md

@@ -10,6 +10,57 @@ says so where it does.
 
 Nothing yet.
 
+## [0.4.0] - 2026-10-22
+
+The binding is served, and the clock can be moved. **Every stamp changes**:
+it ends in `Z` now.
+
+### Added
+
+- **The UBL binding over HTTP** ([#39]). `GET /_mock/binding/Invoice` and
+  `/_mock/binding/CreditNote` give where each business term and group is in
+  the document, as a tree of elements: each node its element and its term,
+  group or fixed value, the elements UBL requires that have no term among
+  them. It is made from `mockeinvoice.ubl.BINDINGS`, the reader's and
+  writer's own table, when asked. Where one element has several entries
+  (an allowance or a charge), each says the test that picks it, as words and
+  as data. A test reads this project's samples and fifty published documents
+  by the served binding alone and comes to what the reader comes to. In
+  Python, `ubl.described`.
+- **A clock that can be moved** ([#41]). `POST /_mock/advance` takes
+  `seconds` or a time `to` move to, in the query string or as JSON, and what
+  is received or said afterwards is stamped then: the stamps, the date and
+  time in an Invoice Response, and the dates of an invoice the supplier
+  writes. It does not go backwards. In Python, `mockeinvoice.clock.Clock`,
+  which a `Buyer` and a `Supplier` take as their `now`.
+- `GET /_mock/health` says what time it is by the clock, as `"now"`.
+- `--clock` takes a time with `Z` or an offset (`2026-10-07T11:00+02:00`),
+  and a date alone.
+- A time whose `+` offset a query string turned into a space
+  (`?to=2026-10-07T11:00+02:00`) is refused with a word saying a `+` is
+  written `%2B` there ([#44]). Only such a time: one wrong another way is
+  not sent looking for a `+`.
+
+### Changed
+
+- The README and the package's page on PyPI point at the project's page on
+  rickseufert.com ([#43](https://github.com/rseufert/mock-einvoice/pull/43)).
+- **A stamp says its zone.** `"received"` and `"sent"` were
+  `2026-10-07T09:00:00` and are `2026-10-07T09:00:00Z`. They were UTC before
+  and are UTC now; a client that parsed them as a time with no zone has to
+  take the `Z`.
+- **What `--clock` means is written down, and is what it did**: the clock is
+  pinned to that moment, in UTC, and stands still until it is advanced. A
+  `now` given to a `Buyer` or a `Supplier` with a zone other than UTC is said
+  in UTC, where its own wall time was written before.
+- `--clock` refuses what is not a time with a sentence, and no longer takes
+  the other forms `datetime.fromisoformat` does (a space for the `T`,
+  fractions of a second).
+- The tests that pick an entry of the binding (`ubl.sepa`,
+  `ubl.in_accounting_currency`, and what `ubl.indicator` and
+  `ubl.document_type` return) are `ubl.When` objects, called as the
+  functions were. Nothing is read or written differently.
+
 ## [0.3.0] - 2026-10-10
 
 The supplier writes an invoice itself, and the business terms can be read
@@ -290,3 +341,6 @@ built, and was in no release.
 [#27]: https://github.com/rseufert/mock-einvoice/issues/27
 [#33]: https://github.com/rseufert/mock-einvoice/issues/33
 [#34]: https://github.com/rseufert/mock-einvoice/issues/34
+[#39]: https://github.com/rseufert/mock-einvoice/issues/39
+[#41]: https://github.com/rseufert/mock-einvoice/issues/41
+[#44]: https://github.com/rseufert/mock-einvoice/issues/44

{mock_einvoice-0.3.0/mock_einvoice.egg-info → mock_einvoice-0.4.0}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: mock-einvoice
-Version: 0.3.0
+Version: 0.4.0
 Summary: A mock e-invoicing partner: EN 16931 invoices in and out, with the responses that follow. Zero dependencies.
 License: MIT AND EUPL-1.2
+Project-URL: Homepage, https://rickseufert.com/mock-einvoice/
 Project-URL: Repository, https://github.com/rseufert/mock-einvoice
 Project-URL: Issues, https://github.com/rseufert/mock-einvoice/issues
 Project-URL: Changelog, https://github.com/rseufert/mock-einvoice/blob/main/CHANGELOG.md
@@ -34,6 +35,9 @@ A mock e-invoicing partner: EN 16931 invoices in and out, with the responses tha
 
 A sibling of [mock-sap](https://github.com/rseufert/mock-sap), [mock-edi](https://github.com/rseufert/mock-edi) and [mock-bank](https://github.com/rseufert/mock-bank), and of [mock-acme](https://github.com/rseufert/mock-acme), the integration between them.
 
+By [Rick Seufert](https://rickseufert.com). Its [page](https://rickseufert.com/mock-einvoice/)
+has the features and how to start it.
+
 ```
 python3 -m pip install mock-einvoice
 mock-einvoice --port 8100
@@ -41,11 +45,11 @@ mock-einvoice --port 8100
 
 It reads and writes UBL invoices and credit notes, and the Peppol Invoice Response that answers one, and holds them to their published rules: invoices to all 979 rules of the EN 16931 core, to all 165 of Peppol's (its own 63, the 31 it has for Germany and the 71 for seven other countries), and to the 34 of a standard XRechnung document; responses to all 82 of theirs. Over HTTP it is a buyer that takes invoices in and answers the Peppol ones, and a supplier that sends them, writes the invoice for an order it is told of, and takes the answers.
 
-**What 0.3.0 is not:**
+**What 0.4.0 is not:**
 
 - **It writes one kind of invoice of its own, and no other.** The supplier writes the invoice for an order it is told of: every line at one standard rate of VAT, no allowances or charges, no credit note, no XRechnung ([An order, and the invoice for it](#an-order-and-the-invoice-for-it)). Anything else it sends as it is given.
 - **It takes no order off the network.** An order is this mock's own JSON on a `/_mock` path. Peppol's UBL `Order` and its rules are not built.
-- **It knows nothing of the other mocks.** Writing an invoice from one of mock-sap's billing documents, and saying "paid" when SAP has cleared it, is integration, and belongs in [mock-acme](https://github.com/rseufert/mock-acme) with the rest of it: its `order_to_cash`, which is on its `main` and in no release of it yet.
+- **It knows nothing of the other mocks.** Writing an invoice from one of mock-sap's billing documents, and saying "paid" when SAP has cleared it, is integration, and belongs in [mock-acme](https://github.com/rseufert/mock-acme) with the rest of it: its `order_to_cash`, since mock-acme 0.6.0.
 - **Peppol's ten rules for a seller in Iceland are held to this project's tests only.** Peppol publishes unit tests for its rules for Denmark, Greece, Italy, the Netherlands, Norway and Sweden, and every case agrees here; for Iceland it publishes none. Those ten were written from the same reading of the rule file as the tests that hold them, so a misreading would be in both.
 - **No CII, no XRechnung Extension, no ZUGFeRD**, and no transport: see [What it refuses](#what-it-refuses) and [Known to be wrong, or not real](#known-to-be-wrong-or-not-real).
 
@@ -316,11 +320,13 @@ $ curl -s -X POST http://127.0.0.1:8101/_mock/orders/1/invoices
 
 | | |
 | --- | --- |
-| `GET /_mock/health` | that it is up, its version, and how many documents it holds and has sent |
+| `GET /_mock/health` | that it is up, its version, what time it is by its clock (`"now"`), and how many documents it holds and has sent |
+| `POST /_mock/advance` | move the clock forward: `?seconds=90`, or `?to=2026-10-08T08:00`, in the query string or as JSON. It answers `{"from", "to", "seconds", "pinned"}`. `400` for a time behind the clock, a fraction of a second, or more than ten years at once |
 | `GET /_mock/turned-away` | what was not taken in, on which side, and why |
 | `POST /_mock/validate` | an invoice, a credit note or an Invoice Response held to its rules, and not kept |
 | `GET /_mock/terms` | the business terms and groups this package knows, by number: `{"terms": [{"id", "name", "group", "kind"}], "groups": [{"id", "name", "repeats", "inside", "terms"}]}`, 164 terms and 32 groups, in the standard's order |
 | `GET /_mock/terms/BT-13`, `/_mock/terms/BG-25` | one term or one group, as in the list. `404` `NO-SUCH-TERM` for anything else, written any other way (`bt-13`) |
+| `GET /_mock/binding/Invoice`, `/_mock/binding/CreditNote` | where each term and group is in that UBL document: the binding as a tree of elements. `GET /_mock/binding` names the two. `404` `NO-SUCH-KIND` for anything else |
 | `POST /_mock/reset` | forget every document and response, on both sides |
 
 **The terms are the package's own table, served.** `GET /_mock/terms` is made from `mockeinvoice.model.TERMS` and `GROUPS` when it is asked, so what a client reads is what the reader, the writer and the rules go by.
@@ -330,6 +336,48 @@ $ curl -s -X POST http://127.0.0.1:8101/_mock/orders/1/invoices
 - Three terms are written as an attribute of another's element (`BT-130`, the unit, is `BT-129`'s `unitCode`) and say so in `attribute_of`. Sixteen more, the scheme identifiers and their like (`BT-29-1`), have a number and no entry of their own here: each is listed under `attributes` on the term that holds it, and asked for by itself is `404` saying where it is.
 - A finding still gives a term by its number alone. Its path is not always a term (a rule about the XML gives an XPath), and a client that wants the name has this to look it up in.
 
+**The binding is the reader's own table, served.** `GET /_mock/binding/Invoice` is made from `mockeinvoice.ubl.BINDINGS` when it is asked: the table the reader reads a document by and the writer writes one by. A client that walks a document beside it names every element as the reader does, and a test does just that, with `xml.etree` and the served JSON alone, over this project's samples and fifty documents from EN 16931 and XRechnung, and comes to the same terms, values and groups.
+
+```
+{"kind": "Invoice", "element": "Invoice", "namespace": "urn:oasis:...:Invoice-2",
+ "prefixes": {"cbc": "urn:oasis:...", "cac": "urn:oasis:..."},
+ "children": [
+   {"element": "cbc:CustomizationID", "term": "BT-24"},
+   ...
+   {"element": "cac:AllowanceCharge", "group": "BG-20", "repeats": true,
+    "when": {"text": "cbc:ChargeIndicator is false or 0", "path": "cbc:ChargeIndicator", "in": ["false", "0"]},
+    "children": [{"element": "cbc:ChargeIndicator", "fixed": "false", "accepts": ["false", "0"]}, ...]},
+   ...]}
+```
+
+A node has its `element` and what it is:
+
+| | |
+| --- | --- |
+| `term` | the business term its text is the value of. `attributes` names each attribute the element may carry, and the term that attribute is (`"unitCode": "BT-130"`) or `null` where the standard has none for it (`currencyID`). `on_document` marks a term that is the document's whatever element it is in: a credit note's due date is inside `PaymentMeans`. |
+| `group`, `repeats` | the business group the element is, and whether it is one of many, as `/_mock/terms` has it |
+| `fixed`, `accepts` | the one value the binding gives the element (`TaxScheme/ID` is `VAT`), and what is read as that value |
+| `ubl` | something UBL requires or tells things apart by, that the standard has no term or group for, under the name this package holds it by: `ubl:NetworkID` on a payment card, the scheme of a tax registration that is not VAT, the two document references known by their type code |
+| `once_per` | the term the element is written once for each value of: one `PartyIdentification` to an identifier |
+| `subject` | on `cbc:Note`, the term of the code written before the text between two `#` (`#AAI#the note`) |
+| `children` | the elements in it, in the order the schema has them |
+| *none of these* | an element that only holds others: `cac:Party`, `cac:TaxTotal` |
+
+- **One element, several entries.** `cac:AllowanceCharge` is an allowance or a charge; `cac:AdditionalDocumentReference` is the invoiced object, a supporting document, or on a credit note the project. Such entries are in the reader's order, and each but the last has a `when`: the first whose test holds has the element, and one with no `when` takes what is left. A `when` has its `text` in words, and where it can be computed, a `path` under the element (and an `attribute` of what is there), the values it is `in`, and `ignoring_case`. An element's text is compared with the space around it taken off.
+- **One test is not data.** Which of two `cac:TaxTotal` is the VAT total in the accounting currency (BT-111) depends on two currency codes at the head of the document. Those two entries have their test in words and a `name` (`tax-total-in-document-currency`, `tax-total-in-accounting-currency`), and a client has to know them by that.
+- **A tax registration is served as two entries**, the VAT identifier and whatever else, told apart by `cac:TaxScheme/cbc:ID`. In the package it is one piece of code and not a row of the table, so those nodes are written out by hand beside it. A buyer and a tax representative have no term for another registration: theirs is held as the VAT identifier, and the second entry says so by naming the same term.
+- **What has no node has no business term.** An element of a document that the binding has no node for is what the reader reports as `UNHELD`.
+- **Not in it:** which place a value is written back to when a term has two (the creditor identifier, on the seller or the payee), and how often an element may occur.
+
+**The clock.** Every stamp (`"received"`, `"sent"`, `"now"`), the date and time in an Invoice Response, and the dates on an invoice the supplier writes come from one clock.
+
+- **It is UTC, and every stamp says so**: `2026-10-07T09:00:00Z`, to the second.
+- **`--clock` pins it, and a pinned clock stands still.** `--clock 2026-10-07T09:00` is that moment in UTC. `--clock 2026-10-07T11:00+02:00` is the same moment, and is said back in UTC; a `Z` may be written and changes nothing. In a query string a `+` is a space, so `?to=` writes that offset `%2B02:00`; a time whose `+` became a space is refused with a word saying so, and not repaired. Every stamp and every response carries that one instant until the clock is moved, so that what a run writes does not change from run to run. It does not tick on between advances, as mock-sap's pinned clock does: a second that depends on how fast the run went is what pinning is there to take away.
+- **`POST /_mock/advance` moves it**, pinned or not, by whole seconds or to a time, written as `--clock` is (a date alone is its midnight). What is received or said after that is stamped then. Without `--clock` the clock is real time plus whatever it was advanced by.
+- **It does not go backwards.** A time it is already at moves it nowhere and is no error. `POST /_mock/reset` forgets the documents and leaves the clock where it is.
+- **The time inside an Invoice Response has no zone written on it** (`cbc:IssueTime` is `09:00:00`). It is UTC like the rest.
+- Two of the mock run as two processes have two clocks, and each is advanced by itself.
+
 To see the two sides talk, run two: a buyer with `--seller-url http://127.0.0.1:8101/responses`, and a supplier with `--buyer-url http://127.0.0.1:8100/invoices`.
 
 ## What it refuses
@@ -368,7 +416,7 @@ A group with nothing in it is still there: an empty `TaxSubtotal` is a VAT break
 
 - **No transport.** A real Peppol invoice goes by AS4, signed and encrypted, between access points that find each other by SMP lookup. Here it is a `POST`, and the other party is a URL. The paths and status codes are this mock's own; nothing published defines an HTTP interface for any of it.
 - **An invalid document is turned away at the door and gets no Invoice Response.** On the real network the sender's access point validates before it sends, and Peppol's guide puts the status of a transmission outside what an Invoice Response is for. That this is how a failed validation should look from the seller's side is this project's reading and not a published rule.
-- **Nothing happens with time.** A real buyer moves an invoice to in process, accepted and paid over days, and Peppol asks for a first response within three working days. Here each status after the first is asked for.
+- **Nothing happens with time**, though the clock can be moved (`POST /_mock/advance`): moving it changes what is stamped next and nothing else. A real buyer moves an invoice to in process, accepted and paid over days, and Peppol asks for a first response within three working days. Here each status after the first is asked for.
 - **A duplicate is taken like the first.** A second document with a seller and a number already held is held too. A real buyer's system would likely reject it; with which status and reason is not known here, and is not guessed.
 - **Any buyer an invoice names is this mock**, and no document is turned away because its buyer is unknown. Nor does the supplier compare who a response is from with who its invoice was for: a response is matched by the invoice's number and type code alone, and of two documents sent with one number it is taken to be about the later.
 - **A response about a document that was never sent is turned away**, and so is one that names a type code other than its document's (`OP-BR111-R014`). The guide says the code must be the document's own and not what a seller does when it is not; and on the real network a response would be delivered whatever it was about. Both are this project's choices.

{mock_einvoice-0.3.0 → mock_einvoice-0.4.0}/README.md

@@ -4,6 +4,9 @@ A mock e-invoicing partner: EN 16931 invoices in and out, with the responses tha
 
 A sibling of [mock-sap](https://github.com/rseufert/mock-sap), [mock-edi](https://github.com/rseufert/mock-edi) and [mock-bank](https://github.com/rseufert/mock-bank), and of [mock-acme](https://github.com/rseufert/mock-acme), the integration between them.
 
+By [Rick Seufert](https://rickseufert.com). Its [page](https://rickseufert.com/mock-einvoice/)
+has the features and how to start it.
+
 ```
 python3 -m pip install mock-einvoice
 mock-einvoice --port 8100
@@ -11,11 +14,11 @@ mock-einvoice --port 8100
 
 It reads and writes UBL invoices and credit notes, and the Peppol Invoice Response that answers one, and holds them to their published rules: invoices to all 979 rules of the EN 16931 core, to all 165 of Peppol's (its own 63, the 31 it has for Germany and the 71 for seven other countries), and to the 34 of a standard XRechnung document; responses to all 82 of theirs. Over HTTP it is a buyer that takes invoices in and answers the Peppol ones, and a supplier that sends them, writes the invoice for an order it is told of, and takes the answers.
 
-**What 0.3.0 is not:**
+**What 0.4.0 is not:**
 
 - **It writes one kind of invoice of its own, and no other.** The supplier writes the invoice for an order it is told of: every line at one standard rate of VAT, no allowances or charges, no credit note, no XRechnung ([An order, and the invoice for it](#an-order-and-the-invoice-for-it)). Anything else it sends as it is given.
 - **It takes no order off the network.** An order is this mock's own JSON on a `/_mock` path. Peppol's UBL `Order` and its rules are not built.
-- **It knows nothing of the other mocks.** Writing an invoice from one of mock-sap's billing documents, and saying "paid" when SAP has cleared it, is integration, and belongs in [mock-acme](https://github.com/rseufert/mock-acme) with the rest of it: its `order_to_cash`, which is on its `main` and in no release of it yet.
+- **It knows nothing of the other mocks.** Writing an invoice from one of mock-sap's billing documents, and saying "paid" when SAP has cleared it, is integration, and belongs in [mock-acme](https://github.com/rseufert/mock-acme) with the rest of it: its `order_to_cash`, since mock-acme 0.6.0.
 - **Peppol's ten rules for a seller in Iceland are held to this project's tests only.** Peppol publishes unit tests for its rules for Denmark, Greece, Italy, the Netherlands, Norway and Sweden, and every case agrees here; for Iceland it publishes none. Those ten were written from the same reading of the rule file as the tests that hold them, so a misreading would be in both.
 - **No CII, no XRechnung Extension, no ZUGFeRD**, and no transport: see [What it refuses](#what-it-refuses) and [Known to be wrong, or not real](#known-to-be-wrong-or-not-real).
 
@@ -286,11 +289,13 @@ $ curl -s -X POST http://127.0.0.1:8101/_mock/orders/1/invoices
 
 | | |
 | --- | --- |
-| `GET /_mock/health` | that it is up, its version, and how many documents it holds and has sent |
+| `GET /_mock/health` | that it is up, its version, what time it is by its clock (`"now"`), and how many documents it holds and has sent |
+| `POST /_mock/advance` | move the clock forward: `?seconds=90`, or `?to=2026-10-08T08:00`, in the query string or as JSON. It answers `{"from", "to", "seconds", "pinned"}`. `400` for a time behind the clock, a fraction of a second, or more than ten years at once |
 | `GET /_mock/turned-away` | what was not taken in, on which side, and why |
 | `POST /_mock/validate` | an invoice, a credit note or an Invoice Response held to its rules, and not kept |
 | `GET /_mock/terms` | the business terms and groups this package knows, by number: `{"terms": [{"id", "name", "group", "kind"}], "groups": [{"id", "name", "repeats", "inside", "terms"}]}`, 164 terms and 32 groups, in the standard's order |
 | `GET /_mock/terms/BT-13`, `/_mock/terms/BG-25` | one term or one group, as in the list. `404` `NO-SUCH-TERM` for anything else, written any other way (`bt-13`) |
+| `GET /_mock/binding/Invoice`, `/_mock/binding/CreditNote` | where each term and group is in that UBL document: the binding as a tree of elements. `GET /_mock/binding` names the two. `404` `NO-SUCH-KIND` for anything else |
 | `POST /_mock/reset` | forget every document and response, on both sides |
 
 **The terms are the package's own table, served.** `GET /_mock/terms` is made from `mockeinvoice.model.TERMS` and `GROUPS` when it is asked, so what a client reads is what the reader, the writer and the rules go by.
@@ -300,6 +305,48 @@ $ curl -s -X POST http://127.0.0.1:8101/_mock/orders/1/invoices
 - Three terms are written as an attribute of another's element (`BT-130`, the unit, is `BT-129`'s `unitCode`) and say so in `attribute_of`. Sixteen more, the scheme identifiers and their like (`BT-29-1`), have a number and no entry of their own here: each is listed under `attributes` on the term that holds it, and asked for by itself is `404` saying where it is.
 - A finding still gives a term by its number alone. Its path is not always a term (a rule about the XML gives an XPath), and a client that wants the name has this to look it up in.
 
+**The binding is the reader's own table, served.** `GET /_mock/binding/Invoice` is made from `mockeinvoice.ubl.BINDINGS` when it is asked: the table the reader reads a document by and the writer writes one by. A client that walks a document beside it names every element as the reader does, and a test does just that, with `xml.etree` and the served JSON alone, over this project's samples and fifty documents from EN 16931 and XRechnung, and comes to the same terms, values and groups.
+
+```
+{"kind": "Invoice", "element": "Invoice", "namespace": "urn:oasis:...:Invoice-2",
+ "prefixes": {"cbc": "urn:oasis:...", "cac": "urn:oasis:..."},
+ "children": [
+   {"element": "cbc:CustomizationID", "term": "BT-24"},
+   ...
+   {"element": "cac:AllowanceCharge", "group": "BG-20", "repeats": true,
+    "when": {"text": "cbc:ChargeIndicator is false or 0", "path": "cbc:ChargeIndicator", "in": ["false", "0"]},
+    "children": [{"element": "cbc:ChargeIndicator", "fixed": "false", "accepts": ["false", "0"]}, ...]},
+   ...]}
+```
+
+A node has its `element` and what it is:
+
+| | |
+| --- | --- |
+| `term` | the business term its text is the value of. `attributes` names each attribute the element may carry, and the term that attribute is (`"unitCode": "BT-130"`) or `null` where the standard has none for it (`currencyID`). `on_document` marks a term that is the document's whatever element it is in: a credit note's due date is inside `PaymentMeans`. |
+| `group`, `repeats` | the business group the element is, and whether it is one of many, as `/_mock/terms` has it |
+| `fixed`, `accepts` | the one value the binding gives the element (`TaxScheme/ID` is `VAT`), and what is read as that value |
+| `ubl` | something UBL requires or tells things apart by, that the standard has no term or group for, under the name this package holds it by: `ubl:NetworkID` on a payment card, the scheme of a tax registration that is not VAT, the two document references known by their type code |
+| `once_per` | the term the element is written once for each value of: one `PartyIdentification` to an identifier |
+| `subject` | on `cbc:Note`, the term of the code written before the text between two `#` (`#AAI#the note`) |
+| `children` | the elements in it, in the order the schema has them |
+| *none of these* | an element that only holds others: `cac:Party`, `cac:TaxTotal` |
+
+- **One element, several entries.** `cac:AllowanceCharge` is an allowance or a charge; `cac:AdditionalDocumentReference` is the invoiced object, a supporting document, or on a credit note the project. Such entries are in the reader's order, and each but the last has a `when`: the first whose test holds has the element, and one with no `when` takes what is left. A `when` has its `text` in words, and where it can be computed, a `path` under the element (and an `attribute` of what is there), the values it is `in`, and `ignoring_case`. An element's text is compared with the space around it taken off.
+- **One test is not data.** Which of two `cac:TaxTotal` is the VAT total in the accounting currency (BT-111) depends on two currency codes at the head of the document. Those two entries have their test in words and a `name` (`tax-total-in-document-currency`, `tax-total-in-accounting-currency`), and a client has to know them by that.
+- **A tax registration is served as two entries**, the VAT identifier and whatever else, told apart by `cac:TaxScheme/cbc:ID`. In the package it is one piece of code and not a row of the table, so those nodes are written out by hand beside it. A buyer and a tax representative have no term for another registration: theirs is held as the VAT identifier, and the second entry says so by naming the same term.
+- **What has no node has no business term.** An element of a document that the binding has no node for is what the reader reports as `UNHELD`.
+- **Not in it:** which place a value is written back to when a term has two (the creditor identifier, on the seller or the payee), and how often an element may occur.
+
+**The clock.** Every stamp (`"received"`, `"sent"`, `"now"`), the date and time in an Invoice Response, and the dates on an invoice the supplier writes come from one clock.
+
+- **It is UTC, and every stamp says so**: `2026-10-07T09:00:00Z`, to the second.
+- **`--clock` pins it, and a pinned clock stands still.** `--clock 2026-10-07T09:00` is that moment in UTC. `--clock 2026-10-07T11:00+02:00` is the same moment, and is said back in UTC; a `Z` may be written and changes nothing. In a query string a `+` is a space, so `?to=` writes that offset `%2B02:00`; a time whose `+` became a space is refused with a word saying so, and not repaired. Every stamp and every response carries that one instant until the clock is moved, so that what a run writes does not change from run to run. It does not tick on between advances, as mock-sap's pinned clock does: a second that depends on how fast the run went is what pinning is there to take away.
+- **`POST /_mock/advance` moves it**, pinned or not, by whole seconds or to a time, written as `--clock` is (a date alone is its midnight). What is received or said after that is stamped then. Without `--clock` the clock is real time plus whatever it was advanced by.
+- **It does not go backwards.** A time it is already at moves it nowhere and is no error. `POST /_mock/reset` forgets the documents and leaves the clock where it is.
+- **The time inside an Invoice Response has no zone written on it** (`cbc:IssueTime` is `09:00:00`). It is UTC like the rest.
+- Two of the mock run as two processes have two clocks, and each is advanced by itself.
+
 To see the two sides talk, run two: a buyer with `--seller-url http://127.0.0.1:8101/responses`, and a supplier with `--buyer-url http://127.0.0.1:8100/invoices`.
 
 ## What it refuses
@@ -338,7 +385,7 @@ A group with nothing in it is still there: an empty `TaxSubtotal` is a VAT break
 
 - **No transport.** A real Peppol invoice goes by AS4, signed and encrypted, between access points that find each other by SMP lookup. Here it is a `POST`, and the other party is a URL. The paths and status codes are this mock's own; nothing published defines an HTTP interface for any of it.
 - **An invalid document is turned away at the door and gets no Invoice Response.** On the real network the sender's access point validates before it sends, and Peppol's guide puts the status of a transmission outside what an Invoice Response is for. That this is how a failed validation should look from the seller's side is this project's reading and not a published rule.
-- **Nothing happens with time.** A real buyer moves an invoice to in process, accepted and paid over days, and Peppol asks for a first response within three working days. Here each status after the first is asked for.
+- **Nothing happens with time**, though the clock can be moved (`POST /_mock/advance`): moving it changes what is stamped next and nothing else. A real buyer moves an invoice to in process, accepted and paid over days, and Peppol asks for a first response within three working days. Here each status after the first is asked for.
 - **A duplicate is taken like the first.** A second document with a seller and a number already held is held too. A real buyer's system would likely reject it; with which status and reason is not known here, and is not guessed.
 - **Any buyer an invoice names is this mock**, and no document is turned away because its buyer is unknown. Nor does the supplier compare who a response is from with who its invoice was for: a response is matched by the invoice's number and type code alone, and of two documents sent with one number it is taken to be about the later.
 - **A response about a document that was never sent is turned away**, and so is one that names a type code other than its document's (`OP-BR111-R014`). The guide says the code must be the document's own and not what a seller does when it is not; and on the real network a response would be delivered whatever it was about. Both are this project's choices.

{mock_einvoice-0.3.0 → mock_einvoice-0.4.0/mock_einvoice.egg-info}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: mock-einvoice
-Version: 0.3.0
+Version: 0.4.0
 Summary: A mock e-invoicing partner: EN 16931 invoices in and out, with the responses that follow. Zero dependencies.
 License: MIT AND EUPL-1.2
+Project-URL: Homepage, https://rickseufert.com/mock-einvoice/
 Project-URL: Repository, https://github.com/rseufert/mock-einvoice
 Project-URL: Issues, https://github.com/rseufert/mock-einvoice/issues
 Project-URL: Changelog, https://github.com/rseufert/mock-einvoice/blob/main/CHANGELOG.md
@@ -34,6 +35,9 @@ A mock e-invoicing partner: EN 16931 invoices in and out, with the responses tha
 
 A sibling of [mock-sap](https://github.com/rseufert/mock-sap), [mock-edi](https://github.com/rseufert/mock-edi) and [mock-bank](https://github.com/rseufert/mock-bank), and of [mock-acme](https://github.com/rseufert/mock-acme), the integration between them.
 
+By [Rick Seufert](https://rickseufert.com). Its [page](https://rickseufert.com/mock-einvoice/)
+has the features and how to start it.
+
 ```
 python3 -m pip install mock-einvoice
 mock-einvoice --port 8100
@@ -41,11 +45,11 @@ mock-einvoice --port 8100
 
 It reads and writes UBL invoices and credit notes, and the Peppol Invoice Response that answers one, and holds them to their published rules: invoices to all 979 rules of the EN 16931 core, to all 165 of Peppol's (its own 63, the 31 it has for Germany and the 71 for seven other countries), and to the 34 of a standard XRechnung document; responses to all 82 of theirs. Over HTTP it is a buyer that takes invoices in and answers the Peppol ones, and a supplier that sends them, writes the invoice for an order it is told of, and takes the answers.
 
-**What 0.3.0 is not:**
+**What 0.4.0 is not:**
 
 - **It writes one kind of invoice of its own, and no other.** The supplier writes the invoice for an order it is told of: every line at one standard rate of VAT, no allowances or charges, no credit note, no XRechnung ([An order, and the invoice for it](#an-order-and-the-invoice-for-it)). Anything else it sends as it is given.
 - **It takes no order off the network.** An order is this mock's own JSON on a `/_mock` path. Peppol's UBL `Order` and its rules are not built.
-- **It knows nothing of the other mocks.** Writing an invoice from one of mock-sap's billing documents, and saying "paid" when SAP has cleared it, is integration, and belongs in [mock-acme](https://github.com/rseufert/mock-acme) with the rest of it: its `order_to_cash`, which is on its `main` and in no release of it yet.
+- **It knows nothing of the other mocks.** Writing an invoice from one of mock-sap's billing documents, and saying "paid" when SAP has cleared it, is integration, and belongs in [mock-acme](https://github.com/rseufert/mock-acme) with the rest of it: its `order_to_cash`, since mock-acme 0.6.0.
 - **Peppol's ten rules for a seller in Iceland are held to this project's tests only.** Peppol publishes unit tests for its rules for Denmark, Greece, Italy, the Netherlands, Norway and Sweden, and every case agrees here; for Iceland it publishes none. Those ten were written from the same reading of the rule file as the tests that hold them, so a misreading would be in both.
 - **No CII, no XRechnung Extension, no ZUGFeRD**, and no transport: see [What it refuses](#what-it-refuses) and [Known to be wrong, or not real](#known-to-be-wrong-or-not-real).
 
@@ -316,11 +320,13 @@ $ curl -s -X POST http://127.0.0.1:8101/_mock/orders/1/invoices
 
 | | |
 | --- | --- |
-| `GET /_mock/health` | that it is up, its version, and how many documents it holds and has sent |
+| `GET /_mock/health` | that it is up, its version, what time it is by its clock (`"now"`), and how many documents it holds and has sent |
+| `POST /_mock/advance` | move the clock forward: `?seconds=90`, or `?to=2026-10-08T08:00`, in the query string or as JSON. It answers `{"from", "to", "seconds", "pinned"}`. `400` for a time behind the clock, a fraction of a second, or more than ten years at once |
 | `GET /_mock/turned-away` | what was not taken in, on which side, and why |
 | `POST /_mock/validate` | an invoice, a credit note or an Invoice Response held to its rules, and not kept |
 | `GET /_mock/terms` | the business terms and groups this package knows, by number: `{"terms": [{"id", "name", "group", "kind"}], "groups": [{"id", "name", "repeats", "inside", "terms"}]}`, 164 terms and 32 groups, in the standard's order |
 | `GET /_mock/terms/BT-13`, `/_mock/terms/BG-25` | one term or one group, as in the list. `404` `NO-SUCH-TERM` for anything else, written any other way (`bt-13`) |
+| `GET /_mock/binding/Invoice`, `/_mock/binding/CreditNote` | where each term and group is in that UBL document: the binding as a tree of elements. `GET /_mock/binding` names the two. `404` `NO-SUCH-KIND` for anything else |
 | `POST /_mock/reset` | forget every document and response, on both sides |
 
 **The terms are the package's own table, served.** `GET /_mock/terms` is made from `mockeinvoice.model.TERMS` and `GROUPS` when it is asked, so what a client reads is what the reader, the writer and the rules go by.
@@ -330,6 +336,48 @@ $ curl -s -X POST http://127.0.0.1:8101/_mock/orders/1/invoices
 - Three terms are written as an attribute of another's element (`BT-130`, the unit, is `BT-129`'s `unitCode`) and say so in `attribute_of`. Sixteen more, the scheme identifiers and their like (`BT-29-1`), have a number and no entry of their own here: each is listed under `attributes` on the term that holds it, and asked for by itself is `404` saying where it is.
 - A finding still gives a term by its number alone. Its path is not always a term (a rule about the XML gives an XPath), and a client that wants the name has this to look it up in.
 
+**The binding is the reader's own table, served.** `GET /_mock/binding/Invoice` is made from `mockeinvoice.ubl.BINDINGS` when it is asked: the table the reader reads a document by and the writer writes one by. A client that walks a document beside it names every element as the reader does, and a test does just that, with `xml.etree` and the served JSON alone, over this project's samples and fifty documents from EN 16931 and XRechnung, and comes to the same terms, values and groups.
+
+```
+{"kind": "Invoice", "element": "Invoice", "namespace": "urn:oasis:...:Invoice-2",
+ "prefixes": {"cbc": "urn:oasis:...", "cac": "urn:oasis:..."},
+ "children": [
+   {"element": "cbc:CustomizationID", "term": "BT-24"},
+   ...
+   {"element": "cac:AllowanceCharge", "group": "BG-20", "repeats": true,
+    "when": {"text": "cbc:ChargeIndicator is false or 0", "path": "cbc:ChargeIndicator", "in": ["false", "0"]},
+    "children": [{"element": "cbc:ChargeIndicator", "fixed": "false", "accepts": ["false", "0"]}, ...]},
+   ...]}
+```
+
+A node has its `element` and what it is:
+
+| | |
+| --- | --- |
+| `term` | the business term its text is the value of. `attributes` names each attribute the element may carry, and the term that attribute is (`"unitCode": "BT-130"`) or `null` where the standard has none for it (`currencyID`). `on_document` marks a term that is the document's whatever element it is in: a credit note's due date is inside `PaymentMeans`. |
+| `group`, `repeats` | the business group the element is, and whether it is one of many, as `/_mock/terms` has it |
+| `fixed`, `accepts` | the one value the binding gives the element (`TaxScheme/ID` is `VAT`), and what is read as that value |
+| `ubl` | something UBL requires or tells things apart by, that the standard has no term or group for, under the name this package holds it by: `ubl:NetworkID` on a payment card, the scheme of a tax registration that is not VAT, the two document references known by their type code |
+| `once_per` | the term the element is written once for each value of: one `PartyIdentification` to an identifier |
+| `subject` | on `cbc:Note`, the term of the code written before the text between two `#` (`#AAI#the note`) |
+| `children` | the elements in it, in the order the schema has them |
+| *none of these* | an element that only holds others: `cac:Party`, `cac:TaxTotal` |
+
+- **One element, several entries.** `cac:AllowanceCharge` is an allowance or a charge; `cac:AdditionalDocumentReference` is the invoiced object, a supporting document, or on a credit note the project. Such entries are in the reader's order, and each but the last has a `when`: the first whose test holds has the element, and one with no `when` takes what is left. A `when` has its `text` in words, and where it can be computed, a `path` under the element (and an `attribute` of what is there), the values it is `in`, and `ignoring_case`. An element's text is compared with the space around it taken off.
+- **One test is not data.** Which of two `cac:TaxTotal` is the VAT total in the accounting currency (BT-111) depends on two currency codes at the head of the document. Those two entries have their test in words and a `name` (`tax-total-in-document-currency`, `tax-total-in-accounting-currency`), and a client has to know them by that.
+- **A tax registration is served as two entries**, the VAT identifier and whatever else, told apart by `cac:TaxScheme/cbc:ID`. In the package it is one piece of code and not a row of the table, so those nodes are written out by hand beside it. A buyer and a tax representative have no term for another registration: theirs is held as the VAT identifier, and the second entry says so by naming the same term.
+- **What has no node has no business term.** An element of a document that the binding has no node for is what the reader reports as `UNHELD`.
+- **Not in it:** which place a value is written back to when a term has two (the creditor identifier, on the seller or the payee), and how often an element may occur.
+
+**The clock.** Every stamp (`"received"`, `"sent"`, `"now"`), the date and time in an Invoice Response, and the dates on an invoice the supplier writes come from one clock.
+
+- **It is UTC, and every stamp says so**: `2026-10-07T09:00:00Z`, to the second.
+- **`--clock` pins it, and a pinned clock stands still.** `--clock 2026-10-07T09:00` is that moment in UTC. `--clock 2026-10-07T11:00+02:00` is the same moment, and is said back in UTC; a `Z` may be written and changes nothing. In a query string a `+` is a space, so `?to=` writes that offset `%2B02:00`; a time whose `+` became a space is refused with a word saying so, and not repaired. Every stamp and every response carries that one instant until the clock is moved, so that what a run writes does not change from run to run. It does not tick on between advances, as mock-sap's pinned clock does: a second that depends on how fast the run went is what pinning is there to take away.
+- **`POST /_mock/advance` moves it**, pinned or not, by whole seconds or to a time, written as `--clock` is (a date alone is its midnight). What is received or said after that is stamped then. Without `--clock` the clock is real time plus whatever it was advanced by.
+- **It does not go backwards.** A time it is already at moves it nowhere and is no error. `POST /_mock/reset` forgets the documents and leaves the clock where it is.
+- **The time inside an Invoice Response has no zone written on it** (`cbc:IssueTime` is `09:00:00`). It is UTC like the rest.
+- Two of the mock run as two processes have two clocks, and each is advanced by itself.
+
 To see the two sides talk, run two: a buyer with `--seller-url http://127.0.0.1:8101/responses`, and a supplier with `--buyer-url http://127.0.0.1:8100/invoices`.
 
 ## What it refuses
@@ -368,7 +416,7 @@ A group with nothing in it is still there: an empty `TaxSubtotal` is a VAT break
 
 - **No transport.** A real Peppol invoice goes by AS4, signed and encrypted, between access points that find each other by SMP lookup. Here it is a `POST`, and the other party is a URL. The paths and status codes are this mock's own; nothing published defines an HTTP interface for any of it.
 - **An invalid document is turned away at the door and gets no Invoice Response.** On the real network the sender's access point validates before it sends, and Peppol's guide puts the status of a transmission outside what an Invoice Response is for. That this is how a failed validation should look from the seller's side is this project's reading and not a published rule.
-- **Nothing happens with time.** A real buyer moves an invoice to in process, accepted and paid over days, and Peppol asks for a first response within three working days. Here each status after the first is asked for.
+- **Nothing happens with time**, though the clock can be moved (`POST /_mock/advance`): moving it changes what is stamped next and nothing else. A real buyer moves an invoice to in process, accepted and paid over days, and Peppol asks for a first response within three working days. Here each status after the first is asked for.
 - **A duplicate is taken like the first.** A second document with a seller and a number already held is held too. A real buyer's system would likely reject it; with which status and reason is not known here, and is not guessed.
 - **Any buyer an invoice names is this mock**, and no document is turned away because its buyer is unknown. Nor does the supplier compare who a response is from with who its invoice was for: a response is matched by the invoice's number and type code alone, and of two documents sent with one number it is taken to be about the later.
 - **A response about a document that was never sent is turned away**, and so is one that names a type code other than its document's (`OP-BR111-R014`). The guide says the code must be the document's own and not what a seller does when it is not; and on the real network a response would be delivered whatever it was about. Both are this project's choices.

{mock_einvoice-0.3.0 → mock_einvoice-0.4.0}/mock_einvoice.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ mock_einvoice.egg-info/top_level.txt
 mockeinvoice/__init__.py
 mockeinvoice/__main__.py
 mockeinvoice/buyer.py
+mockeinvoice/clock.py
 mockeinvoice/model.py
 mockeinvoice/order.py
 mockeinvoice/response.py
@@ -37,8 +38,10 @@ mockeinvoice/rules/ublsyntax.py
 mockeinvoice/rules/untdid.py
 mockeinvoice/rules/xrechnung.py
 tests/__init__.py
+tests/test_binding.py
 tests/test_business_rules.py
 tests/test_buyer.py
+tests/test_clock.py
 tests/test_code_rules.py
 tests/test_model.py
 tests/test_order.py

{mock_einvoice-0.3.0 → mock_einvoice-0.4.0}/mockeinvoice/__init__.py

@@ -37,7 +37,7 @@ from .response import Response
 from .rules import Report, check, check_response
 from .ubl import parse, parse_tree, write
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = ["Document", "Finding", "Group", "Refused", "Report", "Response", "Value", "check",
            "read", "read_response", "validate", "validate_response", "write", "write_response",

{mock_einvoice-0.3.0 → mock_einvoice-0.4.0}/mockeinvoice/buyer.py

@@ -28,6 +28,7 @@ import threading
 from dataclasses import dataclass, field
 from typing import Callable, Dict, List, Optional, Sequence, Tuple, Union
 
+from . import clock as _clock
 from . import response as _response
 from . import specification as _specification
 from .model import Document, Finding, Refused
@@ -166,7 +167,8 @@ class Buyer:
 
     `deliver` is called with each response's XML and returns what became of
     sending it (see `Sent.delivery`); without one, responses are kept and not
-    sent. `now` is the clock.
+    sent. `now` is the clock: a `clock.Clock`, or anything that when called
+    gives the time (one with no zone is taken to be UTC).
     """
 
     def __init__(self, answers: str = "required",
@@ -188,7 +190,7 @@ class Buyer:
             self.turned_away: List[Tuple[str, str, str]] = []
 
     def stamp(self) -> str:
-        return self.now().replace(microsecond=0, tzinfo=None).isoformat()
+        return _clock.stamp(self.now())
 
     # -- taking a document in -----------------------------------------------------------
 
@@ -279,7 +281,7 @@ class Buyer:
                 note: str) -> Response:
         """The response to one document: from its buyer to its seller, about
         it by number, date and type, under the profile its own calls for."""
-        document, now = held.document, self.now()
+        document, now = held.document, _clock.utc(self.now())
         return Response(
             profile=(_response.BILLING_WITH_RESPONSE if held.profile == "02"
                      else _response.PROFILE),

mock_einvoice-0.4.0/mockeinvoice/clock.py

@@ -0,0 +1,128 @@
+"""The mock's clock: one that can be pinned, and moved forward.
+
+    from mockeinvoice.clock import Clock
+
+    clock = Clock("2026-10-07T09:00")       # pinned; or Clock() for real time
+    clock.now()                             # an aware datetime, in UTC
+    clock.advance(seconds=90)               # or to="2026-10-08T08:00"
+    clock.stamp()                           # "2026-10-07T09:01:30Z"
+
+**A pinned clock stands still.** It is at the moment it was pinned to until it
+is advanced, and then at that moment, so that what a run writes does not
+change from run to run: two responses given without an advance between them
+carry the same second. mock-sap's pinned clock ticks on from where it was
+pinned; this one does not, because a second that depends on how fast the run
+went is what pinning is there to take away.
+
+**A clock that is not pinned is real time, plus whatever it was advanced by.**
+
+**It is UTC, and only UTC.** A time given with no zone is taken to be UTC; one
+given with an offset is that moment, and is said back in UTC. Every stamp ends
+in `Z`. Nothing here depends on a zone: there is no cutoff hour and no
+business day.
+
+**It does not go backwards**, because what was stamped since would then be in
+the future, and one advance moves it at most about ten years.
+"""
+from __future__ import annotations
+
+import datetime
+import re
+import threading
+from typing import Callable, Dict, Optional, Union
+
+UTC = datetime.timezone.utc
+MOST = 3650 * 86400         # seconds, the furthest one advance moves
+MOMENT = re.compile(r"\d{4}-\d{2}-\d{2}"
+                    r"(T([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?(Z|[+-]([01]\d|2[0-3]):[0-5]\d)?)?")
+
+
+class Invalid(ValueError):
+    """A time the clock was not given in a way it takes, or cannot move to."""
+
+
+def utc(moment: datetime.datetime) -> datetime.datetime:
+    """A moment in UTC. One with no zone is taken to be UTC already."""
+    if moment.tzinfo is None:
+        return moment.replace(tzinfo=UTC)
+    return moment.astimezone(UTC)
+
+
+def stamp(moment: datetime.datetime) -> str:
+    """A moment as the mock writes one: to the second, in UTC, with a `Z`."""
+    return utc(moment).replace(microsecond=0, tzinfo=None).isoformat() + "Z"
+
+
+def plus_lost(text: object) -> str:
+    """What to add to a refusal of a time whose `+` offset a query string
+    turned into a space, and "" for a time wrong any other way. Not repaired:
+    a URL only this mock took would break wherever else a script sent it."""
+    if isinstance(text, str) and MOMENT.fullmatch(text.replace(" ", "+")):
+        return ": a + in a query string is read as a space, so a + offset is written %2B there"
+    return ""
+
+
+def moment(text: str) -> datetime.datetime:
+    """A moment from `2026-10-07`, `2026-10-07T09:00` or `2026-10-07T09:00:30`,
+    with `Z` or an offset (`+02:00`) after a time, or `Invalid`. With no zone
+    it is UTC; a date alone is its midnight."""
+    if not isinstance(text, str) or not MOMENT.fullmatch(text):
+        raise Invalid("a time is written 2026-10-07, 2026-10-07T09:00 or "
+                      "2026-10-07T09:00:30, in UTC or with Z or an offset such as +02:00 "
+                      "after it, and not %r%s" % (text, plus_lost(text)))
+    try:
+        return utc(datetime.datetime.fromisoformat(text[:-1] if text.endswith("Z") else text))
+    except (ValueError, OverflowError):
+        raise Invalid("%s is no date and time there is" % text) from None
+
+
+class Clock:
+    """The time the mock goes by. Called, it is `now()`, so it can be given
+    wherever a `now` is taken."""
+
+    def __init__(self, pinned: Union[None, str, datetime.datetime] = None,
+                 real: Optional[Callable[[], datetime.datetime]] = None):
+        if isinstance(pinned, str):
+            pinned = moment(pinned)
+        self.pinned = utc(pinned) if pinned is not None else None
+        self.real = real or (lambda: datetime.datetime.now(UTC))
+        self.moved = datetime.timedelta(0)
+        self.lock = threading.Lock()
+
+    def now(self) -> datetime.datetime:
+        return (self.pinned if self.pinned is not None else utc(self.real())) + self.moved
+
+    __call__ = now
+
+    def stamp(self) -> str:
+        return stamp(self.now())
+
+    def advance(self, seconds: object = None, to: object = None) -> Dict[str, object]:
+        """Move the clock forward by a whole number of seconds, or to a time
+        (`moment`), and say where it went, or raise `Invalid`. A time it is
+        already at moves it nowhere and is no error."""
+        if (seconds is None) == (to is None):
+            raise Invalid("advance takes seconds, or a time to move to, and one of them")
+        with self.lock:
+            before = self.now()
+            if seconds is not None:
+                if isinstance(seconds, str) and seconds.isdigit() and seconds.isascii():
+                    seconds = int(seconds)
+                if isinstance(seconds, bool) or not isinstance(seconds, int) or seconds < 0:
+                    raise Invalid("seconds is a whole number, nought or more, and not %r: "
+                                  "a stamp is to the second" % (seconds,))
+                by = seconds
+            else:
+                target = moment(to) if not isinstance(to, datetime.datetime) else utc(to)
+                # To the second, as a stamp is: a time the clock is at within
+                # the second is not behind it.
+                by = int((target - before.replace(microsecond=0)).total_seconds())
+                if by < 0:
+                    raise Invalid("the clock does not go backwards: it is %s, and %s is "
+                                  "before that" % (stamp(before), stamp(target)))
+            if by > MOST:
+                raise Invalid("an advance moves the clock at most %d seconds (%d days), "
+                              "and this is %d" % (MOST, MOST // 86400, by))
+            self.moved += datetime.timedelta(seconds=by)
+            return {"from": stamp(before), "to": self.stamp(), "seconds": by,
+                    "pinned": self.pinned is not None}