twisted.python._release.NewsBuilder : API documentation

Generate the new section of a NEWS file.

The _FEATURE, _BUGFIX, _DOC, _REMOVAL, and _MISC attributes of this class are symbolic names for the news entry types which are supported. Conveniently, they each also take on the value of the file name extension which indicates a news entry of that type.

Method	build	Load all of the change information from the given directory and write it out to the given output file.
Method	buildAll	No summary
Method	main	Build all news files.
Class Variable	_headings	A `dict` mapping one of the news entry types to the heading to write out for that type of news entry.
Class Variable	_NO_CHANGES	A `str` giving the text which appears when there are no significant changes in a release.
Class Variable	_TICKET_HINT	A `str` giving the text which appears at the top of each news file and which should be kept at the top, not shifted down with all the other content. Put another way, this is the text after which the new news text is inserted.
Method	_today	Return today's date as a string in YYYY-MM-DD format.
Method	_findChanges	Load all the feature ticket summaries.
Method	_formatHeader	Format a header for a NEWS file.
Method	_writeHeader	Write a version header to the given file.
Method	_writeSection	Write out one section (features, bug fixes, etc) to the given file.
Method	_writeMisc	Write out a miscellaneous-changes section to the given file.
Method	_getNewsName	Return the name of `project` that should appear in NEWS.
Method	_iterProjects	Iterate through the Twisted projects in `baseDirectory`, yielding everything we need to know to build news for them.
Method	_changeNewsVersion	Change all references to the current version number in a NEWS file to refer to `newVersion` instead.

_headings =

A dict mapping one of the news entry types to the heading to write out for that type of news entry.

_NO_CHANGES =

A str giving the text which appears when there are no significant changes in a release.

_TICKET_HINT =

A str giving the text which appears at the top of each news file and which should be kept at the top, not shifted down with all the other content. Put another way, this is the text after which the new news text is inserted.

def _today(self): (source)

Return today's date as a string in YYYY-MM-DD format.

def _findChanges(self, path, ticketType): (source)

Load all the feature ticket summaries.

Parameters	path	A `FilePath` the direct children of which to search for news entries.
	ticketType	The type of news entries to search for. One of `NewsBuilder._FEATURE`, `NewsBuilder._BUGFIX`, `NewsBuilder._REMOVAL`, or `NewsBuilder._MISC`.
Returns	A `list` of two-tuples. The first element is the ticket number as an `int`. The second element of each tuple is the description of the feature.

def _formatHeader(self, header): (source)

Format a header for a NEWS file.

A header is a title with '=' signs underlining it.

Parameters	header	The header string to format. (type: `str`)
Returns	A `str` containing `header`.

def _writeHeader(self, fileObj, header): (source)

Write a version header to the given file.

Parameters	fileObj	A file-like object to which to write the header.
	header	The header to write to the file. (type: `str`)

def _writeSection(self, fileObj, header, tickets): (source)

Write out one section (features, bug fixes, etc) to the given file.

Parameters	fileObj	A file-like object to which to write the news section.
	header	The header for the section to write. (type: `str`)
	tickets	A `list` of ticket information of the sort returned by `NewsBuilder._findChanges`.

def _writeMisc(self, fileObj, header, tickets): (source)

Write out a miscellaneous-changes section to the given file.

Parameters	fileObj	A file-like object to which to write the news section.
	header	The header for the section to write. (type: `str`)
	tickets	A `list` of ticket information of the sort returned by `NewsBuilder._findChanges`.

def build(self, path, output, header): (source)

Load all of the change information from the given directory and write it out to the given output file.

Parameters	path	A directory (probably a topfiles directory) containing change information in the form of <ticket>.<change type> files. (type: `FilePath`)
	output	The NEWS file to which the results will be prepended. (type: `FilePath`)
	header	The top-level header to use when writing the news. (type: `str`)

def _getNewsName(self, project): (source)

Return the name of project that should appear in NEWS.

Parameters	project	A `Project`
Returns	The name of `project`.

def _iterProjects(self, baseDirectory): (source)

Iterate through the Twisted projects in baseDirectory, yielding everything we need to know to build news for them.

Yields topfiles, news, name, version for each sub-project in reverse-alphabetical order. topfile is the FilePath for the topfiles directory, news is the FilePath for the NEWS file, name is the nice name of the project (as should appear in the NEWS file), version is the current version string for that project.

Parameters baseDirectory A FilePath representing the root directory beneath which to find Twisted projects for which to generate news (see findTwistedProjects). (type: FilePath)

def buildAll(self, baseDirectory): (source)

Find all of the Twisted subprojects beneath baseDirectory and update their news files from the ticket change description files in their topfiles directories and update the news file in baseDirectory with all of the news.

Parameters baseDirectory A FilePath representing the root directory beneath which to find Twisted projects for which to generate news (see findTwistedProjects).

def _changeNewsVersion(self, news, name, oldVersion, newVersion, today): (source)

Change all references to the current version number in a NEWS file to refer to newVersion instead.

Parameters	news	The NEWS file to change. (type: `FilePath`)
	name	The name of the project to change. (type: `str`)
	oldVersion	The old version of the project. (type: `Version`)
	newVersion	The new version of the project. (type: `Version`)
	today	A YYYY-MM-DD string representing today's date. (type: `str`)

def main(self, args): (source)

Build all news files.

Parameters args The command line arguments to process. This must contain one string, the path to the base of the Twisted checkout for which to build the news. (type: list of str)

t.p._.NewsBuilder(object) : class documentation