TabbycatDebate/tabbycat

View on GitHub
docs/locale/it/LC_MESSAGES/features/data-importers.po

Summary

Maintainability
Test Coverage
msgid ""
msgstr ""
"Project-Id-Version: tabbycat\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2019-12-31 10:38-0400\n"
"PO-Revision-Date: 2021-06-25 17:28\n"
"Last-Translator: \n"
"Language-Team: Italian\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.7.0\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
"X-Crowdin-Project: tabbycat\n"
"X-Crowdin-Project-ID: 364715\n"
"X-Crowdin-Language: it\n"
"X-Crowdin-File: /develop/docs/locale/en/LC_MESSAGES/features/data-importers.po\n"
"X-Crowdin-File-ID: 1283\n"
"Language: it_IT\n"

#: ../../features/data-importers.rst:5
msgid "Tournament Data Importers"
msgstr ""

#: ../../features/data-importers.rst:7
msgid "This page describes how to write your own tournament data importer. It is aimed at an audience that is familiar with programming in Python, and may be willing to get their head around the Django model if necessary."
msgstr ""

#: ../../features/data-importers.rst:9
msgid "The **tournament data importer** is the class that imports data from one or more files (usually CSV files) into the database. A base class ``BaseTournamentDataImporter`` is in `importer/base.py <https://github.com/TabbycatDebate/tabbycat/blob/develop/importer/base.py>`_. An example of a data importer is in `importer/anorak.py <https://github.com/TabbycatDebate/tabbycat/blob/develop/importer/anorak.py>`_."
msgstr ""

#: ../../features/data-importers.rst:11
msgid "Todo"
msgstr ""

#: ../../features/data-importers.rst:11
msgid "This page is incomplete. If you're finding this information insufficient, please contact Chuan-Zheng using the contact details in the :ref:`authors` section."
msgstr ""

#: ../../features/data-importers.rst:14
msgid "Why write your own?"
msgstr ""

#: ../../features/data-importers.rst:16
msgid "While Tabbycat has standard import formats, you might find that none of them fit the data that you need to import."
msgstr ""

#: ../../features/data-importers.rst:18
msgid "It's not possible to devise a single, universally-convenient import file format. Tabbycat supports way too many permutations of configurations for this to be workable. Instead, we provide the ones that have been useful before and are therefore likely to be useful again—but if your tournament has different needs, you might decide that it's easier to write an importer to conform to you, rather than conform to the importer."
msgstr ""

#: ../../features/data-importers.rst:20
msgid "A base importer class abstracts away most of the nitty-gritty of parsing files, allowing new importers to focus on their interpretation with as little code as possible."
msgstr ""

#: ../../features/data-importers.rst:22
msgid "To allow new importers to be written with as little code as possible, most of the work is abstracted to the base class. The flipside of this abstraction is that it induces a learning curve."
msgstr ""

#: ../../features/data-importers.rst:25
msgid "Basic workflow"
msgstr ""

#: ../../features/data-importers.rst:27
msgid "Choose a name. We name importers after items of clothing in alphabetical order (starting at 'Anorak')."
msgstr ""

#: ../../features/data-importers.rst:28
msgid "Write a subclass of ``BaseTournamentDataImporter``."
msgstr ""

#: ../../features/data-importers.rst:29
msgid "Write the front-end interface. This will probably be a `Django management command <https://docs.djangoproject.com/en/1.9/howto/custom-management-commands/>`_."
msgstr ""

#: ../../features/data-importers.rst:32
msgid "A basic example"
msgstr ""

#: ../../features/data-importers.rst:34
msgid "It's easiest to start with an example. Here's a basic importer with just one import method, which imports adjudicators."
msgstr ""

#: ../../features/data-importers.rst:60
msgid "Let's break this down. The method ``import_adjudicators()`` takes a single argument, a file object representing the CSV file. Most of the work is passed off to ``self._import()``. This helper method is defined in ``BaseTournamentDataImporter`` and is where most of the intelligence lies."
msgstr ""

