Development Utility Functions

igbpyutils.dev.check_script_vs_lib(path: str | PathLike, *, known_shebangs: Sequence[str] | Pattern = re.compile('\\A\\#\\!/usr(?:/local)?/bin/(?:env +)?python3?\\s*\\Z'), exec_from_git: bool = False) → ScriptLibResult[source]
class igbpyutils.dev.script_vs_lib.ResultLevel(value)[source]

A severity level enum for ScriptLibResult.

(Note the numeric values are mostly borrowed from logging.)

INFO = 20
NOTICE = 25
WARNING = 30
ERROR = 40
class igbpyutils.dev.script_vs_lib.ScriptLibFlags(value)[source]

Flags for ScriptLibResult.

Warning

Always use the named flags, do not rely on the integer flag values staying constant, as they are automatically generated.

EXEC_BIT = 1

Whether the file has its execute bit set

SHEBANG = 2

Whether the file has a shebang line

NAME_MAIN = 4

Whether the file contains if __name__=='__main__': ...

SCRIPT_LIKE = 8

Whether the file contains statements that make it look like a script (i.e. anything that’s not a def, class, etc.)

class igbpyutils.dev.script_vs_lib.ScriptLibResult(path: Path, level: ResultLevel, message: str, flags: ScriptLibFlags)[source]

Result class for check_script_vs_lib()

path: Path

The file that was analyzed

level: ResultLevel

The severity of the result, see ResultLevel

message: str

A textual description of the result, with details

flags: ScriptLibFlags

The individual results of the analysis, see ScriptLibFlags

igbpyutils.dev.script_vs_lib.check_script_vs_lib(path: str | PathLike, *, known_shebangs: Sequence[str] | Pattern = re.compile('\\A\\#\\!/usr(?:/local)?/bin/(?:env +)?python3?\\s*\\Z'), exec_from_git: bool = False) → ScriptLibResult[source]

This function analyzes a Python file to see whether it looks like a library or a script, and checks several features of the file for consistency.

It checks the following points, each of which on their own would indicate the file is a script, but in certain combinations don’t make sense. It checks whether the file…

  • has its execute bit set (ignored on Windows, unless exec_from_git is set)

  • has a shebang line (e.g. #!/usr/bin/env python3, see also the known_shebangs parameter)

  • contains a if __name__=='__main__': line

  • contains statements other than class, def, etc. in the main body

Parameters:

  • path – The name of the file to analyze.

  • known_shebangs – You may provide your own list of shebang lines that this function will recognize here, either as a list of strings (without trailing newlines) or a regular expression.

  • exec_from_git – If you set this to True, then instead of looking at the file’s actual mode bits to determine whether the exec bit is set, the function will ask git for the mode bits of the file and use those.

Returns:

A ScriptLibResult object that indicates what was found and whether there are any inconsistencies.

igbpyutils.dev.script_vs_lib.main() → None[source]

Command-line interface for check_script_vs_lib().

If the module and script have been installed correctly, you should be able to run py-check-script-vs-lib -h for help.