Metadata-Version: 2.4
Name: collective.recipe.cmd
Version: 1.0.0
Summary: Buildout recipe to execute shell commands.
Home-page: https://github.com/collective/collective.recipe.cmd
Author: Gael Pasgrimaud
Author-email: gael@gawel.org
License: BSD
Keywords: buildout recipe
Classifier: Framework :: Buildout
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.rst
Requires-Dist: zc.buildout
Provides-Extra: test
Requires-Dist: zope.testing; extra == "test"
Requires-Dist: zope.testrunner; extra == "test"
Requires-Dist: zc.buildout; extra == "test"
Requires-Dist: manuel; extra == "test"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

*********************
collective.recipe.cmd
*********************

.. contents::

Introduction
************

.. image:: https://secure.travis-ci.org/collective/collective.recipe.cmd.png?branch=master
    :target: http://travis-ci.org/collective/collective.recipe.cmd

``collective.recipe.cmd`` is a `Buildout`_ recipe to execute commands in the
console user interface.

.. _`Buildout`: http://buildout.org/

Usage
*****

Supported options
=================

The recipe supports the following options:

``on_install``
    true if the commands must run on install

``on_update``
    true if the commands must run on update

``cmds``
    a set of command lines

``uninstall_cmds``
    a set of command lines executed in the buildout uninstall phase

``shell``
    a valid interpreter (POSIX only)

Example usage
=============

We need a config file::

  >>> cfg = """
  ... [buildout]
  ... parts = cmds
  ...
  ... [cmds]
  ... recipe = collective.recipe.cmd
  ... on_install=true
  ... cmds= %s
  ... """

  >>> test_file = join(sample_buildout, 'test.txt')
  >>> cmds = 'echo "bouh" > %s' % test_file
  >>> write(sample_buildout, 'buildout.cfg', cfg % cmds)

Ok, so now we can touch a file for testing::

  >>> print(system(buildout))
  Installing cmds...

  >>> 'test.txt' in os.listdir(sample_buildout)
  True

And remove it::

  >>> test_file = join(sample_buildout, 'test.txt')
  >>> if sys.platform == 'win32':
  ...    cmds = 'del %s' % test_file
  ... else:
  ...    cmds = 'rm -f %s' % test_file
  >>> write(sample_buildout, 'buildout.cfg', cfg % cmds)

  >>> print(system(buildout))
  Uninstalling cmds.
  Running uninstall recipe.
  Installing cmds...

  >>> 'test.txt' in os.listdir(sample_buildout)
  False

We can run more than one commands::

  >>> if sys.platform == 'win32':
  ...     cmds = '''
  ... echo "bouh" > %s
  ... del %s
  ... ''' % (test_file, test_file)
  ... else:
  ...     cmds = '''
  ... echo "bouh" > %s
  ... rm -f %s
  ... ''' % (test_file, test_file)

  >>> test_file = join(sample_buildout, 'test.txt')
  >>> if sys.platform == 'win32':
  ...     cmds = 'del %s' % test_file
  ... else:
  ...     cmds = 'rm -f %s' % test_file
  >>> write(sample_buildout, 'buildout.cfg', cfg % cmds)

  >>> print(system(buildout))
  Updating cmds...

  >>> 'test.txt' in os.listdir(sample_buildout)
  False

We can also run some python code::

  >>> cfg = """
  ... [buildout]
  ... parts = py py2
  ...
  ... [py]
  ... recipe = collective.recipe.cmd:py
  ... on_install=true
  ... cmds= 
  ...   >>> import os
  ...   >>> sample_buildout = buildout.get('directory', '.')
  ...   >>> print(sorted(os.listdir(sample_buildout)))
  ...   >>> os.remove(os.path.join(sample_buildout, ".installed.cfg"))
  ...   >>> print(sorted(os.listdir(sample_buildout)))
  ... [py2]
  ... recipe = collective.recipe.cmd:py
  ... on_install=true
  ... cmds=
  ...   >>> def myfunc(value):
  ...   ...     return value and True or False
  ...   >>> v = 20
  ...   >>> print(myfunc(v))
  ... """

  >>> write(sample_buildout, 'buildout.cfg', cfg)

Ok, so now we run it::

  >>> print(system(buildout))
  Uninstalling cmds.
  Running uninstall recipe.
  Installing py.
  ['.installed.cfg', 'bin', 'buildout.cfg', 'develop-eggs', 'eggs', 'parts']
  ['bin', 'buildout.cfg', 'develop-eggs', 'eggs', 'parts']
  Installing py2.
  True...

If the shell script generated from the commands returns a non-zero
exit/status code then an exception is raised and buildout fails::

  >>> cfg = """
  ... [buildout]
  ... parts = cmds
  ...
  ... [cmds]
  ... recipe = collective.recipe.cmd
  ... on_install=true
  ... cmds= exit 23
  ... """

  >>> write(sample_buildout, 'buildout.cfg', cfg)

  >>> print(system(buildout))
  Uninstalling py2.
  Uninstalling py.
  Installing cmds...
  ...subprocess.CalledProcessError: Command 'sh .../run' returned non-zero exit status 23.


Contributors
************

- `Alter Way Solutions <http://www.alterway.fr/solutions/>`_
- Gael Pasgrimaud
- Lorenzo Gil Sanchez
- Maik Röder
- Josip Delić
- Tibor Szakmány (szakitibi), Contributor


Changelog
*********

1.0.0 (2026-08-13)
==================

- Drop support for Python 2 and Python 3 versions older then 3.10.
  [szakitibi]

- Configure with zope.meta.
  [szakitibi]

- Switch to PEP 420 native namespace packages.
  [szakitibi]


0.11 (2015-06-06)
=================

- Add support for Python 3.2 and PyPy3.
- Add support for testing with tox.
- Fix compatibility with ``zope.testing`` 4.2.0.
- Add version and implementation trove classifiers.


0.10 (2015-02-25)
=================

- Fixed PyPy compatibility. [hathawsh]


0.9 (2014-10-04)
================

- Python3. [jod]


0.8 (2013-11-05)
================

- Fix package distribution. [hvelarde]


0.7 (2013-11-04)
================

- Fail if the script generated from ``cmds`` returns with a non-zero
  exit/status code.  [rpatterson]

- Remove GPL remnants.  [rpatterson]


0.6 (2011-11-28)
================

- relicense under BSD as agreed with gawel [jodok]


0.5 (2010-02-03)
================

- dont run commands with on_install/on_update are set to false. Thanks to
  Sean Kelly for bug report
  [gawel]


0.4 (2009-08-18)
================

- Add support for an 'uninstall_cmds' option to execute commands during the
  uninstall Buildout phase.
  [lgs, mroeder]


0.3 (2008-04-22)
================

- apply last version of the recipe template
  [gawel]


0.2 (2008-04-22)
================

- run commands in one process
  [gawel]

- win32 tests compat
  [gawel]
