Skip to content

docstrings2pep727 ¤

docstrings2pep727 package.

Move documentation from docstrings to PEP 727 type annotations.

Functions:

  • get_parser –

    Return the CLI argument parser.

  • main –

    Run the main program.

get_parser ¤

get_parser() -> ArgumentParser

Return the CLI argument parser.

Returns:

Source code in src/docstrings2pep727/_internal/cli.py
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def get_parser() -> argparse.ArgumentParser:
    """Return the CLI argument parser.

    Returns:
        An argparse parser.
    """
    parser = argparse.ArgumentParser(
        prog="docstrings2pep727",
        description="Move docstring sections into Annotated type metadata.",
    )
    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {debug._get_version()}")
    parser.add_argument("--debug-info", action=_DebugInfo, help="Print debug information.")
    subparsers = parser.add_subparsers(dest="command", required=True, title="subcommands")
    for command, description in (
        ("check", "Report files that would change without writing them. Exit with status 1 if changes are needed."),
        ("diff", "Print a unified diff without writing files."),
        ("format", "Transform Python files in place."),
    ):
        subparser = subparsers.add_parser(command, help=description, description=description)
        subparser.add_argument(
            "paths",
            nargs="+",
            type=Path,
            metavar="PATH",
            help="Python files or directories to process.",
        )
        subparser.add_argument(
            "--style",
            choices=("auto", "google", "numpy", "sphinx"),
            default="auto",
            help="Docstring style (default: auto).",
        )
    return parser

main ¤

main(args: list[str] | None = None) -> int

Run the main program.

This function is executed when you type docstrings2pep727 or python -m docstrings2pep727.

Parameters:

  • args ¤

    (list[str] | None, default: None ) –

    Arguments passed from the command line.

Returns:

  • int –

    An exit code.

Source code in src/docstrings2pep727/_internal/cli.py
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
def main(args: list[str] | None = None) -> int:
    """Run the main program.

    This function is executed when you type `docstrings2pep727` or `python -m docstrings2pep727`.

    Parameters:
        args: Arguments passed from the command line.

    Returns:
        An exit code.
    """
    parser = get_parser()
    opts = parser.parse_args(args=args)
    try:
        files = _python_files(opts.paths)
    except (OSError, ValueError) as error:
        print(f"docstrings2pep727: {error}", file=sys.stderr)
        return 2

    changed = False
    failed = False
    for path in files:
        try:
            source, encoding = _read_source(path)
            transformed = _transform_source(source, style=opts.style)
            if transformed == source:
                continue
            changed = True
            if opts.command == "diff":
                print(
                    "".join(
                        difflib.unified_diff(
                            source.splitlines(keepends=True),
                            transformed.splitlines(keepends=True),
                            fromfile=str(path),
                            tofile=str(path),
                        ),
                    ),
                    end="",
                )
            elif opts.command == "check":
                print(f"Would transform {path}")
            else:
                path.write_bytes(transformed.encode(encoding))
                print(f"Transformed {path}")
        except (OSError, UnicodeError, SyntaxError, ValueError, cst.ParserSyntaxError) as error:
            print(f"docstrings2pep727: {path}: {error}", file=sys.stderr)
            failed = True
    if failed:
        return 2
    return 1 if changed and opts.command == "check" else 0