Getting started
===============

Prerequisites
-------------

There is a small set of dependencies which are used by sake:

 #. `Stackless Python`__ 2.7 has to be used to run your application.
 #. `setuptools`__.  In order to install the dependencies that follow, the easiest way is to install setuptools so that you have the :command:`easy_install` command at your disposal.
 #. `Paste`__.  With setuptools, you can easily install this with :command:`easy_install -U Paste`.
 #. `PyYAML`__. With setuptools, you can easily install this with :command:`easy_install -U PyYAML`.

__ http://www.stackless.com/
__ http://pypi.python.org/pypi/setuptools
__ http://pypi.python.org/pypi/Paste
__ http://pypi.python.org/pypi/PyYAML

Making a basic application
--------------------------

While the underlying functionality present in sake is well used and tested, an
aspect that still requires work is the interface provided for developers to
customize their application.

The following makes a basic working (but simplistic) sake application:

.. code-block:: python

    import sys
    import os

    from sake import loop
    from sake.const import PLATFORM_WIN32


    scriptFilePath = os.path.realpath(__file__)
    scriptPath = os.path.dirname(scriptFilePath)


    class ExampleApp(loop.App):
        def __init__(self, appName, **kw):
            super(ExampleApp, self).__init__(appName, **kw)

            # Just make a sub-directory in the same directory as this script,
            # to store and access files.
            dataPath = os.path.join(scriptPath, "data")
            if not os.path.exists(dataPath):
                os.mkdir(dataPath)
            self.SetDataPath(dataPath)

            if sys.platform == PLATFORM_WIN32:
                self.timeout = 10
                self.pumpWindowsMessages = True
                self.SetWin32WindowName(appName)


    if __name__ == "__main__":
        # Make the socket module Stackless-compatible, so that blocking socket
        # operations only block the calling tasklet rather than the entire OS
        # thread it is running on.
        import stacklesslib.magic
        stacklesslib.magic.monkeypatch_socket()

        # Correctly instantiate the application sub-class.
        from sake.app import InitializeApp
        app = InitializeApp(ExampleApp, "Sake Example App", redirectLoggerToStdOut=True)

        # Start any non-default or custom services the application may desire.
        import sake.network
        import sake.telnetServer

        services = [
            sake.network.ConnectionService,
            sake.telnetServer.TelnetServer,
        ]
        app.InitServices(services)
        # Run the application until it exits (perhaps CTRL-C in console).
        app.Run()


The typical pattern used is to put the `ExampleApp` subclass into its own
script file.  From there it is imported, to be instantiated and run using
the rest of the above code.