%global _empty_manifest_terminate_build 0 Name: python-axblack Version: 20220330 Release: 1 Summary: The uncompromising code formatter (compromised version) License: MIT URL: https://github.com/axiros/axblack Source0: https://mirrors.nju.edu.cn/pypi/web/packages/c0/2f/050ce6a4c87db089ee7fc9117ab2ae8fbcd3bcec68eb4f5adcf1e5772b61/axblack-20220330.tar.gz BuildArch: noarch Requires: python3-click Requires: python3-attrs Requires: python3-appdirs Requires: python3-toml Requires: python3-typed-ast Requires: python3-regex Requires: python3-pathspec Requires: python3-typing-extensions Requires: python3-mypy-extensions Requires: python3-dataclasses Requires: python3-aiohttp Requires: python3-aiohttp-cors %description This is a forked alternative to the official [black](https://github.com/psf/black) formatter, which is a wonderful tool but (too?) [strict](https://github.com/psf/black/issues/118) about single quotes, ([very](https://github.com/psf/black/issues/51)) unfortunatelly. > We we are sure they'll change their minds one day, so this fork is not necessary any more - it is a workaround to bridge that time gap. Note: There are other forks as well, with yet more features, e.g. [oitnb](https://pypi.org/project/oitnb/) - orange is the new black. *This* fork is based on [this](https://github.com/psf/black/tree/fb1ac6981257c91a1d3bf753d10e1091f05b001a) psf/black version (2019-11-23). We will not merge in all code restructurings done in 2020. ## Performance This is based on a python only version of black. Meanwhile they compile it to C, gaining some 25-30% performance, compared to axblack. You'll notice a difference only at huge file sizes. Tip: Configure your code formatter to run [async][lfn] at file save. [lfn]: https://github.com/lukas-reineke/lsp-format.nvim ## Background 1. The argument that one unified style **would** be superbeneficial for the whole community we do share - BUT: While line length **is** still configurable that goal cannot be reached anyway, even with opinionated fixed quoting style. Also with the new (since 20.x?) 'line wrap at trailing comma feature' they actually allow a lot of individual 'creative freedom', regarding how code looks. 2. The reason why the black author [changed his mind](https://github.com/psf/black/issues/51#issuecomment-375722810_) away from using single quotes: [pull request/75](https://github.com/psf/black/pull/75#issuecomment-376203386_) was this example: `{MESSAGE.two: "Please don't look over there."}`. We ~~don't~~ do not think, that this example is justifying the strict rejection of the idea of making quoting style even configurable. 3. You are not alone if you prefer single quotes: > [If you use single-quotes for your strings you are in good company: “People use to really love double quotes. I don’t know why.. ](https://www.youtube.com/watch?v=wf-BqAjZb8M&feature=youtu.be&t=1081) [![](https://raw.githubusercontent.com/axiros/axblack/master/docs/_static/ht_tw.png)](https://twitter.com/raymondh/status/1259209765072154624) ```python >>> """"""'what do you prefer'"""""" 'what do you prefer' ``` ## Deviations ### Single Quotes Single quotes are default. Patch is based on this [PR](https://github.com/psf/black/pull/1003). ### Configured Excludes Always Respected When you explitely specify excludes in a toml file, then we respect them *always* - even if a file is given on the CLI. #### Rationale: The list of files to be formatted are often *dynamically* built, e.g.: black `git diff --name-only --diff-filter=ACM` We must in such cases still respect the exclude list, even if files had been changed (e.g. from ZODB dumps). ### Project root kept at path of pyproject.toml When you configure explicitely (via `--config`) a pyproject.toml file, then its path will fix the project root, relevant for regex matching the excludes (see above). Otherwise black would reset the project root per passed file, which is a problem when it finds e.g. subrepos' .git or .hg folders. ### Different Versioning No pre-release foo. - [here](https://github.com/psf/black/issues/209) - [here](https://github.com/microsoft/vscode-python/issues/5171) - [here](https://github.com/microsoft/vscode-python/issues/5756) - [here](https://github.com/psf/black/issues/517) regarding why. We leave the calver style versioning scheme, but w/o dots, to indicate that this is not a "real" project. > Yes this is [PEP-440](https://www.python.org/dev/peps/pep-0440/) compatible. > And yes, we (meanwhile) know that [pipenv](https://chriswarrick.com/blog/2018/07/17/pipenv-promises-a-lot-delivers-very-little/) has a problem with such versions and `^`. Here you have to pin it. # Notes We wanted to keep the offset minimal and not deviate more than necessary. Therefore via the vim plugin and also the blackd server you do not have the option to set double quotes - you have to use the `--double-quotes` command line flag as only way to get them. Should you prefer them for private projects or find them in project policies, by any means, use the official black version then. Q: Why not rename black into axblack to allow coexistance? A: Because black is builtin-supported by [many](https://github.com/dense-analysis/ale/blob/master/doc/ale-python.txt ) tools, which rely on that name. Meaning you need seperate python environments in order to use both on one host. Tip: When a tool has a dependency on the official version than nail it to `18.6b4`, e.g. in pyproject.toml: ```toml [tool.poetry.dev-dependencies] autoflake = "^1.4" axblack = "^20201010" black = "18.6b4" ``` Since axblack still is installed into site-packges directly, while newer version of black are in a subfolder there.
Changelog [2022-03-30 13:33] - Removed the `_unicodefun` patching of click (https://github.com/axiros/axblack/issues/16) [ 2022-03-21 14:47] - Added an unprocessed `--stdin-filename` CLI switch, since some LSP servers (e.g. null-ls) send it [2020-10-09 19:31] - Changed the triple quote behaviour (keep them only in simple statements like docstrings but not assignments). See https://github.com/axiros/axblack/issues/6 [2019-12-12 12:57] - Changed the exclude behaviour: When exclude given in .toml file we *always* respect it - even if a file is excplitely given on CLI for formats. [2019-11-24 11:21] - Set single_quotes as default in black.py `class File`, so that it works also in vim. [2019-11-24 11:21] - Recreated repo as direct fork of psf/black, with adapted master branch for easier future merges from them (and getting their newest improvements) [2019-11-23 21:16] - Dropped the -s in favor of the long argument "double-quotes" - to never collide with any argument of theirs. Default for double-quotes: False - Bugfixed the parsing of single-quotes - Added the [cf](./ax/cf) tool. [2019-11-23 18:05] - Added more README (Usage) [2019-11-23 15:05] Initial version after: - `git clone https://github.com/mark-riley/black.git axblack` - `git reset --hard configure-quote-style` - `git reset --hard remotes/origin/configure-quote-style` - Set `default=True` into black.py - Created axblack pip and pushed to pypi.
## Installation `pip install axblack` into a python3 v(irtual)env or conda environment. See also original docu below - exchange "psf/black" with "axiros/axblack". ### Vim Setup Install black into a python environment and refer to it via `g:black_virtualenv` as shown in the example, then the plugin will install a venv into .vim/black! Also, note that it proves very handy to have formatting being done at each file write.
Suggested vim setup ```vim Plug 'axiros/axblack' " not black related but useful: autocmd FileType python map e Otry:j^ioexcept Exception as ex:print('breakpoint set')breakpoint()keep_ctx=True^ " defaults: let g:black_linelength = 88 let g:black_fast = 1 " set appropriately: let g:black_virtualenv = "" " Clean whitespace at saves: "autocmd BufWritePre * execute ':RemoveWhitespace' fun! Blackify() if &ft =~ 'python' endif endfun " blackify at any write of a python file: autocmd BufWritePre * call Blackify() " Using pythonmode? Keep it happy: let g:pymode_options_max_line_length = 88 let g:pymode_lint_options_pep8 = {'max_line_length': g:pymode_options_max_line_length} let g:pymode_options_colorcolumn = 1 ```
### Usage In Projects #### pyproject.toml Create a `pyproject.toml` file in the toplevel directory of your project as shown below and adapt the exclude directories according to your needs.
Example `pyproject.toml` Add a note for using axblack to avoid confusion: ```toml [tool.black] # using pip install axblack for single_quotes line-length = 88 target-version = ['py27'] include = '\.pyi?$' exclude = ''' ( /( \.eggs # exclude a few common directories in the | \.git # root of the project | \.hg | \.mypy_cache | \.tox | \.venv | _build | build | dist )/ | (.*)/foo.py # also separately exclude a files named foo.py ) ''' ```
Then `black .` will reformat from the current directory, recursively (not above this directory). If you have a mix of python2 and python3 in your project then create a specific `pyproject.toml` within the respective top level directory and run black for each of them seperately. black always searching up the specified directory on the command line for the first project toml file and uses it. #### Conversion of Large Existing Code Bases Black ensures to not break anything, by comparing ASTs before and after formatting - which slows it down a bit. If the code base is large you want to normally have **fast** mode on, therefore, in daily work. This is what you do: 1. Create your project toml file with excludes which shall *never* be formattet. 1. Run black with `--safe` on. If all can be converted then good, you can add `--fast` from now on or put it even into your toml file. Should you have errors from the AST check then, **before** any run in fast mode either - exclude those files within the toml - fix them. From experience this often hints to bugs. Example: ``` error: cannot format .../sleekxmpp/thirdparty/gnupg.py: INTERNAL ERROR: Black produced different code on the second pass of the formatter. ``` Again: **Do not run black in fast mode if you had errors in safe mode!** It will produce source code which is potentially off, behaviourally, from the original! #### Coding Policy Enforcement With more collaborateurs on the same repo (e.g. at a customer site) you may want to consider enforcing your code style via a repo hook:
Repo Hook Example ```bash # cat .git/hooks/pre-commit #!/bin/sh # We reject any commit for unformatted source code # We can't fix here since we might have partial hunks, which after reformat, which is # global, would differ in the non committed hunks from the state in the FS: black="/agent/py3/bin/black" # adapt to your environment git diff --cached --name-only --diff-filter=ACM | while read -r fn do echo "Format check: $fn" "$black" --check "$fn" > /dev/null || exit 1 echo "Accepted." done || { echo "Commit rejected - not all files formatted correctly." echo "Please do so now: $black -h" exit 1 } ```

## Wrapper Tool If you - can't adopt pyproject.toml but want to stick to shell sourceable config and /or environ based config - require composition of such config - easily want to run in client server mode, for speed - require automatically created skip lists then have a look at [this](./ax/cf) code formatter tool we created, which wraps black and blackd. > The tool is not installed by pip currently. %package -n python3-axblack Summary: The uncompromising code formatter (compromised version) Provides: python-axblack BuildRequires: python3-devel BuildRequires: python3-setuptools BuildRequires: python3-pip %description -n python3-axblack This is a forked alternative to the official [black](https://github.com/psf/black) formatter, which is a wonderful tool but (too?) [strict](https://github.com/psf/black/issues/118) about single quotes, ([very](https://github.com/psf/black/issues/51)) unfortunatelly. > We we are sure they'll change their minds one day, so this fork is not necessary any more - it is a workaround to bridge that time gap. Note: There are other forks as well, with yet more features, e.g. [oitnb](https://pypi.org/project/oitnb/) - orange is the new black. *This* fork is based on [this](https://github.com/psf/black/tree/fb1ac6981257c91a1d3bf753d10e1091f05b001a) psf/black version (2019-11-23). We will not merge in all code restructurings done in 2020. ## Performance This is based on a python only version of black. Meanwhile they compile it to C, gaining some 25-30% performance, compared to axblack. You'll notice a difference only at huge file sizes. Tip: Configure your code formatter to run [async][lfn] at file save. [lfn]: https://github.com/lukas-reineke/lsp-format.nvim ## Background 1. The argument that one unified style **would** be superbeneficial for the whole community we do share - BUT: While line length **is** still configurable that goal cannot be reached anyway, even with opinionated fixed quoting style. Also with the new (since 20.x?) 'line wrap at trailing comma feature' they actually allow a lot of individual 'creative freedom', regarding how code looks. 2. The reason why the black author [changed his mind](https://github.com/psf/black/issues/51#issuecomment-375722810_) away from using single quotes: [pull request/75](https://github.com/psf/black/pull/75#issuecomment-376203386_) was this example: `{MESSAGE.two: "Please don't look over there."}`. We ~~don't~~ do not think, that this example is justifying the strict rejection of the idea of making quoting style even configurable. 3. You are not alone if you prefer single quotes: > [If you use single-quotes for your strings you are in good company: “People use to really love double quotes. I don’t know why.. ](https://www.youtube.com/watch?v=wf-BqAjZb8M&feature=youtu.be&t=1081) [![](https://raw.githubusercontent.com/axiros/axblack/master/docs/_static/ht_tw.png)](https://twitter.com/raymondh/status/1259209765072154624) ```python >>> """"""'what do you prefer'"""""" 'what do you prefer' ``` ## Deviations ### Single Quotes Single quotes are default. Patch is based on this [PR](https://github.com/psf/black/pull/1003). ### Configured Excludes Always Respected When you explitely specify excludes in a toml file, then we respect them *always* - even if a file is given on the CLI. #### Rationale: The list of files to be formatted are often *dynamically* built, e.g.: black `git diff --name-only --diff-filter=ACM` We must in such cases still respect the exclude list, even if files had been changed (e.g. from ZODB dumps). ### Project root kept at path of pyproject.toml When you configure explicitely (via `--config`) a pyproject.toml file, then its path will fix the project root, relevant for regex matching the excludes (see above). Otherwise black would reset the project root per passed file, which is a problem when it finds e.g. subrepos' .git or .hg folders. ### Different Versioning No pre-release foo. - [here](https://github.com/psf/black/issues/209) - [here](https://github.com/microsoft/vscode-python/issues/5171) - [here](https://github.com/microsoft/vscode-python/issues/5756) - [here](https://github.com/psf/black/issues/517) regarding why. We leave the calver style versioning scheme, but w/o dots, to indicate that this is not a "real" project. > Yes this is [PEP-440](https://www.python.org/dev/peps/pep-0440/) compatible. > And yes, we (meanwhile) know that [pipenv](https://chriswarrick.com/blog/2018/07/17/pipenv-promises-a-lot-delivers-very-little/) has a problem with such versions and `^`. Here you have to pin it. # Notes We wanted to keep the offset minimal and not deviate more than necessary. Therefore via the vim plugin and also the blackd server you do not have the option to set double quotes - you have to use the `--double-quotes` command line flag as only way to get them. Should you prefer them for private projects or find them in project policies, by any means, use the official black version then. Q: Why not rename black into axblack to allow coexistance? A: Because black is builtin-supported by [many](https://github.com/dense-analysis/ale/blob/master/doc/ale-python.txt ) tools, which rely on that name. Meaning you need seperate python environments in order to use both on one host. Tip: When a tool has a dependency on the official version than nail it to `18.6b4`, e.g. in pyproject.toml: ```toml [tool.poetry.dev-dependencies] autoflake = "^1.4" axblack = "^20201010" black = "18.6b4" ``` Since axblack still is installed into site-packges directly, while newer version of black are in a subfolder there.
Changelog [2022-03-30 13:33] - Removed the `_unicodefun` patching of click (https://github.com/axiros/axblack/issues/16) [ 2022-03-21 14:47] - Added an unprocessed `--stdin-filename` CLI switch, since some LSP servers (e.g. null-ls) send it [2020-10-09 19:31] - Changed the triple quote behaviour (keep them only in simple statements like docstrings but not assignments). See https://github.com/axiros/axblack/issues/6 [2019-12-12 12:57] - Changed the exclude behaviour: When exclude given in .toml file we *always* respect it - even if a file is excplitely given on CLI for formats. [2019-11-24 11:21] - Set single_quotes as default in black.py `class File`, so that it works also in vim. [2019-11-24 11:21] - Recreated repo as direct fork of psf/black, with adapted master branch for easier future merges from them (and getting their newest improvements) [2019-11-23 21:16] - Dropped the -s in favor of the long argument "double-quotes" - to never collide with any argument of theirs. Default for double-quotes: False - Bugfixed the parsing of single-quotes - Added the [cf](./ax/cf) tool. [2019-11-23 18:05] - Added more README (Usage) [2019-11-23 15:05] Initial version after: - `git clone https://github.com/mark-riley/black.git axblack` - `git reset --hard configure-quote-style` - `git reset --hard remotes/origin/configure-quote-style` - Set `default=True` into black.py - Created axblack pip and pushed to pypi.
## Installation `pip install axblack` into a python3 v(irtual)env or conda environment. See also original docu below - exchange "psf/black" with "axiros/axblack". ### Vim Setup Install black into a python environment and refer to it via `g:black_virtualenv` as shown in the example, then the plugin will install a venv into .vim/black! Also, note that it proves very handy to have formatting being done at each file write.
Suggested vim setup ```vim Plug 'axiros/axblack' " not black related but useful: autocmd FileType python map e Otry:j^ioexcept Exception as ex:print('breakpoint set')breakpoint()keep_ctx=True^ " defaults: let g:black_linelength = 88 let g:black_fast = 1 " set appropriately: let g:black_virtualenv = "" " Clean whitespace at saves: "autocmd BufWritePre * execute ':RemoveWhitespace' fun! Blackify() if &ft =~ 'python' endif endfun " blackify at any write of a python file: autocmd BufWritePre * call Blackify() " Using pythonmode? Keep it happy: let g:pymode_options_max_line_length = 88 let g:pymode_lint_options_pep8 = {'max_line_length': g:pymode_options_max_line_length} let g:pymode_options_colorcolumn = 1 ```
### Usage In Projects #### pyproject.toml Create a `pyproject.toml` file in the toplevel directory of your project as shown below and adapt the exclude directories according to your needs.
Example `pyproject.toml` Add a note for using axblack to avoid confusion: ```toml [tool.black] # using pip install axblack for single_quotes line-length = 88 target-version = ['py27'] include = '\.pyi?$' exclude = ''' ( /( \.eggs # exclude a few common directories in the | \.git # root of the project | \.hg | \.mypy_cache | \.tox | \.venv | _build | build | dist )/ | (.*)/foo.py # also separately exclude a files named foo.py ) ''' ```
Then `black .` will reformat from the current directory, recursively (not above this directory). If you have a mix of python2 and python3 in your project then create a specific `pyproject.toml` within the respective top level directory and run black for each of them seperately. black always searching up the specified directory on the command line for the first project toml file and uses it. #### Conversion of Large Existing Code Bases Black ensures to not break anything, by comparing ASTs before and after formatting - which slows it down a bit. If the code base is large you want to normally have **fast** mode on, therefore, in daily work. This is what you do: 1. Create your project toml file with excludes which shall *never* be formattet. 1. Run black with `--safe` on. If all can be converted then good, you can add `--fast` from now on or put it even into your toml file. Should you have errors from the AST check then, **before** any run in fast mode either - exclude those files within the toml - fix them. From experience this often hints to bugs. Example: ``` error: cannot format .../sleekxmpp/thirdparty/gnupg.py: INTERNAL ERROR: Black produced different code on the second pass of the formatter. ``` Again: **Do not run black in fast mode if you had errors in safe mode!** It will produce source code which is potentially off, behaviourally, from the original! #### Coding Policy Enforcement With more collaborateurs on the same repo (e.g. at a customer site) you may want to consider enforcing your code style via a repo hook:
Repo Hook Example ```bash # cat .git/hooks/pre-commit #!/bin/sh # We reject any commit for unformatted source code # We can't fix here since we might have partial hunks, which after reformat, which is # global, would differ in the non committed hunks from the state in the FS: black="/agent/py3/bin/black" # adapt to your environment git diff --cached --name-only --diff-filter=ACM | while read -r fn do echo "Format check: $fn" "$black" --check "$fn" > /dev/null || exit 1 echo "Accepted." done || { echo "Commit rejected - not all files formatted correctly." echo "Please do so now: $black -h" exit 1 } ```

## Wrapper Tool If you - can't adopt pyproject.toml but want to stick to shell sourceable config and /or environ based config - require composition of such config - easily want to run in client server mode, for speed - require automatically created skip lists then have a look at [this](./ax/cf) code formatter tool we created, which wraps black and blackd. > The tool is not installed by pip currently. %package help Summary: Development documents and examples for axblack Provides: python3-axblack-doc %description help This is a forked alternative to the official [black](https://github.com/psf/black) formatter, which is a wonderful tool but (too?) [strict](https://github.com/psf/black/issues/118) about single quotes, ([very](https://github.com/psf/black/issues/51)) unfortunatelly. > We we are sure they'll change their minds one day, so this fork is not necessary any more - it is a workaround to bridge that time gap. Note: There are other forks as well, with yet more features, e.g. [oitnb](https://pypi.org/project/oitnb/) - orange is the new black. *This* fork is based on [this](https://github.com/psf/black/tree/fb1ac6981257c91a1d3bf753d10e1091f05b001a) psf/black version (2019-11-23). We will not merge in all code restructurings done in 2020. ## Performance This is based on a python only version of black. Meanwhile they compile it to C, gaining some 25-30% performance, compared to axblack. You'll notice a difference only at huge file sizes. Tip: Configure your code formatter to run [async][lfn] at file save. [lfn]: https://github.com/lukas-reineke/lsp-format.nvim ## Background 1. The argument that one unified style **would** be superbeneficial for the whole community we do share - BUT: While line length **is** still configurable that goal cannot be reached anyway, even with opinionated fixed quoting style. Also with the new (since 20.x?) 'line wrap at trailing comma feature' they actually allow a lot of individual 'creative freedom', regarding how code looks. 2. The reason why the black author [changed his mind](https://github.com/psf/black/issues/51#issuecomment-375722810_) away from using single quotes: [pull request/75](https://github.com/psf/black/pull/75#issuecomment-376203386_) was this example: `{MESSAGE.two: "Please don't look over there."}`. We ~~don't~~ do not think, that this example is justifying the strict rejection of the idea of making quoting style even configurable. 3. You are not alone if you prefer single quotes: > [If you use single-quotes for your strings you are in good company: “People use to really love double quotes. I don’t know why.. ](https://www.youtube.com/watch?v=wf-BqAjZb8M&feature=youtu.be&t=1081) [![](https://raw.githubusercontent.com/axiros/axblack/master/docs/_static/ht_tw.png)](https://twitter.com/raymondh/status/1259209765072154624) ```python >>> """"""'what do you prefer'"""""" 'what do you prefer' ``` ## Deviations ### Single Quotes Single quotes are default. Patch is based on this [PR](https://github.com/psf/black/pull/1003). ### Configured Excludes Always Respected When you explitely specify excludes in a toml file, then we respect them *always* - even if a file is given on the CLI. #### Rationale: The list of files to be formatted are often *dynamically* built, e.g.: black `git diff --name-only --diff-filter=ACM` We must in such cases still respect the exclude list, even if files had been changed (e.g. from ZODB dumps). ### Project root kept at path of pyproject.toml When you configure explicitely (via `--config`) a pyproject.toml file, then its path will fix the project root, relevant for regex matching the excludes (see above). Otherwise black would reset the project root per passed file, which is a problem when it finds e.g. subrepos' .git or .hg folders. ### Different Versioning No pre-release foo. - [here](https://github.com/psf/black/issues/209) - [here](https://github.com/microsoft/vscode-python/issues/5171) - [here](https://github.com/microsoft/vscode-python/issues/5756) - [here](https://github.com/psf/black/issues/517) regarding why. We leave the calver style versioning scheme, but w/o dots, to indicate that this is not a "real" project. > Yes this is [PEP-440](https://www.python.org/dev/peps/pep-0440/) compatible. > And yes, we (meanwhile) know that [pipenv](https://chriswarrick.com/blog/2018/07/17/pipenv-promises-a-lot-delivers-very-little/) has a problem with such versions and `^`. Here you have to pin it. # Notes We wanted to keep the offset minimal and not deviate more than necessary. Therefore via the vim plugin and also the blackd server you do not have the option to set double quotes - you have to use the `--double-quotes` command line flag as only way to get them. Should you prefer them for private projects or find them in project policies, by any means, use the official black version then. Q: Why not rename black into axblack to allow coexistance? A: Because black is builtin-supported by [many](https://github.com/dense-analysis/ale/blob/master/doc/ale-python.txt ) tools, which rely on that name. Meaning you need seperate python environments in order to use both on one host. Tip: When a tool has a dependency on the official version than nail it to `18.6b4`, e.g. in pyproject.toml: ```toml [tool.poetry.dev-dependencies] autoflake = "^1.4" axblack = "^20201010" black = "18.6b4" ``` Since axblack still is installed into site-packges directly, while newer version of black are in a subfolder there.
Changelog [2022-03-30 13:33] - Removed the `_unicodefun` patching of click (https://github.com/axiros/axblack/issues/16) [ 2022-03-21 14:47] - Added an unprocessed `--stdin-filename` CLI switch, since some LSP servers (e.g. null-ls) send it [2020-10-09 19:31] - Changed the triple quote behaviour (keep them only in simple statements like docstrings but not assignments). See https://github.com/axiros/axblack/issues/6 [2019-12-12 12:57] - Changed the exclude behaviour: When exclude given in .toml file we *always* respect it - even if a file is excplitely given on CLI for formats. [2019-11-24 11:21] - Set single_quotes as default in black.py `class File`, so that it works also in vim. [2019-11-24 11:21] - Recreated repo as direct fork of psf/black, with adapted master branch for easier future merges from them (and getting their newest improvements) [2019-11-23 21:16] - Dropped the -s in favor of the long argument "double-quotes" - to never collide with any argument of theirs. Default for double-quotes: False - Bugfixed the parsing of single-quotes - Added the [cf](./ax/cf) tool. [2019-11-23 18:05] - Added more README (Usage) [2019-11-23 15:05] Initial version after: - `git clone https://github.com/mark-riley/black.git axblack` - `git reset --hard configure-quote-style` - `git reset --hard remotes/origin/configure-quote-style` - Set `default=True` into black.py - Created axblack pip and pushed to pypi.
## Installation `pip install axblack` into a python3 v(irtual)env or conda environment. See also original docu below - exchange "psf/black" with "axiros/axblack". ### Vim Setup Install black into a python environment and refer to it via `g:black_virtualenv` as shown in the example, then the plugin will install a venv into .vim/black! Also, note that it proves very handy to have formatting being done at each file write.
Suggested vim setup ```vim Plug 'axiros/axblack' " not black related but useful: autocmd FileType python map e Otry:j^ioexcept Exception as ex:print('breakpoint set')breakpoint()keep_ctx=True^ " defaults: let g:black_linelength = 88 let g:black_fast = 1 " set appropriately: let g:black_virtualenv = "" " Clean whitespace at saves: "autocmd BufWritePre * execute ':RemoveWhitespace' fun! Blackify() if &ft =~ 'python' endif endfun " blackify at any write of a python file: autocmd BufWritePre * call Blackify() " Using pythonmode? Keep it happy: let g:pymode_options_max_line_length = 88 let g:pymode_lint_options_pep8 = {'max_line_length': g:pymode_options_max_line_length} let g:pymode_options_colorcolumn = 1 ```
### Usage In Projects #### pyproject.toml Create a `pyproject.toml` file in the toplevel directory of your project as shown below and adapt the exclude directories according to your needs.
Example `pyproject.toml` Add a note for using axblack to avoid confusion: ```toml [tool.black] # using pip install axblack for single_quotes line-length = 88 target-version = ['py27'] include = '\.pyi?$' exclude = ''' ( /( \.eggs # exclude a few common directories in the | \.git # root of the project | \.hg | \.mypy_cache | \.tox | \.venv | _build | build | dist )/ | (.*)/foo.py # also separately exclude a files named foo.py ) ''' ```
Then `black .` will reformat from the current directory, recursively (not above this directory). If you have a mix of python2 and python3 in your project then create a specific `pyproject.toml` within the respective top level directory and run black for each of them seperately. black always searching up the specified directory on the command line for the first project toml file and uses it. #### Conversion of Large Existing Code Bases Black ensures to not break anything, by comparing ASTs before and after formatting - which slows it down a bit. If the code base is large you want to normally have **fast** mode on, therefore, in daily work. This is what you do: 1. Create your project toml file with excludes which shall *never* be formattet. 1. Run black with `--safe` on. If all can be converted then good, you can add `--fast` from now on or put it even into your toml file. Should you have errors from the AST check then, **before** any run in fast mode either - exclude those files within the toml - fix them. From experience this often hints to bugs. Example: ``` error: cannot format .../sleekxmpp/thirdparty/gnupg.py: INTERNAL ERROR: Black produced different code on the second pass of the formatter. ``` Again: **Do not run black in fast mode if you had errors in safe mode!** It will produce source code which is potentially off, behaviourally, from the original! #### Coding Policy Enforcement With more collaborateurs on the same repo (e.g. at a customer site) you may want to consider enforcing your code style via a repo hook:
Repo Hook Example ```bash # cat .git/hooks/pre-commit #!/bin/sh # We reject any commit for unformatted source code # We can't fix here since we might have partial hunks, which after reformat, which is # global, would differ in the non committed hunks from the state in the FS: black="/agent/py3/bin/black" # adapt to your environment git diff --cached --name-only --diff-filter=ACM | while read -r fn do echo "Format check: $fn" "$black" --check "$fn" > /dev/null || exit 1 echo "Accepted." done || { echo "Commit rejected - not all files formatted correctly." echo "Please do so now: $black -h" exit 1 } ```

## Wrapper Tool If you - can't adopt pyproject.toml but want to stick to shell sourceable config and /or environ based config - require composition of such config - easily want to run in client server mode, for speed - require automatically created skip lists then have a look at [this](./ax/cf) code formatter tool we created, which wraps black and blackd. > The tool is not installed by pip currently. %prep %autosetup -n axblack-20220330 %build %py3_build %install %py3_install install -d -m755 %{buildroot}/%{_pkgdocdir} if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi pushd %{buildroot} if [ -d usr/lib ]; then find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/lib64 ]; then find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/bin ]; then find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst fi if [ -d usr/sbin ]; then find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst fi touch doclist.lst if [ -d usr/share/man ]; then find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst fi popd mv %{buildroot}/filelist.lst . mv %{buildroot}/doclist.lst . %files -n python3-axblack -f filelist.lst %dir %{python3_sitelib}/* %files help -f doclist.lst %{_docdir}/* %changelog * Mon May 29 2023 Python_Bot - 20220330-1 - Package Spec generated