cement/ChangeLog

.. _changelog:

ChangeLog
==============================================================================

All bugs/feature details can be found at:

   https://github.com/datafolklabs/cement/issues/XXXXX


Where XXXXX is the 'Issue #' referenced below.  Additionally, this change log
is available online at:

    http://builtoncement.com/2.8/changes/


See the :ref:`upgrading` section for more information related to
any incompatible changes, and how to update your application to fix them.
Also check out the :ref:`whats_new` section for details on new features.


2.10.13 - DEVELOPMENT
------------------------------------------------------------------------------

Bugs:

    * :issue:`672` - Fix 2.10.x for Python 3.12


2.10.6-12 - Sat Apr 28, 2018
------------------------------------------------------------------------------

- Bumping version(s) trying to update PyPi Description to Markdown


2.10.4 - Fri Apr 13, 2018
------------------------------------------------------------------------------

Bugs:

    * :issue:`401` - Can't get user in daemon extension
    * :issue:`397` - Removes deprecated `warn` from ILog validator, in-favor
      of `warning`
    * :issue:`401` - Can't get user in daemon extension
    * :issue:`415` - FrameworkError when reusing CementApp object

Features:

    * None

Refactoring:

    * None

Incompatible:

    * None

Deprecation:

    * None


2.10.2 - Thu July 14, 2016
------------------------------------------------------------------------------

Bumping version due to issue with uploading to PyPi.


2.10.0 - Thu July 14, 2016
------------------------------------------------------------------------------

Bugs:

    * :issue:`363` - CementTestCase does not delete temporary
      files/directories
    * :issue:`346` - AttributeError: 'module' object has no attribute 'SIGHUP'
      on Windows
    * :issue:`352` - ``CementApp.extend()`` breaks on ``CementApp.reload()``
    * :issue:`366` - Output handler override options dissappear
    * :issue:`385` - JsonOutputHandler/YamlOutputHandler/MustacheOutputHandler
      Do not pass keyword args down to backend render functions
    * :issue:`393` - ``CementApp.Meta.hooks`` ignored for hooks defined by
      extensions

Features:

    * :issue:`350` - Support for plugin directories
    * :issue:`370` - Handlebars templating support
    * :pr:`371` - Jinja2 templating support
    * :issue:`373` - Switch over to using Flake8 for PEP8 and style compliance
    * :pr:`375` - Redis cache handler support
    * :issue:`379` - Support for alternative config file extensions
    * :issue:`380` - Support for Cython/Compiled Plugins
    * :issue:`389` - ConfigObj support for Python 3
    * :issue:`394` - Watchdog extension for cross-platform filesystem event
      monitoring
    * :issue:`395` - Ability to pass metadata keyword arguments to handlers
      via ``CementApp.Meta.meta_defaults``.

Refactoring;

    * :issue:`386` - Partially deprecated use of ``imp`` in favor of
      ``importlib`` on Python >= 3.1
    * :issue:`390` - ArgparseArgumentHandler should store unknown arguments

Incompatible:

    * None

Deprecation:

    * :issue:`365` - Deprecated ``LoggingLogHandler.warn()``
    * :issue:`372` - Deprecated Explicit Python 3.2 Support
    * :issue:`376` - Deprecated ``cement.core.interface.list()``


2.8.0 - Wed Feb 24, 2016
------------------------------------------------------------------------------

Bugs:

    * :issue:`310` - Resolved issue where console/file logs had duplicate
      entries under certain circumstances.
    * :issue:`314` - Resolved inconsistent behavor in ``colorlog`` extension.
    * :issue:`316` - Running Nose tests with ``-s`` option causes traceback
    * :issue:`317` - Calling ``CementApp.run()`` should return results from
      ``Controller._dispatch()``
    * :issue:`320` - Partials not rendering with Mustache templates
    * :issue:`325` - Wrap Utility Doesn't Support Unicode
    * :issue:`328` - Post Run Hook Not Executing
    * :issue:`331` - KeyError: 'USER' When Running Nose Tests
    * :issue:`338` - Support non-ascii encoding for email subject and body

Features:

    * :issue:`205` - Added new ``ArgparseController`` and ``expose`` decorator
      in ``ext_argparse`` to eventually replace ``CementBaseController``.
    * :issue:`299` - Added Argcomplete Framework Extension
    * :issue:`322` - Added Tabulate Framework Extension (tabulatized output)
    * :issue:`336` - Added Support for ``CementApp.reload()`` (SIGHUP)
    * :issue:`337` - Added ``app.run_forever()`` alternative run method.
    * :issue:`342` - Added Alarm/Timeout Support
    * :issue:`343` - Memcached Extension/Pylibmc Now Supports Python 3

