Metadata-Version: 2.1
Name: darker
Version: 1.4.0
Summary: Apply Black formatting only in regions changed since last commit
Home-page: https://github.com/akaihola/darker
Author: Antti Kaihola
Author-email: 13725+akaihola@users.noreply.github.com
License: BSD
Project-URL: Source Code, https://github.com/akaihola/darker
Project-URL: Change Log, https://github.com/akaihola/darker/blob/master/CHANGES.rst
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
Provides-Extra: isort
Provides-Extra: test
License-File: LICENSE.rst

=================================================
 Darker – reformat and lint modified Python code
=================================================

|build-badge|_ |license-badge|_ |pypi-badge|_ |downloads-badge|_ |black-badge|_ |changelog-badge|_

.. |build-badge| image:: https://github.com/akaihola/darker/actions/workflows/python-package.yml/badge.svg
   :alt: master branch build status
.. _build-badge: https://github.com/akaihola/darker/actions/workflows/python-package.yml?query=branch%3Amaster
.. |license-badge| image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
   :alt: BSD 3 Clause license
.. _license-badge: https://github.com/akaihola/darker/blob/master/LICENSE.rst
.. |pypi-badge| image:: https://img.shields.io/pypi/v/darker
   :alt: Latest release on PyPI
.. _pypi-badge: https://pypi.org/project/darker/
.. |downloads-badge| image:: https://pepy.tech/badge/darker
   :alt: Number of downloads
.. _downloads-badge: https://pepy.tech/project/darker
.. |black-badge| image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :alt: Source code formatted using Black
.. _black-badge: https://github.com/psf/black
.. |changelog-badge| image:: https://img.shields.io/badge/-change%20log-purple
   :alt: Change log
.. _changelog-badge: https://github.com/akaihola/darker/blob/master/CHANGES.rst
.. |next-milestone| image:: https://img.shields.io/github/milestones/progress/akaihola/darker/12?color=red&label=release%201.4.1
   :alt: Next milestone
.. _next-milestone: https://github.com/akaihola/darker/milestone/12


What?
=====

This utility reformats and checks Python source code files.
However, when run in a Git repository, it only applies reformatting and reports errors
in regions which have changed in the Git working tree since the last commit.

The reformatters supported are:

- Black_ for code reformatting
- isort_ for sorting imports

See `Using linters`_ below for the list of supported linters.

.. _Black: https://github.com/python/black
.. _isort: https://github.com/timothycrosley/isort


.. _#151: https://github.com/akaihola/darker/issues/151

Why?
====

You want to start unifying code style in your project using Black_.
Maybe you also like to standardize on how to order your imports,
or do static type checking or other static analysis for your code.

However, instead of formatting the whole code base in one giant commit,
you'd like to only change formatting when you're touching the code for other reasons.

This can also be useful
when contributing to upstream codebases that are not under your complete control.

Partial formatting is not supported by Black_ itself,
for various good reasons, and so far there hasn't been a plan to implemented it either
(`134`__, `142`__, `245`__, `370`__, `511`__, `830`__).
However, in September 2021 Black developers started to hint towards adding this feature
after all (`1352`__). This might at least simplify Darker's algorithm substantially.

__ https://github.com/psf/black/issues/134
__ https://github.com/psf/black/issues/142
__ https://github.com/psf/black/issues/245
__ https://github.com/psf/black/issues/370
__ https://github.com/psf/black/issues/511
__ https://github.com/psf/black/issues/830
__ https://github.com/psf/black/issues/1352

But for the time being, this is where ``darker`` enters the stage.
This tool is for those who want to do partial formatting right now.

Note that this tool is meant for special situations
when dealing with existing code bases.
You should just use Black_ and isort_ as is when starting a project from scratch.

How?
====

To install, use::

  pip install darker

Or, if you're using Conda_ for package management::

  conda install -c conda-forge darker isort

The ``darker <myfile.py>`` or ``darker <directory>`` command
reads the original file(s),
formats them using Black_,
combines original and formatted regions based on edits,
and writes back over the original file(s).

Alternatively, you can invoke the module directly through the ``python`` executable,
which may be preferable depending on your setup.
Use ``python -m darker`` instead of ``darker`` in that case.

By default, ``darker`` just runs Black_ to reformat the code.
You can enable additional features with command line options:

