0
# Towncrier
1

2
Towncrier is a utility to produce useful, summarized news files (changelogs) for your project. Rather than reading Git history or having one single file which developers all write to and produce merge conflicts, towncrier reads "news fragments" which contain information useful to end users.
3

4
## Package Information
5

6
- **Package Name**: towncrier
7
- **Language**: Python  
8
- **Installation**: `pip install towncrier`
9

10
## Core Imports
11

12
```python
13
import towncrier
14
```
15

16
For programmatic usage:
17

18
```python
19
from towncrier.build import __main as build_main
20
from towncrier.create import __main as create_main  
21
from towncrier.check import __main as check_main
22
from towncrier._settings import load_config_from_options, Config
23
from towncrier._builder import find_fragments, render_fragments, parse_newfragment_basename
24
from towncrier._project import get_version, get_project_name
25
from towncrier._writer import append_to_newsfile
26
from towncrier._vcs import remove_files, stage_newsfile, get_remote_branches
27
```
28

29
## Basic Usage
30

31
### Command Line Usage
32

33
Build a changelog from news fragments:
34

35
```bash
36
towncrier build
37
```
38

39
Create a new news fragment:
40

41
```bash
42
towncrier create 123.feature
43
```
44

45
Check for news fragments on a branch:
46

47
```bash
48
towncrier check --compare-with origin/main
49
```
50

51
### Programmatic Usage
52

53
```python
54
from towncrier.build import __main as build_main
55
from towncrier._settings import load_config_from_options
56

57
# Load configuration
58
base_directory, config = load_config_from_options(
59
    directory=None,  # Use current directory
60
    config_path=None  # Auto-detect config file
61
)
62

63
# Build changelog programmatically
64
build_main(
65
    draft=False,              # Write to files
66
    directory=None,           # Use current directory  
67
    config_file=None,         # Use auto-detected config
68
    project_name=None,        # Use config or auto-detect
69
    project_version=None,     # Use config or auto-detect
70
    project_date=None,        # Use current date
71
    answer_yes=True,          # Auto-confirm actions
72
    answer_keep=False         # Remove fragments after build
73
)
74
```
75

76
## Architecture
77

78
Towncrier uses a modular architecture with these key components:
79

80
- **Fragment Discovery**: Finds and parses news fragment files based on naming conventions
81
- **Template Rendering**: Uses Jinja2 templates to format the final changelog output
82
- **VCS Integration**: Supports Git, Mercurial, or no VCS for file management
83
- **Configuration System**: TOML-based configuration with sensible defaults
84
- **Multi-format Support**: Can generate RST, Markdown, or custom formatted output
85

86
The workflow involves creating individual fragment files for each change, then running the build command to combine them into a cohesive changelog entry.
87

88
## Capabilities
89

90
### Build Command
91

92
Build a combined news file from news fragments, with options for drafts, custom versions, and fragment management.
93

94
```python { .api }
95
def __main(
96
    draft: bool,
97
    directory: str | None,
98
    config_file: str | None, 
99
    project_name: str | None,
100
    project_version: str | None,
101
    project_date: str | None,
102
    answer_yes: bool,
103
    answer_keep: bool
104
) -> None
105
```
106

107
[Build Command](./build.md)
108

109
### Create Command
110

111
Create new news fragments with customizable content, sections, and automatic editor integration.
112

113
```python { .api }
114
def __main(
115
    ctx: click.Context,
116
    directory: str | None,
117
    config_path: str | None,
118
    filename: str,
119
    edit: bool | None,
120
    content: str,
121
    section: str | None
122
) -> None
123
```
124

125
[Create Command](./create.md)
126

127
### Check Command
128

129
Check for new fragments on a branch by comparing with a base branch and validating fragment requirements.
130

131
```python { .api }
132
def __main(
133
    comparewith: str | None,
134
    directory: str | None,
135
    config_path: str | None,
136
    staged: bool
137
) -> None
138
```
139

140
[Check Command](./check.md)
141

142
### Fragment Processing
143

144
Core functionality for finding, parsing, and rendering news fragments with support for various formats and organization.
145

146
```python { .api }
147
def find_fragments(
148
    base_directory: str,
149
    config: Config,
150
    strict: bool = False
151
) -> tuple[dict[str, dict[tuple[str, str, int], str]], list[tuple[str, str]]]
152

153
def render_fragments(
154
    template: str,
155
    issue_format: str | None,
156
    fragments: Mapping[str, Mapping[str, Mapping[str, Sequence[str]]]],
157
    definitions: Mapping[str, Mapping[str, Any]],
158
    underlines: Sequence[str],
159
    wrap: bool,
160
    versiondata: Mapping[str, str],
161
    top_underline: str = "=",
162
    all_bullets: bool = False,
163
    render_title: bool = True,
164
    md_header_level: int = 1
165
) -> str
166
```
167

168
[Fragment Processing](./fragments.md)
169

170
### Configuration Management
171

172
Load and manage towncrier configuration from TOML files with validation and defaults.
173

174
```python { .api }
175
def load_config_from_options(
176
    directory: str | None,
177
    config_path: str | None
178
) -> tuple[str, Config]
179

180
class Config:
181
    sections: Mapping[str, str]
182
    types: Mapping[str, Mapping[str, Any]]
183
    template: str | tuple[str, str]
184
    start_string: str
185
    package: str
186
    package_dir: str
187
    single_file: bool
188
    filename: str
189
    directory: str | None
190
    version: str | None
191
    name: str
192
    title_format: str | Literal[False] 
193
    issue_format: str | None
194
    underlines: Sequence[str]
195
    wrap: bool
196
    all_bullets: bool
197
    orphan_prefix: str
198
    create_eof_newline: bool
199
    create_add_extension: bool
200
    ignore: list[str] | None
201
    issue_pattern: str
202
```
203

204
[Configuration](./configuration.md)
205

206
### Project Utilities
207

208
Extract project metadata like version and name from packages for automatic changelog generation.
209

210
```python { .api }
211
def get_version(package_dir: str, package: str) -> str
212
def get_project_name(package_dir: str, package: str) -> str
213
```
214

215
[Project Utilities](./project.md)
216

217
### VCS Integration
218

219
Version control system integration for fragment management, branch operations, and news file staging.
220

221
```python { .api }
222
def remove_files(base_directory: str, fragment_filenames: list[str]) -> None
223
def stage_newsfile(directory: str, filename: str) -> None  
224
def get_remote_branches(base_directory: str) -> list[str]
225
def get_default_compare_branch(
226
    base_directory: str, 
227
    branches: Container[str]
228
) -> str | None
229
```
230

231
[VCS Integration](./vcs.md)