:py:mod:`oioioi.problems.package`
=================================

.. py:module:: oioioi.problems.package

.. autoapi-nested-parse::

   This module contains a problem package backend interface. You should
   create a ``package.py`` file in your new app and implement your package
   backend (inheriting from
   :class:`~oioioi.problems.package.ProblemPackageBackend`)
   whenever you introduce a new problem package format.



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

Classes
~~~~~~~

.. autoapisummary::

   oioioi.problems.package.ProblemPackageBackend



Functions
~~~~~~~~~

.. autoapisummary::

   oioioi.problems.package.backend_for_package



Attributes
~~~~~~~~~~

.. autoapisummary::

   oioioi.problems.package.logger


.. py:data:: logger
   

   

.. py:exception:: ProblemPackageError

   Bases: :py:obj:`Exception`

   A generic exception to be used by or subclassed by backends.


.. py:exception:: PackageProcessingError(func_name, func_doc)

   Bases: :py:obj:`ProblemPackageError`

   A generic exception to be used by or subclassed by backends.


.. py:class:: ProblemPackageBackend

   Bases: :py:obj:`oioioi.base.utils.RegisteredSubclassesBase`, :py:obj:`oioioi.base.utils.ObjectWithMixins`

   A class which manages problem packages.

   The main functionality is extracting archives with problem statements,
   data, model solutions etc. and building
   :class:`~oioioi.problems.models.Problem` instances.

   .. py:attribute:: description
      :annotation: = __human_readable_name_here__

      

   .. py:attribute:: abstract
      :annotation: = True

      

   .. py:attribute:: modules_with_subclasses
      :annotation: = package

      

   .. py:method:: identify(path, original_filename=None)
      :abstractmethod:

      Checks if the backend is suitable for processing the specified
      problem package.

      :param path: a path to the processed problem package

      :param original_filename: the name of the package specified by the
      uploading user.

      Returns ``True`` if the backend can handle the specified problem
      package file.


   .. py:method:: get_short_name(path, original_filename=None)
      :abstractmethod:

      Returns the problem's short name.

      :param path: a path to the processed problem package

      :param original_filename: the name of the package specified by the
      uploading user.


   .. py:method:: unpack(env)
      :abstractmethod:

      Processes a package, creating a new
      :class:`~oioioi.problems.models.Problem` or updating an existing
      one.

      This function will be called either from
      :func:`~oioioi.problems.unpackmgr.unpackmgr_job` (Celery task)
      or from :func:`~oioioi.problems.package.simple_unpack` (e.g. when
      a problem is added from a command line).

      Used ``env`` keys:
        ``package_id``: an id of the
        :class:`~oioioi.problems.models.ProblemPackage` instance
        with the package file to unpack.

      Produced ``env`` keys:
        ``problem_id``: an id of the
        :class:`~oioioi.problems.models.Problem` instance
        representing the created or modified problem.


   .. py:method:: simple_unpack(filename, existing_problem=None)

      This function may be used for unpacking outside unpackmgr.

      :param filename: a path to the problem package file

      :param existing_problem: an instance of
       :class:`~oioioi.problems.models.Problem` to be changed.
        If ``None``, a new :class:`~oioioi.problems.models.Problem` is
        created.

      Returns a :class:`~oioioi.problems.models.Problem` instance.


   .. py:method:: pack(problem)
      :abstractmethod:

      Creates a package from problem, returns a
      :class:`django.http.HttpResponse` instance.

      Should raise ``NotImplementedError`` if creating packages is not
      supported.



.. py:exception:: NoBackend

   Bases: :py:obj:`NotImplementedError`

   Method or function hasn't been implemented yet.


.. py:function:: backend_for_package(filename, original_filename=None)

   Finds a backend suitable for unpacking the given package and returns
   its dotted name.

   :param filename: a path to the processed problem package

   :param original_filename: the name of the package specified by the
   uploading user.