SoL 3.28

Carrom tournaments management

This project contains some tools that make it easier the organization of a championship of Carrom tournaments using a variant of the Swiss system.

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 clubs, championships, tourneys, players and ratings. You can see it in action on the public SoL instance at http://sol3.arstecnica.it/lit/.

2. A complete ExtJS based desktop-like application, that exposes all the functionalities described below in an easy to manage interface, that you can try out visiting http://sol3.arstecnica.it/.

Attention!

SoL 3 requires Python 3.3 or higher, it does not work with Python 2

Warning

SoL 3.1+ requires SQLite 3.8 or higher

Contents

• Goals

  • High level description

• Installation and Setup

  • Easiest way, SoLista

  • Pre-built Docker image

  • The good old way

• Development

  • I18N / L10N

  • Feedback and support

  • Changes

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 made it very difficult to get foreign contributions

2. Multiuser

   There is a super user (named “admin” by default) that can do everything, in particular assign a nickname and a password to any player, who can then log in and manage her own tournaments, but can’t change information owned by other users

3. Real database

   Scarry used Paradox tables, but we are in the third millennium, now: SoL uses a real, even if simple and light, SQL database under its skin

4. Easy to use

   The application is usually driven by computer-illiterated guys, so little to no surprises

5. Easy to deploy

   Gods know how many hours went in building f*cking installers with BDE goodies

6. 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 championship, manually tweaking the scores, and so on;

• handle a single tourney

  1. compose a list of competitors: usually this is just a single player, but there are two people in doubles, or more (teams)

  2. set up the first round, made up of matches, each pairing two distinct competitors: if the tournament is associated with a rating this considers the Glicko2 rate of each player, otherwise uses a random pairing; either way, the tournament secretary is able to manually change the combinations

  3. print the game sheets, where the player will write the scores

  4. possibly show a clock, to alert the end of the game

  5. insert the score of each match

  6. compute the new ranking

  7. print the current ranking

  8. possibly offer a way to withdraw some competitors, or to add a new competitor

  9. compute the next round

  10. repeat steps c. thru i. usually up to seven rounds

  11. possibly offer a way to go back, delete last round, correct a score and repeat

  12. recompute the ranking, assigning prizes

  13. update the rating the tournament is associated to

• handle a championship of tourneys

  • each tourney is associated to one championship

  • print the championship ranking

• 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.5 or better[1]. This step obviously depends on the operating system you are using: on most GNU/Linux distributions it is already available[2], for example on Debian and derivatives like Ubuntu the following command will do the task:

$ apt-get install python3

If instead you are using M$-Windows, you should select the right installer from the downloads page on http://www.python.org/.

Non pure Python packages and Windows

The most problematic thing on Windows is being able to install all the required packages: a few of them are actually written in C and there are chances that your particular combination of Python version and Windows version (32bit vs 64bit in particular) isn’t supported by the respective authors.

If the installation fails because a suitable package cannot be found, your only option (other than bugging me) is to install the needed development tools on your machine and retry the installation: the installer should be able to figure out the details and compile the modules.

Since a couple of years Microsoft started to pay attention to the Python world, and actually released a trimmed down version of its development suites expressly to compile Python 2 extension modules, but nothing equivalent is available for Python 3 yet. Instead, you need to install the complete Visual Studio suite in particular, for Python 3.5, the Visual Studio 2015 Community Edition.

Another recommended, although optional, add-on is the DejaVu fonts set, to support a rather wide range of glyphs when producing the PDFs printouts. 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.

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.

Pre-built Docker image

Note

This is a work-in-progress facility: better documentation and helper tools are on the way! It targets brave souls willing to face a bleeding edge experience.

Current state has been contributed by Amar Sanakal, thank you!

Another option, if you have a 64bit computer, is to run the pre-built Docker image.

Requirements

First of all, you must enable the hardware virtualization in the BIOS of your computer.

Then you can proceed to install the Docker Engine for your particular operating system (that is, GNU/Linux, Windows or Mac OS X).

After you have tested the install in the Docker Quickstart terminal (for example as depicted here), run the following command in the same window:

docker run -d -p 80:6996 --name sol amarsanakal/solista

This will start the software and is now accessible on port 80. You can access it as http://<ip-address>.

The <ip-address> is the ip address of the docker machine running on your PC. This would have been displayed to you when you launched the Docker Quickstart terminal. You can check it anytime by running:

docker-machine ls

the ip address is shown under the URL column. Use that without the port number shown there. See https://docs.docker.com/machine/get-started/ for more details.

Roadmap

1. Integrate the image description into SoL itself

2. Figure out how to persist data within the docker container

3. Find a way to automate the steps above, ideally providing a single shell script or batch file to hide nasty details

4. Complete this section

5. Figure out how to build a new image on hub.docker.com tagged with the right version, whenever a new SoL release happens

