Freedom

Usage

Very much a Work In Progress

Quick start

>>> python release.py --help

Usage: release.py [OPTIONS]

argument parsing for the cmdline, scripts, programmatic entry-points.

param kwargs:

kwargs exported by the click module.

Options:
--verbose

Enabled more verbose output.

--wizard

Run the release process as an interactive wizard.

--tag-release

tag this release

--push-release

push this release to git

--build-release
 

build this release

--build-docs

build this release’ docs

--publish-pypi

publish release to pypi

--publish-docs-pypi
 

publish release docs to pypi

--publish-docs-rtd
 

publish release docs to ReadTheDocs

--dry-run

Perform a dry-run (no side effects in git or pypi)

--register-project
 

Register project on pypi - see: –project- name

–interactive / –unattended Interactive or unattended execution

(defaults to unattended)

–git-propagate-env / –no-git-propagate-env

Propagate the current environement when calling git (defaults to True)

–python-propagate-env / –no-python-propagate-env

Propagate the current environement when calling python (defaults to True)

--interactive-prompt TEXT
 

Interactive prompt to display(defaults to >>>).

--pypirc TEXT

Path to .pypirc file.

--generate-rcfile TEXT
 

Export all options to this file and exit immediately.

--profile-env TEXT
 

Environmental variable which holds profile information in, defaults to RELEASEME_PROFILE.

--profile TEXT

Load options from this profile file (overrides all other options).

--history-version TEXT
 

New version (optional - previous version will be incremented).

--history-date TEXT
 

The date to use in the history synopsis when tagging a release.

--history-comment TEXT
 

The changelog comment to add.

--history-format TEXT
 

The changelog format to add (must contain three “%s” for version, date, comment).

--history-file TEXT
 

The history text file to use.

--history-delimiter TEXT
 

The history file synopsis delimiter (just prior to history entries).

--history-meta TEXT
 

The history file synopsis (prior to the delimiter).

--git-profile TEXT
 

Load options from this git profile file (overrides all other options)

--git-repo TEXT
 

Location of the git repo to release (defaults to cwd)

--gitrc TEXT

Location of the .gitconfig file (defaults to cwd)

--project-name TEXT
 

