The |Database| reporitories can be serialized in binary format for faster reloading.
To ensure integrity and freshness of the serialized file, metadata about the packages,
such as source url and
:cpp:type:`RepodataOrigin <mamba::solver::libsolv::RepodataOrigin>`, are stored inside the
file when calling
:cpp:func:`DataBase.native_serialize_repo <mamba::solver::libsolv::Database::native_serialize_repo>` .
Upon reading, similar parameters are expected as inputs to
:cpp:func:`DataBase.add_repo_from_native_serialization <mamba::solver::libsolv::Database::add_repo_from_native_serialization>`.
If they mismatch, the loading results in an error.

A typical wokflow first tries to load a repository from such binary cache, and then quietly
fallbacks to ``repodata.json`` on failure.

Creating a solving request
--------------------------
All jobs that need to be resolved are added as part of a |Request|.
This includes installing, updating, removing packages, as well as solving cutomization parameters.

.. code:: python

   Request = libmambapy.solver.Request
   MatchSpec = libmambapy.specs.MatchSpec

   request = Request(
       jobs=[
           Request.Install(MatchSpec.parse("python>=3.9")),
           Request.Update(MatchSpec.parse("numpy")),
           Request.Remove(MatchSpec.parse("pandas"), clean_dependencies=False),
       ],
       flags=Request.Flags(
           allow_downgrade=True,
           allow_uninstall=True,
       ),
   )

Solving the request
-------------------
The |Request| and the |Database| are the two input parameters needed to solve an environment.
This task is achieved with the :cpp:func:`Solver.solve <mamba::solver::libsolv::Solver::solve>`
method.

.. code:: python

   solver = libmambapy.solver.libsolv.Solver()
   outcome = solver.solve(db, request)

The outcome can be of two types, either a |Solution| listing packages (|Packageinfo|) and the
action to take on them (install, remove...), or an |UnSolvable| type when no solution exists
(because of conflict, missing packages...).

Examine the solution
~~~~~~~~~~~~~~~~~~~~
We can test if a valid solution exists by checking the type of the outcome.
The attribute :cpp:member:`Solution.actions <mamba::solver::Solution::actions>` contains the actions
to take on the installed repository so that it satisfies the |Request| requirements.

.. code:: python

    Solution = libmambapy.solver.Solution

    if isinstance(outcome, Solution):
        for action in outcome.actions:
            if isinstance(action, Solution.Upgrade):
                my_upgrade(from_pkg=action.remove, to_pkg=action.install)
            if isinstance(action, Solution.Reinstall):
                ...
            ...

Alternatively, an easy way to compute the update to the environment is to check for ``install`` and
``remove`` members, since they will populate the relevant fields for all actions:

.. code:: python

    Solution = libmambapy.solver.Solution

    if isinstance(outcome, Solution):
        for action in outcome.actions:
            if hasattr(action, "install"):
                my_download_and_install(action.install)
            # WARN: Do not use `elif` since actions like `Upgrade`
            # are represented as an `install` and `remove` pair.
            if hasattr(action, "remove"):
                my_delete(action.remove)

Understand unsolvable problems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When a problem has no |Solution|, it is inherenty hard to come up with an explanation.
In the easiest case, a required package is missing from the |Database|.
In the most complex, many package dependencies are incompatible without a single culprit.
In this case, packages should be rebuilt with weaker requirements, or with more build variants.
The |UnSolvable| class attempts to build an explanation.

The :cpp:func:`UnSolvable.problems <mamba::solver::libsolv::UnSolvable::problems>` is a list
of problems, as defined by the solver.
It is not easy to understand without linking it to specific |MatchSpec| and |PackageInfo|.
The method
:cpp:func:`UnSolvable.problems_graph <mamba::solver::libsolv::UnSolvable::problems_graph>`
gives a more structured graph of package dependencies and incompatibilities.
This graph is the underlying mechanism used in
:cpp:func:`UnSolvable.explain_problems <mamba::solver::libsolv::UnSolvable::explain_problems>`
to build a detail unsolvability message.