Refactoring:

    * :issue:`311` - Refactor Hooks/Handlers into CementApp
    * :issue:`319` - Use ``os.devnull`` instead of internal ``NullOut`` hack.

Incompatible:

    * :issue:`311` - Hook ``signal`` now requires ``app`` argument.
    * :issue:`313` - Default ``Cement.Meta.exit_on_close`` to ``False``.
      Calls to ``sys.exit()`` should be explicit by the app developer, and
      not implied by the framework.
    * :issue:`332` - Output Handler Interface Must Support Keyword Arguments


2.6.0 - Thu May 14, 2015
------------------------------------------------------------------------------

Bugs:

    * :issue:`294` - Added work-around for scenario where an app wants to
      support arbitrary positional argument with a value of ``default``.
      By default, this will attempt to explicitly call the ``default`` command
      rather than using ``default`` as the argument.  This fix adds
      ``CementBaseController.Meta.default_func`` allowing the developer to
      override the name of the default function that is called if no matching
      sub-command is passed.

Features:

    * :issue:`197` - Added support for colorized logging.
    * :issue:`281` - Added support for Python `with` statement.
    * :issue:`282` - Added support to define/register hooks and handlers via
      ``CementApp.Meta``.
    * :issue:`290` - Added ability to disable Cement framework logging via
      ``CementApp.Meta.framework_logging = False``.
    * :issue:`297` - Added **experimental** support for reloading
      configurations anytime config files and/or plugin config files are
      modified.  Optional extension `ext_reload_config`.

Incompatible:

    * :issue:`308` - No longer require explicit
      ``CementApp.Meta.base_controller`` if a controller with the label of
      ``base`` is registered.  This is potentially backward in-compatible in
      that previously ``CementBaseController.Meta.label`` defaulted to
      ``base``.  It now defaults to ``None``, which makes more sense but will
      break for any controllers that have not explicitly set a ``label`` of
      ``base``.


2.4.0 - Wed Sep 17, 2014
------------------------------------------------------------------------------

Bugs:

    * :issue:`211` - LoggingLogHandler namespace causes issues (regression)
    * :issue:`235` - Duplicate Config Section when plugin already loaded
    * :issue:`246` - Plugin extension does not disable after already being
      enabled

Features:

    * :issue:`119` - Added cement.utils.shell.Prompt to quickly gather user
      input in several different ways.
    * :issue:`182` - Added a mail interface with basic implementations of
      'dummy' (just prints message to console) and 'smtp'
    * :issue:`229` - Ability to override handlers via command line options.
      Also related: :issue:`225`.
    * :issue:`248` - Added documentation for BASH Auto-Completion example.
    * :issue:`249` - Allow utils.shell.exec_cmd* to accept additional.
      parameters, passing all `args` and `kwargs` down to subprocess.Popen.
      Allows features such as changing the current working directory, and
      setting a timeout value, etc (everything that Popen supports).
    * :issue:`257` - CementBaseController._dispatch() should return result
      of controller function.
    * :issue:`259` - Add yaml and yaml_configobj config handlers.
    * :issue:`262` - Add json and json_configobj config handlers.
    * :issue:`267` - Add support for multiple `plugin_dirs` and
      `plugin_config_dirs`
    * :issue:`269` - Allow app.close() to accept an exit code, and exit with
      that code.
    * :issue:`270` - Add support for multiple template_dirs
    * :issue:`274` - Add cement.core.interface.list function
    * :issue:`275` - Added `examples/` directory with working examples based
      on Examples section of the documentation.

Incompatible:

    * :issue:`227` - Standardize handler config section naming conventions.
      All handler config sections are now labeled after ``interface.handler``
      (i.e. ``output.json``, or ``mail.sendgrid``, etc).
    * :issue:`229` - Handler override options deprecate the use of ``--json``,
      and ``--yaml`` output handler options.
    * :issue:`260` - Extensions/Plugins/Bootstrap modules must accept `app`
      argument in `load()` function.  See Upgrading doc for more information.


2.2.0 - Wed Jan 29, 2014
------------------------------------------------------------------------------

