:py:mod:`grading_lib.common`
============================

.. py:module:: grading_lib.common

.. autodoc2-docstring:: grading_lib.common
   :allowtitles:

Module Contents
---------------

Classes
~~~~~~~

.. list-table::
   :class: autosummary longtable
   :align: left

   * - :py:obj:`MinimalistTestResult <grading_lib.common.MinimalistTestResult>`
     - .. autodoc2-docstring:: grading_lib.common.MinimalistTestResult
          :summary:
   * - :py:obj:`BaseTestCaseMeta <grading_lib.common.BaseTestCaseMeta>`
     - .. autodoc2-docstring:: grading_lib.common.BaseTestCaseMeta
          :summary:
   * - :py:obj:`BaseTestCase <grading_lib.common.BaseTestCase>`
     - .. autodoc2-docstring:: grading_lib.common.BaseTestCase
          :summary:
   * - :py:obj:`GeneratorBase <grading_lib.common.GeneratorBase>`
     - .. autodoc2-docstring:: grading_lib.common.GeneratorBase
          :summary:

Functions
~~~~~~~~~

.. list-table::
   :class: autosummary longtable
   :align: left

   * - :py:obj:`is_debug_mode <grading_lib.common.is_debug_mode>`
     - .. autodoc2-docstring:: grading_lib.common.is_debug_mode
          :summary:
   * - :py:obj:`get_seed_from_env <grading_lib.common.get_seed_from_env>`
     - .. autodoc2-docstring:: grading_lib.common.get_seed_from_env
          :summary:
   * - :py:obj:`get_mtime_as_datetime <grading_lib.common.get_mtime_as_datetime>`
     - .. autodoc2-docstring:: grading_lib.common.get_mtime_as_datetime
          :summary:
   * - :py:obj:`has_file_changed <grading_lib.common.has_file_changed>`
     - .. autodoc2-docstring:: grading_lib.common.has_file_changed
          :summary:
   * - :py:obj:`populate_folder_with_filenames <grading_lib.common.populate_folder_with_filenames>`
     - .. autodoc2-docstring:: grading_lib.common.populate_folder_with_filenames
          :summary:
   * - :py:obj:`run_executable <grading_lib.common.run_executable>`
     - .. autodoc2-docstring:: grading_lib.common.run_executable
          :summary:

Data
~~~~

.. list-table::
   :class: autosummary longtable
   :align: left

   * - :py:obj:`COMMAND_FAILED_TEXT_TEMPLATE <grading_lib.common.COMMAND_FAILED_TEXT_TEMPLATE>`
     - .. autodoc2-docstring:: grading_lib.common.COMMAND_FAILED_TEXT_TEMPLATE
          :summary:
   * - :py:obj:`FILE_NOT_EXIST_TEXT_TEMPLATE <grading_lib.common.FILE_NOT_EXIST_TEXT_TEMPLATE>`
     - .. autodoc2-docstring:: grading_lib.common.FILE_NOT_EXIST_TEXT_TEMPLATE
          :summary:
   * - :py:obj:`DEFAULT_FILENAME_POOL <grading_lib.common.DEFAULT_FILENAME_POOL>`
     - .. autodoc2-docstring:: grading_lib.common.DEFAULT_FILENAME_POOL
          :summary:
   * - :py:obj:`FILE_SUFFIX_POOL <grading_lib.common.FILE_SUFFIX_POOL>`
     - .. autodoc2-docstring:: grading_lib.common.FILE_SUFFIX_POOL
          :summary:
   * - :py:obj:`NAME_POOL <grading_lib.common.NAME_POOL>`
     - .. autodoc2-docstring:: grading_lib.common.NAME_POOL
          :summary:
   * - :py:obj:`CommandResult <grading_lib.common.CommandResult>`
     - .. autodoc2-docstring:: grading_lib.common.CommandResult
          :summary:

API
~~~

.. py:data:: COMMAND_FAILED_TEXT_TEMPLATE
   :canonical: grading_lib.common.COMMAND_FAILED_TEXT_TEMPLATE
   :value: <Multiline-String>

   .. autodoc2-docstring:: grading_lib.common.COMMAND_FAILED_TEXT_TEMPLATE

.. py:data:: FILE_NOT_EXIST_TEXT_TEMPLATE
   :canonical: grading_lib.common.FILE_NOT_EXIST_TEXT_TEMPLATE
   :value: "File '{path}' does not exist"

   .. autodoc2-docstring:: grading_lib.common.FILE_NOT_EXIST_TEXT_TEMPLATE

.. py:data:: DEFAULT_FILENAME_POOL
   :canonical: grading_lib.common.DEFAULT_FILENAME_POOL
   :value: ['main.cpp', 'file.txt']

   .. autodoc2-docstring:: grading_lib.common.DEFAULT_FILENAME_POOL

.. py:data:: FILE_SUFFIX_POOL
   :canonical: grading_lib.common.FILE_SUFFIX_POOL
   :value: ['.cpp', '.txt', '.md', '.zip', '.py', '.toml', '.yml', '.yaml']

   .. autodoc2-docstring:: grading_lib.common.FILE_SUFFIX_POOL

.. py:data:: NAME_POOL
   :canonical: grading_lib.common.NAME_POOL
   :value: ['herta', 'cat', 'dog', 'dolphin', 'falcon', 'dandilion', 'fox', 'jett']

   .. autodoc2-docstring:: grading_lib.common.NAME_POOL