The good old 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

2. Install ExtJS 4.2.1:

   python3 -m metapensiero.extjs.desktop

3. Create a standard config file:

   soladmin create-config config.ini

   and edit it as appropriate; you can also directly specify the name and the password of the super user (by default the name is admin and the password will be asked interactively):

   soladmin create-config --admin differentone --password str4nge

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 either

make test

or

python setup.py nosetests

I18N / L10N

Currently SoL is translated in English[3], French 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.

Otherwise if like me you prefer using more traditional tools[4] you can extract a copy of the sources and operate directly on the local catalogs under the directory src/sol/locale.

To extract translatable messages use the following command:

make update-catalogs

To check your work you must compile them with:

make compile-catalogs

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.

Consider also joining the dedicated mailing list where you can get in contact with other users of the application. There is also an issues tracker where you can open a new tickets about bugs or enhancements.

---

[1]

As of this writing I’m using version 3.5.1 and I’d recommend using that, but SoL used to work great with Python 3.3 and Python 3.4 as well.

[2]

In fact it may even be already installed!

[3]

The are actually two distinct catalogs, to take into account US and UK variants.

[4]

GNU Emacs comes to mind of course, but there are zillions of them: start looking at the gettext page on Wikipedia.

Changes

3.28 (2016-04-01)

• Add a --data-dir option to soladmin create-config to specify a different location of persistent state

• Recommend Python 3.5

• Initial&incomplete Docker image setup: needs further documentation and some helper tools

3.27 (2016-03-23)

• Fix problem that prevented loading SoL 2 dumps containing a tourney associated with old championship

• In the matches panel, highlight the winning competitor

3.26 (2016-02-16)

• soladmin create-config and soladmin update-config can change the name and the password of the super user

• The final badges show the player’s points, bucholz and netscore

3.25 (2015-12-06)

• Now the admin password can be passed as an option to soladmin create-config

• Request JSON format backup in soladmin restore (N.B.: this requires that the remote server is at least at version 3.23)

3.24 (2015-12-01)

• Fix translation glitch

3.23 (2015-12-01)

• Faster alternative JSON-based dumps and backups, the default is still YAML though

• Always use the serial pairing method when there are less than eight competitors

3.22 (2015-11-27)

• Re-release due to PyPI fault

3.21 (2015-11-27)

• Refresh package dependencies

3.20 (2015-06-07)

• New menu action to assign ownership of multiple records at once

• New “owners admin” permission to permit normal users to adjust ownership of everything

3.19 (2015-05-26)

• Fix URL generation when filtering active players

• Do not fail badly when trying to merge players while importing data

• Handle the case of retired players, while recomputing the rating

3.18 (2015-04-04)

• Handle the “around midnight” case when asking the estimated start time

• Fix a long standing bug with dictionary-based field editors

3.17 (2015-03-22)

• Fix the ordering used to compute the next round when delay of top players pairing is disabled

• Ask the estimated start time when printing the scorecards

• Quicker interaction with the grid filters when adding players to a tournament

3.16 (2015-02-28)

• Allow rectification of any round results

• Fix visualization of notification windows

3.15 (2015-02-20)

• Fix default values in several places

• Rectify assignment of highest numbered board to phantom matches

• Use single click to edit values when entering scores and final bounties

• Show the actual rank used to compute the next turn

3.14 (2015-01-21)

• Fix distribution, including the new robots.txt file

3.13 (2015-01-20)

• Use the OGG format instead of MP3 for the sound files

• Fix tourney replication

• Always assign the highest numbered board to phantom matches

3.12 (2014-12-24)

• Integrate the initial French translation, thanks to Stéphane Cano

• Fix visibility of buttons after deletion of final round

• Use “bounty” instead of “final prize”, hopefully reducing confusion

3.11 (2014-12-06)

• Fix import of championships chain

• Workaround to an annoying bug in ExtJS 4.2.1 grid TAB handling

• Fix strange problem with logout quickly followed by a new login (experienced by Elisa)

• Add missing article related to the Queen to the italian rules (reported by Daniele)

3.10 (2014-11-21)

• Fix ratings modelization that prevented database dumps

• Rectify opponents matches Lit page, showing only direct matches

3.9 (2014-11-08)

• Fix glitch in victories computation in the wins trend chart

3.8 (2014-11-08)

• Allow to restrict rating usage to a single club

• Add player’s opponents summaries to the Lit interface

3.7 (2014-10-19)

• Fix matches panel title, when focusing on a single competitor

• Properly populate the responsible field when showing duplicated players

• Disallow merging of not owned players

3.6 (2014-09-13)

• Raise the pageSize parameter of the Board view to 999

3.5 (2014-09-12)

• Do not show “my” items shortcuts for the guest user

3.4 (2014-09-11)

• Fix localization issues related to reloading the translations catalog, when the user’s language is different from the browser’s default

