Files
@ 877bcf22bf71
Branch filter:
Location: kallithea/docs/installation_win.rst
877bcf22bf71
8.4 KiB
text/prs.fallenstein.rst
pytest migration: introduce TestControllerPytest
In order to allow tests to benefit from pytest specific functionality, like
fixtures, they can no longer derive from unittest.TestCase. What's more,
while they can derive from any user-defined class, none of the classes
involved (the test class itself nor any of the base classes) can have an
__init__ method.
Converting all tests from unittest-style to pytest-style in one commit is
not realistic. Hence, a more gradual approach is needed.
Most existing test classes derive from TestController, which in turn derives
from BaseTestCase, which derives from unittest.TestCase. Some test classes
derive directly from BaseTestCase.
Supporting both unittest-style and pytest-style from TestController directly
is not possible: pytest-style _cannot_ and unittest-style _must_ derive from
unittest.TestCase. Thus, in any case, an extra level in the class hierarchy
is needed (TestController deriving from Foo and from unittest.TestCase;
pytest-style test classes would then directly derive from Foo).
The requirement that pytest-style test classes cannot have an __init__
method anywhere in the class hierarchy imposes another restriction that
makes it difficult to support both unittest-style and pytest-style test
classes with one class. Any init code needs to be placed in another method
than __init__ and be called explicitly when the test class is initialized.
For unittest-style test classes this would naturally be done with a
setupClass method, but several test classes already use that. Thus, there
would need to be explicit 'super' calls from the test classes. This is
technically possible but not very nice.
A more transparent approach (from the existing test classes point of view),
implemented by this patch, works as follows:
- the implementation of the existing TestController class is now put under
a new class BaseTestController. To accomodate pytest, the __init__ method
is renamed init.
- contrary to the original TestController, BaseTestController does not
derive from BaseTestCase (and neither from unittest.TestCase). Instead,
the 'new' TestController derives both from BaseTestCase, which is
untouched, and from BaseTestController.
- TestController has an __init__ method that calls the base classes'
__init__ methods and the renamed 'init' method of BaseTestController.
- a new class TestControllerPytest is introduced that derives from
BaseTestController but not from BaseTestCase. It uses a pytest fixture to
automatically call the setup functionality previously provided by
BaseTestCase and also calls 'init' on BaseTestController. This means a
little code duplication but is hard to avoid.
The app setup fixture is scoped on the test method, which means that the app
is recreated for every test (unlike for the unittest-style tests where the
app is created per test class). This has the advantage of detecting current
inter-test dependencies and thus improve the health of our test suite. This
in turn is one step closer to allowing parallel test execution.
The unittest-style assert methods (assertEqual, assertIn, ...) do not exist
for pytest-style tests. To avoid having to change all existing test cases
upfront, provide transitional implementations of these methods. The
conversion of the unittest asserts to the pytest/python asserts can happen
gradually over time.
In order to allow tests to benefit from pytest specific functionality, like
fixtures, they can no longer derive from unittest.TestCase. What's more,
while they can derive from any user-defined class, none of the classes
involved (the test class itself nor any of the base classes) can have an
__init__ method.
Converting all tests from unittest-style to pytest-style in one commit is
not realistic. Hence, a more gradual approach is needed.
Most existing test classes derive from TestController, which in turn derives
from BaseTestCase, which derives from unittest.TestCase. Some test classes
derive directly from BaseTestCase.
Supporting both unittest-style and pytest-style from TestController directly
is not possible: pytest-style _cannot_ and unittest-style _must_ derive from
unittest.TestCase. Thus, in any case, an extra level in the class hierarchy
is needed (TestController deriving from Foo and from unittest.TestCase;
pytest-style test classes would then directly derive from Foo).
The requirement that pytest-style test classes cannot have an __init__
method anywhere in the class hierarchy imposes another restriction that
makes it difficult to support both unittest-style and pytest-style test
classes with one class. Any init code needs to be placed in another method
than __init__ and be called explicitly when the test class is initialized.
For unittest-style test classes this would naturally be done with a
setupClass method, but several test classes already use that. Thus, there
would need to be explicit 'super' calls from the test classes. This is
technically possible but not very nice.
A more transparent approach (from the existing test classes point of view),
implemented by this patch, works as follows:
- the implementation of the existing TestController class is now put under
a new class BaseTestController. To accomodate pytest, the __init__ method
is renamed init.
- contrary to the original TestController, BaseTestController does not
derive from BaseTestCase (and neither from unittest.TestCase). Instead,
the 'new' TestController derives both from BaseTestCase, which is
untouched, and from BaseTestController.
- TestController has an __init__ method that calls the base classes'
__init__ methods and the renamed 'init' method of BaseTestController.
- a new class TestControllerPytest is introduced that derives from
BaseTestController but not from BaseTestCase. It uses a pytest fixture to
automatically call the setup functionality previously provided by
BaseTestCase and also calls 'init' on BaseTestController. This means a
little code duplication but is hard to avoid.
The app setup fixture is scoped on the test method, which means that the app
is recreated for every test (unlike for the unittest-style tests where the
app is created per test class). This has the advantage of detecting current
inter-test dependencies and thus improve the health of our test suite. This
in turn is one step closer to allowing parallel test execution.
The unittest-style assert methods (assertEqual, assertIn, ...) do not exist
for pytest-style tests. To avoid having to change all existing test cases
upfront, provide transitional implementations of these methods. The
conversion of the unittest asserts to the pytest/python asserts can happen
gradually over time.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 | .. _installation_win:
================================================================
Installation and upgrade on Windows (7/Server 2008 R2 and newer)
================================================================
First time install
------------------
Target OS: Windows 7 and newer or Windows Server 2008 R2 and newer
Tested on Windows 8.1, Windows Server 2008 R2 and Windows Server 2012
To install on an older version of Windows, see `<installation_win_old.html>`_
Step 1 -- Install Python
^^^^^^^^^^^^^^^^^^^^^^^^
Install Python 2.x.y (x = 6 or 7). Latest version is recommended. If you need another version, they can run side by side.
.. warning:: Python 3.x is not supported.
- Download Python 2.x.y from http://www.python.org/download/
- Choose and click on the version
- Click on "Windows X86-64 Installer" for x64 or "Windows x86 MSI installer" for Win32.
- Disable UAC or run the installer with admin privileges. If you chose to disable UAC, do not forget to reboot afterwards.
While writing this guide, the latest version was v2.7.9.
Remember the specific major and minor versions installed, because they will
be needed in the next step. In this case, it is "2.7".
Step 2 -- Python BIN
^^^^^^^^^^^^^^^^^^^^
Add Python BIN folder to the path. This can be done manually (editing
"PATH" environment variable) or by using Windows Support Tools that
come pre-installed in Windows Vista/7 and later.
Open a CMD and type::
SETX PATH "%PATH%;[your-python-path]" /M
Please substitute [your-python-path] with your Python installation
path. Typically this is ``C:\\Python27``.
Step 3 -- Install pywin32 extensions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Download pywin32 from:
http://sourceforge.net/projects/pywin32/files/
- Click on "pywin32" folder
- Click on the first folder (in this case, Build 219, maybe newer when you try)
- Choose the file ending with ".amd64-py2.x.exe" (".win32-py2.x.exe"
for Win32) where x is the minor version of Python you installed.
When writing this guide, the file was:
http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win-amd64-py2.7.exe/download
(x64)
http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win32-py2.7.exe/download
(Win32)
Step 4 -- Install pip
^^^^^^^^^^^^^^^^^^^^^
pip is a package management system for Python. You will need it to install Kallithea and its dependencies.
If you installed Python 2.7.9+, you already have it (as long as you ran the installer with admin privileges or disabled UAC).
If it was not installed or if you are using Python>=2.6,<2.7.9:
- Go to https://bootstrap.pypa.io
- Right-click on get-pip.py and choose Saves as...
- Run "python2 get-pip.py" in the folder where you downloaded get-pip.py (may require admin access).
.. note::
See http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows
for details and alternative methods.
Note that pip.exe will be placed inside your Python installation's
Scripts folder, which is likely not on your path. To correct this,
open a CMD and type::
SETX PATH "%PATH%;[your-python-path]\Scripts" /M
Step 5 -- Kallithea folder structure
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create a Kallithea folder structure.
This is only an example to install Kallithea. Of course, you can
change it. However, this guide will follow the proposed structure, so
please later adapt the paths if you change them. Folders without
spaces are recommended.
Create the following folder structure::
C:\Kallithea
C:\Kallithea\Bin
C:\Kallithea\Env
C:\Kallithea\Repos
Step 6 -- Install virtualenv
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
A python virtual environment will allow for isolation between the Python packages of your system and those used for Kallithea.
It is strongly recommended to use it to ensure that Kallithea does not change a dependency that other software uses or vice versa.
In a command prompt type::
pip install virtualenv
Virtualenv will now be inside your Python Scripts path (C:\\Python27\\Scripts or similar).
To create a virtual environment, run::
virtualenv C:\Kallithea\Env
Step 7 -- Install Kallithea
^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to install Kallithea, you need to be able to run "pip install kallithea". It will use pip to install the Kallithea Python package and its dependencies.
Some Python packages use managed code and need to be compiled.
This can be done on Linux without any special steps. On Windows, you will need to install Microsoft Visual C++ compiler for Python 2.7.
Download and install "Microsoft Visual C++ Compiler for Python 2.7" from http://aka.ms/vcpython27
.. note::
You can also install the dependencies using already compiled Windows binaries packages. A good source of compiled Python packages is http://www.lfd.uci.edu/~gohlke/pythonlibs/. However, not all of the necessary packages for Kallithea are on this site and some are hard to find, so we will stick with using the compiler.
In a command prompt type (adapting paths if necessary)::
cd C:\Kallithea\Env\Scripts
activate
pip install --upgrade pip setuptools
The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar
(depending of your folder structure). Then type::
pip install kallithea
.. note:: This will take some time. Please wait patiently until it is fully
complete. Some warnings will appear. Don't worry, they are
normal.
Step 8 -- Install git (optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Mercurial being a python package, it was installed automatically when doing "pip install kallithea".
You need to install git manually if you want Kallithea to be able to host git repositories.
See http://git-scm.com/book/en/v2/Getting-Started-Installing-Git#Installing-on-Windows for instructions.
Step 9 -- Configuring Kallithea
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Steps taken from `<setup.html>`_
You have to use the same command prompt as in Step 7, so if you closed
it, reopen it following the same commands (including the "activate"
one). When ready, type::
cd C:\Kallithea\Bin
paster make-config Kallithea production.ini
Then you must edit production.ini to fit your needs (IP address, IP
port, mail settings, database, etc.). `NotePad++`__ or a similar text
editor is recommended to properly handle the newline character
differences between Unix and Windows.
__ http://notepad-plus-plus.org/
For the sake of simplicity, run it with the default settings. After your edits (if any) in the previous command prompt, type::
paster setup-db production.ini
.. warning:: This time a *new* database will be installed. You must
follow a different step to later *upgrade* to a newer
Kallithea version)
The script will ask you for confirmation about creating a new database, answer yes (y)
The script will ask you for the repository path, answer C:\\Kallithea\\Repos (or similar).
The script will ask you for the admin username and password, answer "admin" + "123456" (or whatever you want)
The script will ask you for admin mail, answer "admin@xxxx.com" (or whatever you want).
If you make a mistake and the script doesn't end, don't worry: start it again.
If you decided not to install git, you will get errors about it that you can ignore.
Step 10 -- Running Kallithea
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the previous command prompt, being in the C:\\Kallithea\\Bin folder, type::
paster serve production.ini
Open your web server, and go to http://127.0.0.1:5000
It works!! :-)
Remark:
If it does not work the first time, Ctrl-C the CMD process and start it again. Don't forget the "http://" in Internet Explorer.
What this guide does not cover:
- Installing Celery
- Running Kallithea as a Windows Service. You can investigate here:
- http://pypi.python.org/pypi/wsgisvc
- http://ryrobes.com/python/running-python-scripts-as-a-windows-service/
- http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service
- Using Apache. You can investigate here:
- https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4
Upgrading
---------
Stop running Kallithea
Open a CommandPrompt like in Step 7 (cd to C:\Kallithea\Env\Scripts and activate) and type::
pip install kallithea --upgrade
cd \Kallithea\Bin
Backup your production.ini file now.
Then run::
paster make-config Kallithea production.ini
Look for changes and update your production.ini accordingly.
Next, update the database::
paster upgrade-db production.ini
More details can be found in `<upgrade.html>`_.
|