I was inspired by@takluyver's graciousness in his responses to#664 to report my new user experience with Flit.

Background: I have considerable (hobbyist) experiencecoding (scripting) in Python (almost ten years of Advent of Code!), but none at all inpackaging Python code. Upon seeing Flit included in thetool recommendations of the Python Packaging documentation ("minimal and opinionated" sounded about right to me in this context), I decided to give it a whirl, only to encounter a seemingly bizarre error: Flit was apparently trying to run my script under its own name (and terminating abnormally since the script wasn't being provided its proper arguments).

After a bunch more reading, I concluded that Flit's build process includes the importing of the provided modules, and that Flit (like most Python packaging tools?) apparently expects its provided modules' code to be esconced inside functions (with the possible inclusion of anif __name__ == "__main__:" clause), and thus importing the modules shouldn't actually run the code. But I humbly suggest that this may not be quite so obvious to those new to Python packaging, and perhaps Flit should explain more clearly just what sort of code structure it expects provided modules to have. (I did read the"Scripts section" section, but even this leaves unstated the basic requirement that executable code be esconced within functions. Alternatively, if I've badly misunderstood what's going on here, I'll be happy to be set straight.)

Thank you for this tool, and I hope to successfully package my first Python project with it soon!