PyCQA / PyCQA/isort

Add some documentation about how isort moves comments.

Open
#1,843 2 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
Python
Stars
7k
Forks
687
Avg merge
4h 56m
Merged PRs (30d)
2

Description

It appears that:

  1. comments before an import line (with no intervening blank line) will be sorted with that import
  2. comments on their own line within an multiline import statement are moved to the opening line of that import (at least for multi_line_mode = 3)
  3. trailing comments on an import item (in multi_line_mode = 3) are floated to a new single import of that item
  4. If there are multiple import lines from the same module (for example due point 3 above), comments before any of them are floated to be above the first one.

I spent some time trying to figure out this behavior, or see if there was some way to configure it.

In particular, I was looking to see if there was a way to change some the behavior. A few of things I was looking for
a. the ability to have a comment on a multiline import be on the line following the from module import ( line, rather than on it
b. the ability to have a comment on the line before an import item in a multiline import sort with that import.
c. the ability to have import items with trailing comments kept in the original multiline import, rather than floated to the top.

I realize that a comment before the first import item would have an ambiguous interpretation if both (a) and (b) were supported. These occurred to me at different times looking at specific places where I had comments, and trying to figure out a way to have comments near the appropriate thing in each case. If I had known about (1) and (3), I probably would have spent less time trying to find a way to do (a) or (b) (though (c) would still be useful, I think).

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue names no documentation file or test. Start from its four observed comment-handling cases, especially the multi_line_mode = 3 examples, and document the behavior and the configuration limitations it describes. Done means users can understand how comments move and which requested alternatives are unavailable.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, tooling
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.