Recent commits to derivepassphrase.git (320cc9a7f1ff7097b812adcf9c76d6a0ebb48dfe)

Add changelog entries for Buffer support and documentation fix

2024-09-30T15:18:00+02:00

</pre>

Fix bad documentation for SSHAgentClient.request return value

2024-09-30T15:03:05+02:00

</pre>

Add proper support for Buffer types in the SSH agent client

2024-09-30T14:35:47+02:00

As of Python 3.12, any custom Python class can declare support for the
buffer protocol.  So instead of special-casing `bytes` and `bytearray`,
and ignoring all other types, support arbitrary classes with buffer
protocol support.  Furthermore, explicitly return bytes objects (i.e.,
read-only copies) of all involved byte strings, because the buffer
protocol ensures that copies are relatively cheap.
</pre>

Add explicit example in hypothesis test, for test coverage

2024-09-30T10:40:45+02:00

The test coverage otherwise gets flaky.
</pre>

Overhaul the validation function for vault(1) configurations

2024-09-30T10:25:58+02:00

Rewrite `derivepassphrase._types.is_vault_config` into a proper,
validation function `validate_vault_config` that throws errors, and
optionally disallows extension or unknown settings.  The old
`is_vault_config` function is then implemented in terms of the new
function.

Use this opportunity to change the return annotation to
`typing_extensions.TypeIs`, because that is what was semantically
intended anyway.

Naturally, throwing actual errors instead of returning `False` means
that the error handling gets bulkier and more fine-grained.  Which in
turn means that extra tests are necessary to stay at high test coverage
levels.
</pre>

Merge topic branch 'documentation-fixes' into master

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

* t/documentation-fixes:
  Add changelog entry for recent documentation fixes
  Generate nicer documentation via `scoped_crossrefs`
  Convert old syntax for Yields annotations to new syntax
  Enable cross-references on function signatures in documentation
  Fix bad docstring reference to Python standard library
  Rename reference documentation pages as per the Python standard library convention
  Update all URLs to stable and "less legally risky" versions, if possible
  Demonstrate config storing and SSH agent use in README
  Include explanation for virtual environments and package extras in README
  Fix miscellaneous small docstring issues
</pre>

Add changelog entry for recent documentation fixes

2024-09-29T23:57:51+02:00

</pre>

Generate nicer documentation via `scoped_crossrefs`

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

Now that (some) versions of `mkdocstrings-python` have support for
[scoped crossreferences] [SCOPED], references to documented objects can
be named like they would be in code.  This leads to (Markdown)
docstrings that are much more readable in source form than when having
to type or re-type the fully qualified identifier name.

[SCOPED]: https://github.com/mkdocstrings/python/issues/166
</pre>

Convert old syntax for Yields annotations to new syntax

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

[Griffe now handles non-multiple yields and returns similarly.] [YIELDS]
There is thus no need for an empty argument name and type annotation.

[YIELDS]: https://github.com/mkdocstrings/griffe/issues/263
</pre>

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>