align-comments pads the gap before each trailing comment in a run so every # sits at one shared column, and the notes then read straight down beside the code they describe. Without it a trailing comment starts wherever its line of code stops, so a block of annotated lines opens its notes at a different offset on every row even after the assignments beside them share a column, and the eye tracks two ragged edges instead of one.
The rule reads the trailing comments in source order and extends a run while each next comment sits on the line directly below the last. A line with no trailing comment, a blank line, and an own-line comment each end the run, and a run whose rows sit at differing indents gets no column at all, since a shared column would sit where neither row's code ends. The shared column sits two spaces past the widest row in the run, the gap normalize-comment-spacing sets, which keeps every aligned row at or above the PEP 8 minimum.
attempts, threshold, and window each carry a trailing comment, and each comment starts wherever its own code ends. Every # in the run moves to the column two spaces past the widest line, threshold = 200, so the annotations read down one edge the way the assignments beside them already do.
attempts = 1 # retries before the backoff widensthreshold = 200 # rows per flushwindow = 30 # seconds
python
A row that reaches no shared column takes the two-space minimum instead, which is how a hand-set gap lining up with nothing settles. That covers a lone trailing comment, since a run of one has no column to share, and it covers a row that leaves its run. Two limits split a row out of a run, the max-shift limit every alignment rule carries and the code-line-lengthbudget, where a row whose aligned line would cross the budget stays where it sits rather than creating an overflow for line-overflow to report.
The RETRY_DELAYS list holds one entry per line, and 1, 30, and 3600 differ in width, so each trailing comment starts at a different column. The three comments move to one column two spaces past 3600, because the entries sit at one indent on consecutive lines and so form one run, leaving the notes reading as a second column beside the values.
RETRY_DELAYS = [ 1, # immediate 30, # after the first failure 3600 # hourly from here on]
python
The column resolves to two spaces past the widest row whether that moves a comment right or left, so a run whose notes already line up at a wider gutter tightens onto that same column. The alignment the author drew survives, with the slack past it removed the way strip-stranded-padding removes padding that lines up with nothing.
The three DECODING_TABLE entries carry a wide hand-set gutter that already lines their comments up in one column. The gutter closes as a block to two spaces past the widest row, because the shared column resolves at that offset whatever gap the input carries, so the alignment the author wrote survives at the tighter column.
DECODING_TABLE = { 0x0080 : 0x00C7, # LATIN CAPITAL LETTER C WITH CEDILLA 0x0081 : 0x00FC, # LATIN SMALL LETTER U WITH DIAERESIS 0x0082 : 0x00E9 # LATIN SMALL LETTER E WITH ACUTE}
python
warm_the_cache_now(), reconcile_open_charges(), and flush_writes() each carry a trailing comment, and the comment on flush_writes() is long. The first two rows align on one column and flush_writes() keeps its two-space minimum, because padding it out to the shared column would push its line past code-line-length, and the rule never creates an overflowing line.
warm_the_cache_now() # cheapreconcile_open_charges() # slowflush_writes() # padding this one out to the shared column would cross the budget
python
A # prose: skip on a row keeps it out of the column math without ending the run, so the rows above and below it reach across it and align together. The directive is itself a trailing comment, which is what lets one annotation both name the exception and carry it.
How far apart the widest and narrowest rows of a run may be for the run to still align on one column. A positive N caps that gap, 0 forbids any padding so every row sits flush, and false lifts the cap so a run of any width aligns on one column. A row marked # prose: skip stays out of its group.
max-shift limits how much padding one comment may take to reach the shared column. The rule reads each run in source order and extends a column while the gap between the widest and narrowest rows stays within the limit, starting a new column at the first row that would exceed it. Setting max-shift to false removes the limit, so a run of any width aligns on one column, and 0 forbids padding altogether, leaving every trailing comment at the two-space minimum. The per-rule facets reference covers the full semantics.
attempts, threshold, and window each carry a trailing comment, and each comment starts wherever its own code ends. Every # in the run moves to the column two spaces past the widest line, threshold = 200, so the annotations read down one edge the way the assignments beside them already do.
attempts = 1 # retries before the backoff widensthreshold = 200 # rows per flushwindow = 30 # seconds
seed(), flush_all(), and warm_now() carry comments padded by hand to one column, and the case runs with max-shift = 0. Every hand-set gap closes to the two spaces PEP 8 prescribes, because 0 forbids padding altogether, so no comment moves to meet another and each row stands alone.
seed() and reconcile_every_pending_shipment_record() each carry a trailing comment, and the case runs with max-shift = false. The # after seed() moves all the way out to the columnreconcile_every_pending_shipment_record() sets, rather than falling back to the two-space minimum, because false removes the limit on how much padding one row may take, so a run the default limit would split aligns on one column.
foo() carries a bare # with no text after it, and barbaz() below it carries # note. The bare # moves to the same column as # note, because the rule measures only the code before each # and never reads what follows the hash, so a bare # joins the run like any other trailing comment.
Two annotated calls sit above a blank line and two more sit below it. The blank line ends the run, so warm_the_cache() and seed() share one comment column and flush() and compact_the_index() share another. Each column is measured from the rows it spans alone, so the wider second pair pushes only its own # further right.
flush() carries the only trailing comment in the module, written with a wide gap before its #. The gap closes to two spaces, because one annotated line is not a run and so has no shared column, the same spacing a row takes when it leaves a run.
warm_the_cache_now(), reconcile_open_charges(), and flush_writes() each carry a trailing comment, and the comment on flush_writes() is long. The first two rows align on one column and flush_writes() keeps its two-space minimum, because padding it out to the shared column would push its line past code-line-length, and the rule never creates an overflowing line.
compact_the_index() carries a # prose: skip[align-comments] directive between the annotated seed() and flush(). seed() and flush() align on one column measured from their own widths alone, because the skipped row neither moves nor ends the run, so its comment stays where it was written and the rows on either side of it bridge across.
seed() and reconcile_every_pending_shipment_record() each carry a trailing comment, and the one after seed() is padded by hand to line up with the other. The hand-set gap after seed() closes to two spaces, because the two rows differ in width by more than max-shift allows, so neither reaches the other's column and each stands alone at the two-space minimum.
The three DECODING_TABLE entries carry a wide hand-set gutter that already lines their comments up in one column. The gutter closes as a block to two spaces past the widest row, because the shared column resolves at that offset whatever gap the input carries, so the alignment the author wrote survives at the tighter column.
counter = 1 carries a #: Sphinx attribute doc and n = 20 carries a # type: ignore pragma, two openers normalize-comment-spacing leaves as written. Both comments still align on one shared column, because that exemption covers what a comment opens with rather than where it sits.
An own-line comment sits between seed() and flush() in a stretch of four annotated calls. The own-line comment ends the run above it and never joins a column, so warm_the_cache() and seed() align on one column, flush() and compact_the_index() align on another, and the comment stays flush at the indent it was written on.
The RETRY_DELAYS list holds one entry per line, and 1, 30, and 3600 differ in width, so each trailing comment starts at a different column. The three comments move to one column two spaces past 3600, because the entries sit at one indent on consecutive lines and so form one run, leaving the notes reading as a second column beside the values.
BeforeAfter
No Change
seed() and flush() form a run whose two # already sit on the column the widest row sets. The rule emits no edit, because every row's target column matches the one it already occupies, and the rule never reports a fix that would change no bytes.
BeforeAfter
No Change
flush() sits indented inside the if ready: branch and compact_the_index() sits at module level, each with a trailing comment. Neither comment moves, because the two rows open at different indents and so never form one run, leaving both the two-space gap they already carry.
retries, timeout_seconds, and window are annotated assignments with trailing comments, and three alignment rules pad the same rows, each checking its own padding against the 72-column budget. Every rule measures the row's settled form rather than the intermediate text the rule before it left, which is what lets the :, the =, and the # all reach their columns with the widest row, retries, still inside the budget.
Puts one space after a comment's hash run and at least two spaces between code and a trailing comment.
🪜
align-equals
Alignment
Pads the space before = so consecutive assignments, annotated parameter defaults, and an exploded call's keyword arguments share one column.
🪜
align-colons
Alignment
Pads the space before : so consecutive dict entries, annotated assignments, signature annotations, and docstring entries share one column, with a docstring entry's parenthesized type in a column of its own.
🧶
line-overflow
Lint
Reports a line still over its line budget once no layout rule can shorten it.
🪜
strip-stranded-padding
Alignment
Removes padding that lines up with nothing, before the : of a one-member group and just inside a bracket, and settles the gap after a : to one space.
align-comments
align-comments pads the gap before each trailing comment in a run so every
#sits at one shared column, and the notes then read straight down beside the code they describe. Without it a trailing comment starts wherever its line of code stops, so a block of annotated lines opens its notes at a different offset on every row even after the assignments beside them share a column, and the eye tracks two ragged edges instead of one.The rule reads the trailing comments in source order and extends a run while each next comment sits on the line directly below the last. A line with no trailing comment, a blank line, and an own-line comment each end the run, and a run whose rows sit at differing indents gets no column at all, since a shared column would sit where neither row's code ends. The shared column sits two spaces past the widest row in the run, the gap normalize-comment-spacing sets, which keeps every aligned row at or above the PEP 8 minimum.
attempts,threshold, andwindoweach carry a trailing comment, and each comment starts wherever its own code ends. Every#in the run moves to the column two spaces past the widest line,threshold = 200, so the annotations read down one edge the way the assignments beside them already do.A row that reaches no shared column takes the two-space minimum instead, which is how a hand-set gap lining up with nothing settles. That covers a lone trailing comment, since a run of one has no column to share, and it covers a row that leaves its run. Two limits split a row out of a run, the
max-shiftlimit every alignment rule carries and thecode-line-lengthbudget, where a row whose aligned line would cross the budget stays where it sits rather than creating an overflow for line-overflow to report.The
RETRY_DELAYSlist holds one entry per line, and1,30, and3600differ in width, so each trailing comment starts at a different column. The three comments move to one column two spaces past3600, because the entries sit at one indent on consecutive lines and so form one run, leaving the notes reading as a second column beside the values.The column resolves to two spaces past the widest row whether that moves a comment right or left, so a run whose notes already line up at a wider gutter tightens onto that same column. The alignment the author drew survives, with the slack past it removed the way strip-stranded-padding removes padding that lines up with nothing.
The three
DECODING_TABLEentries carry a wide hand-set gutter that already lines their comments up in one column. The gutter closes as a block to two spaces past the widest row, because the shared column resolves at that offset whatever gap the input carries, so the alignment the author wrote survives at the tighter column.warm_the_cache_now(),reconcile_open_charges(), andflush_writes()each carry a trailing comment, and the comment onflush_writes()is long. The first two rows align on one column andflush_writes()keeps its two-space minimum, because padding it out to the shared column would push its line pastcode-line-length, and the rule never creates an overflowing line.A
# prose: skipon a row keeps it out of the column math without ending the run, so the rows above and below it reach across it and align together. The directive is itself a trailing comment, which is what lets one annotation both name the exception and carry it.Configuration
enabledtruemax-shift0|false16Ncaps that gap,0forbids any padding so every row sits flush, andfalselifts the cap so a run of any width aligns on one column. A row marked# prose: skipstays out of its group.max-shiftlimits how much padding one comment may take to reach the shared column. The rule reads each run in source order and extends a column while the gap between the widest and narrowest rows stays within the limit, starting a new column at the first row that would exceed it. Settingmax-shifttofalseremoves the limit, so a run of any width aligns on one column, and0forbids padding altogether, leaving every trailing comment at the two-space minimum. The per-rule facets reference covers the full semantics.The Canonical Case
attempts,threshold, andwindoweach carry a trailing comment, and each comment starts wherever its own code ends. Every#in the run moves to the column two spaces past the widest line,threshold = 200, so the annotations read down one edge the way the assignments beside them already do.More Examples
seed(),flush_all(), andwarm_now()carry comments padded by hand to one column, and the case runs withmax-shift = 0. Every hand-set gap closes to the two spaces PEP 8 prescribes, because0forbids padding altogether, so no comment moves to meet another and each row stands alone.seed()andreconcile_every_pending_shipment_record()each carry a trailing comment, and the case runs withmax-shift = false. The#afterseed()moves all the way out to the columnreconcile_every_pending_shipment_record()sets, rather than falling back to the two-space minimum, becausefalseremoves the limit on how much padding one row may take, so a run the default limit would split aligns on one column.foo()carries a bare#with no text after it, andbarbaz()below it carries# note. The bare#moves to the same column as# note, because the rule measures only the code before each#and never reads what follows the hash, so a bare#joins the run like any other trailing comment.Two annotated calls sit above a blank line and two more sit below it. The blank line ends the run, so
warm_the_cache()andseed()share one comment column andflush()andcompact_the_index()share another. Each column is measured from the rows it spans alone, so the wider second pair pushes only its own#further right.flush()carries the only trailing comment in the module, written with a wide gap before its#. The gap closes to two spaces, because one annotated line is not a run and so has no shared column, the same spacing a row takes when it leaves a run.warm_the_cache_now(),reconcile_open_charges(), andflush_writes()each carry a trailing comment, and the comment onflush_writes()is long. The first two rows align on one column andflush_writes()keeps its two-space minimum, because padding it out to the shared column would push its line pastcode-line-length, and the rule never creates an overflowing line.compact_the_index()carries a# prose: skip[align-comments]directive between the annotatedseed()andflush().seed()andflush()align on one column measured from their own widths alone, because the skipped row neither moves nor ends the run, so its comment stays where it was written and the rows on either side of it bridge across.seed()andreconcile_every_pending_shipment_record()each carry a trailing comment, and the one afterseed()is padded by hand to line up with the other. The hand-set gap afterseed()closes to two spaces, because the two rows differ in width by more thanmax-shiftallows, so neither reaches the other's column and each stands alone at the two-space minimum.The three
DECODING_TABLEentries carry a wide hand-set gutter that already lines their comments up in one column. The gutter closes as a block to two spaces past the widest row, because the shared column resolves at that offset whatever gap the input carries, so the alignment the author wrote survives at the tighter column.counter = 1carries a#:Sphinx attribute doc andn = 20carries a# type: ignorepragma, two openers normalize-comment-spacing leaves as written. Both comments still align on one shared column, because that exemption covers what a comment opens with rather than where it sits.An own-line comment sits between
seed()andflush()in a stretch of four annotated calls. The own-line comment ends the run above it and never joins a column, sowarm_the_cache()andseed()align on one column,flush()andcompact_the_index()align on another, and the comment stays flush at the indent it was written on.The
RETRY_DELAYSlist holds one entry per line, and1,30, and3600differ in width, so each trailing comment starts at a different column. The three comments move to one column two spaces past3600, because the entries sit at one indent on consecutive lines and so form one run, leaving the notes reading as a second column beside the values.seed()andflush()form a run whose two#already sit on the column the widest row sets. The rule emits no edit, because every row's target column matches the one it already occupies, and the rule never reports a fix that would change no bytes.flush()sits indented inside theif ready:branch andcompact_the_index()sits at module level, each with a trailing comment. Neither comment moves, because the two rows open at different indents and so never form one run, leaving both the two-space gap they already carry.retries,timeout_seconds, andwindoware annotated assignments with trailing comments, and three alignment rules pad the same rows, each checking its own padding against the 72-column budget. Every rule measures the row's settled form rather than the intermediate text the rule before it left, which is what lets the:, the=, and the#all reach their columns with the widest row,retries, still inside the budget.Related
normalize-comment-spacing
FormattingPuts one space after a comment's hash run and at least two spaces between code and a trailing comment.
align-equals
AlignmentPads the space before
=so consecutive assignments, annotated parameter defaults, and an exploded call's keyword arguments share one column.align-colons
AlignmentPads the space before
:so consecutive dict entries, annotated assignments, signature annotations, and docstring entries share one column, with a docstring entry's parenthesized type in a column of its own.line-overflow
LintReports a line still over its line budget once no layout rule can shorten it.
strip-stranded-padding
AlignmentRemoves padding that lines up with nothing, before the
:of a one-member group and just inside a bracket, and settles the gap after a:to one space.