Package: tan
The Uncompromising Code Formatter“Any color you like.”Blackis the uncompromising Python code formatter. By using it, you agree to cede
control over minutiae of hand-formatting. In return,Blackgives you speed,
determinism, and freedom frompycodestylenagging about formatting. You will save time
and mental energy for more important matters.Blackened code looks the same regardless of the project you're reading. Formatting
becomes transparent after a while and you can focus on the content instead.Blackmakes code review faster by producing the smallest diffs possible.Try it out now using theBlack Playground. Watch thePyCon 2019 talkto learn more.Read the documentation on ReadTheDocs!Installation and usageInstallationBlackcan be installed by runningpip install black. It requires Python 3.7+ to run.
If you want to format Jupyter Notebooks, install withpip install "black[jupyter]".If you can't wait for the latesthotnessand want to install from GitHub, use:pip install git+https://github.com/psf/blackUsageTo get started right away with sensible defaults:black{source_file_or_directory}You can runBlackas a package if running it as a script doesn't work:python-mblack{source_file_or_directory}Further information can be found in our docs:Usage and ConfigurationBlackis alreadysuccessfully usedby many
projects, small and big.Blackhas a comprehensive test suite, with efficient parallel
tests, and our own auto formatting and parallel Continuous Integration runner. Now that
we have become stable, you should not expect large formatting changes in the future.
Stylistic changes will mostly be responses to bug reports and support for new Python
syntax. For more information please refer to theThe Black Code Style.Also, as a safety measure which slows down processing,Blackwill check that the
reformatted code still produces a valid AST that is effectively equivalent to the
original (see thePragmatismsection for details). If you're feeling confident, use--fast.TheBlackcode styleBlackis a PEP 8 compliant opinionated formatter.Blackreformats entire files in
place. Style configuration options are deliberately limited and rarely added. It doesn't
take previous formatting into account (seePragmatismfor exceptions).Our documentation covers the currentBlackcode style, but planned changes to it are
also documented. They're both worth taking a look:TheBlackCode Style: Current styleTheBlackCode Style: Future styleChanges to theBlackcode style are bound by the Stability Policy:TheBlackCode Style: Stability PolicyPlease refer to this document before submitting an issue. What seems like a bug might be
intended behaviour.PragmatismEarly versions ofBlackused to be absolutist in some respects. They took after its
initial author. This was fine at the time as it made the implementation simpler and
there were not many users anyway. Not many edge cases were reported. As a mature tool,Blackdoes make some exceptions to rules it otherwise holds.TheBlackcode style: PragmatismPlease refer to this document before submitting an issue just like with the document
above. What seems like a bug might be intended behaviour.ConfigurationBlackis able to read project-specific default values for its command line options
from apyproject.tomlfile. This is especially useful for specifying custom--includeand--exclude/--force-exclude/--extend-excludepatterns for your
project.You can find more details in our documentation:The basics: Configuration via a fileAnd if you're looking for more general configuration documentation:Usage and ConfigurationPro-tip: If you're asking yourself "Do I need to configure anything?" the answer is
"No".Blackis all about sensible defaults. Applying those defaults will have your
code in compliance with many otherBlackformatted projects.Used byThe following notable open-source projects trustBlackwith enforcing a consistent
code style: pytest, tox, Pyramid, Django, Django Channels, Hypothesis, attrs,
SQLAlchemy, Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv),
pandas, Pillow, Twisted, LocalStack, every Datadog Agent Integration, Home Assistant,
Zulip, Kedro, OpenOA, FLORIS, ORBIT, WOMBAT, and many more.The following organizations useBlack: Facebook, Dropbox, KeepTruckin, Mozilla, Quora,
Duolingo, QuantumBlack, Tesla, Archer Aviation.Are we missing anyone? Let us know.TestimonialsMike Bayer,author ofSQLAlchemy:I can't think of any single tool in my entire programming career that has given me a
bigger productivity increase by its introduction. I can now do refactorings in about
1% of the keystrokes that it would have taken me previously when we had no way for
code to format itself.Dusty Phillips,writer:Blackis opinionated so you don't have to be.Hynek Schlawack,creator ofattrs, core developer of
Twisted and CPython:An auto-formatter that doesn't suck is all I want for Xmas!Carl Meyer,Djangocore developer:At least the name is good.Kenneth Reitz, creator ofrequestsandpipenv:This vastly improves the formatting of our code. Thanks a ton!Show your styleUse the badge in your project's README.md:[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)Using the badge in README.rst:.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/blackLooks like this:LicenseMITContributingWelcome! Happy to see you willing to make the project better. You can get started by
reading this:Contributing: The basicsYou can also take a look at the rest of the contributing docs or talk with the
developers:Contributing documentationChat on DiscordChange logThe log has become rather long. It moved to its own file.SeeCHANGES.AuthorsThe author list is quite long nowadays, so it lives in its own file.SeeAUTHORS.mdCode of ConductEveryone participating in theBlackproject, and in particular in the issue tracker,
pull requests, and social media activity, is expected to treat other people with respect
and more generally to follow the guidelines articulated in thePython Community Code of Conduct.At the same time, humor is encouraged. In fact, basic familiarity with Monty Python's
Flying Circus is expected. We are not savages.And if youreallyneed to slap somebody, do it with a fish while dancing.Change LogUnreleasedHighlightsStable stylePreview styleConfigurationPackagingParserPerformanceOutputBlackdIntegrationsDocumentation23.7.0HighlightsRuntime support for Python 3.7 has been removed. Formatting 3.7 code will still be
supported until further notice (#3765)Stable styleFix a bug where an illegal trailing comma was added to return type annotations using
PEP 604 unions (#3735)Fix several bugs and crashes where comments in stub files were removed or mishandled
under some circumstances (#3745)Fix a crash with multi-line magic comments liketype: ignorewithin parentheses
(#3740)Fix error in AST validation whenBlackremoves trailing whitespace in a type comment
(#3773)Preview styleImplicitly concatenated strings used as function args are no longer wrapped inside
parentheses (#3640)Remove blank lines between a class definition and its docstring (#3692)ConfigurationThe--workersargument toBlackcan now be specified via theBLACK_NUM_WORKERSenvironment variable (#3743).pytest_cache,.ruff_cacheand.vscodeare now excluded by default (#3691)FixBlacknot honouringpyproject.tomlsettings when running--stdin-filenameand thepyproject.tomlfound isn't in the current working directory (#3719)Blackwill now error ifexcludeandextend-excludehave invalid data types inpyproject.toml, instead of silently doing the wrong thing (#3764)PackagingUpgrade mypyc from 0.991 to 1.3 (#3697)Remove patching of Click that mitigated errors on Python 3.6 withLANG=C(#3768)ParserAdd support for the new PEP 695 syntax in Python 3.12 (#3703)PerformanceSpeed upBlacksignificantly when the cache is full (#3751)Avoid importingIPythonin a case where we wouldn't need it (#3748)OutputUse aware UTC datetimes internally, avoids deprecation warning on Python 3.12 (#3728)Change verbose logging to exactly mirrorBlack's logic for source discovery (#3749)BlackdTheblackdargument parser now shows the default values for options in their help
text (#3712)IntegrationsBlack is now tested withPYTHONWARNDEFAULTENCODING = 1(#3763)Update GitHub Action to display black output in the job summary (#3688)DocumentationAdd a CITATION.cff file to the root of the repository, containing metadata on how to
cite this software (#3723)Update theclassesandexceptionsdocumentation in Developer reference to match
the latest code base (#3755)23.3.0HighlightsThis release fixes a longstanding confusing behavior in Black's GitHub action, where the
version of the action did not determine the version of Black being run (issue #3382). In
addition, there is a small bug fix around imports and a number of improvements to the
preview style.Please try out thepreview stylewithblack --previewand tell us your feedback. All changes in the preview style are
expected to become part of Black's stable style in January 2024.Stable styleImport lines with# fmt: skipand# fmt: offno longer have an extra blank line
added when they are right after another import line (#3610)Preview styleAdd trailing commas to collection literals even if there's a comment after the last
entry (#3393)async def,async for, andasync withstatements are now formatted consistently
compared to their non-async version. (#3609)withstatements that contain two context managers will be consistently wrapped in
parentheses (#3589)Let string splitters respectEast Asian Width(#3445)Now long string literals can be split after East Asian commas and periods (、U+3001
IDEOGRAPHIC COMMA,。U+3002 IDEOGRAPHIC FULL STOP, &，U+FF0C FULLWIDTH COMMA)
besides before spaces (#3445)For stubs, enforce one blank line after a nested class with a body other than just...(#3564)Improve handling of multiline strings by changing line split behavior (#1879)ParserAdded support for formatting files with invalid type comments (#3594)IntegrationsUpdate GitHub Action to use the version of Black equivalent to action's version if
version input is not specified (#3543)Fix missing Python binary path in autoload script for vim (#3508)DocumentationDocument that only the most recent release is supported for security issues;
vulnerabilities should be reported through Tidelift (#3612)23.1.0HighlightsThis is the first release of 2023, and following ourstability policy,
it comes with a number of improvements to our stable style, including improvements to
empty line handling, removal of redundant parentheses in several contexts, and output
that highlights implicitly concatenated strings better.There are also many changes to the preview style; try outblack --previewand give us
feedback to help us set the stable style for next year.In addition to style changes, Black now automatically infers the supported Python
versions from yourpyproject.tomlfile, removing the need to set Black's target
versions separately.Stable styleIntroduce the 2023 stable style, which incorporates most aspects of last year's
preview style (#3418). Specific changes:Enforce empty lines before classes and functions with sticky leading comments
(#3302) (22.12.0)Reformat empty and whitespace-only files as either an empty file (if no newline is
present) or as a single newline character (if a newline is present) (#3348)
(22.12.0)Implicitly concatenated strings used as function args are now wrapped inside
parentheses (#3307) (22.12.0)Correctly handle trailing commas that are inside a line's leading non-nested parens
(#3370) (22.12.0)--skip-string-normalization/-Snow prevents docstring prefixes from being
normalized as expected (#3168) (since 22.8.0)When using--skip-magic-trailing-commaor-C, trailing commas are stripped from
subscript expressions with more than 1 element (#3209) (22.8.0)Implicitly concatenated strings inside a list, set, or tuple are now wrapped inside
parentheses (#3162) (22.8.0)Fix a string merging/split issue when a comment is present in the middle of
implicitly concatenated strings on its own line (#3227) (22.8.0)Docstring quotes are no longer moved if it would violate the line length limit
(#3044, #3430) (22.6.0)Parentheses around return annotations are now managed (#2990) (22.6.0)Remove unnecessary parentheses around awaited objects (#2991) (22.6.0)Remove unnecessary parentheses inwithstatements (#2926) (22.6.0)Remove trailing newlines after code block open (#3035) (22.6.0)Code cell separators#%%are now standardised to# %%(#2919) (22.3.0)Remove unnecessary parentheses fromexceptstatements (#2939) (22.3.0)Remove unnecessary parentheses from tuple unpacking inforloops (#2945) (22.3.0)Avoid magic-trailing-comma in single-element subscripts (#2942) (22.3.0)Fix a crash when a colon line is marked between# fmt: offand# fmt: on(#3439)Preview styleFormat hex codes in unicode escape sequences in string literals (#2916)Add parentheses aroundif-elseexpressions (#2278)Improve performance on large expressions that contain many strings (#3467)Fix a crash in preview style with assert + parenthesized string (#3415)Fix crashes in preview style with walrus operators used in function return annotations
and except clauses (#3423)Fix a crash in preview advanced string processing where mixed implicitly concatenated
regular and f-strings start with an empty span (#3463)Fix a crash in preview advanced string processing where a standalone comment is placed
before a dict's value (#3469)Fix an issue where extra empty lines are added when a decorator has# fmt: skipapplied or there is a standalone comment between decorators (#3470)Do not put the closing quotes in a docstring on a separate line, even if the line is
too long (#3430)Long values in dict literals are now wrapped in parentheses; correspondingly
unnecessary parentheses around short values in dict literals are now removed; long
string lambda values are now wrapped in parentheses (#3440)Fix two crashes in preview style involving edge cases with docstrings (#3451)Exclude string type annotations from improved string processing; fix crash when the
return type annotation is stringified and spans across multiple lines (#3462)Wrap multiple context managers in parentheses when targeting Python 3.9+ (#3489)Fix several crashes in preview style with walrus operators used inwithstatements
or tuples (#3473)Fix an invalid quote escaping bug in f-string expressions where it produced invalid
code. Implicitly concatenated f-strings with different quotes can now be merged or
quote-normalized by changing the quotes used in expressions. (#3509)Fix crash onawait (yield)when Black is compiled with mypyc (#3533)ConfigurationBlack now tries to infer its--target-versionfrom the project metadata specified inpyproject.toml(#3219)PackagingUpgrade mypyc from0.971to0.991so mypycifiedBlackcan be built on armv7
(#3380)This also fixes some crashes while using compiled Black with a debug build of
CPythonDrop specific support for thetomlirequirement on 3.11 alpha releases, working
around a bug that would cause the requirement not to be installed on any non-final
Python releases (#3448)Black now depends onpackagingversion22.0or later. This is required for new
functionality that needs to parse part of the project metadata (#3219)OutputCallingblack --helpmultiple times will return the same help contents each time
(#3516)Verbose logging now shows the values ofpyproject.tomlconfiguration variables
(#3392)Fix false symlink detection messages in verbose output due to using an incorrect
relative path to the project root (#3385)IntegrationsMove 3.11 CI to normal flow now that all dependencies support 3.11 (#3446)Docker: Add newlatest_prereleasetag automation to follow latest black alpha
release on docker images (#3465)DocumentationExpandvim-pluginstallation instructions to offer more explicit options (#3468)22.12.0Preview styleEnforce empty lines before classes and functions with sticky leading comments (#3302)Reformat empty and whitespace-only files as either an empty file (if no newline is
present) or as a single newline character (if a newline is present) (#3348)Implicitly concatenated strings used as function args are now wrapped inside
parentheses (#3307)For assignment statements, prefer splitting the right hand side if the left hand side
fits on a single line (#3368)Correctly handle trailing commas that are inside a line's leading non-nested parens
(#3370)ConfigurationFix incorrectly applied.gitignorerules by considering the.gitignorelocation
and the relative path to the target file (#3338)Fix incorrectly ignoring.gitignorepresence when more than one source directory is
specified (#3336)ParserParsing support has been added for walruses inside generator expression that are
passed as function args (for example,any(match := my_re.match(text) for text in texts)) (#3327).IntegrationsVim plugin: Optionally allow using the system installation of Black vialet g:black_use_virtualenv = 0(#3309)22.10.0HighlightsRuntime support for Python 3.6 has been removed. Formatting 3.6 code will still be
supported until further notice.Stable styleFix a crash when# fmt: onis used on a different block level than# fmt: off(#3281)Preview styleFix a crash when formatting some dicts with parenthesis-wrapped long string keys
(#3262)Configuration.ipynb_checkpointsdirectories are now excluded by default (#3293)Add--skip-source-first-line/-xoption to ignore the first line of source code
while formatting (#3299)PackagingExecutables made with PyInstaller will no longer crash when formatting several files
at once on macOS. Native x86-64 executables for macOS are available once again.
(#3275)Hatchling is now used as the build backend. This will not have any effect for users
who install Black with its wheels from PyPI. (#3233)Faster compiled wheels are now available for CPython 3.11 (#3276)BlackdWindows style (CRLF) newlines will be preserved (#3257).IntegrationsVim plugin: add flag (g:black_preview) to enable/disable the preview style (#3246)Update GitHub Action to support formatting of Jupyter Notebook files via ajupyteroption (#3282)Update GitHub Action to support use of version specifiers (e.g.<23) for Black
version (#3265)22.8.0HighlightsPython 3.11 is now supported, except forblackdas aiohttp does not support 3.11 as
of publishing (#3234)This is the last release that supports runningBlackon Python 3.6 (formatting 3.6
code will continue to be supported until further notice)Reword the stability policy to say that we may, in rare cases, make changes that
affect code that was not previously formatted byBlack(#3155)Stable styleFix an infinite loop when using# fmt: on/offin the middle of an expression or code
block (#3158)Fix incorrect handling of# fmt: skipon colon (:) lines (#3148)Comments are no longer deleted when a line had spaces removed around power operators
(#2874)Preview styleSingle-character closing docstring quotes are no longer moved to their own line as
this is invalid. This was a bug introduced in version 22.6.0. (#3166)--skip-string-normalization/-Snow prevents docstring prefixes from being
normalized as expected (#3168)When using--skip-magic-trailing-commaor-C, trailing commas are stripped from
subscript expressions with more than 1 element (#3209)Implicitly concatenated strings inside a list, set, or tuple are now wrapped inside
parentheses (#3162)Fix a string merging/split issue when a comment is present in the middle of implicitly
concatenated strings on its own line (#3227)Blackdblackdnow supports enabling the preview style via theX-Previewheader (#3217)ConfigurationBlack now uses the presence of debug f-strings to detect target version (#3215)Fix misdetection of project root and verbose logging of sources in cases involving--stdin-filename(#3216)Immediate.gitignorefiles in source directories given on the command line are now
also respected, previously only.gitignorefiles in the project root and
automatically discovered directories were respected (#3237)DocumentationRecommend using BlackConnect in IntelliJ IDEs (#3150)IntegrationsVim plugin: prefix messages withBlack:so it's clear they come from Black (#3194)Docker: changed to a /opt/venv installation + added to PATH to be available to
non-root users (#3202)OutputChange from deprecatedasyncio.get_event_loop()to create our event loop which
removes DeprecationWarning (#3164)Remove logging from internalblib2to3library since it regularly emits error logs
about failed caching that can and should be ignored (#3193)ParserType comments are now included in the AST equivalence check consistently so accidental
deletion raises an error. Though type comments can't be tracked when running on PyPy
3.7 due to standard library limitations. (#2874)PerformanceReduce Black's startup time when formatting a single file by 15-30% (#3211)22.6.0StyleFix unstable formatting involving#fmt: skipand# fmt:skipcomments (notice the
lack of spaces) (#2970)Preview styleDocstring quotes are no longer moved if it would violate the line length limit (#3044)Parentheses around return annotations are now managed (#2990)Remove unnecessary parentheses around awaited objects (#2991)Remove unnecessary parentheses inwithstatements (#2926)Remove trailing newlines after code block open (#3035)IntegrationsAddscripts/migrate-black.pyscript to ease introduction of Black to a Git project
(#3038)OutputOutput Python version and implementation as part of--versionflag (#2997)PackagingUsetomliinstead oftomllibon Python 3.11 builds wheretomllibis not
available (#2987)ParserPEP 654syntax (for example,except *ExceptionGroup:) is now supported (#3016)PEP 646syntax (for example,Array[Batch, *Shape]ordef fn(*args: *T) -> None) is now supported (#3071)Vim PluginFixstrtoboolfunction. It didn't parse true/on/false/off. (#3025)22.3.0Preview styleCode cell separators#%%are now standardised to# %%(#2919)Remove unnecessary parentheses fromexceptstatements (#2939)Remove unnecessary parentheses from tuple unpacking inforloops (#2945)Avoid magic-trailing-comma in single-element subscripts (#2942)ConfigurationDo not format__pypackages__directories by default (#2836)Add support for specifying stable version with--required-version(#2832).Avoid crashing when the user has no homedir (#2814)Avoid crashing when md5 is not available (#2905)Fix handling of directory junctions on Windows (#2904)DocumentationUpdate pylint config documentation (#2931)IntegrationsMove test to disable plugin in Vim/Neovim, which speeds up loading (#2896)OutputIn verbose mode, log whenBlackis using user-level config (#2861)PackagingFix Black to work with Click 8.1.0 (#2966)On Python 3.11 and newer, use the standard library'stomllibinstead oftomli(#2903)black-primer, the deprecated internal devtool, has been removed and copied to aseparate repository(#2924)ParserBlack can now parse starred expressions in the target offorandasync forstatements, e.gfor item in *items_1, *items_2: pass(#2879).22.1.0At long last,Blackis no longer a beta product! This is the first non-beta release
and the first release covered by our newstability policy.HighlightsRemove Python 2 support(#2740)Introduce the--previewflag (#2752)StyleDeprecate--experimental-string-processingand move the functionality under--preview(#2789)For stubs, one blank line between class attributes and methods is now kept if there's
at least one pre-existing blank line (#2736)Black now normalizes string prefix order (#2297)Remove spaces around power operators if both operands are simple (#2726)Work around bug that causes unstable formatting in some cases in the presence of the
magic trailing comma (#2807)Use parentheses for attribute access on decimal float and int literals (#2799)Don't add whitespace for attribute access on hexadecimal, binary, octal, and complex
literals (#2799)Treat blank lines in stubs the same inside top-levelifstatements (#2820)Fix unstable formatting with semicolons and arithmetic expressions (#2817)Fix unstable formatting around magic trailing comma (#2572)ParserFix mapping cases that contain as-expressions, likecase {"key": 1 | 2 as password}(#2686)Fix cases that contain multiple top-level as-expressions, likecase 1 as a, 2 as b(#2716)Fix call patterns that contain as-expressions with keyword arguments, likecase Foo(bar=baz as quux)(#2749)Tuple unpacking onreturnandyieldconstructs now implies 3.8+ (#2700)Unparenthesized tuples on annotated assignments (e.gvalues: Tuple[int, ...] = 1, 2, 3) now implies 3.8+ (#2708)Fix handling of standalonematch()orcase()when there is a trailing newline or a
comment inside of the parentheses. (#2760)from __future__ import annotationsstatement now implies Python 3.7+ (#2690)PerformanceSpeed-up the new backtracking parser about 4X in general (enabled when--target-versionis set to 3.10 and higher). (#2728)Blackis now compiled withmypycfor an overall 2x
speed-up. 64-bit Windows, MacOS, and Linux (not including musl) are supported. (#1009,
#2431)ConfigurationDo not accept bare carriage return line endings in pyproject.toml (#2408)Add configuration option (python-cell-magics) to format cells with custom magics in
Jupyter Notebooks (#2744)Allow setting custom cache directory on all platforms with environment variableBLACK_CACHE_DIR(#2739).Enable Python 3.10+ by default, without any extra need to specify--target-version=py310. (#2758)Make passingSRCor--codemandatory and mutually exclusive (#2804)OutputImprove error message for invalid regular expression (#2678)Improve error message when parsing fails during AST safety check by embedding the
underlying SyntaxError (#2693)No longer color diff headers white as it's unreadable in light themed terminals
(#2691)Text coloring added in the final statistics (#2712)Verbose mode also now describes how a project root was discovered and which paths will
be formatted. (#2526)PackagingAll upper version bounds on dependencies have been removed (#2718)typing-extensionsis no longer a required dependency in Python 3.10+ (#2772)Setclicklower bound to8.0.0(#2791)IntegrationsUpdate GitHub action to support containerized runs (#2748)DocumentationChange protocol in pip installation instructions tohttps://(#2761)Change HTML theme to Furo primarily for its responsive design and mobile support
(#2793)Deprecate theblack-primertool (#2809)Document Python support policy (#2819)21.12b0BlackFix determination of f-string expression spans (#2654)Fix bad formatting of error messages about EOF in multi-line statements (#2343)Functions and classes in blocks now have more consistent surrounding spacing (#2472)Jupyter Notebook supportCell magics are now only processed if they are known Python cell magics. Earlier, all
cell magics were tokenized, leading to possible indentation errors e.g. with%%writefile. (#2630)Fix assignment to environment variables in Jupyter Notebooks (#2642)Python 3.10 supportPoint users to using--target-version py310if we detect 3.10-only syntax (#2668)Fixmatchstatements with open sequence subjects, likematch a, b:ormatch a, *b:(#2639) (#2659)Fixmatch/casestatements that containmatch/casesoft keywords multiple
times, likematch re.match()(#2661)Fixcasestatements with an inline body (#2665)Fix styling of starred expressions insidematchsubject (#2667)Fix parser error location on invalid syntax in amatchstatement (#2649)Fix Python 3.10 support on platforms without ProcessPoolExecutor (#2631)Improve parsing performance on code that usesmatchunder--target-version py310up to ~50% (#2670)PackagingRemove dependency onregex(#2644) (#2663)21.11b1BlackBumped regex version minimum to 2021.4.4 to fix Pattern class usage (#2621)21.11b0BlackWarn about Python 2 deprecation in more cases by improving Python 2 only syntax
detection (#2592)Add experimental PyPy support (#2559)Add partial support for the match statement. As it's experimental, it's only enabled
when--target-version py310is explicitly specified (#2586)Add support for parenthesized with (#2586)Declare support for Python 3.10 for running Black (#2562)IntegrationsFixed vim plugin with Python 3.10 by removing deprecated distutils import (#2610)The vim plugin now parsesskip_magic_trailing_commafrom pyproject.toml (#2613)21.10b0BlackDocument stability policy, that will apply for non-beta releases (#2529)Add new--workersparameter (#2514)Fixed feature detection for positional-only arguments in lambdas (#2532)Bumped typed-ast version minimum to 1.4.3 for 3.10 compatibility (#2519)Fixed a Python 3.10 compatibility issue where the loop argument was still being passed
even though it has been removed (#2580)Deprecate Python 2 formatting support (#2523)BlackdRemove dependency on aiohttp-cors (#2500)Bump required aiohttp version to 3.7.4 (#2509)Black-PrimerAdd primer support for --projects (#2555)Print primer summary after individual failures (#2570)IntegrationsAllow to passtarget_versionin the vim plugin (#1319)Install build tools in docker file and use multi-stage build to keep the image size
down (#2582)21.9b0PackagingFix missing modules in self-contained binaries (#2466)Fix missing toml extra used during installation (#2475)21.8b0BlackAdd support for formatting Jupyter Notebook files (#2357)Move fromappdirsdependency toplatformdirs(#2375)Present a more user-friendly error if .gitignore is invalid (#2414)The failsafe for accidentally added backslashes in f-string expressions has been
hardened to handle more edge cases during quote normalization (#2437)Avoid changing a function return type annotation's type to a tuple by adding a
trailing comma (#2384)Parsing support has been added for unparenthesized walruses in set literals, set
comprehensions, and indices (#2447).Pinsetuptools-scmbuild-time dependency version (#2457)Exclude typing-extensions version 3.10.0.1 due to it being broken on Python 3.10
(#2460)BlackdReplace sys.exit(-1) with raise ImportError as it plays more nicely with tools that
scan installed packages (#2440)IntegrationsThe provided pre-commit hooks no longer specifylanguage_versionto avoid overridingdefault_language_version(#2430)21.7b0BlackConfiguration files using TOML features higher than spec v0.5.0 are now supported
(#2301)Add primer support and test for code piped into black via STDIN (#2315)Fix internal error whenFORCE_OPTIONAL_PARENTHESESfeature is enabled (#2332)Accept empty stdin (#2346)Provide a more useful error when parsing fails during AST safety checks (#2304)DockerAdd newlatest_releasetag automation to follow latest black release on docker
images (#2374)IntegrationsThe vim plugin now searches upwards from the directory containing the current buffer
instead of the current working directory for pyproject.toml. (#1871)The vim plugin now reads the correct string normalization option in pyproject.toml
(#1869)The vim plugin no longer crashes Black when there's boolean values in pyproject.toml
(#1869)21.6b0BlackFix failure caused byfmt: skipand indentation (#2281)Account for += assignment when deciding whether to split string (#2312)Correct max string length calculation when there are string operators (#2292)Fixed option usage when using the--codeflag (#2259)Do not calluvloop.install()whenBlackis used as a library (#2303)Added--required-versionoption to require a specific version to be running (#2300)Fix incorrect custom breakpoint indices when string group contains fake f-strings
(#2311)Fix regression whereRprefixes would be lowercased for docstrings (#2285)Fix handling of named escapes (\N{...}) when--experimental-string-processingis
used (#2319)IntegrationsThe official Black action now supports choosing what version to use, and supports the
major 3 OSes. (#1940)21.5b2BlackA space is no longer inserted into empty docstrings (#2249)Fix handling of .gitignore files containing non-ASCII characters on Windows (#2229)Respect.gitignorefiles in all levels, not onlyroot/.gitignorefile (apply.gitignorerules likegitdoes) (#2225)Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)Add extra uvloop install + import support if in python env (#2258)Fix --experimental-string-processing crash when matching parens are not found (#2283)Make sure to split lines that start with a string operator (#2286)Fix regular expression that black uses to identify f-expressions (#2287)BlackdAdd a lower bound for theaiohttp-corsdependency. Only 0.4.0 or higher is
supported. (#2231)PackagingRelease self-contained x86_64 MacOS binaries as part of the GitHub release pipeline
(#2198)Always build binaries with the latest available Python (#2260)DocumentationAdd discussion of magic comments to FAQ page (#2272)--experimental-string-processingwill be enabled by default in the future (#2273)Fix typos discovered by codespell (#2228)Fix Vim plugin installation instructions. (#2235)Add new Frequently Asked Questions page (#2247)Fix encoding + symlink issues preventing proper build on Windows (#2262)21.5b1BlackRefactorsrc/black/__init__.pyinto many files (#2206)DocumentationReplaced all remaining references to themasterbranch with themainbranch. Some additional changes in
the source code were also made. (#2210)Sigificantly reorganized the documentation to make much more sense. Check them out by
heading over tothe stable docs on RTD.
(#2174)21.5b0BlackSet--pyimode if--stdin-filenameends in.pyi(#2169)Stop detecting target version as Python 3.9+ with pre-PEP-614 decorators that are
being called but with no arguments (#2182)Black-PrimerAdd--no-diffto black-primer to suppress formatting changes (#2187)21.4b2BlackFix crash if the user configuration directory is inaccessible. (#2158)Clarifycircumstancesin whichBlackmay change the AST (#2159)Allow.gitignorerules to be overridden by specifyingexcludeinpyproject.tomlor on the command line. (#2170)PackagingInstallprimer.json(used byblack-primerby default) with black. (#2154)21.4b1BlackFix crash on docstrings ending with "\ ". (#2142)Fix crash when atypical whitespace is cleaned out of dostrings (#2120)Reflect the--skip-magic-trailing-commaand--experimental-string-processingflags
in the name of the cache file. Without this fix, changes in these flags would not take
effect if the cache had already been populated. (#2131)Don't remove necessary parentheses from assignment expression containing assert /
return statements. (#2143)PackagingBump pathspec to >= 0.8.1 to solve invalid .gitignore exclusion handling21.4b0BlackFixed a rare but annoying formatting instability created by the combination of
optional trailing commas inserted byBlackand optional parentheses looking at
pre-existing "magic" trailing commas. This fixes issue #1629 and all of its many many
duplicates. (#2126)Blacknow processes one-line docstrings by stripping leading and trailing spaces,
and adding a padding space when needed to break up """". (#1740)Blacknow cleans up leading non-breaking spaces in comments (#2092)Blacknow respects--skip-string-normalizationwhen normalizing multiline
docstring quotes (#1637)Blackno longer removes all empty lines between non-function code and decorators
when formatting typing stubs. NowBlackenforces a single empty line. (#1646)Blackno longer adds an incorrect space after a parenthesized assignment expression
in if/while statements (#1655)Added--skip-magic-trailing-comma/-Cto avoid using trailing commas as a reason
to split lines (#1824)fixed a crash when PWD=/ on POSIX (#1631)fixed "I/O operation on closed file" when using --diff (#1664)Prevent coloured diff output being interleaved with multiple files (#1673)Added support for PEP 614 relaxed decorator syntax on python 3.9 (#1711)Added parsing support for unparenthesized tuples and yield expressions in annotated
assignments (#1835)added--extend-excludeargument (PR #2005)speed up caching by avoiding pathlib (#1950)--diffcorrectly indicates when a file doesn't end in a newline (#1662)Added--stdin-filenameargument to allow stdin to respect--force-excluderules
(#1780)Lines ending withfmt: skipwill now be not formatted (#1800)PR #2053: Black no longer relies on typed-ast for Python 3.8 and higherPR #2053: Python 2 support is now optional, install withpython3 -m pip install black[python2]to maintain support.Excludevenvdirectory by default (#1683)Fixed "Black produced code that is not equivalent to the source" when formatting
Python 2 docstrings (#2037)PackagingSelf-contained nativeBlackbinaries are now provided for releases via GitHub
Releases (#1743)20.8b1Packagingexplicitly depend on Click 7.1.2 or newer asBlackno longer works with versions
older than 7.020.8b0Blackre-implemented support for explicit trailing commas: now it works consistently within
any bracket pair, including nested structures (#1288 and duplicates)Blacknow reindents docstrings when reindenting code around it (#1053)Blacknow shows colored diffs (#1266)Blackis now packaged using 'py3' tagged wheels (#1388)Blacknow supports Python 3.8 code, e.g. star expressions in return statements
(#1121)Blackno longer normalizes capital R-string prefixes as those have a
community-accepted meaning (#1244)Blacknow uses exit code 2 when specified configuration file doesn't exit (#1361)Blacknow works on AWS Lambda (#1141)added--force-excludeargument (#1032)removed deprecated--py36option (#1236)fixed--diffoutput when EOF is encountered (#526)fixed# fmt: offhandling around decorators (#560)fixed unstable formatting with some# type: ignorecomments (#1113)fixed invalid removal on organizing brackets followed by indexing (#1575)introducedblack-primer, a CI tool that allows us to run regression tests against
existing open source users of Black (#1402)introduced property-based fuzzing to our test suite based on Hypothesis and
Hypothersmith (#1566)implemented experimental and disabled by default long string rewrapping (#1132),
hidden under a--experimental-string-processingflag while it's being worked on;
this is an undocumented and unsupported feature, you lose Internet points for
depending on it (#1609)Vim pluginprefer virtualenv packages over global packages (#1383)19.10b0added support for PEP 572 assignment expressions (#711)added support for PEP 570 positional-only arguments (#943)added support for async generators (#593)added support for pre-splitting collections by putting an explicit trailing comma
inside (#826)addedblack -cas a way to format code passed from the command line (#761)--safe now works with Python 2 code (#840)fixed grammar selection for Python 2-specific code (#765)fixed feature detection for trailing commas in function definitions and call sites
(#763)# fmt: off/# fmt: oncomment pairs placed multiple times within the same block of
code now behave correctly (#1005)Blackno longer crashes on Windows machines with more than 61 cores (#838)Blackno longer crashes on standalone comments prepended with a backslash (#767)Blackno longer crashes onfrom...importblocks with comments (#829)Blackno longer crashes on Python 3.7 on some platform configurations (#494)Blackno longer fails on comments in from-imports (#671)Blackno longer fails when the file starts with a backslash (#922)Blackno longer merges regular comments with type comments (#1027)Blackno longer splits long lines that contain type comments (#997)removed unnecessary parentheses aroundyieldexpressions (#834)added parentheses around long tuples in unpacking assignments (#832)added parentheses around complex powers when they are prefixed by a unary operator
(#646)fixed bug that ledBlackformat some code with a line length target of 1 (#762)Blackno longer introduces quotes in f-string subexpressions on string boundaries
(#863)ifBlackputs parenthesis around a single expression, it moves comments to the
wrapped expression instead of after the brackets (#872)blackdnow returns the version ofBlackin the response headers (#1013)blackdcan now output the diff of formats on source code when theX-Diffheader is
provided (#969)19.3b0new option--target-versionto control which Python versionsBlack-formatted code
should target (#618)deprecated--py36(use--target-version=py36instead) (#724)Blackno longer normalizes numeric literals to include_separators (#696)longdelstatements are now split into multiple lines (#698)type comments are no longer mangled in function signaturesimproved performance of formatting deeply nested data structures (#509)Blacknow properly formats multiple files in parallel on Windows (#632)Blacknow creates cache files atomically which allows it to be used in parallel
pipelines (likexargs -P8) (#673)Blacknow correctly indents comments in files that were previously formatted with
tabs (#262)blackdnow supports CORS (#622)18.9b0numeric literals are now formatted byBlack(#452, #461, #464, #469):numeric literals are normalized to include_separators on Python 3.6+ codeadded--skip-numeric-underscore-normalizationto disable the above behavior and
leave numeric underscores as they were in the inputcode with_in numeric literals is recognized as Python 3.6+most letters in numeric literals are lowercased (e.g., in1e10,0x01)hexadecimal digits are always uppercased (e.g.0xBADC0DE)addedblackd, seeits documentationfor
more info (#349)adjacent string literals are now correctly split into multiple lines (#463)trailing comma is now added to single imports that don't fit on a line (#250)cache is now populated when--checkis successful for a file which speeds up
consecutive checks of properly formatted unmodified files (#448)whitespace at the beginning of the file is now removed (#399)fixed manglingpweaveandSpyder IDEspecial comments (#532)fixed unstable formatting when unpacking big tuples (#267)fixed parsing of__future__imports with renames (#389)fixed scope of# fmt: offwhen directly precedingyieldand other nodes (#385)fixed formatting of lambda expressions with default arguments (#468)fixedasync forstatements:Blackno longer breaks them into separate lines (#372)note: the Vim plugin stopped registering,=as a default chord as it turned out to
be a bad idea (#415)18.6b4hotfix: don't freeze when multiple comments directly precede# fmt: off(#371)18.6b3typing stub files (.pyi) now have blank lines added after constants (#340)# fmt: offand# fmt: onare now much more dependable:they now work also within bracket pairs (#329)they now correctly work across function/class boundaries (#335)they now work when an indentation block starts with empty lines or misaligned
comments (#334)made Click not fail on invalid environments; note that Click is right but the
likelihood we'll need to access non-ASCII file paths when dealing with Python source
code is low (#277)fixed improper formatting of f-strings with quotes inside interpolated expressions
(#322)fixed unnecessary slowdown when long list literals where found in a filefixed unnecessary slowdown on AST nodes with very many siblingsfixed cannibalizing backslashes during string normalizationfixed a crash due to symbolic links pointing outside of the project directory (#338)18.6b2added--config(#65)added-hequivalent to--help(#316)fixed improper unmodified file caching when-Swas usedfixed extra space in string unpacking (#305)fixed formatting of empty triple quoted strings (#313)fixed unnecessary slowdown in comment placement calculation on lines without comments18.6b1hotfix: don't output human-facing information on stdout (#299)hotfix: don't output cake emoji on non-zero return code (#300)18.6b0added--includeand--exclude(#270)added--skip-string-normalization(#118)added--verbose(#283)the header output in--diffnow actually conforms to the unified diff specfixed long trivial assignments being wrapped in unnecessary parentheses (#273)fixed unnecessary parentheses when a line contained multiline strings (#232)fixed stdin handling not working correctly if an old version of Click was used (#276)Blacknow preserves line endings when formatting a file in place (#258)18.5b1added--pyi(#249)added--py36(#249)Python grammar pickle caches are stored with the formatting caches, makingBlackwork in environments where site-packages is not user-writable (#192)Blacknow enforces a PEP 257 empty line after a class-level docstring (and/or
fields) and the first methodfixed invalid code produced when standalone comments were present in a trailer that
was omitted from line splitting on a large expression (#237)fixed optional parentheses being removed within# fmt: offsections (#224)fixed invalid code produced when stars in very long imports were incorrectly wrapped
in optional parentheses (#234)fixed unstable formatting when inline comments were moved around in a trailer that was
omitted from line splitting on a large expression (#238)fixed extra empty line between a class declaration and the first method if no class
docstring or fields are present (#219)fixed extra empty line between a function signature and an inner function or inner
class (#196)18.5b0call chains are now formatted according to thefluent interfacesstyle (#67)data structure literals (tuples, lists, dictionaries, and sets) are now also always
exploded like imports when they don't fit in a single line (#152)slices are now formatted according to PEP 8 (#178)parentheses are now also managed automatically on the right-hand side of assignments
and return statements (#140)math operators now use their respective priorities for delimiting multiline
expressions (#148)optional parentheses are now omitted on expressions that start or end with a bracket
and only contain a single operator (#177)empty parentheses in a class definition are now removed (#145, #180)string prefixes are now standardized to lowercase anduis removed on Python 3.6+
only code and Python 2.7+ code with theunicode_literalsfuture import (#188, #198,
#199)typing stub files (.pyi) are now formatted in a style that is consistent with PEP
484 (#207, #210)progress when reformatting many files is now reported incrementallyfixed trailers (content with brackets) being unnecessarily exploded into their own
lines after a dedented closing bracket (#119)fixed an invalid trailing comma sometimes left in imports (#185)fixed non-deterministic formatting when multiple pairs of removable parentheses were
used (#183)fixed multiline strings being unnecessarily wrapped in optional parentheses in long
assignments (#215)fixed not splitting long from-imports with only a single namefixed Python 3.6+ file discovery by also looking at function calls with unpacking.
This fixed non-deterministic formatting if trailing commas where used both in function
signatures with stars and function calls with stars but the former would be
reformatted to a single line.fixed crash on dealing with optional parentheses (#193)fixed "is", "is not", "in", and "not in" not considered operators for splitting
purposesfixed crash when dead symlinks where encountered18.4a4don't populate the cache on--check(#175)18.4a3added a "cache"; files already reformatted that haven't changed on disk won't be
reformatted again (#109)--checkand--diffare no longer mutually exclusive (#149)generalized star expression handling, including double stars; this fixes
multiplication making expressions "unsafe" for trailing commas (#132)Blackno longer enforces putting empty lines behind control flow statements (#90)Blacknow splits imports like "Mode 3 + trailing comma" of isort (#127)fixed comment indentation when a standalone comment closes a block (#16, #32)fixed standalone comments receiving extra empty lines if immediately preceding a
class, def, or decorator (#56, #154)fixed--diffnot showing entire path (#130)fixed parsing of complex expressions after star and double stars in function calls
(#2)fixed invalid splitting on comma in lambda arguments (#133)fixed missing splits of ternary expressions (#141)18.4a2fixed parsing of unaligned standalone comments (#99, #112)fixed placement of dictionary unpacking inside dictionary literals (#111)Vim plugin now works on Windows, toofixed unstable formatting when encountering unnecessarily escaped quotes in a string
(#120)18.4a1added--quiet(#78)added automatic parentheses management (#4)addedpre-commitintegration (#103, #104)fixed reporting on--checkwith multiple files (#101, #102)fixed removing backslash escapes from raw strings (#100, #105)18.4a0added--diff(#87)add line breaks before all delimiters, except in cases like commas, to better comply
with PEP 8 (#73)standardize string literals to use double quotes (almost) everywhere (#75)fixed handling of standalone comments within nested bracketed expressions;Blackwill no longer produce super long lines or put all standalone comments at the end of
the expression (#22)fixed 18.3a4 regression: don't crash and burn on empty lines with trailing whitespace
(#80)fixed 18.3a4 regression:# yapf: disableusage as trailing comment would causeBlackto not emit the rest of the file (#95)when CTRL+C is pressed while formatting many files,Blackno longer freaks out with
a flurry of asyncio-related exceptionsonly allow up to two empty lines on module level and only single empty lines within
functions (#74)18.3a4# fmt: offand# fmt: onare implemented (#5)automatic detection of deprecated Python 2 forms of print statements and exec
statements in the formatted file (#49)use proper spaces for complex expressions in default values of typed function
arguments (#60)only return exit code 1 when --check is used (#50)don't remove single trailing commas from square bracket indexing (#59)don't omit whitespace if the previous factor leaf wasn't a math operator (#55)omit extra space in kwarg unpacking if it's the first argument (#46)omit extra space inSphinx auto-attribute comments(#68)18.3a3don't remove single empty lines outside of bracketed expressions (#19)added ability to pipe formatting from stdin to stdin (#25)restored ability to format code with legacy usage ofasyncas a name (#20, #42)even better handling of numpy-style array indexing (#33, again)18.3a2changed positioning of binary operators to occur at beginning of lines instead of at
the end, followinga recent change to PEP 8(#21)ignore empty bracket pairs while splitting. This avoids very weirdly looking
formattings (#34, #35)remove a trailing comma if there is a single argument to a callif top level functions were separated by a comment, don't put four empty lines after
the upper functionfixed unstable formatting of newlines with importsfixed unintentional folding of post scriptum standalone comments into last statement
if it was a simple statement (#18, #28)fixed missing space in numpy-style array indexing (#33)fixed spurious space after star-based unary expressions (#31)18.3a1added--checkonly put trailing commas in function signatures and calls if it's safe to do so. If
the file is Python 3.6+ it's always safe, otherwise only safe if there are no*argsor**kwargsused in the signature or call. (#8)fixed invalid spacing of dots in relative imports (#6, #13)fixed invalid splitting after comma on unpacked variables in for-loops (#23)fixed spurious space in parenthesized set expressions (#7)fixed spurious space after opening parentheses and in default arguments (#14, #17)fixed spurious space after unary operators when the operand was a complex expression
(#15)18.3a0first published version, Happy 🍰 Day 2018!alpha qualitydate-versioned (see:https://calver.org/)