docs: rewrite the README, and replace the examples with measured output - #18
Merged
Conversation
Same structural rewrite as openadapt-flow. Two accuracy fixes matter more than the prose: - The example table claimed outputs the package does not produce. Against openadapt-privacy 1.0.3 from PyPI: 'SSN: 923-45-6789' scrubs to '<ORGANIZATION>: <US_SSN>', not 'SSN: <US_SSN>'; 'Card: 4532-1234-5678-9012' scrubs to 'Card: <DATE_TIME>', not '<CREDIT_CARD>'; the US_BANK_NUMBER and US_DRIVER_LICENSE rows also produce a different entity than documented. Every example in the file is now a real captured result. - The scrub_dict example used the 'text' key, which is treated as character-separated action text joined by ACTION_TEXT_SEP. The real output is hyphenated one character at a time. The example now uses keys that behave, and the caveat is stated. Also removed the substrate sentence claiming RDP and Windows replay are early and Citrix is exploratory; flow's docs/PRODUCT_STATUS.md records counted 3/3 acceptance for Windows, macOS, Linux, and RDP. 312 lines to 212. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of the README pass across the public repos
(openadapt-flow#423
has the diagnosis).
The prose changes are the smaller half of this. The examples were wrong.
What I found
I installed
openadapt-privacy[presidio]==1.0.3from PyPI, downloadeden_core_web_sm, and ran every example in the README. Four of the nine rows inthe "Example Inputs & Outputs" table do not produce what the table says:
SSN: 923-45-6789→SSN: <US_SSN><ORGANIZATION>: <US_SSN>Card: 4532-1234-5678-9012→Card: <CREDIT_CARD>Card: <DATE_TIME>DOB: 01/15/1985→DOB: <DATE_TIME><ORGANIZATION>: <DATE_TIME>635526789012→<US_BANK_NUMBER><DATE_TIME>A123-456-789-012→<US_DRIVER_LICENSE><ORGANIZATION>The card number is the one I would worry about. It does get redacted, so
nothing leaks, but it comes back as
DATE_TIMErather thanCREDIT_CARD. ALuhn-valid
4111111111111111behaves the same way. Anyone who writes a policythat keys off the placeholder name would be building on a false premise, so the
README now says so explicitly instead of listing a clean table.
Second one, and I think this is a real bug rather than a docs bug: the
scrub_dictexample uses thetextkey.textis inSCRUB_KEYS_HTMLand isscrubbed as character-separated action text joined by
ACTION_TEXT_SEP, so thedocumented input comes back as
"<-P-E-R-S-O-N->-:- -<-E-M-A-I-L-_-A-D-D-R-E-S-S->".The README showed clean output. I switched the example to
title/tooltip/value, which behave, and noted the caveat. Worth fixing in the code.Prose changes
Cut the status admonition and the stack table that appears word for word in
five other repos. Cut the substrate sentence claiming "RDP and Windows replay
are early, and Citrix is exploratory" — flow's
docs/PRODUCT_STATUS.mdrecordscounted 3/3 acceptance for Windows, macOS, Linux and RDP, so that line was
stale in both directions.
Promoted the honest caveat (synthetic regression evidence, not clinical
validation; scrubbing is one control in a reviewed egress process) from a
paragraph in the middle to its own section near the top, because it's the thing
a reader most needs before they trust this.
Merged the three tables that each demonstrated the same thing into one worked
example with real output.
312 lines to 212. Zero em dashes.