Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

forgot to truncate __doc__ to first line when extracting command help text #552

Closed
sebleblanc opened this issue Apr 23, 2019 · 5 comments

Comments

Projects
None yet
3 participants
@sebleblanc
Copy link

commented Apr 23, 2019

Displaying the --help option in the command line outputs excessively verbose text, including pydoc-formatted text:

% alembic --help                                                                                               ~/project/proj1/src
usage: alembic [-h] [-c CONFIG] [-n NAME] [-x X] [--raiseerr]
               {branches,current,downgrade,edit,heads,history,init,list_templates,merge,revision,show,stamp,upgrade}
               ...

positional arguments:
  {branches,current,downgrade,edit,heads,history,init,list_templates,merge,revision,show,stamp,upgrade}
    branches            Show current branch points. :param config: a
                        :class:`.Config` instance. :param verbose: output in
                        verbose mode.
    current             Display the current revision for a database. :param
                        config: a :class:`.Config` instance. :param verbose:
                        output in verbose mode. :param head_only: deprecated;
                        use ``verbose`` for additional output.
    downgrade           Revert to a previous version. :param config: a
                        :class:`.Config` instance. :param revision: string
                        revision target or range for --sql mode :param sql: if
                        True, use ``--sql`` mode :param tag: an arbitrary
                        "tag" that can be intercepted by custom ``env.py``
                        scripts via the
                        :meth:`.EnvironmentContext.get_tag_argument` method.
    edit                Edit revision script(s) using $EDITOR. :param config:
                        a :class:`.Config` instance. :param rev: target
                        revision.
    heads               Show current available heads in the script directory
                        :param config: a :class:`.Config` instance. :param
                        verbose: output in verbose mode. :param
                        resolve_dependencies: treat dependency version as down
                        revisions.
    history             List changeset scripts in chronological order. :param
                        config: a :class:`.Config` instance. :param rev_range:
                        string revision range :param verbose: output in
                        verbose mode. :param indicate_current: indicate
                        current revision. ..versionadded:: 0.9.9
    init                Initialize a new scripts directory. :param config: a
                        :class:`.Config` object. :param directory: string path
                        of the target directory :param template: string name
                        of the migration environment template to use.
    list_templates      List available templates :param config: a
                        :class:`.Config` object.
    merge               Merge two revisions together. Creates a new migration
                        file. .. versionadded:: 0.7.0 :param config: a
                        :class:`.Config` instance :param message: string
                        message to apply to the revision :param branch_label:
                        string label name to apply to the new revision :param
                        rev_id: hardcoded revision identifier instead of
                        generating a new one. .. seealso:: :ref:`branches`
    revision            Create a new revision file. :param config: a
                        :class:`.Config` object. :param message: string
                        message to apply to the revision; this is the ``-m``
                        option to ``alembic revision``. :param autogenerate:
                        whether or not to autogenerate the script from the
                        database; this is the ``--autogenerate`` option to
                        ``alembic revision``. :param sql: whether to dump the
                        script out as a SQL string; when specified, the script
                        is dumped to stdout. This is the ``--sql`` option to
                        ``alembic revision``. :param head: head revision to
                        build the new revision upon as a parent; this is the
                        ``--head`` option to ``alembic revision``. :param
                        splice: whether or not the new revision should be made
                        into a new head of its own; is required when the given
                        ``head`` is not itself a head. This is the
                        ``--splice`` option to ``alembic revision``. :param
                        branch_label: string label to apply to the branch;
                        this is the ``--branch-label`` option to ``alembic
                        revision``. :param version_path: string symbol
                        identifying a specific version path from the
                        configuration; this is the ``--version-path`` option
                        to ``alembic revision``. :param rev_id: optional
                        revision identifier to use instead of having one
                        generated; this is the ``--rev-id`` option to
                        ``alembic revision``. :param depends_on: optional list
                        of "depends on" identifiers; this is the ``--depends-
                        on`` option to ``alembic revision``. :param
                        process_revision_directives: this is a callable that
                        takes the same form as the callable described at :para
                        mref:`.EnvironmentContext.configure.process_revision_d
                        irectives`; will be applied to the structure generated
                        by the revision process where it can be altered
                        programmatically. Note that unlike all the other
                        parameters, this option is only available via
                        programmatic use of :func:`.command.revision` ..
                        versionadded:: 0.9.0
    show                Show the revision(s) denoted by the given symbol.
                        :param config: a :class:`.Config` instance. :param
                        revision: string revision target
    stamp               'stamp' the revision table with the given revision;
                        don't run any migrations. :param config: a
                        :class:`.Config` instance. :param revision: target
                        revision. :param sql: use ``--sql`` mode :param tag:
                        an arbitrary "tag" that can be intercepted by custom
                        ``env.py`` scripts via the
                        :class:`.EnvironmentContext.get_tag_argument` method.
    upgrade             Upgrade to a later version. :param config: a
                        :class:`.Config` instance. :param revision: string
                        revision target or range for --sql mode :param sql: if
                        True, use ``--sql`` mode :param tag: an arbitrary
                        "tag" that can be intercepted by custom ``env.py``
                        scripts via the
                        :meth:`.EnvironmentContext.get_tag_argument` method.

