Recent commits to derivepassphrase.git (7dbdf936ba20627aa4211f99d1d7e06ec9a5fd1c)

Enable cross-references on function signatures in documentation

2024-09-29T23:17:02+02:00

When enabling `signature_crossrefs`, some default values use enumeration
values that we'd really like to have anchors for in the documentation.
(This also seems sensible for typing-only classes.)  We currently use an
"attributes" table in the class docstring for this purpose; build on
this by forcing MkDocs to render the respective class attribute too, via
an empty "docstring" for the attribute.

I considered enabling parameter headings, but these cannot be suppressed
from the table of contents, and the table of contents then starts
looking very cramped.
</pre>

Fix bad docstring reference to Python standard library

2024-09-28T09:10:01+02:00

</pre>

Reintegrate branch 'master' into documentation-fixes

2024-09-27T22:33:03+02:00

* master:
  Fix outstanding formatting and linting issues
  Switch from towncrier to scriv for changelog management
  Add changelog entry for hypothesis use
  Add hypothesis-based tests (and bugfix) for the vault derivation scheme
  Set up the "hypothesis" testing library
</pre>

Fix outstanding formatting and linting issues

2024-09-27T22:18:46+02:00

</pre>

Merge topic branch 'remove-towncrier' into master

2024-09-27T22:15:41+02:00

* t/remove-towncrier:
  Switch from towncrier to scriv for changelog management
</pre>

Switch from towncrier to scriv for changelog management

2024-09-27T21:35:32+02:00

I have found towncrier to be rather painful when used together with
Markdown entries: it feels very much like a reStructuredText-only tool
retrofitted with patchy Markdown support.  In particular, towncrier
blindly concatenates all entries (assumed to be list items) into the
output (and adds the implied issue links afterwards), manually adjusted
for nicer indentation in an ad-hoc fashion.  This fails horribly if the
changelog entry is anything except a single, paragraph-free list item;
it fails in particular for reference-style links and for multi-paragraph
entries.

So switch to scriv, by Ned Batchelder, which is a similar style to
towncrier.  That too has its issues, such as the automatically
generated, non-configurable HTML4-style heading anchor, but it's
somewhat more tolerant/encouraging of manual editing of the changelog
entries and the changelog master file.

Since we're cleaning up the changelog, use this opportunity to fix the
formatting of the existing entries.
</pre>

Merge topic branch 'hypothesis' into master

2024-09-27T19:13:27+02:00

* t/hypothesis:
  Add changelog entry for hypothesis use
  Add hypothesis-based tests (and bugfix) for the vault derivation scheme
  Set up the "hypothesis" testing library
</pre>

Add changelog entry for hypothesis use

2024-09-27T19:13:10+02:00

</pre>

Add hypothesis-based tests (and bugfix) for the vault derivation scheme

2024-09-27T19:05:16+02:00

There are currently three such property-based tests: a test for general
adherence to constraints (with small numbers), and two tests
specifically for length and repeat constraints (with larger numbers).
Combining these into a single test caused the test runs to vary wildly
in execution time, which is undesirable from a configuration point of
view (and also causes hypothesis to complain).

The hypothesis tests actually uncovered a bug in the API specification
of the vault derivation scheme: during generation, we may run out of
possible characters for the next letter due to repeat constraints, but
only realize this now.  This already generated a `ValueError`, but with
a confusing error message, and the documentation seemed to suggest that
all unsatisfiable constraints are already detected at construction time.
So now explicitly mention that constraint unsatisfiability may be
detected both in the `Vault` constructor and in `Vault.generate`, and
handle lower-lever `ValueError`s in `Vault.generate` explicitly too.
</pre>

Set up the "hypothesis" testing library

2024-09-27T17:32:46+02:00

"hypothesis" is a Python library for property-based testing, i.e. for
asserting that the output of the tested code satisfies some property by
generating valid test inputs and testing these.  For `derivepassphrase`
in particular, this means generating different passphrase constraint
settings and testing that the generated passphrases match these
constraints, no matter what constraints exactly are chosen (within
reason).  The hypothesis library provides methods to generate test input
(test function parameter values, or custom walks for state machine-like
systems) and, for failing examples, shrink those to shorter/simpler ones
exhibiting the same error.

By its nature, hypothesis runs unit test functions multiple times with
different inputs, and so takes much longer than normal unit tests.  (In
the default configuration, 200 examples per test are run.)  It is
therefore sensible to set up alternate testing profiles with more or
less examples per test, and to include a mechanism in the test runner to
switch to these profiles.  The hypothesis documentation provides an
explicit example for profile setup for pytest use, plus three sensible
configurations "ci", "dev" and "debug", which I copied.  The pytest
command-line as called by `hatch test` is also straightforward to adapt:
add `--hypothesis-profile=...` to all pytest invocations.  However, the
shape of the `hatch test` environment matrix no longer matches the
reality of scenarios we'd like to test (because we added a new
dimension: slow, thorough testing, or fast testing).  So use this
opportunity to also clean up the matrix.
</pre>