0
# Built-in Import Styles
1

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

4
## Capabilities
5

6
### Base Style Class
7

8
Abstract base class that defines the interface for import ordering styles and provides common error checking functionality.
9

10
```python { .api }
11
class Style:
12
    """Base class for import ordering styles."""
13
    
14
    accepts_application_package_names = False  # Whether style supports app package names
15
    
16
    def __init__(self, nodes):
17
        """
18
        Initialize style with list of imports and newlines.
19
        
20
        Args:
21
            nodes: List of ClassifiedImport and NewLine objects in file order
22
        """
23
    
24
    def check(self):
25
        """
26
        Check import order according to style rules.
27
        
28
        Yields:
29
            Error objects for each style violation found
30
        """
31
    
32
    def sorted_names(self, names):
33
        """
34
        Return names in the order they should appear.
35
        
36
        Args:
37
            names: List of imported names
38
            
39
        Returns:
40
            Names sorted according to style rules
41
        """
42
    
43
    def import_key(self, import_):
44
        """
45
        Generate sort key for import statement.
46
        
47
        Args:
48
            import_: Import to generate key for
49
            
50
        Returns:
51
            Sort key tuple for ordering imports
52
        """
53
    
54
    def same_section(self, previous, current):
55
        """
56
        Check if two imports belong to the same section/group.
57
        
58
        Args:
59
            previous: Previous import
60
            current: Current import
61
            
62
        Returns:
63
            True if imports are in same section
64
        """
65
```
66

67
### Built-in Style Classes
68

69
Pre-implemented styles covering common Python import ordering conventions.
70

71
```python { .api }
72
class PEP8(Style):
73
    """PEP8 style - groups only, no internal ordering."""
74
    pass
75

76
class Google(Style):
77
    """Google style guide import ordering."""
78
    
79
    @staticmethod
80
    def name_key(name):
81
        """Generate sort key for imported name (case-insensitive, then case-sensitive)."""
82
    
83
    @staticmethod  
84
    def sorted_names(names):
85
        """Sort names case-insensitively, then case-sensitively."""
86
    
87
    @staticmethod
88
    def import_key(import_):
89
        """Enhanced sort key including module and name sorting."""
90

91
class Smarkets(Style):
92
    """Smarkets style - like Google but import before from-import."""
93
    
94
    @staticmethod
95
    def name_key(name):
96
        """Generate sort key for imported name."""
97
    
98
    @staticmethod
99
    def sorted_names(names):
100
        """Sort names case-insensitively."""
101
    
102
    @staticmethod
103
    def import_key(import_):
104
        """Sort key with is_from ordering."""
105

106
class AppNexus(Google):
107
    """AppNexus style - extends Google with application package support."""
108
    accepts_application_package_names = True
109

110
class Edited(Smarkets):
111
    """Edited style - extends Smarkets with application package support and optional newlines."""
112
    accepts_application_package_names = True
113
    
114
    @staticmethod
115
    def same_section(previous, current):
116
        """Same section check with stricter type matching."""
117

118
class PyCharm(Smarkets):
119
    """PyCharm style - like Smarkets with case-sensitive name sorting."""
120
    
121
    @staticmethod
122
    def sorted_names(names):
123
        """Sort names case-sensitively."""
124
    
125
    @staticmethod
126
    def import_key(import_):
127
        """Sort key with case-sensitive ordering."""
128

129
class ISort(PyCharm):
130
    """ISort-compatible style with CONSTANT, Class, func grouping."""
131
    
132
    @staticmethod
133
    def name_key(name):
134
        """Group by CONSTANT (0), Class (1), func (2), then alphabetically."""
135
    
136
    @staticmethod
137
    def sorted_names(names):
138
        """Sort with CONSTANT, Class, func precedence."""
139

140
class Cryptography(Style):
141
    """Cryptography style (default) - groups by package within third-party/application."""
142
    
143
    @staticmethod
144
    def sorted_names(names):
145
        """Sort names alphabetically."""
146
    
147
    @staticmethod
148
    def import_key(import_):
149
        """Sort key with package-based grouping for third-party/application imports."""
150
    
151
    @staticmethod
152
    def same_section(previous, current):
153
        """Same section with package-based grouping."""
154
```
155

156
### Style Discovery and Loading
157

158
Functions for discovering and loading available import styles from entry points.
159

