*************
Freedom
*************
.. currentmodule:: freedom

Usage
=====

Quick start
-----------
.. code-block:: python

>>> python release.py --help

Usage: release.py [OPTIONS]

Options:
  --verbose                    Enabled more verbose output.
  --tag-release                tag this release
  --push-release               push this release to git
  --build-release              build this release
  --build-release-docs         build this release' docs
  --publish-release-pypi       publish release to pypi
  --publish-release-docs-pypi  publish release docs to pypi
  --publish-release-docs-rtd   publish release docs to ReadTheDocs
  --pypirc TEXT                Path to .pypirc file.
  --export-options TEXT        Export all options to this file.
  --dryrun                     Perform a dry-run (no side effects in git or
                               pypi)
  --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-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: /home/francis/PycharmProjects/freedom)
  --help                       Show this message and exit.

TODO: How the release process works.


.. _resourceLimits-conf:

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

.. tabularcolumns:: |p{6.5cm}|p{8.5cm}|

============================== ================================================
``verbose``                    A more verbose output.
============================== ================================================


.. _resourceLimits-string:

.. _keyfunc-customization:

Recipes
=======

.. _logging:

Logging
-------
Each :class:`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 :mod:`freedom`.

Simple stdout handler::

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

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

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

API
===

Core
----
.. autoclass:: core


Exceptions
----------
.. autoexception:: ProfileLoadError
.. autoexception:: NoProfileFile


.. include:: ../../meta/HISTORY.rst

References
==========

.. include:: ../../meta/CONTRIBUTIONS.rst