Metadata-Version: 1.1
Name: SoL
Version: 3.0a22
Summary: Carrom tournaments management
Home-page: https://bitbucket.org/lele/sol
Author: Lele Gaifax
Author-email: lele@metapensiero.it
License: GPLv3+
Description: .. -*- coding: utf-8 -*-
        
        ======================
         Scarry On Lin{e|ux}³
        ======================
        
        -------------------------------------------------------------
        Powerful and complete solution to manage Carrom championships
        -------------------------------------------------------------
        
        This project contains some tools that make it easier the organization of a championship of
        Carrom_.
        
        The main component is a Pyramid_ application serving two distinct user interfaces:
        
        1. A very light, HTML only, read only view of the whole database, where you can actually browse
           thru the tourneys, seasons and players. You can see it in action on the public SoL instance
           at http://sol.metapensiero.it/lit/.
        
        2. A complete ExtJS_ based desktop-like application, that expose all the functionalities
           described below__ in an easy to manage interface, that you can try out visiting
           http://sol.metapensiero.it/.
        
        .. attention:: SoL 3 **requires** Python 3.3 or higher, it does **not** work with Python 2
        
        __ Goals_
        
        .. _Carrom: http://en.wikipedia.org/wiki/Carrom
        .. _Pyramid: http://http://www.pylonsproject.org/
        .. _ExtJS: http://www.sencha.com/products/extjs/
        
        .. contents::
        
        Goals
        =====
        
        These are the key points:
        
        1. Multilingual application
        
           Scarry spoke only italian, because the i18n mechanism in Delphi (and in general under
           Windows) sucks. Most of the code was written and commented in italian too, and that makes it
           very difficult to get foreign contributions
        
        2. Real database
        
           Scarry used Paradox tables, but we are in the third millenium, now: SoL uses a real, even if
           simple and light, SQL database under its skin
        
        3. Easy to use
        
           The application is usually driven by computer-illiterated guys, so little to no surprises
        
        4. Easy to deploy
        
           Gods know how many hours went in building f*cking installers with BDE goodies
        
        5. Bring back the fun
        
           Programming in Python is just that, since the beginning
        
        
        High level description
        ----------------------
        
        The application implements the following features:
        
        * basic tables editing, like adding a new player, opening a new season, manually tweaking the
          scores, and so on;
        
        * handle a single tourney
        
          a. compose a list of `competitors`: usually this is just a single player, but there are two
             people in doubles, or more (teams)
        
          b. set up the first turn, made up of `matches`, each coupling two distinct `competitors`:
             this is usually done randomly, but the arbiter must be able to manually change the
             combinations
        
          c. print the game sheets, where the player will write the scores
        
          d. possibly show a clock, to alert the end of the game
        
          e. insert the score of each table
        
          f. compute the ranking
        
          g. print the current ranking
        
          h. possibly offer a way to retire some competitors, or to add a new competitor
        
          i. compute the next turn
        
          j. repeat steps c. thru i. usually up to seven turns
        
          k. possibly offer a way to go back, delete last turn, correct a score and repeat
        
          l. recompute the ranking, assigning prizes
        
        * handle a season of tourneys
        
          * each tourney is associated to one season
        
          * print the season championship
        
        * data exchange, to import/export whole tourneys in a portable way
        
        
        Installation and Setup
        ======================
        
        The very first requirement to install an instance of SoL on your own machine is getting Python
        3.3\ [#]_. This step obviously depends on the operating system you are using: on most GNU/Linux
        distributions it is already available\ [#]_, for example on Debian and derivatives like Ubuntu
        the following command will do the task::
        
          $ apt-get install python3.3
        
        If instead you are using M$-Windows, you should select the right installer from the downloads__
        page on http://www.python.org/. Most probably you need to install also the `Visual Studio 2010
        Express`__, or alternatively just its runtime__.
        
        To be able to produce readable PDF you need to install also the `DejaVu fonts`__. As usual, on
        GNU/Linux it's a matter of executing the following command::
        
          $ apt-get install fonts-dejavu
        
        or equivalent for your distribution, while on M$-Windows you need to download__ them and
        extract the archive in the right location which usually is ``C:\Windows\Fonts``.
        
        __ http://www.python.org/downloads/windows/
        __ http://www.visualstudio.com/downloads/download-visual-studio-vs#d-2010-express
        __ http://www.microsoft.com/en-us/download/details.aspx?id=5555
        __ http://dejavu-fonts.org/wiki/Main_Page
        __ http://sourceforge.net/projects/dejavu/files/dejavu/2.34/dejavu-fonts-ttf-2.34.zip
        
        
        Easiest way, SoLista
        --------------------
        
        The easiest way is using SoLista_, a buildout_ configuration that will perform most of the
        needed steps with a few clicks: this is particularly indicated if you are *not* fluent with the
        command line interface of your operating system.
        
        Follow the hopefully clear enough steps in SoLista's `README`__.
        
        .. _SoLista: https://bitbucket.org/lele/solista/
        .. _buildout: http://www.buildout.org/en/latest/
        __ https://bitbucket.org/lele/solista/src/master/README.rst
        
        
        The manual way
        --------------
        
        1. Install ``SoL`` using ``pip``::
        
            pip install SoL
        
           that will download the latest version of SoL from PyPI__ and all its dependencies as well
        
           __ https://pypi.python.org/pypi/SoL
        
        2. Install ExtJS_ 4.2.1::
        
            python3.3 -m metapensiero.extjs.desktop
        
        3. Create a standard config file::
        
            soladmin create-config config.ini
        
           and edit it as appropriate
        
        4. Setup the database::
        
            soladmin initialize-db config.ini
        
        5. Load official data::
        
            soladmin restore config.ini
        
        6. Run the application server::
        
            pserve config.ini
        
        7. Enjoy!
           ::
        
            firefox http://localhost:6996/
        
           or, for poor Window$ users or just because using Python makes you
           happier::
        
            python -m webbrowser http://localhost:6996/
        
        
        Development
        ===========
        
        The complete sources are available on Bitbucket__ and can be downloaded with the following
        command::
        
            git clone https://bitbucket.org/lele/sol
        
        After that, you can setup a development environment by executing the command::
        
            pip install -r requirements/development.txt
        
        If you are a developer, you are encouraged to create your own `fork` of the software and
        possibly open a `pull request`: I will happily merge your changes!
        
        You can run the test suite with::
        
            python3.3 setup.py nosetests
        
        __ https://bitbucket.org/lele/sol
        
        
        I18N / L10N
        -----------
        
        Currently SoL is translated in english and italian. If you know other languages and want to
        contribute, the easiest way to create a new translation is to create an account on the
        Weblate__ site and follow its `translators guide`__.
        
        __ https://hosted.weblate.org/projects/sol/
        __ http://docs.weblate.org/en/latest/user/index.html
        
        
        Feedback and support
        --------------------
        
        If you run in troubles, or want to suggest something, or simply a desire of saying *“Thank
        you”* raises up, feel free to contact me via email as ``lele at metapensiero dot it``.
        
        -----
        
        .. [#] As of this writing I'm using version 3.3.5, but SoL should work with the recently
               released Python 3.4 just as well.
        
        .. [#] In fact it may even be already installed!
        
        
        Changes
        -------
        
        3.0a22 (2014-06-16)
        ~~~~~~~~~~~~~~~~~~~
        
        * Show also the organizing club in the tourneys listing
        
        * Parametrize the formula used to compute match outcomes for the Glicko algorithm,
          introducing an exponential variant that takes into account the score difference
        
        * Fix score cards printout, using a smaller font for the competitors names
        
        * Fix data dump, there was an str/bytes issue when operating in non-debug mode
        
        
        3.0a21 (2014-06-13)
        ~~~~~~~~~~~~~~~~~~~
        
        * Change the logic used to determine the current rate of a player, considering only
          the referenced rating and, when inherit is active, those at an higher level, not
          at the same level
        
        
        3.0a20 (2014-06-12)
        ~~~~~~~~~~~~~~~~~~~
        
        * Fix generation of first turn when number of turns when the number of players is odd
        
        * Fix reordering of first turn combinations when the number of players is odd
        
        
        3.0a19 (2014-06-10)
        ~~~~~~~~~~~~~~~~~~~
        
        * Fix the formula used to compute matches outcome, using the whole range of values
          from 0 to 1 instead of just 0, 0.5 and 1
        
        * Parametrize the lower and higher range of the interval used to interpolate players
          rates when the tourney's competitors are (almost) all unrated
        
        
        3.0a18 (2014-05-24)
        ~~~~~~~~~~~~~~~~~~~
        
        * New printout with the results of all played turns
        
        * Fix database upgrade logic
        
        
        3.0a17 (2014-05-16)
        ~~~~~~~~~~~~~~~~~~~
        
        * Fix tourneys export, forgot to include the new phantomscore field
        
        
        3.0a16 (2014-05-16)
        ~~~~~~~~~~~~~~~~~~~
        
        * Show also the player's club after his name in the ranking printout
        
        * Allow customization of the score assigned to players in phantom matches
        
        * Do not delete historical rates when recomputing from scratch non-inheriting
          ratings
        
        
        3.0a15 (2014-04-25)
        ~~~~~~~~~~~~~~~~~~~
        
        * Add an inherit flag to ratings, so the lookup behaviour for player's rate lookup
          is a user choice
        
        * Align the two versions of the user manual
        
        * Minor tweaks to the lit interface
        
        
        3.0a14 (2014-04-06)
        ~~~~~~~~~~~~~~~~~~~
        
        * Fix glitch in player's rate lookup
        
        
        3.0a13 (2014-04-05)
        ~~~~~~~~~~~~~~~~~~~
        
        * Fix PDF printouts font usage, using DejaVuSans also for the page decorations
        
        * ``soladmin create-config`` now asks for the admin password, instead of
          generating it randomly
        
        
        3.0a12 (2014-04-04)
        ~~~~~~~~~~~~~~~~~~~
        
        * Fix glitch in the configuration template
        
        
        3.0a11 (2014-04-04)
        ~~~~~~~~~~~~~~~~~~~
        
        * Fix overlaps in score cards printout
        
        * ``soladmin load-historical-rating`` is now able to use arbitrary formulas
          to compute rate, deviation and volatility
        
        
        3.0a10 (2014-03-31)
        ~~~~~~~~~~~~~~~~~~~
        
        * Do not translate log messages
        
        * More detailed log of applied changes
        
        * Do not clobber existing information from an uploaded archive, as SoL 2 did
        
        * Impose a lower limit of 800 to the player's rates computed by Glicko2
        
        
        3.0a9 (2014-03-28)
        ~~~~~~~~~~~~~~~~~~
        
        * Explicitly require Pillow, since ReportLab 3.0 does not
        
        
        3.0a8 (2014-03-22)
        ~~~~~~~~~~~~~~~~~~
        
        * Tested on Python 3.4
        
        * Require nssjson instead of simplejson
        
        * Minor tweaks to the player window, changing default fields visibility and
          slightly taller to show 23 records at a time
        
        
        3.0a7 (2014-03-17)
        ~~~~~~~~~~~~~~~~~~
        
        * Automatic check of the release date in CHANGES.rst
        
        * Fix compatibility with Python 3.4 using Chameleon 2.15
        
        * Fix another glitch when the guest user is not defined in the configuration
        
        
        3.0a6 (2014-03-08)
        ~~~~~~~~~~~~~~~~~~
        
        * Add a link to this section (on PyPI) to the login panel
        
        
        3.0a5 (2014-03-06)
        ~~~~~~~~~~~~~~~~~~
        
        * New command to update an existing configuration file
        
        
        3.0a4 (2014-03-06)
        ~~~~~~~~~~~~~~~~~~
        
        * Fix minor deploy issue with metapensiero.extjs.desktop
        
        
        3.0a3 (2014-03-06)
        ~~~~~~~~~~~~~~~~~~
        
        * Tweak the deployment infrastructure
        
        * Change package description to improve the chance it gets found
        
        * Some work on the user manuals
        
        
        3.0a2 (2014-03-04)
        ~~~~~~~~~~~~~~~~~~
        
        * Fix various deploy related issues
        
        
        3.0a1 (2014-03-03)
        ~~~~~~~~~~~~~~~~~~
        
        * Let's try the release process!
        
        
        Version 3
        ~~~~~~~~~
        
        * Ported to Python 3.3 and to ExtJS 4.2
        
        * Built on `metapensiero.extjs.desktop`__ and `metapensiero.sqlalchemy.proxy`__
        
          __ https://pypi.python.org/pypi/metapensiero.extjs.desktop
          __ https://pypi.python.org/pypi/metapensiero.sqlalchemy.proxy
        
        * Version control moved from darcs__ to git__ (darcs is beautiful, but git is more powerful and
          many more people use it)
        
          __ http://darcs.net/
          __ http://git-scm.com/
        
        * It tooks almost one year and more than 760 changesets (still counting!)...
        
        
        Highlights
        ++++++++++
        
        * Glicko2__ ratings, with graphical charts
        
          __ http://en.wikipedia.org/wiki/Glicko_rating_system
        
        * Old `championships` are gone, old `seasons` has been renamed to `championships`
        
          People got confused by the overlapping functionality, old championships were an attempt to
          compute national-wide rankings: the new Glicko2-based ratings are much better at that
        
        * Augmented players information to fit international tourneys requirements, clubs may be marked
          as `federations`
        
        * Easier interfaces to insert and modify
        
        * Easier way to upload players portraits and clubs logos
        
        * Hopefully easier installation
        
        * Better infrastructure to accomodate database migrations
        
        * Simpler way to detect potential duplicated players
        
        * Most entities carry a ``GUID`` that make it possible to reliably match them when imported
          from a different SoL instance
        
        * Players merges are tracked and distribuited to other SoL instances
        
        
        Dark ages
        ~~~~~~~~~
        
        ``Scarry`` was a `Delphi 5`__ application I wrote years ago, with the equivalent goal. It
        started as a "quick and dirty" solution to the problem, and Delphi was quite good at that. It
        has served us with good enough reliability for years, but since programming in that environment
        really bored me to death, there's no way I could be convinced to enhance it further.
        
        ``SoL`` is a complete reimplementation, restarting from scratch: it uses exclusively `free
        software`__ components, so that I won't be embaraced to public the whole source code.
        
        __ http://en.wikipedia.org/wiki/Borland_Delphi
        __ http://en.wikipedia.org/wiki/Free_software
        
Keywords: web wsgi bfg pylons pyramid
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: JavaScript
Classifier: Operating System :: OS Independent
Classifier: Framework :: Pyramid
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Natural Language :: Italian
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