Name of this project (same as that which would be published to pypi

--help

Show this message and exit.

TODO: How the release process works.

Configuration

The following freedom configuration values are honored by freedom. If the corresponding configuration is passed in to the freedom constructor, those will take precedence.

verbose A more verbose output.

Recipes

Logging

Each freedom instance has a logger instance variable that is by default not configured with a handler. You can add your own handler to obtain log messages emitted by freedom.

Simple stdout handler:

free = freedom(*args, **kwargs)
free.logger.addHandler(StreamHandler())

Reusing all the handlers of the logger instance of the freedom app:

free = freedom(*args, **kwargs)
for handler in free.logger.handlers:
    free.logger.addHandler(handler)

API

Core

A simple helper interface to the more complex releaser.

This is the programmatic entry-point if calling from another script but does NOT verify kwargs.

freedom.api.build(run=False, logger_name=None, handlers=None, **kwargs)[source]

Convenience method to Build the current release.

FIXME: The exec dict is incorrect/need-updating.

freedom.api.main(run=False, logger_name=None, handlers=None, **kwargs)[source]

Everything - Publish this release to pypi (possibly including the docs)

Parameters:
  • run – Immediately run the release, False - return an object on which can be called with no arguments.
  • logger_name – logger name to use.
  • kwargs – kwargs to pass to the releaser constructor.
freedom.api.publish(run=False, logger_name=None, handlers=None, **kwargs)[source]

Publish this release to pypi (possibly including the docs)

Parameters:
  • run – Immediately run the release, False - return an object on which can be called with no arguments.
  • logger_name – logger name to use.
  • kwargs – kwargs to pass to the releaser constructor.
freedom.api.push(run=False, logger_name=None, handlers=None, **kwargs)[source]

Convenience method to Push the current code to git.

FIXME: The exec dict is incorrect/need-updating.

freedom.api.release(run=False, logger_name=None, handlers=None, **kwargs)[source]

The full-monty: everything involved in a release.

Parameters:
  • run – Immediately run the release, False - return an object on which can be called with no arguments.
  • logger_name – logger name to use.
  • kwargs – kwargs to pass to the releaser constructor.
freedom.api.tag(run=False, logger_name=None, handlers=None, **kwargs)[source]

Tag the current release in git (auto-incrementing the version).

FIXME: The exec dict is incorrect/need-updating.

summary:The Release process work-flow management.
author:francis.horsman@gmail.com
class freedom.core.releaser(logger=None, handlers=None, **kwargs)[source]

Bases: object

The releaser work-flow.

Misc

summary:All actions related functionality goes in here.
author:francis.horsman@gmail.com
class freedom.actions.Actions(core, logger=None, **kwargs)[source]

Bases: freedom.helper.Helper

Actions are called by a Task only.

See:.task.py
Attention:all public methods must have the same signature: “def method_name(self, context)”.
summary:All apps callable from either the bin/freedom-* scripts OR from the

command-line.

author:Francis.horsman@gmail.com
freedom.apps.main_entry(run=True, **kwargs)[source]

Main entry point to the command-line app.

Parameters:kwargs – kwargs exported by the click module.
summary:All building related activities in here.
author:francis.horsman@gpypimail.com
summary:The command-line invoked wrapper for the release system.
author:francis.horsman@gmail.com
class freedom.cli.cli(run=True, logger=None, handlers=None, **kwargs)[source]

Bases: object

Command-line wrapper.

summary:Sensible project defaults
attention:‘options’ flags must have their default value set to ‘False’.
author:francis.horsman@gmail.com
summary:All command execution for git, python and shell goes in here.
author:Francis.horsman@gmail.com
class freedom.execute.Executor(core, logger=None, **kwargs)[source]

Bases: freedom.helper.Helper

The executor controls centralized access to all externals commands.

git(*args, **kwargs)[source]

Run a Git command.

Parameters:
  • args – Args passed directly to Git
  • kwargs – ‘cwd’ = str (see sh _cwd special command kwarg)
  • kwargs – ‘env’ = str (see sh _env special command kwarg)
Returns:

The result from executing the Git command.

python(*args, **kwargs)[source]

Run a Python command.

Parameters:
  • args – Args passed directly to Python
  • kwargs – ‘cwd’ = str (see sh _cwd special command kwarg)
  • kwargs – ‘env’ = str (see sh _env special command kwarg)
Returns:

The result from executing the Python command.

shell(*args, **kwargs)[source]

Run a Shell command.

Parameters:
  • args – Args passed directly to the Shell
  • kwargs – ‘cwd’ = str (see sh _cwd special command kwarg)
  • kwargs – ‘env’ = str (see sh _env special command kwarg)
Returns:

The result from executing the Shell command.

summary:All data export, import is done through here.
author:Francis.horsman@gmail.com
class freedom.export.JsonCodec[source]

Bases: freedom.export.ExporterCodec

Codec designed to import and export using JSON.

class freedom.export.MsgpackCodec[source]

Bases: freedom.export.ExporterCodec

Codec designed to import and export using MSGPACK.

class freedom.export.PickleCodec[source]

Bases: freedom.export.ExporterCodec

Codec designed to import and export using PICKLE.

CODEC_IMPL = <module 'pickle' from '/usr/lib/python2.7/pickle.pyc'>
impl = <module 'pickle' from '/usr/lib/python2.7/pickle.pyc'>
class freedom.export.YamlCodec[source]

Bases: freedom.export.ExporterCodec

Codec designed to import and export using YAML.

summary:All caller’s handlers’s handling (!) goes in here.
author:francis.horsman@gmail.com
summary:All historian related activity is done from here.
author:francis.horsman@gmail.com
class freedom.history.History(core, logger=None, **kwargs)[source]

Bases: freedom.helper.Helper

All functionality relating to historian and versions.

static generate_new_version(history_version_overwrite, current_version)[source]

Increment the current version.

Parameters:
  • history_version_overwrite – new version to use irrespective of current version.
  • current_version – Existing ‘major.minor.revision’, eg: ‘0.1.2’
Returns:

Incremented ‘major.minor.revision’, eg: ‘0.1.3’

summary:All logging and event related functionality is done in here.
author:francis.horsman@gmail.com
summary:
author:Francis.horsman@gmail.com
summary:Profile and options handling.
author:francis.horsman@gmail.com
class freedom.profiles.Profile[source]

Bases: freedom.utils.iExporter

Profile class to allow easy inspection of the profile sections.

static build(d)[source]

Build (overwrite) a new class from exported_data.

static create(d)[source]

Create a new class from a single-depth dict (ie: options).

summary:All publishing to pypi is done from here.
author:francis.horsman@gmail.com
summary:All task related activity in here.
author:francis.horsman@gmail.com
summary:All utility functionality goes in here.
attention:Serialisation to json is attempted using the following libraries in order: (ujson, simplejson, json)
author:francis.horsman@gmail.com
summary:All vcs operations are done through here.
author:francis.horsman@gmail.com

Command line

CLI interface to the release management process
(exposes the entire API).

Exceptions

summary:All exceptions we export.
author:francis.horsman@gmail.com
exception freedom.errors.ConfigurationError(name, value, extended_info=None)[source]

Bases: exceptions.ValueError

A configuration value is incorrect.

exception freedom.errors.ExporterConfigurationError[source]

Bases: exceptions.Exception

An error occurred in the exporter codec creation.

exception freedom.errors.HelperAccessorError(helper_name, exc=None)[source]

Bases: exceptions.Exception

There was an runtime error accessing a helper from another helper.

A helper was accessed by a helper before it was created by the core.

exception freedom.errors.HelperConfigurationError[source]

Bases: exceptions.Exception

An error occurred in the Helper creation.

exception freedom.errors.ImportFailure[source]

Bases: exceptions.Exception

An error occurred when using the exporter to import data.

exception freedom.errors.InteractiveAbort(msg=None, response=None, releaser=None, additional=None)[source]

Bases: freedom.errors.InteractiveMessage

An interactive user requested an abort.

exception freedom.errors.InteractiveDeny(msg=None, response=None, releaser=None, additional=None)[source]

Bases: freedom.errors.InteractiveMessage

An interactive user requested a deny.

exception freedom.errors.InvalidEventLevel(evt)[source]

Bases: exceptions.ValueError

An attempt was made to raise an event with a level that was not supported.

exception freedom.errors.NoProfileFile[source]

Bases: exceptions.Exception

The profile file is not found at the given location.

exception freedom.errors.ProfileConfigurationError[source]

Bases: exceptions.Exception

An error occurred in the profile creation.

exception freedom.errors.ProfileLoadError(exc, msg)[source]

Bases: exceptions.Exception

There was an error loading the profile

exception freedom.errors.TaskConfigurationError[source]

Bases: exceptions.Exception

An error occurred in the task creation.

exception freedom.errors.TaskError(item)[source]

Bases: exceptions.TypeError

A task was used that was not of type: [NoneType, _Task]

exception freedom.errors.UnknownExportCodec(codec)[source]

Bases: exceptions.Exception

An export codec with the given name was not found.

exception freedom.errors.UnsupportedEvent(evt)[source]

Bases: exceptions.ValueError

An attempt was made to raise an event that was not supported.

Changelog

Requirements

sh==1.11 click==3.3 pyyaml==3.11 nose==1.3.1 coverage==3.7.1 tox==1.8 gitpython==0.3.4 sphinx==1.2.3 sphinx-pypi-upload==0.2.1 ujson==1.33 msgpack-python==0.4.4 six==1.9.0 flake8==2.3.0 pylint==1.4.0

References

Francis Horsman

About

Freedom provides full python and pypi release management.

Useful Links

Table Of Contents

This Page