0
# Flake8 Import Order
1

2
A flake8 and pylama plugin that checks the ordering of import statements. This plugin enforces proper import grouping and ordering according to various coding style guidelines, helping maintain consistent and readable import organization across Python projects.
3

4
## Package Information
5

6
- **Package Name**: flake8-import-order
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install flake8-import-order`
10

11
## Core Imports
12

13
```python
14
import flake8_import_order
15
```
16

17
For core data types and enums:
18

19
```python
20
from flake8_import_order import ClassifiedImport, ImportType, NewLine
21
```
22

23
For AST processing:
24

25
```python
26
from flake8_import_order import ImportVisitor
27
```
28

29
For utility functions and constants:
30

31
```python
32
from flake8_import_order import get_package_names, root_package_name, STDLIB_NAMES, DEFAULT_IMPORT_ORDER_STYLE
33
```
34

35
## Basic Usage
36

37
### As a Flake8 Plugin
38

39
```python
40
# Configuration in setup.cfg or tox.ini
41
[flake8]
42
application-import-names = myapp
43
import-order-style = cryptography
44
```
45

46
### Programmatic Usage
47

48
```python
49
from flake8_import_order.checker import ImportOrderChecker
50
from flake8_import_order.styles import lookup_entry_point
51
import ast
52

53
# Analyze import order in Python code
54
code = '''
55
import os
56
import sys
57
from myapp import module1
58
'''
59

60
tree = ast.parse(code)
61
checker = ImportOrderChecker('example.py', tree)
62
checker.options = {
63
    'application_import_names': ['myapp'],
64
    'application_package_names': [],
65
    'import_order_style': lookup_entry_point('cryptography')
66
}
67

68
# Check for import order violations
69
for error in checker.check_order():
70
    print(f"Line {error.lineno}: {error.code} {error.message}")
71
```
72

73
## Architecture
74

75
The plugin architecture consists of several key components:
76

77
- **Import Classification**: AST visitor that categorizes imports into groups (future, stdlib, third-party, application, relative)
78
- **Style System**: Pluggable style implementations that define ordering rules within and between import groups
79
- **Error Detection**: Checker logic that compares actual import order against style requirements
80
- **Plugin Integration**: Flake8 and pylama linter adapters that bridge the checker with linting frameworks
81

82
## Capabilities
83

84
### Core Data Types and Classification
85

86
Essential data structures for representing classified imports, import types, and AST processing utilities for analyzing Python import statements.
87

88
```python { .api }
89
# Package metadata (from __about__.py)
90
__title__ = "flake8-import-order"
91
__summary__ = "Flake8 and pylama plugin that checks the ordering of import statements."
92
__uri__ = "https://github.com/PyCQA/flake8-import-order"
93
__version__ = "0.19.2"  
94
__author__ = "Alex Stapleton"
95
__email__ = "alexs@prol.etari.at"
96
__maintainer__ = "Phil Jones"
97
__maintainer_email__ = "philip.graham.jones+flake8-import@gmail.com"
98
__license__ = "LGPLv3"
99
__copyright__ = "Copyright 2013-2016 Alex Stapleton"
100

101
# Core data types
102
ClassifiedImport = namedtuple("ClassifiedImport", [
103
    "type", "is_from", "modules", "names", "lineno", 
104
    "end_lineno", "level", "package", "type_checking"
105
])
106

107
class ImportType(IntEnum):
108
    FUTURE = 0
109
    STDLIB = 10
110
    THIRD_PARTY = 20
111
    APPLICATION_PACKAGE = 30
112
    APPLICATION = 40
113
    APPLICATION_RELATIVE = 50
114
    MIXED = -1
115

116
def get_package_names(name)
117
def root_package_name(name)
118
```
119

120
[Core Types and Classification](./core-types.md)
121

122
### Import Order Checking and Validation
123

124
Main checker functionality for validating import order according to configured style rules, including file loading, AST analysis, and error detection.
125

126
```python { .api }
127
class ImportOrderChecker:
128
    def __init__(self, filename: str, tree: ast.AST)
129
    def load_file(self) -> None
130
    def check_order(self) -> Iterator[Error]
131
    def error_is_ignored(self, error: Error) -> bool
132

133
def parse_comma_separated_list(value: str) -> Set[str]
134
```
135

136
[Import Order Checking](./checker.md)
137

138
### Built-in Import Styles
139

140
Collection of pre-implemented import ordering styles including cryptography (default), Google, PEP8, and others, with extensible base class for custom styles.
141

142
```python { .api }
143
class Style:
144
    accepts_application_package_names: bool = False
145
    def __init__(self, nodes: List[Union[ClassifiedImport, NewLine]])
146
    def check(self) -> Iterator[Error]
147
    def sorted_names(self, names: List[str]) -> List[str]
148
    def import_key(self, import_: ClassifiedImport) -> Tuple
149
    def same_section(self, previous: ClassifiedImport, current: ClassifiedImport) -> bool
150

151
def list_entry_points() -> List[EntryPoint]
152
def lookup_entry_point(name: str) -> EntryPoint
153
```
154

155
[Built-in Styles](./styles.md)
156

157
### Plugin Integrations
158

159
Flake8 and pylama linter integrations that provide command-line options, configuration parsing, and error formatting for seamless integration with Python linting workflows.
160

161
```python { .api }
162
class Linter(ImportOrderChecker):  # Flake8 integration
163
    name: str = "import-order"
164
    version: str
165
    def add_options(cls, parser) -> None
166
    def parse_options(cls, options) -> None
167
    def run(self) -> Iterator[Tuple[int, int, str, Type]]
168

169
class Linter(ImportOrderChecker, BaseLinter):  # Pylama integration
170
    def allow(self, path: str) -> bool
171
    def run(self, path: str, **meta) -> Iterator[Dict[str, Any]]
172
```
173

174
[Plugin Integrations](./integrations.md)
175

176
## Error Codes
177

178
The plugin defines the following error codes:
179

180
- **I100**: Import statements are in wrong order
181
- **I101**: Imported names are in wrong order
182
- **I201**: Missing newline between import groups
183
- **I202**: Additional newline in import group
184
- **I300**: TYPE_CHECKING block should have one newline above
185
- **I666**: Import statement mixes groups
186

187
## Types
188

189
```python { .api }
190
NewLine = namedtuple("NewLine", ["lineno"])
191

192
Error = namedtuple("Error", ["lineno", "code", "message"])
193

194
STDLIB_NAMES  # Comprehensive set of Python standard library module names
195

196
DEFAULT_IMPORT_ORDER_STYLE = "cryptography"
197
```