- ``-i`` / ``--isort``: Reorder imports using isort_
- ``-L <linter>`` / ``--lint <linter>``: Run a supported linter (see `Using linters`_)

*New in version 1.1.0:* The ``-L`` / ``--lint`` option.
*New in version 1.2.2:* Package available in conda-forge_.

.. _Conda: https://conda.io/
.. _conda-forge: https://conda-forge.org/


Example
=======

This example walks you through a minimal practical use case for Darker.

First, create an empty Git repository:

.. code-block:: shell

   $ mkdir /tmp/test
   $ cd /tmp/test
   $ git init
   Initialized empty Git repository in /tmp/test/.git/

In the root of that directory, create the ill-formatted Python file ``our_file.py``:

.. code-block:: python

   if True: print('hi')
   print()
   if False: print('there')

Commit that file:

.. code-block:: shell

   $ git add our_file.py
   $ git commit -m "Initial commit"
   [master (root-commit) a0c7c32] Initial commit
    1 file changed, 3 insertions(+)
    create mode 100644 our_file.py

Now modify the first line in that file:

.. code-block:: python

   if True: print('CHANGED TEXT')
   print()
   if False: print('there')

You can ask Darker to show the diff for minimal reformatting
which makes edited lines conform to Black rules:

.. code-block:: diff

   $ darker --diff our_file.py
   --- our_file.py
   +++ our_file.py
   @@ -1,3 +1,4 @@
   -if True: print('CHANGED TEXT')
   +if True:
   +    print("CHANGED TEXT")
   print()
   if False: print('there')

Alternatively, Darker can output the full reformatted file
(works only when a single Python file is provided on the command line):

.. code-block:: python

   $ darker --stdout our_file.py
   if True:
       print("CHANGED TEXT")
   print()
   if False: print('there')

If you omit the ``--diff`` and ``--stdout`` options,
Darker replaces the files listed on the command line
with partially reformatted ones as shown above:

.. code-block:: shell

   $ darker our_file.py

Now the contents of ``our_file.py`` will have changed.
Note that the original ``print()`` and ``if False: ...`` lines have not been reformatted
since they had not been edited!

.. code-block:: python

   if True:
       print("CHANGED TEXT")
   print()
   if False: print('there')

You can also ask Darker to reformat edited lines in all Python files in the repository:

.. code-block:: shell

   $ darker .

Or, if you want to compare to another branch (or, in fact, any commit)
instead of the last commit:

.. code-block:: shell

   $ darker --revision master .


Customizing ``darker``, Black and isort behavior
================================================

Project-specific default options for ``darker``, Black_ and isort_
are read from the project's ``pyproject.toml`` file in the repository root.
isort_ also looks for a few other places for configuration.

Darker does honor exclusion options in Black configuration files when recursing
directories, but the exclusions are only applied to Black reformatting. Isort and
linters are still run on excluded files. Also, individual files explicitly listed on the
command line are still reformatted even if they match exclusion patterns.

For more details, see:

- `Black documentation about pyproject.toml`_
- `isort documentation about config files`_

The following `command line arguments`_ can also be used to modify the defaults:

-r REV, --revision REV
       Git revision against which to compare the working tree. Tags, branch names,
       commit hashes, and other expressions like ``HEAD~5`` work here. Also a range like
       ``master...HEAD`` or ``master...`` can be used to compare the best common
       ancestor. With the magic value ``:PRE-COMMIT:``, Darker works in pre-commit
       compatible mode. Darker expects the revision range from the
       ``PRE_COMMIT_FROM_REF`` and ``PRE_COMMIT_TO_REF`` environment variables. If those
       are not found, Darker works against ``HEAD``.
--diff
       Don't write the files back, just output a diff for each file on stdout. Highlight
       syntax on screen if the ``pygments`` package is available.
-d, --stdout
       Force complete reformatted output to stdout, instead of in-place. Only valid if
       there's just one file to reformat.
--check
       Don't write the files back, just return the status. Return code 0 means nothing
       would change. Return code 1 means some files would be reformatted.
-i, --isort
       Also sort imports using the ``isort`` package
-L CMD, --lint CMD
       Also run a linter on changed files. ``CMD`` can be a name of path of the linter
       binary, or a full quoted command line
-c PATH, --config PATH
       Ask ``black`` and ``isort`` to read configuration from ``PATH``.