#: ../../features/data-importers.rst:65
msgid "When called, ``self._import(f, model, interpreter)`` does the following:"
msgstr ""

#: ../../features/data-importers.rst:67
msgid "It reads the CSV file using a `csv.DictReader <https://docs.python.org/3/library/csv.html#csv.DictReader>`_. A ``DictReader`` iterates through the CSV file, yielding a dict for each line, whose keys are given by the column header names in the first row of the file."
msgstr ""

#: ../../features/data-importers.rst:72
msgid "On each line:"
msgstr ""

#: ../../features/data-importers.rst:74
msgid "It passes the dict given by the ``DictReader`` to ``interpreter``. The interpreter modifies the dict (or creates a new one) to prepare it for the model constructor, and returns it."
msgstr ""

#: ../../features/data-importers.rst:78
msgid "The dict returned by ``interpreter`` is then passed as keyword arguments to the ``model`` constructor."
msgstr ""

#: ../../features/data-importers.rst:81
msgid "So in very simplified form, ``self._import(f, model, interpreter)`` does this:"
msgstr ""

#: ../../features/data-importers.rst:92
msgid "(There's a lot more to it than that, but that's the basic idea.)"
msgstr ""

#: ../../features/data-importers.rst:94
msgid "A consequence of relying on column headers to identify fields is that the header names in CSV files must match model field names exactly, unless they are deleted by the interpreter using the ``DELETE`` keyword (see below)."
msgstr ""

#: ../../features/data-importers.rst:100
msgid "Interpreters"
msgstr ""

#: ../../features/data-importers.rst:101
msgid "The main task of an importer, then, is to provide interpreters so that ``self._import`` knows how to interpret the data in a CSV file. An interpreter takes a dict and returns a dict. For example:"
msgstr ""

#: ../../features/data-importers.rst:113
msgid "This interpreter does the following:"
msgstr ""

#: ../../features/data-importers.rst:115
msgid "Replaces ``line['institution']`` with an Institution object, by looking up the original value by name."
msgstr ""

#: ../../features/data-importers.rst:117
msgid "Replaces ``line['gender']`` with a ``Person.GENDER_*`` constant. We'll come back to how this works later."
msgstr ""

#: ../../features/data-importers.rst:119
msgid "Adds a new ``line['tournament']`` entry to the dict, being the Tournament object represented by ``self.tournament``, the tournament that was passed to the importer's constructor."
msgstr ""

#: ../../features/data-importers.rst:122
msgid "Leaves all other entries in the dict unchanged."
msgstr ""

#: ../../features/data-importers.rst:124
msgid "This looks simple enough, but it's very robust. What if a cell in the CSV file is blank, or what if the file omits a column? (For example, some tournaments might not collect information about participant gender, so Tabbycat doesn't require it.) We could deal with these scenarios on a case-by-case basis, but that's cumbersome."
msgstr ""

#: ../../features/data-importers.rst:130
msgid "Instead, we provide a ``make_interpreter`` method that returns an interpreter method which, in turn, takes care of all these details. This way, all you have to do is provide the functions that transform fields. So the following is equivalent to the above, but better:"
msgstr ""

#: ../../features/data-importers.rst:143
msgid "Notice that we provided a callable in two of these keyword arguments, and a (non-callable) Tournament object to the third. ``make_interpreter`` is smart enough to tell the difference, and treat them differently. What it does with each field depends on (a) whether a value exists in the CSV file and (b) what transformation function was provided, as summarised in the following table:"
msgstr ""

#: ../../features/data-importers.rst:150
msgid "Value in CSV file"
msgstr ""

#: ../../features/data-importers.rst:150
msgid "Transformation"
msgstr ""

#: ../../features/data-importers.rst:150
msgid "Action"
msgstr ""

#: ../../features/data-importers.rst:152
msgid "provided and not callable"
msgstr ""

#: ../../features/data-importers.rst:152
msgid "populate model field with interpreter value"
msgstr ""

