FilesExpand file tree

main

/

check_docstring_first.py

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

61 lines (49 loc) · 1.88 KB

main

/

check_docstring_first.py

Copy path

Top

File metadata and controls

• Code
• Blame

61 lines (49 loc) · 1.88 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

from __future__ import annotations

import argparse

import io

import tokenize

from tokenize import tokenize as tokenize_tokenize

from typing import Sequence

NON_CODE_TOKENS = frozenset((

tokenize.COMMENT, tokenize.ENDMARKER, tokenize.NEWLINE, tokenize.NL,

tokenize.ENCODING,

))

def check_docstring_first(src: bytes, filename: str = '<unknown>') -> int:

"""Returns nonzero if the source has what looks like a docstring that is

not at the beginning of the source.

A string will be considered a docstring if it is a STRING token with a

col offset of 0.

"""

found_docstring_line = None

found_code_line = None

tok_gen = tokenize_tokenize(io.BytesIO(src).readline)

for tok_type, _, (sline, scol), _, _ in tok_gen:

# Looks like a docstring!

if tok_type == tokenize.STRING and scol == 0:

if found_docstring_line is not None:

print(

f'{filename}:{sline}: Multiple module docstrings '

f'(first docstring on line {found_docstring_line}).',

)

return 1

elif found_code_line is not None:

print(

f'{filename}:{sline}: Module docstring appears after code '

f'(code seen on line {found_code_line}).',

)

return 1

else:

found_docstring_line = sline

elif tok_type not in NON_CODE_TOKENS and found_code_line is None:

found_code_line = sline

return 0

def main(argv: Sequence[str] | None = None) -> int:

parser = argparse.ArgumentParser()

parser.add_argument('filenames', nargs='*')

args = parser.parse_args(argv)

retv = 0

for filename in args.filenames:

with open(filename, 'rb') as f:

contents = f.read()

retv |= check_docstring_first(contents, filename=filename)

return retv