-v, --verbose
       Show steps taken and summarize modifications
-q, --quiet
       Reduce amount of output
-S, --skip-string-normalization
       Don't normalize string quotes or prefixes
--no-skip-string-normalization
       Normalize string quotes or prefixes. This can be used to override
       ``skip_string_normalization = true`` from a configuration file.
--skip-magic-trailing-comma
       Skip adding trailing commas to expressions that are split by comma where each
       element is on its own line. This includes function signatures. This can be used
       to override ``skip_magic_trailing_comma = true`` from a configuration file.
-l LENGTH, --line-length LENGTH
       How many characters per line to allow [default: 88]

To change default values for these options for a given project,
add a ``[tool.darker]`` section to ``pyproject.toml`` in the project's root directory.
For example:

.. code-block:: toml

   [tool.darker]
   src = [
       "src/mypackage",
   ]
   revision = "master"
   diff = true
   check = true
   isort = true
   lint = [
       "pylint",
   ]
   log_level = "INFO"

*New in version 1.0.0:*

- The ``-c``, ``-S`` and ``-l`` command line options.
- isort_ is configured with ``-c`` and ``-l``, too.

*New in version 1.1.0:* The command line options

- ``-r`` / ``--revision``
- ``--diff``
- ``--check``
- ``--no-skip-string-normalization``
- ``-L`` / ``--lint``

*New in version 1.2.0:* Support for

- commit ranges in ``-r`` / ``--revision``.
- a ``[tool.darker]`` section in ``pyproject.toml``.

*New in version 1.2.2:* Support for ``-r :PRE-COMMIT:`` / ``--revision=:PRE_COMMIT:``

*New in version 1.3.0:* Support for command line option ``--skip-magic-trailing-comma``

*New in version 1.3.0:* The ``-d`` / ``--stdout`` command line option

.. _Black documentation about pyproject.toml: https://black.readthedocs.io/en/stable/pyproject_toml.html
.. _isort documentation about config files: https://timothycrosley.github.io/isort/docs/configuration/config_files/
.. _command line arguments: https://black.readthedocs.io/en/stable/installation_and_usage.html#command-line-options

Editor integration
==================

Many editors have plugins or recipes for integrating Black_.
You may be able to adapt them to be used with ``darker``.
See `editor integration`__ in the Black_ documentation.

__ https://github.com/psf/black/#editor-integration

PyCharm/IntelliJ IDEA
---------------------

1. Install ``darker``::

     $ pip install darker

2. Locate your ``darker`` installation folder.

   On macOS / Linux / BSD::

     $ which darker
     /usr/local/bin/darker  # possible location

   On Windows::

     $ where darker
     %LocalAppData%\Programs\Python\Python36-32\Scripts\darker.exe  # possible location

3. Open External tools in PyCharm/IntelliJ IDEA

   On macOS:

   ``PyCharm -> Preferences -> Tools -> External Tools``

   On Windows / Linux / BSD:

   ``File -> Settings -> Tools -> External Tools``

4. Click the ``+`` icon to add a new external tool with the following values:

   - Name: Darker
   - Description: Use Black to auto-format regions changed since the last git commit.
   - Program: <install_location_from_step_2>
   - Arguments: ``"$FilePath$"``

   If you need any extra command line arguments
   like the ones which change Black behavior,
   you can add them to the ``Arguments`` field, e.g.::

       --config /home/myself/black.cfg "$FilePath$"

5. Format the currently opened file by selecting ``Tools -> External Tools -> Darker``.

   - Alternatively, you can set a keyboard shortcut by navigating to
     ``Preferences or Settings -> Keymap -> External Tools -> External Tools - Darker``

6. Optionally, run ``darker`` on every file save:

   1. Make sure you have the `File Watcher`__ plugin installed.
   2. Go to ``Preferences or Settings -> Tools -> File Watchers`` and click ``+`` to add
      a new watcher:

      - Name: Darker
      - File type: Python
      - Scope: Project Files
      - Program: <install_location_from_step_2>
      - Arguments: ``$FilePath$``
      - Output paths to refresh: ``$FilePath$``
      - Working directory: ``$ProjectFileDir$``

   3. Uncheck "Auto-save edited files to trigger the watcher"