Bugs:

    * :issue:`211` - LoggingLogHandler namespace causes issues
    * :issue:`215` - Epilog not printed on --help

Features:

    * :issue:`209` - Added app.debug property to allow developers to know if
      `--debug` was passed at command line of via the config
    * :issue:`219` - Merged ext.memcached into mainline
    * :issue:`222` - Merged ext.configobj into mainline
    * :issue:`223` - Merged ext.genshi into mainline
    * :issue:`224` - Merged ext.yaml into mainline

Incompatible:

    * :issue:`202` - Deprecated namespace packaging for cement and cement.ext.
      Resolves issues with certain IDE's and other situations where the lack
      of a proper ``__init__.py`` causes issues.  This change means that
      external extensions can no longer share the ``cement.ext`` module
      namespace, and must have it's own unique module path.

Misc:

    * Official Git repo relocated to: http://github.com/datafolklabs/cement


2.1.4 - Tue Oct 29, 2013
------------------------------------------------------------------------------

Bugs:

    * :issue:`191` - KeyError when using minimal logger with --debug
    * :issue:`199` - Moved post_argument_parsing hook down, after
      arguments_override_config logic happens.
    * :issue:`204` - utils.misc.wrap should handle None type
    * :issue:`208` - LoggingLogHandler does not honor Meta.config_section


Features:

    * :issue:`190` - Merged daemon extension into core
    * :issue:`194` - Added pre_argument_parsing/post_argument_parsing hooks
    * :issue:`196` - Added utils.misc.wrap
    * :issue:`200` - Merged ext.mustache into mainline.
    * :issue:`203` - Added support for external template directory
    * :issue:`207` - Added support for alternative 'display' name for stacked
      controllers

Incompatible:

    * :issue:`163` - LoggingLogHandler.Meta.clear_loggers was changed from a
      boolean option, to a list.  Additionally,
      LoggingLogHandler.clear_loggers() now requires a `namespace` argument.
      ILog interface no longer defines `clear_loggers()` as a required
      function (though ILog interfaces are welcome to implement one if
      necessary).
    * :issue:`173` - Deprecated 'has_key()' from configparser extension
    * :issue:`201` - Add Deprecation Warning for CementApp.get_last_rendered()


2.1.2 - Thu Nov 1st, 2012
------------------------------------------------------------------------------

This is a branch off of the 2.0.x stable code base.  Maintenance releases for
2.0.x will happen under the stable/2.0.x git branch, while forward feature
development will happen here under as 2.1.x under the git master branch.

Bugs:

    * :issue:`162` - Unable to set log 'level' by config
    * :issue:`167` - Non-stacked controllers not listed in --help
    * :issue:`169` - Fixed tests.utils.shell_tests timeout issue
    * :issue:`171` - No handlers could be found for logger
    * :issue:`183` - os.environ['HOME'] does not exist on Windows

Features:

    * :issue:`161` - Ability to override `usage`
    * :issue:`164` - Store previously rendered data as app._last_rendered, and
      retrievable by app.get_last_rendered().
    * :issue:`165` - Allow utils.fs.backup() to support a suffix kwarg
    * :issue:`166` - Ability to set the 'app' for CementTestCase.make_app()
    * :issue:`170` - Added support for `nested` and `embedded` controllers.

Misc:

    * :issue:`172` - 100% PEP8 Compliant
    * :issue:`160` - Refactor CementApp._resolve_handler() as
      handler.resolve()

Deprecation Notices:

    * :issue:`173` - ConfigParserConfigHandler.has_key() is now deprecated,
      and will be removed in future versions.  Please use `if key in
      app.config.keys(section)` instead.

Incompatible Changes:

    * :issue:`141` - Removed shortcuts from CementBaseController (such as
      log, pargs, etc).  Use `self.app.<shortcut>` instead.
    * :issue:`167` - Listed above, in order to fix this issue as well as
      restrict future issues we implemented a hard requirement that all
      base controllers have the label 'base'.  This should not be a major
      change for anyone using Cement 2.0.x as it is a simple 1 line change
      in any one application.  As all documentation encourages the use of the
      label 'base' it should not be a wide spread incompatibility.
    * :issue:`179` - CementBaseController `hidden`, `visible`, and `exposed`
      have been removed, and replaced by other private means of managing
      the dispatch of commands.
    * CementBaseController no longer implements a `default` command.
    * :issue:`177` - Renamed several cement.core.backend pieces including:
      `handlers` -> `__handlers__`, `hooks` -> `__hooks__`, `SAVED_STDOUT`
      -> `__saved_stdout__`, and `SAVED_STDERR` -> `__saved_stderr__`.
    * :issue:`178` - Moved `backend.defaults()` to
      `utils.misc.init_defaults()`, and `backend.minimal_logger()` to
      `utils.misc.minimal_logger()`


