Let me try to explain why it is that way: First, it's consistent with Python functions. The docstring for functions is below the signature as well. Second, consider a file with only a docstring and then a variable declaration. Here it would be ambiguous if that's the module or the variable docstring. Finally, this behavior is consistent with other tools (and failed standardization efforts) in the space. So yeah - I share your sentiment, but I think it's the most pragmatic approach for pdoc. :)
Maybe it is me, but I find that idea unhinged and aesthetically/semantically offputting to a degree you would have to force me to do it. I know that isn't rational, but hey, it is my personal taste and those may differ.
I much prefer the way Rust did it, so just a separate type of comment-prefix for docstrings. In Rust a regular comment may be
// this is a comment
foo = 1.5;
while a docstring is simply
/// this shows up in docs
foo = 1.5;
with //! for docstrings at a module level. This is elegant. This is simple. It is a pythonic solution. Treating comments below a variable declaration implicity as a docstring is not. At the beginning of class or function declarations, ok (although I also would have prefered that to be above the declaration), but this.. I need a drink.
FWIW I agree that the Rust way is nicer, but I can't impose the Rust way on Python. I guess the secret hack is to use PyO3, which pdoc supports quite well. ;)
not sure if this is a typo or a misunderstanding, but to be clear: pdoc does not treat a comment immediately below a variable declaration as a docstring, it treats an unassigned string immediately following a variable declaration as a docstring, same as how python treats an unassigned string literal immediately following a function signature as a docstring
my_var = 5
"documentation for my_var"
def my_func():
"documentation for my_func"
also worth noting, pdoc didn't invent this design pattern, sphinx did (or perhaps something preceding sphinx?)
and since sphinx is the documentation tool of choice by the python core devs to document python itself, i have to assume they've given this design pattern at least tacit approval... :shrug:
There's a workaround for this case (relevant issue has a link at the top), which is cool, but it uses an "internal" function to solve it, which is not.
I'd say neither fork as made great strides since then, but I'm also biased here as the maintainer of pdoc.
There is no pdoc-specific library for link checking as far as I'm aware. It's all plain HTML though, so you can use a more general tool like https://lychee.cli.rs/. :)
Congrats on the seccomp-based interception, that's a really neat way to solve this problem! We did some BPF_PROG_TYPE_CGROUP_SOCK eBPF shenanigans in mitmproxy for redirection, but that doesn't work with containers at all. Cool to see that intercepting all relevant syscalls works that well.
This is really cool, thank you for sharing! We've built a similar feature for mitmproxy lately, but with different tradeoffs. Our approach does require root and we don't have automated certificate install (yet), but we don't require apps to run in a dedicated namespace (so you can capture already-running processes). Super awesome to see this now, excited to dive into the code and see how you do TCP reassembly etc. :)
Fully reproducible builds would of course be nicer from a security standpoint, but attestations have vastly lower implementation costs and scale much better while still raising the bar meaningfully.
One of the main promises of HTTP/3 is better performance under worse network conditions (e.g. no head-of-line blocking as in HTTP/2, connection migration, 0-RTT). For all of that HTTP/3 between client and proxy is really great. HTTP/3 between proxy and server is not required for that.
Thank you for your work on Hickory! It's super exciting to see how PyO3's Python <-> Rust interop enables us to use a production-grade DNS library with Hickory and also a really solid user-space networking stack with smoltcp. These things wouldn't be available in Python otherwise.