__ https://plugins.jetbrains.com/plugin/7177-file-watchers

Visual Studio Code
------------------

1. Install ``darker``::

     $ pip install darker

2. Locate your ``darker`` installation folder.

   On macOS / Linux / BSD::

     $ which darker
     /usr/local/bin/darker  # possible location

   On Windows::

     $ where darker
     %LocalAppData%\Programs\Python\Python36-32\Scripts\darker.exe  # possible location

3. Add these configuration options to VS code, ``Cmd-Shift-P``, ``Open Settings (JSON)``::

    "python.formatting.provider": "black",
    "python.formatting.blackPath": "<install_location_from_step_2>",
    "python.formatting.blackArgs": ["--diff"],

You can pass additional arguments to ``darker`` in the ``blackArgs`` option
(e.g. ``["--diff", "--isort"]``), but make sure at least ``--diff`` is included.

Note that VSCode first copies the file to reformat into a temporary
``<filename>.py.<hash>.tmp`` file, then calls Black (or Darker in this case) on that
file, and brings the changes in the modified files back into the editor.
Darker is aware of this behavior, and will correctly compare ``.py.<hash>.tmp`` files
to corresponding ``.py`` files from earlier repository revisions.


Vim
---

Unlike Black_ and many other formatters, ``darker`` needs access to the Git history.
Therefore it does not work properly with classical auto reformat plugins.

You can though ask vim to run ``darker`` on file save with the following in your
``.vimrc``:

.. code-block:: vim

   set autoread
   autocmd BufWritePost *.py silent :!darker %

- ``BufWritePost`` to run ``darker`` *once the file has been saved*,
- ``silent`` to not ask for confirmation each time,
- ``:!`` to run an external command,
- ``%`` for current file name.

Vim should automatically reload the file.


Using as a pre-commit hook
==========================

*New in version 1.2.1*

To use Darker locally as a Git pre-commit hook for a Python project,
do the following:

1. Install pre-commit_ in your environment
   (see `pre-commit Installation`_ for details).

1. Create a base pre-commit configuration::

       pre-commit sample-config >.pre-commit-config.yaml

1. Append to the created ``.pre-commit-config.yaml`` the following lines::

       -   repo: https://github.com/akaihola/darker
           rev: 1.4.0
           hooks:
           -   id: darker

2. install the Git hook scripts::

       pre-commit install

.. _pre-commit: https://pre-commit.com/
.. _pre-commit Installation: https://pre-commit.com/#installation


Using arguments
---------------

You can provide arguments, such as enabling isort, by specifying ``args``.
Note the inclusion of the isort Python package under ``additional_dependencies``::

   -   repo: https://github.com/akaihola/darker
       rev: 1.4.0
       hooks:
       -   id: darker
           args: [--isort]
           additional_dependencies:
           -   isort~=5.9


GitHub Actions integration
==========================

You can use Darker within a GitHub Actions workflow
without setting your own Python environment.
Great for enforcing that modifications and additions to your code
match the Black_ code style.

Compatibility
-------------

This action is known to support all GitHub-hosted runner OSes. In addition, only
published versions of Darker are supported (i.e. whatever is available on PyPI).

Usage
-----

Create a file named ``.github/workflows/darker.yml`` inside your repository with:

.. code-block:: yaml

   name: Lint
   
   on: [push, pull_request]
   
   jobs:
     lint:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v2
           with:
             fetch-depth: 0 
         - uses: akaihola/darker@1.4.0

We recommend the use per version tags.
The version of Darker the action will use can be configured via ``version``.
The action defaults to the action's version tag.
Only versions available from PyPI are supported, so no commit SHAs or branch names.

You can also configure the arguments passed to Darker via ``options``
(defaults to ``'--check --diff'``) and ``src`` (default is ``'.'``).

Here's an example configuration:

.. code-block:: yaml

   - uses: akaihola/darker@1.4.0
     with:
       options: "--check --verbose"
       src: "./src"
       version: "1.3.2"

*New in version 1.1.0:*
GitHub Actions integration. Modeled after how Black_ does it,
thanks to Black authors for the example!


.. _Using linters:

Using linters
=============

One way to use Darker is to filter linter output to modified lines only.
Darker supports any linter with output in one of the following formats::

    <file>:<linenum>: <description>
    <file>:<linenum>:<col>: <description>