2.0.0 - Fri Aug 03, 2012
------------------------------------------------------------------------------

This is the initial stable release of the 2.0.x branch.  Future releases of
this branch will include bug/security fixes and minor feature updates.
Forward moving feature development will continue out of the 2.1.x branch.

Bugs:

    * :issue:`143` - Incorrect doc regarding logging.  The LoggingLogHandler
      now supports an optional 'namespace' argument allowing the developer
      to override the log prefix.
    * :issue:`150` - foundation.CementApp.Meta.argv now defaults to None,
      but is overridden in __init__() with sys.argv if no other argv is
      passed as meta.

Features:

    * :issue:`138` - Added 'shell' argument to utils.shell.exec_cmd() and
      utils.shell.exec_cmd2().
    * :issue:`140` - Included ~/.myapp/config in default config search
    * :issue:`144` - Added a note on Contributing, as well as a CONTRIBUTORS
      file.
    * :issue:`152` - Added 'argument_formatter' to ControllerBaseClass.Meta.
    * :issue:`153` - Added spawn_process() and spawn_thread() to utils.shell.

Incompatible Changes:

    * :issue:`100` - Interfaces audit.
        * ILog.level() redefined as ILog.get_level()
        * IPlugin.loaded_plugins attribute redefined as
          IPlugin.get_loaded_plugins()
        * IPlugin.enable_plugins attribute redefined as
          IPlugin.get_enabled_plugins()
        * IPlugin.disabled_plugins attribute redefined as
          IPlugin.get_disabled_plugins()
    * :issue:`145` - The IArgument interface no longer specifies that the
      `parsed_args` be maintained by the handler implementation.  This means
      that `app.args.parsed_args` is no longer available, however
      `app.pargs` functions just the same as it points to
      `app._parsed_args`.
    * :issue:`148` - The CementExtensionHandler.loaded_extensions property is
        now a callable at CementExtensionHandler.get_loaded_extensions().
    * :issue:`151` - Removed all previously deprecated code including:
        * Removed CementApp.Meta.defaults, and CementBaseHandler.Meta.defaults.
          Now use `config_defaults` instead.
        * Removed cement.foundation.lay_cement().  Now use CementApp directly.
        * Removed cement.handler.enabled().  Now use `handler.registered()`
          instead.
    * :issue:`154` - Validate for handler config_defaults and config_section
      by default.  Only incompatible if not previously sub-classing from
      handler.CementBaseHandler.
    * :issue:`157` - CementRuntimeError renamed as FrameworkError
    * :issue:`158` - CementSignalError renamed as CaughtSignal
    * :issue:`159` - CementInterfaceError renamed as InterfaceError

Misc:

    * :issue:`155` - Removed unused CementArgumentError, and
      CementConfigError.  These types of exceptions should be defined at
      the application level.

1.9.14 - Sun Jul 16, 2012
------------------------------------------------------------------------------

Bugs:

    * :issue:`127` - Inherited positional arguments listed multiple times

Feature Enhancements:

    * :issue:`131` - Controller aliases
    * :issue:`126` - Add a 'bootstrap' importer to CementApp
    * Added cement.utils.test.CementTestCase for improved testing.

Incompatible Changes:

    * :issue:`129` - Simplify extensions/plugins/hooks/etc.
        * Hooks renamed from 'cement_xxx_hook' to just 'xxx'.  For example, the
          'cement_pre_setup_hook' is now simply 'pre_setup'.  Additionally, the
          'cement_on_close_hook' is now broken out into 'pre_close', and
          'post_close'.
        * The cement.core.hooks.register decorator was replaced with a  simple
          function of the same name.  New usage is:
          register('hook_name', hook_func).
        * Plugins, extensions, and the application bootstrap now attempt to
          call a 'load()' function, meaning library code and loading code can
          live in the same file (i.e. hooks won't be registered just because
          you imported an extension to sub-class a handler, etc).
    * cement.utils.test_helper moved to cement.utils.test.
    * By default, command line arguments no longer override config settings.
      This is now configurable by the CementApp.Meta.arguments_override_config
      boolean.  Related: :issue:`136`.


