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, header_text, git_path='.', 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

  • header_text (string) – The text that appears in the header of the 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 that represent a file changed by the commit as well as the change type and all other commit metadata

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

author_date

Date authored

Type

datetime

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

Get a python datetime object of the committed date

Returns

datetime

property hexsha_short

Short version of the commit sha

Returns

str