Re: “Literate” python?

[Diego Zamboni <diego@zzamboni.org>]

[-- Attachment #1: Type: text/plain, Size: 4617 bytes --]

Hi Norm,

As George said, the trick in this case is to use the =:noweb= and
=:noweb-ref= headers. The change is minimal from the script you sent:

#+TITLE: Python literate programming
#+OPTIONS: html-postamble:nil

It starts off as a completely standard Python3 program.

#+BEGIN_SRC python :tangle yes :weave no
#!/usr/bin/env python3
#+END_SRC

It defines ~a~.

#+BEGIN_SRC python :tangle yes
def a():
    print("a")

#+END_SRC

And ~b~.

#+BEGIN_SRC python :tangle yes
def b():
    print("b")

#+END_SRC

Now ~c~ is a little more complicated:

#+BEGIN_SRC python :tangle yes :noweb no-export
def c():
   print("c")
   <<call-a-and-b>>
#+END_SRC

Not only does ~c~ print “c”, it calls ~a()~ and ~b()~.

#+BEGIN_SRC python :tangle no :noweb-ref call-a-and-b
   b()
   a()
#+END_SRC

Finally, make it importable. Not that you’d want to.

#+BEGIN_SRC python :tangle yes
if __name__ == "__main__":
    main()
#+END_SRC

Note the =:noweb no-export= in the block that contains =def c()=. The
=no-export= value makes it so that, on HTML export, the noweb reference is
shown as a reference instead of expanded (which is usually what you want).
The next block is given its name using the =:noweb-ref= header argument.
You could also use =#+name:= - the main difference is that =:noweb-ref=
allows you to have multiple blocks with the same name, which are
concatenated together when tangled, whereas =#+name:= only allows one block
with the same name.

If I may do a bit of self-promotion, feel free to check out my "Literate
Config" booklet, which I published just a few days ago (available for free)
and which contains some more tips for doing literate programming:
https://leanpub.com/lit-config/read

Best,
--Diego


On Fri, Nov 29, 2019 at 7:09 PM Norman Walsh <ndw@nwalsh.com> wrote:

> Hi,
>
> I’ve seen a couple of pointers recently to using Org mode and tangle
> to write more literate Emacs configurations. I use Org+babel all the
> time to write “interactive” documents, so I thought I’d try out tangle
> from Org.
>
> I didn’t want to start with something as comlicated as my Emacs
> config :-) so I figured I’d kick the tires with a small python
> program. That did not end well.
>
> Consider:
>
> #+TITLE: Python literate programming
> #+OPTIONS: html-postamble:nil
>
> It starts off as a completely standard Python3 program.
>
> ---%<------------------------------------------------------
> #+BEGIN_SRC python :tangle yes :weave no
> #!/usr/bin/env python3
>
> #+END_SRC
>
> It defines ~a~.
>
> #+BEGIN_SRC python :tangle yes
> def a():
>     print("a")
>
>
> #+END_SRC
>
> And ~b~.
>
> #+BEGIN_SRC python :tangle yes
> def b():
>     print("b")
>
>
> #+END_SRC
>
> Now ~c~ is a little more complicated:
>
> #+BEGIN_SRC python :tangle yes
> def c():
>    print("c")
> #+END_SRC
>
> Not only does ~c~ print “c”, it calls ~a()~ and ~b()~.
>
> #+BEGIN_SRC python :tangle yes
>    b()
>    a()
> #+END_SRC
>
> Finally, make it importable. Not that you’d want to.
>
> #+BEGIN_SRC python :tangle yes
> if __name__ == "__main__":
>     main()
> #+END_SRC
> --->%------------------------------------------------------
>
> That’s the script. It weaves into HTML more-or-less ok (there’s a
> weird black box at the front of indented lines, but I can come back to
> that later).
>
> It’s a complete mess when tangled.
>
> The extra blank lines between functions (to make pylint happy with
> some PEP guideline) have disappeared. I guess I could live with that,
> but the complete failure to preserve indention in the penultimate code
> block is a show stopper:
>
> #!/usr/bin/env python3
>
> def a():
>     print("a")
>
> def b():
>     print("b")
>
> def c():
>    print("c")
>
> b()
> a()
>
> if __name__ == "__main__":
>     main()
>
> (Also, why is there an extra blank line before the incorrectly
> indented block?)
>
> Is this user error on my part somehow? I suppose I could write my own
> version of tangle, though I’m not clear if the whitespace is lost in
> the tangle function or in the Org mode data model.
>
> Thoughts?
>
>                                         Be seeing you,
>                                           norm
>
> --
> Norman Walsh <ndw@nwalsh.com> | We discover in ourselves what others
> http://nwalsh.com/            | hide from us, and we recognize in
>                               | others what we hide from
>                               | ourselves.--Vauvenargues
>

[-- Attachment #2: Type: text/html, Size: 5787 bytes --]