Upgrading isort 4 to 5
Breaking4.3.21 → 5.13.2Breaking4Security1Platform5Deprecated3New50Changed43Fixed134Other44
BreakingUpgrade verdict
4 breaking changes and 5 platform requirement changes and a security fix.
In plain terms
- Some imports from namespace packages may now be classified differently, which can change sort order.
- Output using the Google profile may change to match Google style more closely.
- Output using the PyCharm profile may change to always include two blank lines.
- If you scanned standard output for ERROR: messages about incorrect imports, you now need to look at standard error instead.
Must act Top 5 of 13 that need code or config changes
Python requirement changed in 5.12.0: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.* → >=3.8.0.
What you must change
Breaking4
Fixes incorrect third vs first party categorization for namespace packages.
Fixes the "Google" profile not quite matching Google style.
GoogleFixes the "PyCharm" profile to always add 2 lines, consistent with PyCharm Optimize Imports.
PyCharmFixes --check to print to stderr as documented, so ERROR: messages for incorrect imports move from stdout to stderr.
--checkSecurity1
Adds recursive symbolic link protection.
Platform5
Adds support for Python 3.12.
Adds support for Python 3.11.
Removes support for Python 3.6.
Adds official support for Python 3.10.
Officially supports Python 3.9 stdlib imports by default.
Deprecations to plan for
Deprecated3
Cleans up deprecated extras.
Deprecates the -k or --keep-direct-and-as-imports option, which is now always on.
-k--keep-direct-and-as-importsAdds a warning for deprecated CLI flags and links to the upgrade guide.
API changes
Generated by DepDelta from published Python source. Not mixed with prose notes.
- removed:
export SortImports - added:
export Config - added:
export ImportKey - added:
export __version__ - added:
export check_code - added:
export check_file - added:
export check_stream - added:
export code - added:
export file - added:
export find_imports_in_code - added:
export find_imports_in_file - added:
export find_imports_in_paths - added:
export find_imports_in_stream - added:
export place_module - added:
export place_module_with_reason - added:
export stream
- added:
class ImportKey(Enum) - added:
export place_module - added:
export place_module_with_reason - added:
field ImportKey.ALIAS - added:
field ImportKey.ATTRIBUTE - added:
field ImportKey.MODULE - added:
field ImportKey.PACKAGE - added:
function check_code_string(code: str, show_diff: Union[bool, TextIO]=…, extension: Optional[str]=…, config: Config=…, file_path: Optional[Path]=…, disregard_skip: bool=…, **config_kwargs: Any) -> bool - added:
function check_file(filename: Union[str, Path], show_diff: Union[bool, TextIO]=…, config: Config=…, file_path: Optional[Path]=…, disregard_skip: bool=…, extension: Optional[str]=…, **config_kwargs: Any) -> bool - added:
function check_stream(input_stream: TextIO, show_diff: Union[bool, TextIO]=…, extension: Optional[str]=…, config: Config=…, file_path: Optional[Path]=…, disregard_skip: bool=…, **config_kwargs: Any) -> bool - added:
function find_imports_in_code(code: str, config: Config=…, file_path: Optional[Path]=…, unique: Union[bool, ImportKey]=…, top_only: bool=…, **config_kwargs: Any) -> Iterator[identify.Import] - added:
function find_imports_in_file(filename: Union[str, Path], config: Config=…, file_path: Optional[Path]=…, unique: Union[bool, ImportKey]=…, top_only: bool=…, **config_kwargs: Any) -> Iterator[identify.Import] - added:
function find_imports_in_paths(paths: Iterator[Union[str, Path]], config: Config=…, file_path: Optional[Path]=…, unique: Union[bool, ImportKey]=…, top_only: bool=…, **config_kwargs: Any) -> Iterator[identify.Import] - added:
function find_imports_in_stream(input_stream: TextIO, config: Config=…, file_path: Optional[Path]=…, unique: Union[bool, ImportKey]=…, top_only: bool=…, _seen: Optional[Set[str]]=…, **config_kwargs: Any) -> Iterator[identify.Import] - added:
function sort_code_string(code: str, extension: Optional[str]=…, config: Config=…, file_path: Optional[Path]=…, disregard_skip: bool=…, show_diff: Union[bool, TextIO]=…, **config_kwargs: Any) -> str - added:
function sort_file(filename: Union[str, Path], extension: Optional[str]=…, config: Config=…, file_path: Optional[Path]=…, disregard_skip: bool=…, ask_to_apply: bool=…, show_diff: Union[bool, TextIO]=…, write_to_stdout: bool=…, output: Optional[TextIO]=…, **config_kwargs: Any) -> bool - added:
function sort_stream(input_stream: TextIO, output_stream: TextIO, extension: Optional[str]=…, config: Config=…, file_path: Optional[Path]=…, disregard_skip: bool=…, show_diff: Union[bool, TextIO]=…, raise_on_skip: bool=…, **config_kwargs: Any) -> bool
- added:
function add_to_line(comments: Optional[List[str]], original_string: str=…, removed: bool=…, comment_prefix: str=…) -> str - added:
function parse(line: str) -> Tuple[str, str]
- added:
function process(input_stream: TextIO, output_stream: TextIO, extension: str=…, raise_on_skip: bool=…, config: Config=…) -> bool - added:
variable CIMPORT_IDENTIFIERS - added:
variable CODE_SORT_COMMENTS - added:
variable COMMENT_INDICATORS - added:
variable DOCSTRING_INDICATORS - added:
variable IMPORT_START_IDENTIFIERS - added:
variable LITERAL_TYPE_MAPPING
- added:
class BaseFinder - added:
class DefaultFinder(BaseFinder) - added:
class FindersManager - added:
class ForcedSeparateFinder(BaseFinder) - added:
class KnownPatternFinder(BaseFinder) - added:
class LocalFinder(BaseFinder) - added:
class PathFinder(BaseFinder) - added:
class ReqsBaseFinder(BaseFinder) - added:
class RequirementsFinder(ReqsBaseFinder) - added:
constructor BaseFinder(config: Config) -> None - added:
constructor FindersManager(config: Config, finder_classes: Optional[Iterable[Type[BaseFinder]]]=…) -> None - added:
constructor KnownPatternFinder(config: Config) -> None - added:
constructor PathFinder(config: Config, path: str=…) -> None - added:
constructor ReqsBaseFinder(config: Config, path: str=…) -> None - added:
field ReqsBaseFinder.enabled - added:
field RequirementsFinder.enabled - added:
field RequirementsFinder.exts - added:
function chdir(path: str) -> Iterator[None] - added:
method BaseFinder.find(module_name: str) -> Optional[str] - added:
method DefaultFinder.find(module_name: str) -> Optional[str] - added:
method FindersManager.find(module_name: str) -> Optional[str] - added:
method ForcedSeparateFinder.find(module_name: str) -> Optional[str] - added:
method KnownPatternFinder.find(module_name: str) -> Optional[str] - added:
method LocalFinder.find(module_name: str) -> Optional[str] - added:
method PathFinder.find(module_name: str) -> Optional[str] - added:
method ReqsBaseFinder.find(module_name: str) -> Optional[str] - added:
variable parse_requirements - added:
variable pipreqs
- added:
class AssignmentsFormatMismatch(ISortError) - added:
class ExistingSyntaxErrors(ISortError) - added:
class FileSkipComment(FileSkipped) - added:
class FileSkipSetting(FileSkipped) - added:
class FileSkipped(ISortError) - added:
class FormattingPluginDoesNotExist(ISortError) - added:
class ISortError(Exception) - added:
class IntroducedSyntaxErrors(ISortError) - added:
class InvalidSettingsPath(ISortError) - added:
class LiteralParsingFailure(ISortError) - added:
class LiteralSortTypeMismatch(ISortError) - added:
class MissingSection(ISortError) - added:
class ProfileDoesNotExist(ISortError) - added:
class SortingFunctionDoesNotExist(ISortError) - added:
class UnsupportedEncoding(ISortError) - added:
class UnsupportedSettings(ISortError) - added:
constructor AssignmentsFormatMismatch(code: str) - added:
constructor ExistingSyntaxErrors(file_path: str) - added:
constructor FileSkipComment(file_path: str, **kwargs: str) - added:
constructor FileSkipSetting(file_path: str, **kwargs: str) - added:
constructor FileSkipped(message: str, file_path: str) - added:
constructor FormattingPluginDoesNotExist(formatter: str) - added:
constructor IntroducedSyntaxErrors(file_path: str) - added:
constructor InvalidSettingsPath(settings_path: str) - added:
constructor LiteralParsingFailure(code: str, original_error: Union[Exception, Type[Exception]]) - added:
constructor LiteralSortTypeMismatch(kind: type, expected_kind: type) - added:
constructor MissingSection(import_module: str, section: str) - added:
constructor ProfileDoesNotExist(profile: str) - added:
constructor SortingFunctionDoesNotExist(sort_order: str, available_sort_orders: List[str]) - added:
constructor UnsupportedEncoding(filename: Union[str, Path]) - added:
constructor UnsupportedSettings(unsupported_settings: Dict[str, Dict[str, str]])
- added:
function find(paths: Iterable[str], config: Config, skipped: List[str], broken: List[str]) -> Iterator[str]
- removed:
class BaseFinder(object) - removed:
class DefaultFinder(BaseFinder) - removed:
class FindersManager(object) - removed:
class ForcedSeparateFinder(BaseFinder) - removed:
class KnownPatternFinder(BaseFinder) - removed:
class LocalFinder(BaseFinder) - removed:
class PathFinder(BaseFinder) - removed:
class PipfileFinder(ReqsBaseFinder) - removed:
class ReqsBaseFinder(BaseFinder) - removed:
class RequirementsFinder(ReqsBaseFinder) - removed:
constructor BaseFinder(config, sections) - removed:
constructor FindersManager(config, sections, finders=…) - removed:
constructor KnownPatternFinder(config, sections) - removed:
constructor PathFinder(config, sections) - removed:
constructor ReqsBaseFinder(config, sections, path=…) - removed:
field FindersManager.finders - removed:
field PipfileFinder.enabled - removed:
field RequirementsFinder.enabled - removed:
field RequirementsFinder.exts - removed:
method DefaultFinder.find(module_name) - removed:
method FindersManager.find(module_name) - removed:
method ForcedSeparateFinder.find(module_name) - removed:
method KnownPatternFinder.find(module_name) - removed:
method LocalFinder.find(module_name) - removed:
method PathFinder.find(module_name) - removed:
method ReqsBaseFinder.find(module_name) - removed:
variable KNOWN_SECTION_MAPPING - removed:
variable Pipfile - removed:
variable parse_requirements - removed:
variable pipreqs
- added:
class BasicPrinter - added:
class ColoramaPrinter(BasicPrinter) - added:
constructor BasicPrinter(error: str, success: str, output: Optional[TextIO]=…) - added:
constructor ColoramaPrinter(error: str, success: str, output: Optional[TextIO]) - added:
field BasicPrinter.ERROR - added:
field BasicPrinter.SUCCESS - added:
function ask_whether_to_apply_changes_to_file(file_path: str) -> bool - added:
function create_terminal_printer(color: bool, output: Optional[TextIO]=…, error: str=…, success: str=…) -> BasicPrinter - added:
function format_natural(import_line: str) -> str - added:
function format_simplified(import_line: str) -> str - added:
function remove_whitespace(content: str, line_separator: str=…) -> str - added:
function show_unified_diff(*, file_input: str, file_output: str, file_path: Optional[Path], output: Optional[TextIO]=…, color_output: bool=…) -> None - added:
method BasicPrinter.diff_line(line: str) -> None - added:
method BasicPrinter.error(message: str) -> None - added:
method BasicPrinter.success(message: str) -> None - added:
method ColoramaPrinter.diff_line(line: str) -> None - added:
static method ColoramaPrinter.style_text(text: str, style: Optional[str]=…) -> str - added:
variable ADDED_LINE_PATTERN - added:
variable REMOVED_LINE_PATTERN - added:
variable colorama_unavailable
- changed:
function get_lines(command) → function get_lines(command: List[str]) -> List[str] - changed:
function get_output(command) → function get_output(command: List[str]) -> str - changed:
function git_hook(strict=…, modify=…) → function git_hook(strict: bool=…, modify: bool=…, lazy: bool=…, settings_file: str=…, directories: Optional[List[str]]=…) -> int
- added:
class Import(NamedTuple) - added:
field Import.alias: Optional[str] - added:
field Import.attribute: Optional[str] - added:
field Import.cimport: bool - added:
field Import.file_path: Optional[Path] - added:
field Import.indented: bool - added:
field Import.line_number: int - added:
field Import.module: str - added:
function imports(input_stream: TextIO, config: Config=…, file_path: Optional[Path]=…, top_only: bool=…) -> Iterator[Import] - added:
method Import.statement() -> str - added:
variable STATEMENT_DECLARATIONS: Tuple[str, ...]
- added:
class File - added:
field File.encoding: str - added:
field File.path: Path - added:
field File.stream: TextIO - added:
property File.extension -> str - added:
static method File.detect_encoding(filename: Union[str, Path], readline: Callable[[], bytes]) -> str - added:
static method File.from_contents(contents: str, filename: str) -> File - added:
static method File.read(filename: Union[str, Path]) -> Iterator[File] - added:
variable Empty
- removed:
class SortImports(object) - removed:
constructor SortImports(file_path=…, file_contents=…, file_=…, write_to_stdout=…, check=…, show_diff=…, settings_path=…, ask_to_apply=…, run_path=…, check_skip=…, extension=…, **setting_overrides) - removed:
field SortImports.incorrectly_sorted - removed:
field SortImports.skipped - removed:
function coding_check(lines, default=…) - removed:
method SortImports.place_module(module_name) - removed:
property SortImports.correctly_sorted
- added:
class ISortPrettyPrinter(PrettyPrinter) - added:
constructor ISortPrettyPrinter(config: Config) - added:
function assignment(code: str, sort_type: str, extension: str, config: Config=…) -> str - added:
function assignments(code: str) -> str - added:
function register_type(name: str, kind: type) -> Callable[[Callable[[Any, ISortPrettyPrinter], str]], Callable[[Any, ISortPrettyPrinter], str]] - added:
variable type_mapping: Dict[str, Tuple[type, Callable[[Any, ISortPrettyPrinter], str]]]
- added:
variable ASCII_ART
- removed:
class ISortCommand(setuptools.Command) - removed:
field ISortCommand.description - removed:
field ISortCommand.user_options - removed:
function is_python_file(path) - removed:
function iter_source_code(paths, config, skipped) - removed:
method ISortCommand.distribution_files() - removed:
method ISortCommand.finalize_options() - removed:
method ISortCommand.initialize_options() - removed:
method ISortCommand.run() - removed:
variable INTRO - removed:
variable shebang_re - changed:
class SortAttempt(object) → class SortAttempt - changed:
constructor SortAttempt(incorrectly_sorted, skipped) → constructor SortAttempt(incorrectly_sorted: bool, skipped: bool, supported_encoding: bool) -> None - changed:
function main(argv=…) → function main(argv: Optional[Sequence[str]]=…, stdin: Optional[TextIOWrapper]=…) -> None - changed:
function parse_args(argv=…) → function parse_args(argv: Optional[Sequence[str]]=…) -> Dict[str, Any] - changed:
function sort_imports(file_name, **arguments) → function sort_imports(file_name: str, config: Config, check: bool=…, ask_to_apply: bool=…, write_to_stdout: bool=…, **kwargs: Any) -> Optional[SortAttempt] - added:
function identify_imports_main(argv: Optional[Sequence[str]]=…, stdin: Optional[TextIOWrapper]=…) -> None - added:
variable DEPRECATED_SINGLE_DASH_ARGS - added:
variable QUICK_GUIDE
- removed:
function nsorted(to_sort, key=…)
- added:
function sorted_imports(parsed: parse.ParsedContent, config: Config=…, extension: str=…, import_type: str=…) -> str
- added:
class ParsedContent(NamedTuple) - added:
field ParsedContent.as_map: Dict[str, Dict[str, List[str]]] - added:
field ParsedContent.categorized_comments: CommentsDict - added:
field ParsedContent.change_count: int - added:
field ParsedContent.import_index: int - added:
field ParsedContent.import_placements: Dict[str, str] - added:
field ParsedContent.imports: Dict[str, Dict[str, Any]] - added:
field ParsedContent.in_lines: List[str] - added:
field ParsedContent.line_separator: str - added:
field ParsedContent.lines_without_imports: List[str] - added:
field ParsedContent.original_line_count: int - added:
field ParsedContent.place_imports: Dict[str, List[str]] - added:
field ParsedContent.sections: Any - added:
field ParsedContent.trailing_commas: Set[str] - added:
field ParsedContent.verbose_output: List[str] - added:
function file_contents(contents: str, config: Config=…) -> ParsedContent - added:
function import_type(line: str, config: Config=…) -> Optional[str] - added:
function normalize_line(raw_line: str) -> Tuple[str, str] - added:
function skip_line(line: str, in_quote: str, index: int, section_comments: Tuple[str, ...], needs_import: bool=…) -> Tuple[bool, str] - added:
function strip_syntax(import_string: str) -> str - added:
variable CommentsAboveDict - added:
variable CommentsDict
- removed:
export lru_cache - removed:
function apply_changes_to_python_environment() - removed:
function lru_cache(maxsize=…) - removed:
variable PY2 - removed:
variable PY3
- added:
function module(name: str, config: Config=…) -> str - added:
function module_with_reason(name: str, config: Config=…) -> Tuple[str, str] - added:
variable LOCAL
- added:
variable appnexus - added:
variable attrs - added:
variable black - added:
variable django - added:
variable google - added:
variable hug - added:
variable open_stack - added:
variable plone - added:
variable profiles: Dict[str, Dict[str, Any]] - added:
variable pycharm - added:
variable wemake
- changed:
method Linter.allow(path) → method Linter.allow(path: str) -> bool - changed:
method Linter.run(path, **meta) → method Linter.run(path: str, params: Optional[Dict[str, Any]]=…, **meta: Any) -> List[Dict[str, Any]] - added:
function suppress_stdout() -> Iterator[None]
- added:
variable DEFAULT: Tuple[str, ...] - added:
variable FIRSTPARTY: str - added:
variable FUTURE: str - added:
variable LOCALFOLDER: str - added:
variable STDLIB: str - added:
variable THIRDPARTY: str
- removed:
function from_path(path) - removed:
function should_skip(filename, config, path=…) - removed:
variable DEFAULT_SECTIONS - removed:
variable WrapModes - removed:
variable appdirs - removed:
variable default - removed:
variable safety_exclude_re - removed:
variable toml - changed:
variable MAX_CONFIG_SEARCH_DEPTH → variable MAX_CONFIG_SEARCH_DEPTH: int - added:
class Config(_Config) - added:
constructor Config(settings_file: str=…, settings_path: str=…, config: Optional[_Config]=…, **config_overrides: Any) - added:
function find_all_configs(path: str) -> Trie - added:
method Config.is_skipped(file_path: Path) -> bool - added:
method Config.is_supported_filetype(file_name: str) -> bool - added:
property Config.known_patterns -> List[Tuple[Pattern[str], str]] - added:
property Config.section_comments -> Tuple[str, ...] - added:
property Config.section_comments_end -> Tuple[str, ...] - added:
property Config.skip_globs -> FrozenSet[str] - added:
property Config.skips -> FrozenSet[str] - added:
property Config.sorting_function -> Callable[..., List[str]] - added:
variable BLOCKED_EXTENSIONS - added:
variable CONFIG_SECTIONS: Dict[str, Tuple[str, ...]] - added:
variable CONFIG_SOURCES: Tuple[str, ...] - added:
variable CYTHON_EXTENSIONS - added:
variable DEFAULT_CONFIG - added:
variable DEFAULT_SKIP: FrozenSet[str] - added:
variable DEPRECATED_SETTINGS - added:
variable FALLBACK_CONFIG_SECTIONS: Tuple[str, ...] - added:
variable FILE_SKIP_COMMENTS: Tuple[str, ...] - added:
variable IMPORT_FOOTER_PREFIX - added:
variable IMPORT_HEADING_PREFIX - added:
variable KNOWN_PREFIX - added:
variable KNOWN_SECTION_MAPPING: Dict[str, str] - added:
variable RUNTIME_SOURCE - added:
variable STOP_CONFIG_SEARCH_ON_DIRS: Tuple[str, ...] - added:
variable SUPPORTED_EXTENSIONS - added:
variable VALID_PY_TARGETS: Tuple[str, ...] - added:
variable tomllib: Any
- added:
class ISortCommand(setuptools.Command) - added:
field ISortCommand.description - added:
field ISortCommand.user_options: List[Any] - added:
method ISortCommand.distribution_files() -> Iterator[str] - added:
method ISortCommand.finalize_options() -> None - added:
method ISortCommand.initialize_options() -> None - added:
method ISortCommand.run() -> None
- added:
function module_key(module_name: str, config: Config, sub_imports: bool=…, ignore_case: bool=…, section_name: Optional[Any]=…, straight_import: Optional[bool]=…) -> str - added:
function naturally(to_sort: Iterable[str], key: Optional[Callable[[str], Any]]=…, reverse: bool=…) -> List[str] - added:
function section_key(line: str, config: Config) -> str - added:
function sort(config: Config, to_sort: Iterable[str], key: Optional[Callable[[str], Any]]=…, reverse: bool=…) -> List[str] - added:
variable Config
- added:
export py2 - added:
export py27 - added:
export py3 - added:
export py310 - added:
export py311 - added:
export py312 - added:
export py36 - added:
export py37 - added:
export py38 - added:
export py39
- added:
variable stdlib
- added:
variable stdlib
- added:
variable stdlib
- added:
variable stdlib
- added:
variable stdlib
- added:
variable stdlib
- added:
variable stdlib
- added:
variable stdlib
- added:
variable stdlib
- added:
variable stdlib
- added:
variable stdlib
- removed:
function chdir(path) - removed:
function difference(a, b) - removed:
function union(a, b) - changed:
function exists_case_sensitive(path) → function exists_case_sensitive(path: str) -> bool - added:
class Trie - added:
class TrieNode - added:
constructor Trie(config_file: str=…, config_data: Optional[Dict[str, Any]]=…) -> None - added:
constructor TrieNode(config_file: str=…, config_data: Optional[Dict[str, Any]]=…) -> None - added:
method Trie.insert(config_file: str, config_data: Dict[str, Any]) -> None - added:
method Trie.search(filename: str) -> Tuple[str, Dict[str, Any]]
- added:
function import_statement(import_start: str, from_imports: List[str], comments: Sequence[str]=…, line_separator: str=…, config: Config=…, multi_line_output: Optional[Modes]=…, explode: bool=…) -> str - added:
function line(content: str, line_separator: str, config: Config=…) -> str
- added:
function backslash_grid(**interface: Any) -> str - added:
function formatter_from_string(name: str) -> Callable[..., str] - added:
function from_string(value: str) -> WrapModes - added:
function grid(**interface: Any) -> str - added:
function hanging_indent(**interface: Any) -> str - added:
function hanging_indent_with_parentheses(**interface: Any) -> str - added:
function noqa(**interface: Any) -> str - added:
function vertical(**interface: Any) -> str - added:
function vertical_grid(**interface: Any) -> str - added:
function vertical_grid_grouped(**interface: Any) -> str - added:
function vertical_grid_grouped_no_comma(**interface: Any) -> str - added:
function vertical_hanging_indent(**interface: Any) -> str - added:
function vertical_hanging_indent_bracket(**interface: Any) -> str - added:
function vertical_prefix_from_module_import(**interface: Any) -> str - added:
variable WrapModes