.. py:function:: is_debug_mode(variable_name: str = 'DEBUG', vals_for_true: list[str] = ['true', 't', 'on', '1']) -> bool
   :canonical: grading_lib.common.is_debug_mode

   .. autodoc2-docstring:: grading_lib.common.is_debug_mode

.. py:function:: get_seed_from_env(variable_name: str = 'SEED') -> int
   :canonical: grading_lib.common.get_seed_from_env

   .. autodoc2-docstring:: grading_lib.common.get_seed_from_env

.. py:function:: get_mtime_as_datetime(path: pathlib.Path | str) -> datetime.datetime
   :canonical: grading_lib.common.get_mtime_as_datetime

   .. autodoc2-docstring:: grading_lib.common.get_mtime_as_datetime

.. py:function:: has_file_changed(last_known_mtime: datetime.datetime, path: pathlib.Path | str) -> bool
   :canonical: grading_lib.common.has_file_changed

   .. autodoc2-docstring:: grading_lib.common.has_file_changed

.. py:function:: populate_folder_with_filenames(path: pathlib.Path | str, filnames: list[str])
   :canonical: grading_lib.common.populate_folder_with_filenames

   .. autodoc2-docstring:: grading_lib.common.populate_folder_with_filenames

.. py:data:: CommandResult
   :canonical: grading_lib.common.CommandResult
   :value: 'namedtuple(...)'

   .. autodoc2-docstring:: grading_lib.common.CommandResult

.. py:function:: run_executable(args, cwd: typing.Optional[str | pathlib.Path] = None) -> grading_lib.common.CommandResult
   :canonical: grading_lib.common.run_executable

   .. autodoc2-docstring:: grading_lib.common.run_executable

.. py:class:: MinimalistTestResult(*args, **kwargs)
   :canonical: grading_lib.common.MinimalistTestResult

   Bases: :py:obj:`unittest.TextTestResult`

   .. autodoc2-docstring:: grading_lib.common.MinimalistTestResult

   .. rubric:: Initialization

   .. autodoc2-docstring:: grading_lib.common.MinimalistTestResult.__init__

   .. py:method:: getDescription(test)
      :canonical: grading_lib.common.MinimalistTestResult.getDescription

      .. autodoc2-docstring:: grading_lib.common.MinimalistTestResult.getDescription

   .. py:method:: addFailure(test, err)
      :canonical: grading_lib.common.MinimalistTestResult.addFailure

.. py:class:: BaseTestCaseMeta
   :canonical: grading_lib.common.BaseTestCaseMeta

   Bases: :py:obj:`type`

   .. autodoc2-docstring:: grading_lib.common.BaseTestCaseMeta

   .. py:method:: __new__(name: str, bases, attrs: dict)
      :canonical: grading_lib.common.BaseTestCaseMeta.__new__

      .. autodoc2-docstring:: grading_lib.common.BaseTestCaseMeta.__new__

.. py:class:: BaseTestCase(methodName='runTest')
   :canonical: grading_lib.common.BaseTestCase

   Bases: :py:obj:`unittest.TestCase`

   .. autodoc2-docstring:: grading_lib.common.BaseTestCase

   .. rubric:: Initialization

   .. autodoc2-docstring:: grading_lib.common.BaseTestCase.__init__

   .. py:attribute:: with_temporary_dir
      :canonical: grading_lib.common.BaseTestCase.with_temporary_dir
      :type: bool
      :value: None

      .. autodoc2-docstring:: grading_lib.common.BaseTestCase.with_temporary_dir

   .. py:method:: setUp()
      :canonical: grading_lib.common.BaseTestCase.setUp

   .. py:method:: tearDown() -> None
      :canonical: grading_lib.common.BaseTestCase.tearDown

   .. py:method:: assertFileExists(path: pathlib.Path, msg_template: str = FILE_NOT_EXIST_TEXT_TEMPLATE) -> None
      :canonical: grading_lib.common.BaseTestCase.assertFileExists

      .. autodoc2-docstring:: grading_lib.common.BaseTestCase.assertFileExists

   .. py:method:: assertAllFilesExist(paths: list[pathlib.Path], msg=None) -> None
      :canonical: grading_lib.common.BaseTestCase.assertAllFilesExist

      .. autodoc2-docstring:: grading_lib.common.BaseTestCase.assertAllFilesExist

   .. py:method:: assertCommandSuccessful(result: grading_lib.common.CommandResult, msg_template: str = COMMAND_FAILED_TEXT_TEMPLATE) -> None
      :canonical: grading_lib.common.BaseTestCase.assertCommandSuccessful

      .. autodoc2-docstring:: grading_lib.common.BaseTestCase.assertCommandSuccessful

   .. py:method:: assertCommandOutputEqual(result: grading_lib.common.CommandResult, expected_output: str, msg: typing.Optional[str] = None) -> None
      :canonical: grading_lib.common.BaseTestCase.assertCommandOutputEqual

      .. autodoc2-docstring:: grading_lib.common.BaseTestCase.assertCommandOutputEqual

.. py:class:: GeneratorBase
   :canonical: grading_lib.common.GeneratorBase

   .. autodoc2-docstring:: grading_lib.common.GeneratorBase

   .. py:method:: generate(path: pathlib.Path | str) -> None
      :canonical: grading_lib.common.GeneratorBase.generate
      :abstractmethod:

      .. autodoc2-docstring:: grading_lib.common.GeneratorBase.generate

   .. py:method:: run(path: pathlib.Path | str) -> None
      :canonical: grading_lib.common.GeneratorBase.run

      .. autodoc2-docstring:: grading_lib.common.GeneratorBase.run