"Fossies" - the Fresh Open Source Software Archive

Member "conda-4.7.10/conda/api.py" (19 Jul 2019, 17222 Bytes) of package /linux/misc/conda-4.7.10.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Python source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "api.py" see the Fossies "Dox" file reference documentation and the last Fossies "Diffs" side-by-side code changes report: 4.7.4_vs_4.7.5.

    1 # -*- coding: utf-8 -*-
    2 # Copyright (C) 2012 Anaconda, Inc
    3 # SPDX-License-Identifier: BSD-3-Clause
    4 from __future__ import absolute_import, division, print_function, unicode_literals
    5 
    6 from .common.constants import NULL
    7 from .core.package_cache_data import PackageCacheData as _PackageCacheData
    8 from .core.prefix_data import PrefixData as _PrefixData
    9 from .core.solve import DepsModifier as _DepsModifier, Solver as _Solver
   10 from .core.solve import UpdateModifier as _UpdateModifier
   11 from .core.subdir_data import SubdirData as _SubdirData
   12 from .models.channel import Channel
   13 
   14 DepsModifier = _DepsModifier
   15 """Flags to enable alternate handling of dependencies."""
   16 
   17 UpdateModifier = _UpdateModifier
   18 """Flags to enable alternate handling for updates of existing packages in the environment."""
   19 
   20 
   21 class Solver(object):
   22     """
   23     **Beta** While in beta, expect both major and minor changes across minor releases.
   24 
   25     A high-level API to conda's solving logic. Three public methods are provided to access a
   26     solution in various forms.
   27 
   28       * :meth:`solve_final_state`
   29       * :meth:`solve_for_diff`
   30       * :meth:`solve_for_transaction`
   31 
   32     """
   33 
   34     def __init__(self, prefix, channels, subdirs=(), specs_to_add=(), specs_to_remove=()):
   35         """
   36         **Beta**
   37 
   38         Args:
   39             prefix (str):
   40                 The conda prefix / environment location for which the :class:`Solver`
   41                 is being instantiated.
   42             channels (Sequence[:class:`Channel`]):
   43                 A prioritized list of channels to use for the solution.
   44             subdirs (Sequence[str]):
   45                 A prioritized list of subdirs to use for the solution.
   46             specs_to_add (Set[:class:`MatchSpec`]):
   47                 The set of package specs to add to the prefix.
   48             specs_to_remove (Set[:class:`MatchSpec`]):
   49                 The set of package specs to remove from the prefix.
   50 
   51         """
   52         self._internal = _Solver(prefix, channels, subdirs, specs_to_add, specs_to_remove)
   53 
   54     def solve_final_state(self, update_modifier=NULL, deps_modifier=NULL, prune=NULL,
   55                           ignore_pinned=NULL, force_remove=NULL):
   56         """
   57         **Beta** While in beta, expect both major and minor changes across minor releases.
   58 
   59         Gives the final, solved state of the environment.
   60 
   61         Args:
   62             deps_modifier (DepsModifier):
   63                 An optional flag indicating special solver handling for dependencies. The
   64                 default solver behavior is to be as conservative as possible with dependency
   65                 updates (in the case the dependency already exists in the environment), while
   66                 still ensuring all dependencies are satisfied.  Options include
   67                 * NO_DEPS
   68                 * ONLY_DEPS
   69                 * UPDATE_DEPS
   70                 * UPDATE_DEPS_ONLY_DEPS
   71                 * FREEZE_INSTALLED
   72             prune (bool):
   73                 If ``True``, the solution will not contain packages that were
   74                 previously brought into the environment as dependencies but are no longer
   75                 required as dependencies and are not user-requested.
   76             ignore_pinned (bool):
   77                 If ``True``, the solution will ignore pinned package configuration
   78                 for the prefix.
   79             force_remove (bool):
   80                 Forces removal of a package without removing packages that depend on it.
   81 
   82         Returns:
   83             Tuple[PackageRef]:
   84                 In sorted dependency order from roots to leaves, the package references for
   85                 the solved state of the environment.
   86 
   87         """
   88         return self._internal.solve_final_state(update_modifier, deps_modifier, prune,
   89                                                 ignore_pinned, force_remove)
   90 
   91     def solve_for_diff(self, update_modifier=NULL, deps_modifier=NULL, prune=NULL,
   92                        ignore_pinned=NULL, force_remove=NULL, force_reinstall=False):
   93         """
   94         **Beta** While in beta, expect both major and minor changes across minor releases.
   95 
   96         Gives the package references to remove from an environment, followed by
   97         the package references to add to an environment.
   98 
   99         Args:
  100             deps_modifier (DepsModifier):
  101                 See :meth:`solve_final_state`.
  102             prune (bool):
  103                 See :meth:`solve_final_state`.
  104             ignore_pinned (bool):
  105                 See :meth:`solve_final_state`.
  106             force_remove (bool):
  107                 See :meth:`solve_final_state`.
  108             force_reinstall (bool):
  109                 For requested specs_to_add that are already satisfied in the environment,
  110                 instructs the solver to remove the package and spec from the environment,
  111                 and then add it back--possibly with the exact package instance modified,
  112                 depending on the spec exactness.
  113 
  114         Returns:
  115             Tuple[PackageRef], Tuple[PackageRef]:
  116                 A two-tuple of PackageRef sequences.  The first is the group of packages to
  117                 remove from the environment, in sorted dependency order from leaves to roots.
  118                 The second is the group of packages to add to the environment, in sorted
  119                 dependency order from roots to leaves.
  120 
  121         """
  122         return self._internal.solve_for_diff(update_modifier, deps_modifier, prune, ignore_pinned,
  123                                              force_remove, force_reinstall)
  124 
  125     def solve_for_transaction(self, update_modifier=NULL, deps_modifier=NULL, prune=NULL,
  126                               ignore_pinned=NULL, force_remove=NULL, force_reinstall=False):
  127         """
  128         **Beta** While in beta, expect both major and minor changes across minor releases.
  129 
  130         Gives an UnlinkLinkTransaction instance that can be used to execute the solution
  131         on an environment.
  132 
  133         Args:
  134             deps_modifier (DepsModifier):
  135                 See :meth:`solve_final_state`.
  136             prune (bool):
  137                 See :meth:`solve_final_state`.
  138             ignore_pinned (bool):
  139                 See :meth:`solve_final_state`.
  140             force_remove (bool):
  141                 See :meth:`solve_final_state`.
  142             force_reinstall (bool):
  143                 See :meth:`solve_for_diff`.
  144 
  145         Returns:
  146             UnlinkLinkTransaction:
  147 
  148         """
  149         return self._internal.solve_for_transaction(update_modifier, deps_modifier, prune,
  150                                                     ignore_pinned, force_remove, force_reinstall)
  151 
  152 
  153 class SubdirData(object):
  154     """
  155     **Beta** While in beta, expect both major and minor changes across minor releases.
  156 
  157     High-level management and usage of repodata.json for subdirs.
  158     """
  159 
  160     def __init__(self, channel):
  161         """
  162         **Beta** While in beta, expect both major and minor changes across minor releases.
  163 
  164         Args:
  165             channel (str or Channel):
  166                 The target subdir for the instance. Must either be a url that includes a subdir
  167                 or a :obj:`Channel` that includes a subdir. e.g.:
  168                     * 'https://repo.anaconda.com/pkgs/main/linux-64'
  169                     * Channel('https://repo.anaconda.com/pkgs/main/linux-64')
  170                     * Channel('conda-forge/osx-64')
  171         """
  172         channel = Channel(channel)
  173         assert channel.subdir
  174         self._internal = _SubdirData(channel)
  175 
  176     def query(self, package_ref_or_match_spec):
  177         """
  178         **Beta** While in beta, expect both major and minor changes across minor releases.
  179 
  180         Run a query against this specific instance of repodata.
  181 
  182         Args:
  183             package_ref_or_match_spec (PackageRef or MatchSpec or str):
  184                 Either an exact :obj:`PackageRef` to match against, or a :obj:`MatchSpec`
  185                 query object.  A :obj:`str` will be turned into a :obj:`MatchSpec` automatically.
  186 
  187         Returns:
  188             Tuple[PackageRecord]
  189 
  190         """
  191         return tuple(self._internal.query(package_ref_or_match_spec))
  192 
  193     @staticmethod
  194     def query_all(package_ref_or_match_spec, channels=None, subdirs=None):
  195         """
  196         **Beta** While in beta, expect both major and minor changes across minor releases.
  197 
  198         Run a query against all repodata instances in channel/subdir matrix.
  199 
  200         Args:
  201             package_ref_or_match_spec (PackageRef or MatchSpec or str):
  202                 Either an exact :obj:`PackageRef` to match against, or a :obj:`MatchSpec`
  203                 query object.  A :obj:`str` will be turned into a :obj:`MatchSpec` automatically.
  204             channels (Iterable[Channel or str] or None):
  205                 An iterable of urls for channels or :obj:`Channel` objects. If None, will fall
  206                 back to context.channels.
  207             subdirs (Iterable[str] or None):
  208                 If None, will fall back to context.subdirs.
  209 
  210         Returns:
  211             Tuple[PackageRecord]
  212 
  213         """
  214         return tuple(_SubdirData.query_all(package_ref_or_match_spec, channels, subdirs))
  215 
  216     def iter_records(self):
  217         """
  218         **Beta** While in beta, expect both major and minor changes across minor releases.
  219 
  220         Returns:
  221             Iterable[PackageRecord]: A generator over all records contained in the repodata.json
  222                 instance.  Warning: this is a generator that is exhausted on first use.
  223 
  224         """
  225         return self._internal.iter_records()
  226 
  227     def reload(self):
  228         """
  229         **Beta** While in beta, expect both major and minor changes across minor releases.
  230 
  231         Update the instance with new information. Backing information (i.e. repodata.json)
  232         is lazily downloaded/loaded on first use by the other methods of this class. You
  233         should only use this method if you are *sure* you have outdated data.
  234 
  235         Returns:
  236             SubdirData
  237 
  238         """
  239         self._internal = self._internal.reload()
  240         return self
  241 
  242 
  243 class PackageCacheData(object):
  244     """
  245     **Beta** While in beta, expect both major and minor changes across minor releases.
  246 
  247     High-level management and usage of package caches.
  248     """
  249 
  250     def __init__(self, pkgs_dir):
  251         """
  252         **Beta** While in beta, expect both major and minor changes across minor releases.
  253 
  254         Args:
  255             pkgs_dir (str):
  256         """
  257         self._internal = _PackageCacheData(pkgs_dir)
  258 
  259     def get(self, package_ref, default=NULL):
  260         """
  261         **Beta** While in beta, expect both major and minor changes across minor releases.
  262 
  263         Args:
  264             package_ref (PackageRef):
  265                 A :obj:`PackageRef` instance representing the key for the
  266                 :obj:`PackageCacheRecord` being sought.
  267             default: The default value to return if the record does not exist. If not
  268                 specified and no record exists, :exc:`KeyError` is raised.
  269 
  270         Returns:
  271             PackageCacheRecord
  272 
  273         """
  274         return self._internal.get(package_ref, default)
  275 
  276     def query(self, package_ref_or_match_spec):
  277         """
  278         **Beta** While in beta, expect both major and minor changes across minor releases.
  279 
  280         Run a query against this specific package cache instance.
  281 
  282         Args:
  283             package_ref_or_match_spec (PackageRef or MatchSpec or str):
  284                 Either an exact :obj:`PackageRef` to match against, or a :obj:`MatchSpec`
  285                 query object.  A :obj:`str` will be turned into a :obj:`MatchSpec` automatically.
  286 
  287         Returns:
  288             Tuple[PackageCacheRecord]
  289 
  290         """
  291         return tuple(self._internal.query(package_ref_or_match_spec))
  292 
  293     @staticmethod
  294     def query_all(package_ref_or_match_spec, pkgs_dirs=None):
  295         """
  296         **Beta** While in beta, expect both major and minor changes across minor releases.
  297 
  298         Run a query against all package caches.
  299 
  300         Args:
  301             package_ref_or_match_spec (PackageRef or MatchSpec or str):
  302                 Either an exact :obj:`PackageRef` to match against, or a :obj:`MatchSpec`
  303                 query object.  A :obj:`str` will be turned into a :obj:`MatchSpec` automatically.
  304             pkgs_dirs (Iterable[str] or None):
  305                 If None, will fall back to context.pkgs_dirs.
  306 
  307         Returns:
  308             Tuple[PackageCacheRecord]
  309 
  310         """
  311         return tuple(_PackageCacheData.query_all(package_ref_or_match_spec, pkgs_dirs))
  312 
  313     def iter_records(self):
  314         """
  315         **Beta** While in beta, expect both major and minor changes across minor releases.
  316 
  317         Returns:
  318             Iterable[PackageCacheRecord]: A generator over all records contained in the package
  319                 cache instance.  Warning: this is a generator that is exhausted on first use.
  320 
  321         """
  322         return self._internal.iter_records()
  323 
  324     @property
  325     def is_writable(self):
  326         """
  327         **Beta** While in beta, expect both major and minor changes across minor releases.
  328 
  329         Indicates if the package cache location is writable or read-only.
  330 
  331         Returns:
  332             bool
  333 
  334         """
  335         return self._internal.is_writable
  336 
  337     @staticmethod
  338     def first_writable(pkgs_dirs=None):
  339         """
  340         **Beta** While in beta, expect both major and minor changes across minor releases.
  341 
  342         Get an instance object for the first writable package cache.
  343 
  344         Args:
  345             pkgs_dirs (Iterable[str]):
  346                 If None, will fall back to context.pkgs_dirs.
  347 
  348         Returns:
  349             PackageCacheData:
  350                 An instance for the first writable package cache.
  351 
  352         """
  353         return PackageCacheData(_PackageCacheData.first_writable(pkgs_dirs).pkgs_dir)
  354 
  355     def reload(self):
  356         """
  357         **Beta** While in beta, expect both major and minor changes across minor releases.
  358 
  359         Update the instance with new information. Backing information (i.e. contents of
  360         the pkgs_dir) is lazily loaded on first use by the other methods of this class. You
  361         should only use this method if you are *sure* you have outdated data.
  362 
  363         Returns:
  364             PackageCacheData
  365 
  366         """
  367         self._internal = self._internal.reload()
  368         return self
  369 
  370 
  371 class PrefixData(object):
  372     """
  373     **Beta** While in beta, expect both major and minor changes across minor releases.
  374 
  375     High-level management and usage of conda environment prefixes.
  376     """
  377 
  378     def __init__(self, prefix_path):
  379         """
  380         **Beta** While in beta, expect both major and minor changes across minor releases.
  381 
  382         Args:
  383             prefix_path (str):
  384         """
  385         self._internal = _PrefixData(prefix_path)
  386 
  387     def get(self, package_ref, default=NULL):
  388         """
  389         **Beta** While in beta, expect both major and minor changes across minor releases.
  390 
  391         Args:
  392             package_ref (PackageRef):
  393                 A :obj:`PackageRef` instance representing the key for the
  394                 :obj:`PrefixRecord` being sought.
  395             default: The default value to return if the record does not exist. If not
  396                 specified and no record exists, :exc:`KeyError` is raised.
  397 
  398         Returns:
  399             PrefixRecord
  400 
  401         """
  402         return self._internal.get(package_ref.name, default)
  403 
  404     def query(self, package_ref_or_match_spec):
  405         """
  406         **Beta** While in beta, expect both major and minor changes across minor releases.
  407 
  408         Run a query against this specific prefix instance.
  409 
  410         Args:
  411             package_ref_or_match_spec (PackageRef or MatchSpec or str):
  412                 Either an exact :obj:`PackageRef` to match against, or a :obj:`MatchSpec`
  413                 query object.  A :obj:`str` will be turned into a :obj:`MatchSpec` automatically.
  414 
  415         Returns:
  416             Tuple[PrefixRecord]
  417 
  418         """
  419         return tuple(self._internal.query(package_ref_or_match_spec))
  420 
  421     def iter_records(self):
  422         """
  423         **Beta** While in beta, expect both major and minor changes across minor releases.
  424 
  425         Returns:
  426             Iterable[PrefixRecord]: A generator over all records contained in the prefix.
  427                 Warning: this is a generator that is exhausted on first use.
  428 
  429         """
  430         return self._internal.iter_records()
  431 
  432     @property
  433     def is_writable(self):
  434         """
  435         **Beta** While in beta, expect both major and minor changes across minor releases.
  436 
  437         Indicates if the prefix is writable or read-only.
  438 
  439         Returns:
  440             bool or None:
  441                 True if the prefix is writable.  False if read-only.  None if the prefix
  442                 does not exist as a conda environment.
  443 
  444         """
  445         return self._internal.is_writable
  446 
  447     def reload(self):
  448         """
  449         **Beta** While in beta, expect both major and minor changes across minor releases.
  450 
  451         Update the instance with new information. Backing information (i.e. contents of
  452         the conda-meta directory) is lazily loaded on first use by the other methods of this
  453         class. You should only use this method if you are *sure* you have outdated data.
  454 
  455         Returns:
  456             PrefixData
  457 
  458         """
  459         self._internal = self._internal.reload()
  460         return self