This is what I expected:

% alembic --help                                                                                               ~/project/proj1/src
usage: alembic [-h] [-c CONFIG] [-n NAME] [-x X] [--raiseerr]
               {branches,current,downgrade,edit,heads,history,init,list_templates,merge,revision,show,stamp,upgrade}
               ...

positional arguments:
  {branches,current,downgrade,edit,heads,history,init,list_templates,merge,revision,show,stamp,upgrade}
    branches            Show current branch points.
    current             Display the current revision for a database.
    downgrade           Revert to a previous version.
    edit                Edit revision script(s) using $EDITOR.
    heads               Show current available heads in the script directory.
    history             List changeset scripts in chronological order.
    init                Initialize a new scripts directory.
    list_templates      List available templates.
    merge               Merge two revisions together. Creates a new migration
                        file.
    revision            Create a new revision file.
    show                Show the revision(s) denoted by the given symbol.
    stamp               'stamp' the revision table with the given revision;
                        don't run any migrations.
    upgrade             Upgrade to a later version.

@sebleblanc

This comment has been minimized.

Copy link
Author

commented Apr 23, 2019

Also, the list of commands {branches,current,…} could be replaced with a placeholder COMMAND expanded below. There is no point really in having the same list of commands three times in the help text.

@zzzeek

This comment has been minimized.

Copy link
Member

commented Apr 23, 2019

hi there-

this bug quite simply appeared when I added complete docstrings to command.py in 364808a and failed to note that the string retrieval logic in https://github.com/sqlalchemy/alembic/blob/master/alembic/config.py#L489 needed to be adjusted to extract only the first line.

as far as COMMAND I don't immediately know what you mean but the behavior of --help is delivered from Python argparse, which we are using in a completely vanilla style with the exception of the inadvertent inclusion of docstring text.

@zzzeek zzzeek changed the title Command interface help text excessively long forgot to truncate __doc__ to first line when extracting command help text Apr 23, 2019

@zzzeek zzzeek added this to the fasttrack milestone Apr 23, 2019

@sqla-tester

This comment has been minimized.

Copy link
Collaborator

commented Apr 23, 2019

Mike Bayer has proposed a fix for this issue in the master branch:

Use first line of command docstring for help text. https://gerrit.sqlalchemy.org/1199

@sebleblanc

This comment has been minimized.

Copy link
Author

commented Apr 23, 2019

Woo, that's a fast fix!

What I mean by COMMAND is if you take for example git, it will show the following as help text:

% LANG=C git --help
usage: git [--version] [--help] [--a-bunch-more-options]
           <command> [<args>]

These are common Git commands used in various situations:

start a working area (see also: git help tutorial)
   clone      Clone a repository into a new directory
   init       Create an empty Git repository or reinitialize an existing one

work on the current change (see also: git help everyday)
   add        Add file contents to the index
   mv         Move or rename a file, a directory, or a symlink
   reset      Reset current HEAD to the specified state
   rm         Remove files from the working tree and from the index

That way, it lets the developer list commands by grouping them together and it minimizes redundancy.

@zzzeek

This comment has been minimized.

Copy link
Member

commented Apr 23, 2019

if there's a flag in argparse to do that I will review pull requests that illustrate what you'd like to see but that is separate from the main issue here about the docstrings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.