[Share Code] File Template to automatically add an header comment block

lukaskollmer

Following up on my previous post from 2 months ago, I wrote a script to automatically add a header comment to new files.

The header contains some basic information about the file and looks like this:

'''
Pythonista template to include some basic information in a header comment

You need to save this file to '~/Documents/Templates', so that Pythonista can find and list it in the "New File" dialog
'''

__author__ = 'Lukas Kollmer'
__copyright__ = 'Copyright (c) 2016 Lukas Kollmer<lukas@kollmer.me>'

You can get the script here from my pythonista-scripts repo.

Setup

Download the script
Save it to the Templates folder

Usage

Create new files by selecting the "New Script with info header" option in the "New File" dialog
After entering a file name, Pythonista will open the file in the editor
Now, you just need to run the new file you just created

How it works
When you run the new file, it'll ask you for some information that will be used for the header comment. Then, the script will replace itself with just the new header comment

What info goes where
You're prompted for author_name, description and documentation

This is how the template will be populated:

'''
${description}

${documentation}
'''

__author__ = '${author_name}'
__copyright__ = 'Copyright (c) ${year} ${author_name}'
'''

omz

That's a very clever idea, I like it! 👍

cook

is this something I should usually include in my code? (like...as a standard?)

Webmaster4o

This is a really neat idea. You should make more of these 😛

lukaskollmer

@cook I don't know if that's a standard, I got the format from this SO question. I just think it's helpful to embed some information about the module in the file.

Also, that's compatible with the built in help() function.
So if your module contains this comment like

'''
Show a PDF on an external display

This Script uses the UIScreen API to show a PDF on an external display (useful for presentations)
'''

and you call help(PresentationPad), you'll get this nice summary:

Help on module PresentationPad:

NAME
    PresentationPad - Show a PDF on an external display

DESCRIPTION
    This Script uses the UIScreen API to show a PDF on an external display

which is really neat

ccc

See the pull request for more fields from that same SO question.

cook

@lukaskollmer okay thanks. This looks like something I might add a bit later into the game. I guess because I'm not great at coding yet that I often just experiment... Maybe I will just use the same stuff but to prepend it to the current file. (Which...maybe that can be an addition to your script... to use it from the wrench menu for scripts that don't have it yet.)

Phuket2

@lukaskollmer , thanks for sharing. I like the clean way which you wrote it. To be honest, I don't use the templates anymore. I absolutely love the snippets. It would be great if snippets had this template substitution facility.
But it would be nice if you could add your template to the wrench menu also (the same file) and you had a wrapper so that when you are being called from the wrench menu, you do the same except just copy the results to the clipboard. Meaning it works in with the snippet concept.
I think it's a great idea. I would love to see everyone use this or equivalent. I hate it when I search though all my scripts, find some code I want to use and have no idea who wrote it. If I take bits and pieces from others code I like to acknowledge that I have done so and give credit to them. Even if it's just there Pythonista Forum handle.
It would also be great as the field list grows if you could write the static fields to file and retrieve them. Like, Author, email, user name etc... I realise you can go in add the constants to the template, but with a data file (simple JSON file for example) you could upgrade your template without people losing the information they have already typed in.

My 2 cents worth for today 😁

filippocld

@lukaskollmer Made a pull request to store the most recent Author's name in a keychain (it will usually be the same)

https://github.com/lukaskollmer/pythonista-scripts/pull/10

P.s. Why do you store these scripts in a repo instead of having them as separate gists?

ccc

Why do you store these scripts in a repo instead of having them as separate gists?

(fixed:) If @lukaskollmer had selected a gist instead a repo then you and I could not have submitted pull requests. See: https://github.com/omz/Pythonista-Issues/issues/98

filippocld

Oh, ok i didn't remember

dgelessus

@ccc said:

If @lukaskollmer had selected a repo over a gist then you and I could not have submitted pull requests.

I think you might have inverted some part of your sentence. If he had used a gist, you wouldn't be able to make PRs, not the other way around.

ccc

I fixed it above. It just goes to show that many eyes make all bugs small.

coomlata1

Added this script to my GitHub repository. It extends the capabilities of the @lukaskollmer script and provides support for editing existing code header comments in scripts. Suggestions and improvements are always welcome.