• Fix ranking printouts, widening the prize column

• Omit the QRCode after more than three days since the event’s date

• New actions to easily open tourney’s championship and championship’s club

3.3 (2014-09-10)

• Add a QRCode on the first page of some printouts, pointing to the “equivalent” Lit page

• Minor tweaks to the font sizes of the personal badges printout

3.2 (2014-09-07)

• Filter out future tourneys by default, to avoid confusion

• Change the “asis” prizing method: it now assigns a decreasing sequence of integer numbers

• New “centesimal” prizing method: similar to the millesimal, but starting from 100

• New variant of top level windows, showing “my” items, launched by shortcuts on the desktop

3.1 (2014-09-04)

• Protect the clock against accidental stops

• Store the timestamp of the countdown start in the database

• Reset the filters when showing possibly duplicated players

• Handle tournament finals, either simple ones or “best of three” matches

• Parametrize the delay of top players pairing

3.0 (2014-08-31)

• Tiny fix to the italian translation catalog

• Final 3.0 release, at last!

3.0rc5 (2014-08-21)

• Fix blank page issue in the results printout, caused by ReportLab KeepTogether shortcoming

• Allow printing selected round results even on prized tourneys

• Fix restore of normal matches visualization after focusing on a single competitor

3.0rc4 (2014-08-21)

• When a particular round is selected, printing the ranking emits the corresponding ranking printout

• Fix recomputation of ranking for earlier rounds, bucholz and netscore were still computed on all the played matches, ignoring the selected round

3.0rc3 (2014-08-17)

• Allow caching on prized tournaments and closed championships pages in the Lit interface

• Allow writing the changes log to a separate file

• Allow reordering of players in new competitors of team events

• Minor fixes to some printouts

• Repeat the printout subtitle in the footer, to avoid confusion when the printout needs several pages (thanks to Daniele for the suggestion)

• Show the corresponding ranking when changing visualized turn matches (thanks to Carlito for the suggestion)

• By default do not restore “in preparation” tournaments

3.0rc2 (2014-07-24)

• Brown paper bag recursive serialization fix

• Slightly faster full backup with stable ordered players and rates

3.0rc1 (2014-07-24)

• Tiny documentation and spelling fixes here and there

• Minor optimizations

• Fix tourney replication, didn’t copy the recently introduced phantomscore

3.0b9 (2014-07-21)

• Fix check that prevented admin to modify managed players

• Fix translation of main menu entries when user has his own preferred language

3.0b8 (2014-07-19)

• Fix message printed by soladmin restore, again

3.0b7 (2014-07-19)

• Fix message printed by soladmin restore

3.0b6 (2014-07-19)

• Minor fixes to the user manuals, thanks to Elisa

• Use better/unambiguous terms, like “turn”->”round”, “coupling”->”pairing”

3.0b5 (2014-07-16)

• Omit the player’s nickname in more common cases

• Better behaviour when the user cancels the edit of a new record

• New players directory pages in the Lit interface

3.0b4 (2014-07-14)

• Add an “About…” link on the login panel pointing to the top level manual

• Slightly improve filtering and tourney subscription sections in the user manual

• Use combos for filtering players and clubs on their nationality

3.0b3 (2014-07-14)

• Fix addition of Owner field when the proxy is called from a lookup combo

• Fix modification of emblems/portraits on old records

3.0b2 (2014-07-13)

• Fix serialization/deserialization when there is a full cycle of ownership

3.0b1 (2014-07-13)

• Beta series, at last, as I do not foresee other disrupting changes

• Use landscape orientation for the championship ranking printout, if needed

• Do not allow nicknames that conflict with the admin or guest accounts

• New “latest tourneys” page in the Lit interface

3.0a28 (2014-07-12)

• More elegant Lit, SVG and PDFs URLs

• Fix chicked-and-egg case in deserialization of owned clubs

• Improve test coverage

3.0a27 (2014-07-10)

• Fix argument handling in SVG rating chart

3.0a26 (2014-07-10)

• Fix translations of the HTML interface

3.0a25 (2014-07-10)

• Revamp the lit interface, using entities UUIDs instead of their internal integer keys and exposing the clubs and ratings

3.0a24 (2014-07-08)

• The guest user cannot upload anymore, so it is effectively harmless

• Prevent filtering and ordering on the Owner column

• Show a popup window to remind that changes needs to be confirmed

3.0a23 (2014-07-06)

• Add the concept of “ownership” on top-level entities, so different users cannot step on each other work in progress (see issue #1)

• Activate a public mailing list and an issue tracker

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

• Version control moved from darcs to git (darcs is beautiful, but git is more powerful and many more people use it)

• It tooks almost one year and more than 760 changesets (still counting!)…

Highlights

• Glicko2 ratings, with graphical charts

• 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 publish the whole source code.