Black is a Python auto code formatter that automatically formats Python code according to a set of predefined rules. It helps maintain consistent and readable code across different projects.

Use case 1: Auto-format a file or entire directory

Code:

black path/to/file_or_directory

Motivation: This use case allows you to automatically format a single file or an entire directory of Python code according to the black formatting rules. It saves time and effort by ensuring consistent code formatting without manual intervention.

Explanation:

• black: The command to run the black formatter.
• path/to/file_or_directory: The path to the Python file or directory that needs to be formatted. Black will analyze the file/directory and apply the formatting rules.

Example Output: If you have a file called example.py with the following inconsistent code:

def     my_function(   parameter1,  parameter2  ):
    print("Hello, World!")

Running the command black example.py will format the code to:

def my_function(parameter1, parameter2):
    print("Hello, World!")

Use case 2: Format the code passed in as a string

Code:

black -c "code"

Motivation: This use case allows you to format code passed in as a string without the need for a file. It can be helpful in situations where you want to experiment with formatting changes before applying them to actual code files.

Explanation:

• black: The command to run the black formatter.
• -c "code": The option -c specifies that the code will be provided as a string instead of a file.

Example Output: Running the command black -c "def my_function(): return 42" will format the code to:

def my_function():
    return 42

Use case 3: Output whether a file or directory would have changes made to them if they were to be formatted

Code:

black --check path/to/file_or_directory

Motivation: This use case allows you to check if there would be any changes made to a file or directory by running the black formatter. It provides a way to ensure that the formatting change is necessary before actually applying it.

Explanation:

• black: The command to run the black formatter.
• --check: The option --check performs a dry run and outputs whether there would be any changes made to the file/directory.
• path/to/file_or_directory: The path to the Python file or directory that needs to be checked for changes.

Example Output: If you have a file called example.py with the code already correctly formatted:

def my_function():
    return 42

Running the command black --check example.py will output:

All done! ✨ 🍰 ✨
1 file would be left unchanged.

Use case 4: Output changes that would be made to a file or directory without performing them (dry-run)

Code:

black --diff path/to/file_or_directory

Motivation: This use case allows you to preview the changes that would be made to a file or directory by running the black formatter, without actually applying those changes. It provides a way to review and verify the modifications before committing them.

Explanation:

• black: The command to run the black formatter.
• --diff: The option --diff performs a dry run and outputs the changes that would be made to the file/directory.
• path/to/file_or_directory: The path to the Python file or directory that needs to be checked for changes.

Example Output: If you have a file called example.py with the following inconsistent code:

def     my_function(   parameter1,  parameter2  ):
    print("Hello, World!")

Running the command black --diff example.py will output:

--- example.py
+++ example.py
@@ -1,2 +1,2 @@
 def my_function(parameter1, parameter2):
-    print("Hello, World!")
\ No newline at end of file
+    print("Hello, World!")

Use case 5: Auto-format a file or directory, emitting exclusively error messages to stderr

Code:

black --quiet path/to/file_or_directory

Motivation: This use case is useful when you want to auto-format a file or directory but only receive error messages in case any formatting issues are encountered. It reduces the amount of output and focuses specifically on errors.

Explanation:

• black: The command to run the black formatter.
• --quiet: The option --quiet outputs only error messages to stderr.
• path/to/file_or_directory: The path to the Python file or directory that needs to be formatted.

Example Output: If you have a file called example.py with the following inconsistent code:

def     my_function(   parameter1,  parameter2  ):
    print("Hello, World!")

Running the command black --quiet example.py will format the code and only output the error message if any:

1 file would be reformatted.

Use case 6: Auto-format a file or directory without replacing single quotes with double quotes

Code:

black --skip-string-normalization path/to/file_or_directory

Motivation: This use case is especially useful for legacy projects that extensively use single quotes for string literals. By skipping string normalization, you can ensure that the formatter does not replace single quotes with double quotes, preserving the existing code style.

Explanation:

• black: The command to run the black formatter.
• --skip-string-normalization: The option --skip-string-normalization prevents the formatter from replacing single quotes with double quotes.
• path/to/file_or_directory: The path to the Python file or directory that needs to be formatted.

Example Output: If you have a file called example.py with the following code:

def my_function():
    return 'Hello, World!'

Running the command black --skip-string-normalization example.py will format the code while preserving the single quotes:

def my_function():
    return 'Hello, World!'

Conclusion

The black command is a powerful tool for automatically formatting Python code. It offers various options to format code files or directories, providing flexibility and control over the formatting process. By using black, you can ensure consistent code style across your Python projects and save time in maintaining code formatting.