1.9.12 - Thu Jul 05, 2012
------------------------------------------------------------------------------

Bugs:

    * Fixed version mis-hap in setup.py


1.9.10 - Wed Jul 04, 2012
------------------------------------------------------------------------------

Feature Enhancements:

    * :issue:`118` - Added utils.fs.backup() to safely backup files/dirs.

Misc:

    * :issue:`111` - Use relative imports (makes cement more portable as it
      can be included and distributed with 3rd party sources).
    * :issue:`120` - Use standard json rather than relying on jsonpickle

Incompatible Changes:

    * core.util.abspath moved to utils.fs.abspath
    * core.util.is_true moved to utils.misc.is_true
    * Namespace reverted from 'cement2' back to 'cement'.
    * The following extensions have been removed from the cement source tree,
      and are now available externally (see: http://github.com/cement): daemon,
      memcached, configobj, yaml, genshi.


1.9.8 - Thu May 3, 2012
------------------------------------------------------------------------------

Feature Enhancements:

    * :issue:`95` - Add a 'config_section' Meta default for all handlers.
      Required to parse config options for a handler.
    * :issue:`97` - Add a standard cache handler interface.
    * :issue:`105` - Add 'meta_override' and 'core_meta_override' list to
      CementApp().Meta.  Also resolves :issue:`104`.
    * :issue:`108` - Add CementApp.extend() functionality.
    * :issue:`109` - Add cement.ext.memcached extension

Incompatible Changes:

    * :issue:`103` - plugin_bootstrap_module renamed as plugin_bootstrap.
    * :issue:`106` - Deprecate Meta.defaults in favor of Meta.config_defaults
    * :issue:`107` - Make the app name the default config section, not [base]

1.9.6 - Wed Apr 18, 2012
------------------------------------------------------------------------------

Bug Fixes:

    * :issue:`89` - Secondary controllers display under other controllers
    * :issue:`90` - Logging to file doesn't expand '~'
    * :issue:`91` - Logging to file doesn't create basedir

Feature Enhancements:

    * :issue:`88` - Add cement.ext.genshi extension, provides Genshi Text
      Templating Launguage support.
    * :issue:`93` - Add epilog support for CementBaseController.

Refactoring:

    * :issue:`87` - Refactor Meta handling

Incompatible Changes:

    * :issue:`96` - Move 'setup()' functions to '_setup()'
    * Moved CementBaseController.dispatch() to _dispatch()
    * Moved CementBaseController.usage_text to _usage_text()
    * Moved CementBaseController.help_text to _help_text()
    * backend.defaults() no longer accepts an app name as an argument.
    * foundation.lay_cement() is deprecated.  Use foundation.CementApp()
      directly.
    * No longer pass anything but 'app' object to handlers _setup() functions.
    * handler.enabled() is deprecated.  Use handler.registered().

1.9.4 - Wed Dec 21, 2011
------------------------------------------------------------------------------

Bug Fixes:

    * :issue:`73` - Hooks broken in Python 3
    * :issue:`81` - Controller defaults should be processed before base
      controller.setup()

Feature Enhancements:

    * :issue:`65` - Added 'daemon' extension.  Process is daemonized by
      passing the '--daemon' option.  Handles switching the run user/group, as
      well as managing a pid file.
    * :issue:`72` - Added new framework hooks.
    * :issue:`76` - Added app.close() functionality including a
      cement_on_close_hook() allowing plugins/extensions/etc to be able to
      cleanup on application exit.
    * :issue:`77` - Added default signal handler for SIGINT/SIGTERM as well as
      the cement_signal_hook which is called when any catch_signals are
      encountered.
    * :issue:`78` - Added cement_pre_render_hook, and cement_post_render_hook
      allowing developers to control the data that is rendered to console.
    * :issue:`84` - Ability to run all tests from utils/run_tests.sh

Incompatible Changes:

    * :issue:`72` - The framework hooks 'cement_add_args_hook' and
      'cement_validate_config' were removed in favor of the new pre/post setup
      and run hooks.
    * :issue:`82` - Change 'meta' classes to Python-proper 'Meta', and
      interfaces to use 'IMeta'.  Old functionality will be completely removed
      before Cement stable release.



1.9.2 - Wed Nov 02, 2011
------------------------------------------------------------------------------

This is an initial beta release of Cement, and therefore no bugs or features
are listed.  Future releases will detail all changes.