Most notably, the following linters/checkers have been verified to work with Darker:

- Mypy_ for static type checking
- Pylint_ for generic static checking of code
- Flake8_ for style guide enforcement
- `cov_to_lint.py`_ for test coverage

*New in version 1.1.0:* Support for Mypy_, Pylint_, Flake8_ and compatible linters.

*New in version 1.2.0:* Support for test coverage output using `cov_to_lint.py`_.

To run a linter, use the ``--lint`` / ``-L`` command line option:

  - ``-L mypy``: do static type checking using Mypy_
  - ``-L pylint``: analyze code using Pylint_
  - ``-L flake8``: enforce the Python style guide using Flake8_
  - ``-L cov_to_lint.py``: read ``.coverage`` and list non-covered modified lines

Darker also groups linter output into blocks of consecutive lines
separated by blank lines.
Here's an example of `cov_to_lint.py`_ output::

    $ darker --revision 0.1.0.. --check --lint cov_to_lint.py src
    src/darker/__main__.py:94:  no coverage:             logger.debug("No changes in %s after isort", src)
    src/darker/__main__.py:95:  no coverage:             break

    src/darker/__main__.py:125: no coverage:         except NotEquivalentError:

    src/darker/__main__.py:130: no coverage:             if context_lines == max_context_lines:
    src/darker/__main__.py:131: no coverage:                 raise
    src/darker/__main__.py:132: no coverage:             logger.debug(

.. _Mypy: https://pypi.org/project/mypy
.. _Pylint: https://pypi.org/project/pylint
.. _Flake8: https://pypi.org/project/flake8
.. _cov_to_lint.py: https://gist.github.com/akaihola/2511fe7d2f29f219cb995649afd3d8d2


How does it work?
=================

Darker takes a ``git diff`` of your Python files,
records which lines of current files have been edited or added since the last commit.
It then runs Black_ and notes which chunks of lines were reformatted.
Finally, only those reformatted chunks on which edited lines fall (even partially)
are applied to the edited file.

Also, in case the ``--isort`` option was specified,
isort_ is run on each edited file before applying Black_.
Similarly, each linter requested using the `--lint <command>` option is run,
and only linting errors/warnings on modified lines are displayed.


License
=======

BSD. See ``LICENSE.rst``.


Prior art
=========

- black-macchiato__
- darken__ (deprecated in favor of Darker; thanks Carreau__ for inspiration!)

__ https://github.com/wbolster/black-macchiato
__ https://github.com/Carreau/darken
__ https://github.com/Carreau


Interesting code formatting and analysis projects to watch
==========================================================

The following projects are related to Black_ or Darker in some way or another.
Some of them we might want to integrate to be part of a Darker run.

- blacken-docs__ – Run Black_ on Python code blocks in documentation files
- blackdoc__ – Run Black_ on documentation code snippets
- velin__ – Reformat docstrings that follow the numpydoc__ convention
- diff-cov-lint__ – Pylint and coverage reports for git diff only
- xenon__ – Monitor code complexity
- pyupgrade__ – Upgrade syntax for newer versions of the language (see `#51`_)
- yapf_ – Google's Python formatter
- yapf_diff__ – apply yapf_ or other formatters to modified lines only

__ https://github.com/asottile/blacken-docs
__ https://github.com/keewis/blackdoc
__ https://github.com/Carreau/velin
__ https://pypi.org/project/numpydoc
__ https://gitlab.com/sVerentsov/diff-cov-lint
__ https://github.com/rubik/xenon
__ https://github.com/asottile/pyupgrade
__ https://github.com/google/yapf/blob/main/yapf/third_party/yapf_diff/yapf_diff.py
.. _yapf: https://github.com/google/yapf
.. _#51: https://github.com/akaihola/darker/pull/51


Contributors ✨
===============

See README.rst_ for the list of contributors.

This project follows the all-contributors_ specification.
Contributions of any kind are welcome!

.. _README.rst: https://github.com/akaihola/darker/blob/master/README.rst
.. _emoji key: https://allcontributors.org/docs/en/emoji-key
.. _all-contributors: https://allcontributors.org


GitHub stars trend
==================

|stargazers|_

.. |stargazers| image:: https://starchart.cc/akaihola/darker.svg
.. _stargazers: https://starchart.cc/akaihola/darker