#: ../../features/data-importers.rst:155
msgid "does not exist or blank"
msgstr ""

#: ../../features/data-importers.rst:155
msgid "callable or not provided"
msgstr ""

#: ../../features/data-importers.rst:155
msgid "do not pass to model constructor"
msgstr ""

#: ../../features/data-importers.rst:158 ../../features/data-importers.rst:161
msgid "exists and not blank"
msgstr ""

#: ../../features/data-importers.rst:158
msgid "callable"
msgstr ""

#: ../../features/data-importers.rst:158
msgid "call interpreter on column value, pass result to model constructor"
msgstr ""

#: ../../features/data-importers.rst:161
msgid "not provided"
msgstr ""

#: ../../features/data-importers.rst:161
msgid "pass column value directly to model constructor"
msgstr ""

#: ../../features/data-importers.rst:169
msgid "If a transformation isn't an existing method, you might find `lambda functions <https://docs.python.org/2/tutorial/controlflow.html#lambda-expressions>`_ useful. For example: ``lambda x: Speaker.objects.get(name=x)``."
msgstr ""

#: ../../features/data-importers.rst:173
msgid "You shouldn't check for mandatory fields. If a mandatory field is omitted, the model constructor will throw an error, and ``self._import()`` will catch the error and pass a useful message on to the caller. On the other hand, if it's an optional field in the model, it should optional in the importer, too. Similarly, interpreters generally shouldn't specify defaults; these should be left to model definitions."
msgstr ""

#: ../../features/data-importers.rst:180
msgid "You don't need to include interpreter transformations for things like converting strings to integers, floats or booleans. Django converts strings to appropriate values when it instantiates models. So, for example, adding ``test_score=float`` to the above interpreter would be redundant."
msgstr ""

#: ../../features/data-importers.rst:186
msgid "More complicated interpreters"
msgstr ""

#: ../../features/data-importers.rst:188
msgid "If you have a column in the CSV file that shouldn't be passed to the model constructor, you can tell the interpreter to remove it by using the special ``DELETE`` argument:"
msgstr ""

#: ../../features/data-importers.rst:199
msgid "The ``make_interpreter`` can only deal with modifications where each field is modified separately of the others (or not at all). If you want to combine information from multiple fields, you need to write your interpreter the long way (perhaps calling a function returned by ``make_interpreter`` to do some of the work)."
msgstr ""

#: ../../features/data-importers.rst:205
msgid "On the other hand, if you don't need to do any transformations involving some sort of object or constant lookup, then you can just omit the ``interpreter`` argument of ``self._lookup()``, and it'll just leave the fields as-is."
msgstr ""

#: ../../features/data-importers.rst:210
msgid "Lookup functions"
msgstr ""

#: ../../features/data-importers.rst:211
msgid "In the above example, we used a function ``self.lookup_gender`` to convert from the text in the CSV file to a ``Person.GENDER_*`` constant. To make this easier, the importer provides a convenience function to define such lookup functions. Let's look at the relevant lines again:"
msgstr ""

#: ../../features/data-importers.rst:224
msgid "This should be a member of your subclass, in our case, ``ExampleTournamentDataImporter``. It generates a function that looks something like:"
msgstr ""

#: ../../features/data-importers.rst:241
msgid "The ``make_lookup`` function takes two arguments. The first is a text description of what it's looking up; this is used for the error message if the value in the CSV file isn't recognised. The second is a dict mapping tuples of valid strings to constants."
msgstr ""

#: ../../features/data-importers.rst:247
msgid "Debugging output"
msgstr ""

#: ../../features/data-importers.rst:249
msgid "The ``BaseTournamentDataImporter`` constructor accepts a ``loglevel`` argument:"
msgstr ""

#: ../../features/data-importers.rst:255
msgid "If ``loglevel`` is set to ``logging.DEBUG``, the importer will print information about every instance it creates."
msgstr ""

#: ../../features/data-importers.rst:258
msgid "You can also pass in a logger for it to use (instead of the default one) with the ``logger`` argument."
msgstr ""