0
# Create Command
1

2
The create command generates new news fragment files with customizable content, automatic filename handling, and optional editor integration.
3

4
## Capabilities
5

6
### Create Main Function
7

8
The primary entry point for creating news fragments.
9

10
```python { .api }
11
def __main(
12
    ctx: click.Context,
13
    directory: str | None,
14
    config_path: str | None,
15
    filename: str,
16
    edit: bool | None,
17
    content: str,
18
    section: str | None
19
) -> None:
20
    """
21
    Create a new news fragment file.
22
    
23
    Args:
24
        ctx: Click context for CLI operations
25
        directory: Directory to create fragment in (None for current directory)
26
        config_path: Path to custom configuration file
27
        filename: Base filename for the fragment (can be empty for interactive)
28
        edit: Whether to open editor for content (None for config default)
29
        content: Fragment content text
30
        section: Section subdirectory to create fragment in
31
    """
32
```
33

34
### CLI Entry Point
35

36
The Click-decorated command-line interface for the create command.
37

38
```python { .api }
39
def _main(
40
    ctx: click.Context,
41
    directory: str | None,
42
    config: str | None,
43
    filename: str,
44
    edit: bool | None,
45
    content: str,
46
    section: str | None
47
) -> None:
48
    """
49
    Create a new news fragment.
50
    
51
    If FILENAME is not provided, you'll be prompted to create it.
52
    
53
    Standard fragment types by extension:
54
    - .feature - a new feature
55
    - .bugfix - a bug fix  
56
    - .doc - a documentation improvement
57
    - .removal - a deprecation or removal of public API
58
    - .misc - an issue has been closed, but not of interest to users
59
    
60
    If the FILENAME base is just '+' (to create a fragment not tied to an
61
    issue), it will be appended with a random hex string.
62
    """
63
```
64

65
### Content Input Function
66

67
Helper for getting fragment content from user input.
68

69
```python { .api }
70
def _get_news_content_from_user(message: str, extension: str = "") -> str:
71
    """
72
    Get fragment content from user via editor or input prompt.
73
    
74
    Args:
75
        message: Prompt message for the user
76
        extension: File extension for temporary editor file
77
        
78
    Returns:
79
        str: The content provided by the user
80
    """
81
```
82

83
## Fragment Types
84

85
Towncrier supports several standard fragment types identified by file extension:
86

87
### Standard Types
88

89
```python { .api }
90
# Default fragment types
91
FRAGMENT_TYPES = {
92
    "feature": "Features",
93
    "bugfix": "Bugfixes", 
94
    "doc": "Improved Documentation",
95
    "removal": "Deprecations and Removals",
96
    "misc": "Misc"
97
}
98
```
99

100
### Fragment Naming Convention
101

102
Fragment files follow the pattern: `{issue}.{type}[.{counter}]`
103

104
- `issue`: Issue number, identifier, or '+' for orphan fragments
105
- `type`: One of the configured fragment types (feature, bugfix, etc.)
106
- `counter`: Optional counter for multiple fragments of same type/issue
107

108
## Usage Examples
109

110
### Basic Fragment Creation
111

112
```python
113
from towncrier.create import __main as create_main
114
import click
115

116
ctx = click.Context(click.Command('create'))
117

118
# Create a feature fragment
119
create_main(
120
    ctx=ctx,
121
    directory=None,
122
    config_path=None,
123
    filename="123.feature",
124
    edit=False,
125
    content="Added new user authentication system",
126
    section=None
127
)
128
```
129

130
### Interactive Fragment Creation
131

132
```python
133
# Create fragment with editor integration
134
create_main(
135
    ctx=ctx,
136
    directory="/path/to/project",
137
    config_path="custom-towncrier.toml",
138
    filename="456.bugfix",
139
    edit=True,  # Opens editor for content
140
    content="Add your info here",  # Default content
141
    section="auth"  # Create in auth section subdirectory
142
)
143
```
144

145
### Orphan Fragment
146

147
```python
148
# Create fragment not tied to specific issue
149
create_main(
150
    ctx=ctx,
151
    directory=None,
152
    config_path=None,
153
    filename="+.misc",  # '+' creates orphan with random suffix
154
    edit=False,
155
    content="Updated development dependencies",
156
    section=None
157
)
158
```
159

160
### Command Line Usage
161

162
```bash
163
# Create basic feature fragment
164
towncrier create 123.feature
165

166
# Create with custom content
167
towncrier create 456.bugfix --content "Fixed memory leak in parser"
168

169
# Create and open editor
170
towncrier create 789.doc --edit
171

172
# Create in specific directory and section
173
towncrier create 101.feature --dir /path/to/project --section api
174

175
# Create orphan fragment
176
towncrier create +.misc --content "Updated CI configuration"
177

178
# Interactive creation (prompts for filename)
179
towncrier create
180
```
181

182
## Configuration Integration
183

184
The create command uses these configuration values:
185

186
- `directory`: Base directory for fragments (if not using package structure)
187
- `package_dir`: Package directory path
188
- `package`: Package name for locating fragment directory
189
- `types`: Configured fragment types and their display names
190
- `sections`: Section configuration for multi-section projects
191
- `orphan_prefix`: Prefix for orphan fragments (default: "+")
192
- `create_add_extension`: Whether to add file extensions automatically
193
- `create_eof_newline`: Whether to add newline at end of fragment files
194

195
## File Handling
196

197
### Fragment Directory Resolution
198

199
The create command determines fragment location using this priority:
200

201
1. Explicit `directory` parameter
202
2. Configuration `directory` setting
203
3. `{package_dir}/{package}/newsfragments/` structure
204
4. Current working directory fallback
205

206
### Content Processing
207

208
- Default content is "Add your info here" if not specified
209
- Editor integration respects `EDITOR` environment variable
210
- Content is written with proper encoding (UTF-8)
211
- Optional EOF newline based on configuration
212

213
## Error Handling
214

215
The create command handles these error scenarios:
216

217
- **ConfigError**: Invalid configuration or missing required settings
218
- **FileExistsError**: Fragment file already exists
219
- **PermissionError**: Cannot write to fragment directory
220
- **ValidationError**: Invalid filename or fragment type
221
- **EditorError**: Editor command fails or is not available