.. -*- coding: utf-8 -*-
.. :Project:   SoL
.. :Created:   dom 11 gen 2026, 16:10:44
.. :Author:    Lele Gaifax <lele@metapensiero.it>
.. :License:   GNU General Public License version 3 or later
.. :Copyright: © 2026 Lele Gaifax
..

===================
 Batched I/O views
===================

.. automodule:: sol.views.bio

.. index::
   triple: Route; GET; /bio/backup

.. autofunction:: backup

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/bio/backup``
      * - Method
        - ``GET``
      * - Response
        - ``ZIP``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - only_played_tourneys
               - a boolean flag: when true, not-yet-played events are omitted
             + - serialization_format
               - either ``yaml`` (default) or ``json``, the output format

   This is used to download the whole ``SoL`` database and all the related images (club
   emblems and player portraits) in a single archive.

   Depending on the configuration, the archive may be encrypted.

.. rubric:: Unauthorized call

.. tab:: GNU/Linux and Curl

   .. code-block:: shell

      curl --silent \\
           --out-null \\
           --write-out '%{http_code}\n' \\
           http://server.sol/bio/backup

   ::

      401

.. tab:: MS-Windows and Powershell

   .. code-block:: powershell

      $res = Invoke-WebRequest `
               -Uri "http://server.sol/bio/backup"

      $res.StatusCode

   ::

      401

.. rubric:: Successful call

.. tab:: GNU/Linux and Curl

   .. code-block:: shell

      curl --silent \\
           --cookie cookies.txt \\
           --output sol.backup.zip \\
           http://server.sol/bio/backup

.. tab:: MS-Windows and Powershell

   .. code-block:: powershell

      $ses = Import-Clixml -Path "cookies.txt"

      $res = Invoke-WebRequest -Method Post -SessionVariable ses `
               -OutFile sol.backup.zip `
               -Uri "http://server.sol/bio/backup"

The ``sol.backup.zip`` contains a ``YAML`` file named ``everything.sol`` with the data and a
list of images, something like this::

  Archive:  sol.backup.zip
   Length   Method    Size  Cmpr    Date    Time   CRC-32   Name
  --------  ------  ------- ---- ---------- ----- --------  ----
  15639022  Defl:N  1694628  89% 2026-01-11 09:41 abce9d62  everything.sol
    163210  Defl:N   162374   1% 2024-07-03 15:23 6d755161  portraits/8860871fb654302254126299cc3e8acb.jpeg
    440379  Defl:N   440048   0% 2024-07-03 15:23 64640a4c  portraits/d2dd7e1180ea17ccd124f767275c18e5.jpeg
    137976  Defl:N   137425   0% 2024-07-03 15:23 15e91469  portraits/462057814f7942d1907498fd316df5b9.jpeg
     53096  Defl:N    52769   1% 2024-07-03 15:23 657f8094  portraits/90a697cff481e3ba428ca507b3e6b9f4.jpeg
  …


.. index::
   triple: Route; GET; /bio/dump

.. autofunction:: dump

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/bio/dump``
      * - Method
        - ``GET``
      * - Response
        - ``YAML`` or ``GZIP``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - idtourney
               - the ID of tourney: dump that event alone
             + - idchampionship
               - the ID of a championship: dump a season of events
             + - idclub
               - the ID of a club: dump all events organized by a club

   This is used to download one or more tournaments, for interchange purposes: the document
   may be :func:`re-uploaded <upload>` in a different ``SoL`` instance.

.. rubric:: Unauthorized call

.. tab:: GNU/Linux and Curl

   .. code-block:: shell

      curl --silent --out-null \\
           --write-out '%{http_code}\n' \\
           http://server.sol/bio/dump

   ::

      401

.. tab:: MS-Windows and Powershell

   .. code-block:: powershell

      $res = Invoke-WebRequest `
               -Uri "http://server.sol/bio/dump"

      $res.StatusCode

   ::

      401

.. rubric:: Successful call

.. tab:: GNU/Linux and Curl

   .. code-block:: shell

      curl --silent --cookie cookies.txt \\
           --output sol.dump.gz \\
           http://server.sol/bio/dump?idtourney=123

.. tab:: MS-Windows and Powershell

   .. code-block:: powershell

      $ses = Import-Clixml -Path "cookies.txt"

      $res = Invoke-WebRequest -Method Post -SessionVariable ses `
               -OutputFile sol.dump.gz `
               -Uri "http://server.sol/bio/backup"

The ``sol.dump.gz`` contains a ``YAML`` document with the specified tourney data, something
like the following snippet:

.. code-block:: yaml

   championships:
   - {closed: true, club: 1, couplings: serial,
     description: Doppio CCM 2011-2012, guid: 9f31c246841711e3ac012e92809967e5,
     modified: ! '2014-01-23 10:17:54', playersperteam: 2, previous: 2,
     prizes: millesimal, skipworstprizes: 0}
   clubs:
   - {couplings: serial, description: Carrom Club Milano, emblem: ccm.png,
     guid: 9d70a7ba841711e3ac012e92809967e5, modified: ! '2020-01-29 11:15:49',
     nationality: ITA, owner: 1, prizes: fixed,
     siteurl: 'http://www.carromclubmilano.it/'}
   players:
   - {agreedprivacy: ' ', club: 1, firstname: Vimfyh7i, guid: 9d83946a841711e3ac012e92809967e5,
     lastname: Chifdzvi, modified: ! '2014-01-23 10:17:51', nationality: ITA, sex: M}
   …


.. index::
   triple: Route; POST; /bio/mergePlayers

.. autofunction:: mergePlayers

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/bio/mergePlayers``
      * - Method
        - ``POST``
      * - Response
        - ``JSON``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - tid
               - the ID of the *target* player
             + - sids
               - a list of ID of the players that shall be merged together


.. index::
   triple: Route; POST; /bio/saveChanges

.. autofunction:: saveChanges

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/bio/saveChanges``
      * - Method
        - ``GET``
      * - Response
        - ``JSON``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - modified_records
               - a ``JSON`` array of inserted and/or modified records
             + - deleted_records
               - a ``JSON`` array of deleted records


.. index::
   triple: Route; POST; /bio/upload

.. autofunction:: upload

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/bio/upload``
      * - Method
        - ``POST``
      * - Response
        - ``JSON``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - archive
               - an archive containing one or more tourneys


.. index::
   triple: Route; POST; /bio/recomputeRating

.. autofunction:: recomputeRating

   .. list-table::
      :align: left
      :stub-columns: 1

      * - URL
        - ``/bio/recomputeRating``
      * - Method
        - ``POST``
      * - Response
        - ``JSON``
      * - Parameters
        - .. list-table::
             :align: left
             :stub-columns: 1
             :class: borderless

             + - idrating
               - the ID of the rating to be recomputed

   Normally the ratings are automatically kept in sync with the results of the related
   tournaments, but in some cases, for example when the parameters change, or because an event
   has been cancelled, they may need to be recomputed from scratch.
