Recent commits to derivepassphrase.git (ad0fe1ec36de50d886fc4b0ed988203bc557c90f)

Document the switch to the logging and warning systems in the changelog

2024-12-08T19:02:03+01:00

</pre>

Adapt the test suite to use the logging system properly

2024-12-07T09:30:38+01:00

Given the previous changes to warning and error reporting, the test
suite needs new helper code to deal with them.  Again, the changes to
mosts tests are straight-forward (the location and formatting of
messages changes slightly), but the new logging machinery itself now
also needs to be tested... particularly the code that hooks into
Python's logging system, into Python's warning system, and between those
two.

`pytest` actually includes test fixtures to capture and interact with
warnings and logging calls, but these work on the library level:
warnings are captured as warnings, logging calls are captured as log
records.  To be useful to application testing, it is necessary to
inspect and assert both the low-level warnings/log records as well as
the standard error output they ultimately translate to.  The
`hypothesis`-based tests need particular (manual) care, because
`hypothesis` rejects tests using function-scoped `pytest` fixtures.
</pre>

Emit new info messages and better debug messages in the exporter modules

2024-12-07T09:30:38+01:00

</pre>

Use the logging system to emit warnings and error messages

2024-12-07T09:30:38+01:00

Employ the Python standard library module `logging` to issue warning
and error messages, as well as (partially new) debug messages.
Operational warning messages and operational deprecation messages are
handled via the `derivepassphrase` and `derivepassphrase.deprecation`
loggers with a custom handler that prints the resulting formatted
message to standard error.  (Errors, info and debug messages use the
same system, but differ slightly in the formatting.)

Most of the rewriting of warnings and error messages to fit this new
machinery is pretty straight-forward.  The messy parts are the
integration of the `logging` machinery and the `warnings` machinery into
`click`, which isn't really designed with this in mind.  Concretely,
this entails writing a custom logging handler that uses `click.echo`,
a custom formatter that prefixes messages with the program name (and
"warning", "deprecation warning" or "debug" as necessary), a singleton
configuration of this handler and formatter, various wrappers around
standard `click` infrastructure to ensure that this integration code
actually runs during normal operation, and finally, new command-line
options to control the level of output on standard error.
</pre>

Shift option parsing and grouping machinery to a separate section

2024-12-07T08:50:03+01:00

We expect to add new option categories that apply to multiple super- and
subcommands, not just the "vault" subcommand.
</pre>

Reimplement deprecated subcommands, properly, in `click`

2024-12-07T08:50:03+01:00

Our previous method of dispatching to subcommands was not tying the
supercommand and the subcommand together properly; each command
essentially ran in its own isolated context.  This lead to unnecessary
double-parsing of the command-line arguments, and to `click` becoming
confused as to what the full command-line actually was; in particular,
the help and usage messages gave a wrong command summary.

Instead, we now use custom `click.Group` objects as the supercommands
which default to the "vault" subcommand (with a deprecation warning) if
no explicit subcommand could be matched, rather than throwing an error;
this all happens internally using the normal mechanism for subcommand
dispatch.  Additionally, if the supercommand callback actually is
invoked -- which only happens if the supercommand is given without any
arguments -- we emit a deprecation warning and dispatch manually to the
"vault" subcommand using the same code path as the `click`
implementation would otherwise do.  We assert that the old and new code
paths work via new tests as necessary, particularly for the
"supercommand without arguments" case.

This implementation necessarily messes with some `click` internals,
duplicating the code as it currently stands.  Being a non-public API,
there is of course no guarantee that this will work with future versions
of `click`.  However, we use this solely to implement a compatibility
interface, which should vanish with `derivepassphrase` v1.0 anyway.  The
alternative -- rewriting `derivepassphrase` for another command-line
framework, or rolling our own command-line interface from scratch --
seems even more expensive/wasteful than this solution.
</pre>

Fix minor formatting quibbles in documentation and code style

2024-11-28T21:30:03+01:00

In particular, in online documentation builds, the URLs are slightly
different, so the CSS rules weren't triggering correctly.
</pre>

Release 0.3.3

2024-11-28T13:47:41+01:00

</pre>

Merge topic branch '033-pre-release-copyediting' into master

2024-11-28T13:38:43+01:00

* t/033-pre-release-copyediting:
  Copyedit tutorials, how-tos and reference pages structure
  Copyedit and reclassify changelog entry for deterministic DSA signatures
</pre>

Copyedit tutorials, how-tos and reference pages structure

2024-11-28T13:34:17+01:00

Includes

  * index pages for the tutorials and how-tos sections
  * adding a "man page" section in the global navigation block
  * dropping the rendundant "tutorial" in the tutorial titles
</pre>