Docs: Hy <-> Python interop fix #1061

[ghost]

I separated the existing text in two sections, with some additional explanations and a link to Hy's import.

[Kodiologist]

You can also compile your module with hyc. Then you can import it directly (Hy still has to be installed)

This isn't always true. If you edit the example greetings module by renaming the parameter name to addressee, then the resulting greetings.pyc no longer requires Hy. Using name makes Hy add from hy.core.language import name at the top of the file because name happens to be the name of a builtin. (Is this a bug or an unavoidable limitation of Hy? It's not obvious to me.)

More generally, I think that fulfilling #1061 calls for adding discussion of lots of gory details. Your additions here don't suffice. @gilch filed that issue, so maybe he can chime in.

It looks like this is your first pull request. Please don't be scared away by how I've received it; we do need more contributors, to both the code and the documentation. Thanks for pitching in.

[ghost]

First PR indeed, not scared away 😬

More generally, I think that fulfilling #1061 calls for adding discussion of lots of gory details. Your additions here don't suffice.

In that case, maybe this should be completely moved away from the tutorial, which would still contain general interop instructions without the “gory details”.

What I have understood so far is that if anywhere in the code, the name of a Hy builtin is found, it is imported.
For example :

(def second 42)

triggers

from hy.core.language import second

[Kodiologist]

In that case, maybe this should be completely moved away from the tutorial, which would still contain general interop instructions without the "gory details".

Yeah, that makes sense to me. We've generally agreed that the tutorial should be fairly short so it isn't too intimidating.

What I have understood so far is that if anywhere in the code, the name of a Hy builtin is found, it is imported.

I think that's how it works, yeah. I've never read the part of the codebase that does this.

[Kodiologist]

This is really nice. Thanks! You even nailed the dorky, humorous tone of the preexisting text.

I have a few requests:

• The section on mangling is incomplete (e.g., there's no mention of ?), but a complete discussion of mangling should probably be in a different part of the documentation anyway, since mangling can surprise you if you aren't trying to do Python interop (e.g., hy -c '(setv *a* 1) (print (in "*a*" (globals)))' prints False). I'd suggest documenting mangling in a separate PR.
• "Even if you do not use a Hy symbol, but just the same name": In the above example, name is still a Hy symbol. What's weird about it is that it will resolve to a local variable instead of the Hy builtin named name. So you could instead write "Even if you do not use a Hy builtin, but just another variable with the name of a Hy builtin".
• You can remove the bit about keyword arguments, which looks like a non-sequitor. I think the only reason it was present originally was that Hy used to lack direct syntax for keyword arguments, so you'd have to use apply.
• Write "See?" rather than "See ?". In English, we never put a space before a question mark or exclamation point.
• Write "Suppose you have written…" rather than "You have written…".
• On line 52, you have a stray trailing pair of colons.
• The sequence : :: can be written as just ::. (You should read up on reStructuredText if you haven't already.)

[Kodiologist]

Oh, and don't forget to add yourself to AUTHORS.

[Kodiologist]

I'd suggest documenting mangling in a separate PR.

Although, you may not want to do this now since mangling may change soon (#1173, #1115), anyway.

[ghost]

Thank you for those words! (tssst, I wanted to put a space before my exclamation mark. It’s hard being French when writing in English)
I’ll make the corrections quickly.

I'd suggest documenting mangling in a separate PR.

Shouldn’t mangling still be mentioned in this section? Maybe a link would suffice.

[Kodiologist]

Yeah, a link would make sense.