======================
 Installation helpers
======================

As icemac.addressbook is not installable using easy_install, there are
some helpers for installation.

ask_user
========

This is a function which ask the user for input, it displays the
default value as set in the configuration file. If the user does not
enter a value the default value is used. The entered value is stored
in the configuration and also returned.

A configuration is needed, it must store the default values:

>>> import ConfigParser
>>> conf = ConfigParser.SafeConfigParser()
>>> conf.add_section('install')
>>> conf.set('install', 'path', '$HOME')

When the user does not enter a value (only hits `enter`) the default
is used:

>>> from icemac.addressbook.install import ask_user
>>> call_with_user_input(
...     '\n', ask_user, conf, 'Choose install dir', 'install', 'path')
Choose install dir: [$HOME]
'$HOME'
>>> conf.get('install', 'path')
'$HOME'

When the user enter a value it is returned and stored:

>>> call_with_user_input(
...     '/Users/mac\n', ask_user, conf, 'Choose install dir', 'install', 'path')
Choose install dir: [$HOME]
'/Users/mac'
>>> conf.get('install', 'path')
'/Users/mac'

The next time the stored value is presented as default:

>>> call_with_user_input(
...     '/home/mac\n', ask_user, conf, 'Choose install dir', 'install', 'path')
Choose install dir: [/Users/mac]
'/home/mac'
>>> conf.get('install', 'path')
'/home/mac'


check_prerequisites
===================

This function tests whether the installation might be successful.

Existing buildout.cfg
---------------------

If there is already a `buildout.cfg` file, an error message is
displayed and ``False`` is returned. In the current directory already
exists a `buildout.cfg`:

>>> ls(sample_buildout)
d  bin
-  buildout.cfg
d  develop-eggs
d  eggs
d  parts
>>> from icemac.addressbook.install import check_prerequisites
>>> check_prerequisites()
ERROR: buildout.cfg already exists.
       Please move the existing one and restart install.
False

If there is no `buildout.cfg` file, ``True`` is returned:

>>> remove(sample_buildout, 'buildout.cfg')
>>> check_prerequisites()
True

Wrong python version
--------------------

icemac.addressbook currently only runs with python 2.5 if another
version is used an error is displayed. We expect here that the version
of the python which runs the tests matches the requirement, so
``True`` is returned:

>>> check_prerequisites()
True

Faking the python version results in the described error message:

>>> import sys
>>> orig_version_info = sys.version_info
>>> sys.version_info = (2, 4, 6, 'final', 0)
>>> check_prerequisites()
ERROR: icemac.addressbook currently only supports python 2.5,
       but you try to install it using python 2.4.6.
False
>>> sys.version_info = (2, 6, 0, 'final', 0)
>>> check_prerequisites()
ERROR: icemac.addressbook currently only supports python 2.5,
       but you try to install it using python 2.6.0.
False
>>> sys.version_info = orig_version_info


Config
======

This function reads a default config file (`install.default.ini`)
whose values are used when the user does not enter a value.

Setup
-----

>>> from icemac.addressbook.install import config
>>> write(sample_buildout, 'install.default.ini',
... """
... [install]
... eggs_dir = py-eggs
...
... [admin]
... login = me
... password = secret
...
... [server]
... host = my.computer.local
... port = 13090
...
... [log]
... handler = FileHandler
... max_size = 1000
... when = midnight
... interval = 1
... backups = 5
... """)

Nothing entered
---------------

>>> call_with_user_input('\n\n\n\n\n\n', config)
Welcome to icemac.addressbook installation
<BLANKLINE>
Hint: to use the default value (the one in [brackets]), enter no value.
<BLANKLINE>
 Directory to store python eggs: [py-eggs]
 Log-in name for the administrator: [me]
 Password for the administrator: [secret]
 Hostname: [my.computer.local]
 Port number: [13090]
 Please choose Log-Handler:
    Details see http://docs.python.org/library/logging.html#handler-objects
 Log-Handler, choose between FileHandler, RotatingFileHandler,
 TimedRotatingFileHandler: [FileHandler]
creating admin.zcml ...
creating buildout.cfg ...
saving config ...

The configuration values are stored in `install.user.ini`:

>>> cat(sample_buildout, 'install.user.ini')
[admin]
login = me
password = secret
<BLANKLINE>
[log]
interval = 1
when = midnight
handler = FileHandler
backups = 5
max_size = 1000
<BLANKLINE>
[install]
eggs_dir = py-eggs
<BLANKLINE>
[server]
host = my.computer.local
port = 13090

To run the installation two more files are written:

>>> cat(sample_buildout, 'buildout.cfg')
[buildout]
extends = profiles/prod.cfg
eggs-directory = py-eggs
<BLANKLINE>
[deploy.ini]
log-handler-args = 'a'
host = my.computer.local
log-handler = FileHandler
port = 13090

