Class Reference

GenerateChangelog

This is the class you are most likely to use if you want to generate a changelog from your own Python script.

class samsgeneratechangelog.GenerateChangelog(start_ref, end_ref, git_path='.', template_variables=None, custom_attributes=None, template_file=None, template_name='author_by_change_type')

Bases: object

Generate a changelog by rendering a simple but flexible CommitFile object using jinja2.

Parameters

  • start_ref (string) – The commit sha or git ref (tag/head/etc) that the comparison will start from

  • end_ref (string) – The commit sha or git ref (tag/head/etc) that the comparison will end at

  • template_variables (dict) – A dict of variables to pass to Jinja’s Template

  • git_path (string) – The path (relative to the cwd or absolute) that contains the .git folder

  • template_file (string) – The path (relative to the cwd or absolute) to a custom jinja2 template file

  • template_name (string) – The name of one of the templates bundled with the SamsGenerateChangelog package

  • custom_attributes (dict) – A dictionary of of custom attributes to make available under each file object in the template

classmethod get_template_names()

Returns a list of valid template names.

render_markdown()

Return the rendered markdown provided by the template.

render_markdown_to_file(file_path, entry_id)

Render the markdown provided by the template and prepend it to a file.

If an entry already exists pertaining to the current entry_id it will be overwritten.

GitHelper

You will only need to interact with this class if you’re creating your own template builder.

class samsgeneratechangelog.GitHelper(path, custom_attributes=None)

Bases: object

Helper class to facilitate in diffing and organising commits.

Parameters

  • path (string) – Path to the folder containing the git repo

  • custom_attributes (dict) – A dictionary of custom attributes with the attribute name as the key, and subkeys of pattern and derived_from

commit_log(rev_a, rev_b)

Get commit objects for every commit between rev_a and rev_b.

generate_file_commits_from_commit(commit)

Returns a list of FileCommit objects from a given commit.

FileCommit

This is the class from which the file_commits objects in the templates are instantiated. Look here for attributes which you can use directly in your Jinja2 template.

class samsgeneratechangelog.FileCommit(commit, file_path, change_type, repo, custom_attributes=None)

Bases: object

A single file changed by a commit.

Parameters

  • commit (Commit) – The Commit that this file was changed in

  • file_path (str) – The path of the file that was changed relative to the root of the repo

  • change_type (str) – The single character change type

  • repo (Repo) – The Repo that the commit is from

  • custom_attributes (dict) – A dictionary of custom attributes with the attribute name as the key, and subkeys of pattern and derived_from

commit

The Commit object for this commit

Type

Commit

author

The Actor object that authored the commit. Contains email and name attributes

Type

Actor

committer

Committer

Type

str

hexsha

Long form commit sha

Type

str

message

The commit message

Type

str

file_path

The path to the file which was changed (relative to the root of the repo)

Type

str

friendly_change_type

The type of change that happend to this file.

Type

str

property committed_date

Python datetime object of the committed date.

Returns

datetime

property hexsha_short

Short version of the commit sha.

Returns

str