160
```python { .api }
161
def list_entry_points():
162
    """
163
    List all available import order style entry points.
164
    
165
    Returns:
166
        List of available style entry points
167
    """
168

169
def lookup_entry_point(name):
170
    """
171
    Look up style entry point by name.
172
    
173
    Args:
174
        name: Style name (e.g., 'cryptography', 'google')
175
        
176
    Returns:
177
        Entry point for the specified style
178
        
179
    Raises:
180
        LookupError: If style name is not found
181
    """
182
```
183

184
### Error Data Type
185

186
Error objects returned by style checking.
187

188
```python { .api }
189
Error = namedtuple("Error", ["lineno", "code", "message"])
190
```
191

192
## Usage Examples
193

194
### Using Built-in Styles
195

196
```python
197
from flake8_import_order.styles import lookup_entry_point, Cryptography
198
from flake8_import_order import ClassifiedImport, NewLine, ImportType
199

200
# Load style by name
201
style_entry = lookup_entry_point('google')
202
style_class = style_entry.load()
203

204
# Create style instance with imports
205
imports = [
206
    ClassifiedImport(ImportType.STDLIB, False, ['os'], [], 1, 1, 0, 'os', False),
207
    ClassifiedImport(ImportType.THIRD_PARTY, False, ['requests'], [], 2, 2, 0, 'requests', False),
208
]
209
style = style_class(imports)
210

211
# Check for errors
212
for error in style.check():
213
    print(f"Line {error.lineno}: {error.code} - {error.message}")
214
```
215

216
### Creating Custom Styles
217

218
```python
219
from flake8_import_order.styles import Style
220

221
class CustomStyle(Style):
222
    """Custom style with reverse alphabetical ordering."""
223
    
224
    @staticmethod
225
    def sorted_names(names):
226
        """Sort names in reverse alphabetical order."""
227
        return sorted(names, reverse=True)
228
    
229
    @staticmethod
230
    def import_key(import_):
231
        """Custom sort key with reverse module ordering."""
232
        return (import_.type, tuple(reversed(import_.modules)))
233

234
# Register custom style via entry points in setup.py:
235
# entry_points={
236
#     'flake8_import_order.styles': [
237
#         'custom = mypackage:CustomStyle',
238
#     ]
239
# }
240
```
241

242
### Style Comparison
243

244
Different styles handle import ordering differently:
245

246
```python
247
# Sample imports
248
imports = [
249
    "import json",
250
    "import os", 
251
    "from mycompany.utils import helper",
252
    "from requests import get"
253
]
254

255
# PEP8: Groups only, no internal ordering enforced
256
# Google: Case-insensitive alphabetical within groups
257
# Smarkets: Like Google, but 'import' statements before 'from' statements
258
# Cryptography: Package-based grouping within third-party/application imports
259
# AppNexus: Like Google with application package support
260
# PyCharm: Case-sensitive alphabetical ordering
261
# ISort: CONSTANTS, Classes, functions ordering within imports
262
```
263

264
### Listing Available Styles
265

266
```python
267
from flake8_import_order.styles import list_entry_points
268

269
# Get all available styles
270
styles = list_entry_points()
271
for style in styles:
272
    print(f"Style: {style.name}")
273
    style_class = style.load()
274
    print(f"  Accepts app packages: {style_class.accepts_application_package_names}")
275
```
276

277
## Style-Specific Features
278

279
### Application Package Names Support
280

281
Some styles support the `application_package_names` configuration option:
282

283
- **AppNexus**: Company/organization packages come after third-party but before application imports
284
- **Edited**: Like AppNexus with additional formatting flexibility
285

286
### Name Sorting Variations
287

288
Different styles sort imported names differently:
289

290
- **Google/Smarkets**: Case-insensitive alphabetical (`import A, a, B, b`)
291
- **PyCharm**: Case-sensitive alphabetical (`import A, B, a, b`)  
292
- **ISort**: Groups by type - CONSTANTS, Classes, functions (`import CONST, Class, func`)
293
- **Cryptography**: Simple alphabetical sorting
294

295
### Section Grouping Rules
296

297
Styles differ in how they group imports into sections:
298

299
- **Standard**: Groups by import type (future, stdlib, third-party, application, relative)
300
- **Cryptography**: Additional sub-grouping by package within third-party/application
301
- **Edited**: Stricter section boundaries, no mixing of import types