>>> cat(sample_buildout, 'admin.zcml')
<configure xmlns="http://namespaces.zope.org/zope">
  <principal
    id="icemac.addressbook.global.Administrator"
    title="global administrator"
    login="me"
    password_manager="Plain Text"
    password="secret" />
  <grant
    role="zope.Manager"
    principal="icemac.addressbook.global.Administrator" />
</configure>

Entered values
--------------

Entered values are stored in all created files. Choosing
`RotatingFileHandler` two more questions are asked:

>>> call_with_user_input(
... """eggs
... admin
... apass
... localhost
... 8080
... RotatingFileHandler
... 12345
... 2
... """, config)
Welcome to icemac.addressbook installation
<BLANKLINE>
Hint: to use the default value (the one in [brackets]), enter no value.
<BLANKLINE>
 Directory to store python eggs: [py-eggs]
 Log-in name for the administrator: [me]
 Password for the administrator: [secret]
 Hostname: [my.computer.local]
 Port number: [13090]
 Please choose Log-Handler:
    Details see http://docs.python.org/library/logging.html#handler-objects
 Log-Handler, choose between FileHandler, RotatingFileHandler,
 TimedRotatingFileHandler: [FileHandler]
 Maximum file size before rotating in bytes: [1000]
 Number of log file backups: [5]
creating admin.zcml ...
creating buildout.cfg ...
saving config ...

>>> cat(sample_buildout, 'install.user.ini')
[admin]
login = admin
password = apass
<BLANKLINE>
[log]
interval = 1
when = midnight
handler = RotatingFileHandler
backups = 2
max_size = 12345
<BLANKLINE>
[install]
eggs_dir = eggs
<BLANKLINE>
[server]
host = localhost
port = 8080

>>> cat(sample_buildout, 'buildout.cfg')
[buildout]
extends = profiles/prod.cfg
eggs-directory = eggs
<BLANKLINE>
[deploy.ini]
log-handler-args = 'a', 12345, 2
host = localhost
log-handler = handlers.RotatingFileHandler
port = 8080

>>> cat(sample_buildout, 'admin.zcml')
<configure xmlns="http://namespaces.zope.org/zope">
  <principal
    id="icemac.addressbook.global.Administrator"
    title="global administrator"
    login="admin"
    password_manager="Plain Text"
    password="apass" />
  <grant
    role="zope.Manager"
    principal="icemac.addressbook.global.Administrator" />
</configure>

Partly entered data
-------------------

If some data is entered those values are stored in the created files
otherwise the defaults are used. When the user enters a wron handler
name he is asked to enter it again. Choosing
`TimedRotatingFileHandler` three additional questions are asked:

>>> call_with_user_input(
... """/Users/icemac/eggs
...
... apass
... localhost
...
... does not matter
... TimedRotatingFileHandler
... D
... 7
...
... """, config)
Welcome to icemac.addressbook installation
<BLANKLINE>
Hint: to use the default value (the one in [brackets]), enter no value.
<BLANKLINE>
 Directory to store python eggs: [py-eggs]
 Log-in name for the administrator: [me]
 Password for the administrator: [secret]
 Hostname: [my.computer.local]
 Port number: [13090]
 Please choose Log-Handler:
    Details see http://docs.python.org/library/logging.html#handler-objects
 Log-Handler, choose between FileHandler, RotatingFileHandler,
 TimedRotatingFileHandler: [FileHandler]
ERROR: 'does not matter' is not in ('FileHandler', 'RotatingFileHandler',
 'TimedRotatingFileHandler').
Please choose one handler out of the list.
 Log-Handler, choose between FileHandler, RotatingFileHandler,
 TimedRotatingFileHandler: [does not matter]
 Type of rotation interval, choose between S, M, H, D, W, midnight: [midnight]
 Rotation interval size: [1]
 Number of log file backups: [5]
creating admin.zcml ...
creating buildout.cfg ...
saving config ...

>>> cat(sample_buildout, 'install.user.ini')
[admin]
login = me
password = apass
<BLANKLINE>
[log]
interval = 7
when = D
handler = TimedRotatingFileHandler
backups = 5
max_size = 1000
<BLANKLINE>
[install]
eggs_dir = /Users/icemac/eggs
<BLANKLINE>
[server]
host = localhost
port = 13090

>>> cat(sample_buildout, 'buildout.cfg')
[buildout]
extends = profiles/prod.cfg
eggs-directory = /Users/icemac/eggs
<BLANKLINE>
[deploy.ini]
log-handler-args = 'D', 7, 5
host = localhost
log-handler = handlers.TimedRotatingFileHandler
port = 13090

>>> cat(sample_buildout, 'admin.zcml')
<configure xmlns="http://namespaces.zope.org/zope">
  <principal
    id="icemac.addressbook.global.Administrator"
    title="global administrator"
    login="me"
    password_manager="Plain Text"
    password="apass" />
  <grant
    role="zope.Manager"
    principal="icemac.addressbook.global.Administrator" />
</configure>
