Closed MajorDallas closed 12 months ago
Thanks a lot for the detailed description. I understand the problem. I think that updating docs is the way to go here. We totally should mention them both here: https://returns.readthedocs.io/en/latest/pages/methods.html#cond and here: https://returns.readthedocs.io/en/latest/pages/pointfree.html#cond
I also think that we can change the docs to advertise from returns import pointfree; pointfree.cond(...)
and from returns import methods; methods.whatever(...)
style, because this is the most convenient way to do this.
Whould you like to contribute? :)
I can take a look at adding a line for each of those.
I am thinking simply adding a .. note::
that points to the other function and change the imports as you explained :)
Sorry for having opened the issue and then disappearing. Work got very crazy shortly after and I couldn't find the energy to come back to this.
I just looked at the docs. Looks good! Thank you for putting that together and getting it released.
Bug report
What's wrong
In the docs for
methods
andpointfree
, it's not immediately clear:cond
This first came to my attention while trying things out with
ipython
:All in all, that's not such a big deal by itself. I'm only using
import *
because I'm in a repl and would never do this in code. Still, because I hadn't read all of pointfree's docs, I had no idea I was importing anothercond
and was very surprised when my previously-working function was suddenly broken.How is that should be
My first thought was to rename the two functions:
methods.cond4
andpointfree.cond3
to reflect their different arg counts. I suppose that is an option, but any library user canimport cond as condx
if that's what they prefer.Instead, I think it would be enough that the docs for both functions at least mention the existence of the other and provide an example of how each interacts with a given context. Currently, both functions have decent examples, but since the two examples use completely different contexts one has to think hard about how the other function would change how the code must be written.
This experiment is what finally made it click for me how both can and should be used:
After this experiment, I can easily see why
pf_cond
is the better choice when usingflow
(orcompose
), but just seeingpf_cond
used withflow
in its example wasn't enough to help me understand why.System information
python
version: 3.11returns
version: 0.22.0mypy
version: 1.5.1