Closes#1246: This PR adds a new option (and automatically a toml entry, hooray for existing configuration management 🎉) to require a specific version of Black to be running.
For example: `black --required-version 20.8b -c "format = 'this'"`
Execution fails straight away if it doesn't match `__version__`.
Commit history before merge:
* Add black_version to github action
* Merge upstream/main into this branch
* Add version support for the Black action pt.2
Since we're moving to a composite based action, quite a few changes
were made. 1) Support was added for all OSes (Windows was painful).
2) Isolation from the rest of the workflow had to be done manually
with a virtual environment.
Other noteworthy changes:
- Rewrote basically all of the logic and put it in a Python script
for easy testing (not doing it here tho cause I'm lazy and I can't
think of a reasonable way of testing it).
- Renamed `black_version` to `version` to better fit the existing
input naming scheme.
- Added support for log groups, this makes our action's output a
bit more fancy (I may or may have not added some debug output too).
* Add more to and sorta rewrite the Action's docs
Reflect compatability and gotchas.
* Add CHANGELOG entry
* Merge main into this branch
* Remove debug; address typos; clean up action.yml
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
PR #2286 did not fix the edge-cases (e.g. when the string is just long
enough to cause a line to be 89 characters long). This PR corrects that
mistake.
Behavior other than output shouldn't depend on the verbose/quiet option. As far as I can tell this currently has no visible effect, since code after this function is called handles an empty list gracefully.
This commit makes use of HTML comments inside GitHub issue templates
to make sure that even if they aren't removed by the issue author they won't be shown
in the rendered output.
The goal is to simply make the issues less noisy by removing template messages.
There's some weird interaction between Click and
sphinxcontrib-programoutput on Windows that leads to an encoding error
during the printing of black-primer's help text.
Also symlinks aren't well supported on Windows so let's just use
includes which actually work because we now use MyST :D
* Add optional uvloop import
- If we find `uvloop` in the env for black, blackd or black-primer lets try and use it
- Add a uvloop extra install
Fixes#2257
Test:
- Add ci job to install black[uvloop] and run a primer run with uvloop
- Only with latest python (3.9)
- Will be handy to compare runtimes as a very unoffical benchmark
* Remove tox install
* Add to CHANGES/news
Resolves#2168 by disabling the insertion of a " " when the docstring is entirely empty.
Note that this PR is focussed only on the case of empty docstrings. In particular this does not make any changes to the behaviour that a " " is inserted if a non-empty docstring begins with the quoting character. That is, black still prefers:
""" "something" """
to:
""""something" """
and that:
""""Something""""
is not a legal docstring.
This commit creates a Frequently Asked Questions document for our users
to read. Hopefully they actually read it too. Items included are:
Black's non-API, AST safety, style stability, file discovery, Flake8
disagreements and Python 2 support. Hopefully I've got the answers
down in general.
Commit history before merge:
* Create FAQ
* Address feedback
* Move to single markdown file
* Minor wording improvements
* Add changelog entry
* Solved Problem with non-alphabetical .gitignore files
When .gitignore file in the user's project directory contained non-alphabetical
characters(Japanese, Korean, Chinese, etc), Nothing works and printed this
weird message in the console('cp949' is the encoding for Korean characters
in this case). It even blocks VSCode's formatting from working. This commit
solves the problem.
Traceback (most recent call last):
File "c:\users\username\anaconda3\envs\project-name\lib\runpy.py", line 193, in _run_module_as_main
"__main__", mod_spec)
File "c:\users\username\anaconda3\envs\project-name\lib\runpy.py", line 85, in _run_code
exec(code, run_globals)
File "C:\Users\username\anaconda3\envs\project-name\Scripts\black.exe\__main__.py", line 7, in <module>
File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\black\__init__.py", line 1056, in patched_main
main()
File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\click\core.py", line 829, in __call__
return self.main(*args, **kwargs)
File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\click\core.py", line 782, in main
rv = self.invoke(ctx)
File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\click\core.py", line 1066, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\click\core.py", line 610, in invoke
return callback(*args, **kwargs)
File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\click\decorators.py", line 21, in new_func
return f(get_current_context(), *args, **kwargs)
File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\black\__init__.py", line 394, in main
stdin_filename=stdin_filename,
File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\black\__init__.py", line 445, in get_sources
gitignore = get_gitignore(root)
File "c:\users\username\anaconda3\envs\project-name\lib\site-packages\black\files.py", line 122, in get_gitignore
lines = gf.readlines()
UnicodeDecodeError: 'cp949' codec can't decode byte 0xb0 in position 13: illegal multibyte sequence
* Made .gitignore File Reader Detect Its Encoding
* Revert "Made .gitignore File Reader Detect Its Encoding"
This reverts commit 6c3a7ea42b5b1e441cc0026c8205d1cee68c1bba.
* Revert "Solved Problem with non-alphabetical .gitignore files"
This reverts commit b0100b5d91c2f5db544a60f34aafab120f0aa458.
* Made .gitignore Reader Open the File with Auto Encoding Detecting
https://docs.python.org/3.8/library/tokenize.html#tokenize.open
* Revert "Made .gitignore Reader Open the File with Auto Encoding Detecting"
This reverts commit 50dd80422938649ccc8c7f43aac752f9f6481779.
* Made .gitignore Reader Use UTF-8
* Updated CHANGES.md for #2229
* Updated CHANGES.md for #2229
* Update CHANGES.md
* Update CHANGES.md
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
The isort configuration currently in the Black code style document is
duplicated in Using Black with other tools document. I think it would
be better to consolidate information and simply link to the tool guide,
mentioning the easy profile in the original document.
I changed the link from isort PyPI page to Black's docs on isort
because for users it could be better to see the Black docs on why that
configuration is necessary and what isort is from Black's perspective.
Why? The default in Prettier 2.0 was
[changed](https://prettier.io/docs/en/options.html#end-of-line) from
`auto` to `LF`. This makes development on Windows awkward, because
every file is marked with changes both by Prettier and then by Git
regardless of repository line ending settings, making committing harder
than it should be.
---
Aside from that: I noticed that runnin pre-commit manually seems to add
line endings to symlink files, but they disappear when actually committing.
Don't know if that's a known.. quirk..(?) or not.
---
Commit history before merge:
* Make Prettier preserve line ending type
* Move options to .prettierrc
Commit history before merge:
Black now respects .gitignore files in all levels, not only root/.gitignore file
(apply .gitignore rules like git does).
* Fix: typo
* Fix: respect .gitignore files in all levels.
* Add: CHANGELOG note.
* Fix: TypeError: unsupported operand type(s) for +: 'NoneType' and 'PathSpec'
* Update docs.
* Fix: no parent .gitignore
* Add a comment since the if expression is a bit hard to understand
* Update tests - conver no parent .gitignore case.
* Use main's Pipfile.lock instead
The original changes in Pipfile.lock are whitespace only. The changes
turned the JSON's file indentation from 4 to 2. Effectively this
happened: `json.dumps(json.loads(old_pipfile_lock), indent=2) + "\n"`.
Just using main's Pipfile.lock instead of undoing the changes because
1) I don't know how to do that easily and quickly, and 2) there's a
merge conflict.
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
* Merge remote-tracking branch 'upstream/main' into i1730 …
conflicts for days ay?
It appears sqlalchemy has recently reformatted their project with
Black 21.5b1.
Most of our dependencies have a lower bound and creating a test
environment with the oldest acceptable dependencies runs the full
Black test suite just fine. The only exception to this is aiohttp-cors.
It's unbounded and the oldest version 0.1.0 until 0.4.0 breaks the
test suite in such an old environment.
Failure with 0.1.0:
```
tests/test_blackd.py:10: in <module>
import blackd
testenv/lib/python3.8/site-packages/blackd/__init__.py:12: in <module>
import aiohttp_cors
testenv/lib/python3.8/site-packages/aiohttp_cors/__init__.py:29: in <module>
from .urldispatcher_router_adapter import UrlDistatcherRouterAdapter
testenv/lib/python3.8/site-packages/aiohttp_cors/urldispatcher_router_adapter.py:27: in <module>
class UrlDistatcherRouterAdapter(RouterAdapter):
testenv/lib/python3.8/site-packages/aiohttp_cors/urldispatcher_router_adapter.py:32: in UrlDistatcherRouterAdapter
def route_methods(self, route: web.Route):
E AttributeError: module 'aiohttp.web' has no attribute 'Route'
```
For 0.2.0:
```
tests/test_blackd.py:10: in <module>
import blackd
testenv/lib/python3.8/site-packages/blackd/__init__.py:12: in <module>
import aiohttp_cors
testenv/lib/python3.8/site-packages/aiohttp_cors/__init__.py:27: in <module>
from .cors_config import CorsConfig
testenv/lib/python3.8/site-packages/aiohttp_cors/cors_config.py:24: in <module>
from .urldispatcher_router_adapter import UrlDistatcherRouterAdapter
testenv/lib/python3.8/site-packages/aiohttp_cors/urldispatcher_router_adapter.py:27: in <module>
class UrlDistatcherRouterAdapter(AbstractRouterAdapter):
testenv/lib/python3.8/site-packages/aiohttp_cors/urldispatcher_router_adapter.py:32: in UrlDistatcherRouterAdapter
def route_methods(self, route: web.Route):
E AttributeError: module 'aiohttp.web' has no attribute 'Route'
```
For 0.3.0:
```
ERROR: Cannot install aiohttp-cors==0.3.0 and aiohttp==3.6.0 because these package versions have conflicting dependencies.
The conflict is caused by:
The user requested aiohttp==3.6.0
aiohttp-cors 0.3.0 depends on aiohttp<=0.20.2 and >=0.18.0
To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict
ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/user_guide/#fixing-conflicting-dependencies
```
- Test and Primer don't run for documentation only changes since it's
unnecessary, eating unnecessary cycles and slowing down CI since these
workflows eat up the 20 max workers limit quite easily!
- Documentation Build runs all of the time now since quite a bit of the
content depends on Black's code so even a simple 1-file change in
src/black/__init__.py may break the docs build. It's not like this is
a costly workflow anyway.
Fuzz is still running on all changes because with fuzzing, the more the
better in general. 6 or 7 jobs on a documentation only commit is much
better than 27/28 jobs anyway :p
I also found an error in our bug report issue template :)
We've depended on Click 7.x ever since we broke CI systems across the
world (oops lol) and flake8-mypy was purged a fair bit back: #1867
Also remove the primer tests import in tests/test_black.py because it's
annoying when just trying to actually target tests/test_black.py tests.
`pytest -k test_black.py` doesn't do what you expect due to that import.
* Add stable tag process to release process documentation
- Add reasoning + step commands
* Bah - I ran the linter but forgot to commit
* Update docs/contributing/release_process.md
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
* Setup groundwork for release process docs
I'm using MyST for the index page since I like it more and it's easier
to work with.
* Fill in Release Process for black
* Apply suggestions from code review
Apply Jelle's grammar + typo fixes. I am a terrible only English speaker.
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
* Update release_process.md
Make lint happy via web UI.
* Move to contribution section and fix prettier
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Commit history before merge:
* Cover more in the usage docs
* Minor fixes
* Even more corrections by Jelle
* Update docs/usage_and_configuration/the_basics.md
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
So these won't go out of date. This does mean the environment has be
setup a bit more carefully so the right version of the tool is used,
but thankfully the build environment is rebuilt on change on RTD anyway.
Also since the HTML docs are known to build fine, let's provide
downloadable HTMLzips of our docs.
This change needs RTD and GH to install Black with the [d] extra so
blackd's help can generated. While editing RTD's config file, let's
migrate the file to a non-deprecated filename.
Also I missed adding AUTHORS.md to the files key in the doc GHA config.
Commit history before merge:
* Replace references to master branch
* Update .flake8 to reference docs on RTD
We're moving away from GitHub as a documentation host to only RTD because
it's makes our lives easier creating good docs. I know this link is dead right now,
but it won't be once we release a new version with the documentation reorganization
changes (which should be soon!).
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
I know I know, this is the second reorganization of the docs. I'm not
saying the first one was bad or anything... but.. actually wait nah,
*it was bad*.
Anyway, welcome to probably my biggest commit. The main thing with this
reorganization was to introduce nesting to the documentation! Having
all of the docs be part of the main TOC was becoming too much. There
wasn't much room to expand either. Finally, the old setup required
a documentation generation step which was just annoying.
The goals of this reorganization was to:
1. Significantly restructure the docs to be discoverable and
understandable
2. Add room for further docs (like guides or contributing docs)
3. Get rid of the doc generation step (it was slow and frustrating)
4. Unblock other improvements and also just make contributing to the
docs easier
Another important change with this is that we are no longer using GitHub
as a documentation host. While GitHub does support Markdown based docs
actually pretty well, the lack of any features outside of GitHub Flavoured
Markdown is quite limiting. ReadTheDocs is just much better suited for
documentation. You can use reST, MyST, CommonMark, and all of their
great features like toctrees and admonitions.
Related to this change, we're adopting MyST as our flavour of Markdown.
MyST introduces neat syntax extensions to Markdown that pretty much
gives us the best of both worlds. The ease of use and simplicity of MD
and the flexibility and expressiveness of reST. Also recommonmark is
deprecated now. This switch was possible now we don't use GH as a docs
host. MyST docs have to be built to really be usable / pretty, so the MD
docs are going to look pretty bad on GH, but that's fine now!
Another thing that should be noted is that the README has been stripped
of most content since it was confusing. Users would read the README and
then think some feature or bug was fixed already and is available in a
release when in reality, they weren't. They were reading effectively
the latest docs without knowing.
See also: https://github.com/psf/black/issues/1759
FYI: CommonMark is a rationalized version of Markdown syntax
--
Commit history before merge:
* Switch to MyST-Parser + doc config cleanup
recommonmark is being deprecated in favour of MyST-Parser. This change
is welcomed, especially since MyST-Parser has syntax extensions for the
Commonmark standard. Effectively we get to use a language that's powerful
and expressive like ReST, but get the simplicity of Markdown.
The rest of this effort will be using some MyST features.
This reorganization efforts aims to remove as much duplication as possible.
The regeneration step once needed is gone, significantly simplifing our
Sphinx documentation configuration.
* Tell pipenv we replaced recommonmark for MyST-Parser
Also update `docs/requirements.txt`
* Delete all auto generated content
* Switch prettier for mdformat (plus a few plugins)
**FYI: THIS WAS EFFECTIVELY REVERTED, SEE THIRD TO LAST COMMIT**
prettier doesn't support MyST's syntax extensions which are going to be
used in this reorganization effort so we have to switch formatter.
Unfortanately mdformat's style is different from prettier's so time to
reformat the whole repo too.
We're excluding .github/ISSUE_TEMPLATE because I have no idea whether
its changes are safe, so let's play it safe.
* Fix the heading levels in CHANGES.md + a link
MyST-Parser / sphinx's linkcheck complains otherwise.
* Move reference docs into a docs/contributing dir
They're for contributors of Black anyway. Also added a note in the
summary document warning about the lack of attention the reference has
been dealing with.
* Rewrite and setup the new landing page + main TOC
- add some more detail about Black's beta status
- add licensing info
- add external links in the main TOC for GitHub, PyPI, and IRC
- prepare main TOC for new structure
* Break out AUTHORS into its own file
Not only was the AUTHORS list quite long, this makes it easy to include
it in the Sphinx docs with just a simple symlink.
* Add license to docs via a simple include
Yes the document is orphaned but it is linked to in the landing page
(docs/index.rst).
* Add "The Black Code Style" section
This mostly was a restructuring commit, there has been a few updates but
not many. The main goal was to split "current style" and "planned
changes to the style that haven't happened yet" to avoid confusion.
* Add "Getting Started" page
This is basically a quick start + even more. This commit is certainly
one of most creatively involved in this effort.
* Add "Usage and Configuration" section
This commit was as much restructuring as new content. Instead of being
in one giant file, usage and configuration documentation can expand
without bloating a single file.
* Add "Integrations" section
Just a restructuring commit ...
* Add "Guides" section
This is a promising area of documentation that could easily grow in the
future, let's prepare for that!
* Add "Contributing" section
This is also another area that I expect to see significant growth in.
Contributors to Black could definitely do with some more specific docs
that clears up certain parts of our slightly confusing project (it's
only confusing because we're getting big and old!).
* Rewrite CONTRIBUTING.md to just point to RTD
* Rewrite README.md to delegate most info to RTD
* Address feedback + a lot of corrections and edits
I know I said I wanted to do these after landing this but given there's
going to be no time between this being merged and a release getting
pushed, I want these changes to make it in.
- drop the number flag for mdformat - to reduce diffs, see also:
https://mdformat.readthedocs.io/en/stable/users/style.html#ordered-lists
- the GH issue templates should be safe by mdformat, so get rid of the
exclude
- clarify our configuration position - i.e. stop claiming we don't have
many options, instead say we want as little formatting knobs as
possible
- lots and lots of punctuation, spelling, and grammar corrections (thanks
Jelle!)
- use RTD as the source for the CHANGELOG too
- visual style cleanups
- add docs about our .gitignore behaviour
- expand GHA Action docs
- clarify we want the PR number in the CHANGELOG entry
- claify Black's behaviour for with statements post Python 3.9
- italicize a bunch of "Black"s
Thank you goes to Jelle, Taneli (hukkinj1 on GH), Felix
(felix-hilden on GH), and Wouter (wbolster on GH) for the feedback!
* Merge remote-tracking branch 'upstream/master' into reorganize-docs-v2
merge conflicts suck, although these ones weren't too bad.
* Add changelog entry + fix merge conflict resolution error
I consider this important enough to be worthy of a changelog entry :)
* Merge branch 'master' into reorganize-docs-v2
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
* Actually let's continue using prettier
Prettier works fine for all of the default MyST syntax so let's not
rock the boat as much. Dropping the mdformat commit was merge-conflict
filled so here's additional commit instead.
* Address Cooper's, Taneli's, and Jelle's feedback
Lots of wording improvements by Cooper. Taneli suggested to disable the
enabled by default MyST syntax not supported by Prettier and I agreed.
And Jelle found one more spelling error!
* More minor fixes
There's three optimizations in this commit:
1. Don't check if Black's output is stable or equivalant if no changes
were made in the first place. It's not like passing the same code
(for both source and actual) through black.assert_equivalent or
black.assert_stable is useful. It's not a big deal for the smaller
tests, but it eats a lot of time in tests/test_format.py since
its test cases are big. This is also closer to how Black works IRL.
2. Use a smaller file for `test_root_logger_not_used_directly` since
the logging it's checking happens during blib2to3's startup so the
file doesn't really matter.
3. If we're checking a file is formatting (i.e. test_source_is_formatted)
don't run Black over it again with `black.format_file_in_place`.
`tests/test_format.py::TestSimpleFormat.check_file` is good enough.
* Move string-related utility to functions to strings.py, const.py
* Move Leaf/Node-related functionality to nodes.py
* Move comment-related functions to comments.py
* Move caching to cache.py and Mode/TargetVersion/Feature to mode.py
* Move some leftover functions to nodes.py, comments.py, strings.py
* Add missing files to source list for test runs
* Move line-related functionality into lines.py, brackets into brackets.py
* Move transformers to trans.py
* Move file handling, output, parsing, concurrency, debug, and report
* Move two more functions to nodes.py
* Add CHANGES
* Add numeric.py
* Add linegen.py
* More docstrings
* Include new files in tests
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
* Speed up test suite via distributed testing
Since we now run the test suite twice, one with Python 2 and another
without, full test runs are getting pretty slow. Let's try to
fix that with parallization.
Also use verbose mode on CI since more logs is usually better since
getting more is quite literally impossible.
The main issue we'll face with this is we'll hit
https://github.com/pytest-dev/pytest-xdist/issues/620 sometimes
(although pretty rarely). I suppose we can test this and see if how bad
this bug is for us, and revert if necessary down the line.
Also let's have some colours 🎉
