support ignore for blocks of code

[12rambau]

This is the follow-up issue of #1212. It is now possible to ignore a single line from a file by adding # codspell: ignore comment.
Would it be possible to continue to mimick what black is doing and implement an on/off comment.

It's easier to understand with a real life example:

in my lib I need to gather some data from USDA wich associate a US state to a 2 letter code. I thus store a boring dictionnary at the start of my module:

# fmt: off
ASSET_CODES = {
    "Alabama": "AL", "Arkansas": "AR", "Arizona": "AZ", "California": "CA", "Colorado": "CO",
    "Connecticut": "CT", "Delaware": "DE", "Georgia": "GA", "Florida": "FL", "Iowa": "IA", "Idaho": "ID",
    "Illinois": "IL", "Indiana": "IN", "Kansas": "KS", "Kentucky": "KY", "Louisiana": "LA", "Massachusetts": "MA",
    "Maryland": "MD", "Maine": "ME", "Michigan": "MI", "Minnesota": "MN", "Missouri": "MO", "Mississippi": "MS",
    "Montana": "MT", "Nebraska": "NE", "New Hampshire": "NH", "New Jersey": "NJ", "New Mexico": "NM",
    "Nevada": "NV", "New York": "NY", "North Carolina": "NC", "North Dakota": "ND", "Ohio": "OH", "Oklahoma": "OK", # codespell: ignore
    "Oregon": "OR", "Pennsylvania": "PA", "Rhode Island": "RI", "South Carolina": "SC", "South Dakota": "SD",
    "Tennessee": "TN", "Texas": "TX", "Utah": "UT", "Vermont": "VT", "Virginia": "VA", "Washington": "WA",
    "West Virginia": "WV", "Wisconsin": "WI", "Wyoming": "WY",
}
# fmt: on

When I run the code spell pre-commit, it falls on "ND" which is the code for Nevada and offers me to replace it with "AND" or "2ND".
The codespell ignore comments is perfectly doing it's job but I lack visibility. If you look carefully at my example, the comments #fmt: off and #fmt: on are deactivating black for the whole length of the dict. Would it be possible to implement such a comment for codespell ?

[julian-smith-artifex-com]

I have recently created a PR that adds support for ignoring regions that span multiple lines: #3476.

It works by allowing the user to specify a regex that is applied using re.DOTALL before codespell's line-based algorithm is used.

So the begin/end tags are not hard coded, instead one sets them on the command line.

For example with:
codespell --ignore-multiline-regex 'codespell:ignore-begin.*codespell:ignore-end'

one can ignore code blocks with:

# codespell:ignore-begin
... codespell will not look at this text.
# codespell:ignore-end

or

// codespell:ignore-begin
... codespell will not look at this text.
// codespell:ignore-end

[DanielYang59]

@julian-smith-artifex-com Thanks that's really helpful.

And I know it's easier said than done, but would it be possible for you (or anyone else) to allow the block ignore to take a pattern just like the inline ignore tag, like:

# codespell:ignore-begin wrod
... codespell will not check `wrod` for this block
# codespell:ignore-end

[electriquo]

@julian-smith-artifex-com i am getting error on this, see below

$ codespell --version
2.3.0

$ codespell --ignore-multiline-regex 'codespell:ignore-begin.*codespell:ignore-end'
codespell: error: unrecognized arguments: --ignore-multiline-regex

trying to replace --ignore-multiline-regex with --ignore-regex does not seem to hold.
i see it on the default branch:

codespell/codespell_lib/_codespell.py

Lines 437 to 449 in c6bdc1f

	parser.add_argument(
	"--ignore-multiline-regex",
	action="store",
	type=str,
	help="regular expression that is used to ignore "
	"text that may span multi-line regions. "
	"The regex is run with re.DOTALL. For example to "
	"allow skipping of regions of Python code using "
	"begin/end comments one could use: "
	"--ignore-multiline-regex "
	"'# codespell:ignore-begin *\\n.*# codespell:ignore-end *\\n'. "
	"Defaults to empty/disabled.",
	)

seems it is not included in version 2.3.0 :(
relates to: #3585 #3520

[julian-smith-artifex-com]

The current release 2.4.0 on pypi.org seems to support --ignore-multiline-regex.

See https://pypi.org/project/codespell/#history. It looks like it was released just a couple of days ago, on 2025-1.21.