conan 2.24.0__tar.gz → 2.25.1__tar.gz

{conan-2.24.0/conan.egg-info → conan-2.25.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: conan
-Version: 2.24.0
+Version: 2.25.1
 Summary: Conan C/C++ package manager
 Home-page: https://conan.io
 Author: JFrog LTD

{conan-2.24.0 → conan-2.25.1}/conan/__init__.py

@@ -2,5 +2,5 @@ from conan.internal.model.conan_file import ConanFile
 from conan.internal.model.workspace import Workspace
 from conan.internal.model.version import Version
 
-__version__ = '2.24.0'
+__version__ = '2.25.1'
 conan_version = Version(__version__)

{conan-2.24.0 → conan-2.25.1}/conan/api/conan_api.py

@@ -64,7 +64,8 @@ class ConanAPI:
         #: Used to get latest refs and list refs of recipes and packages
         self.list: ListAPI = ListAPI(self)
         self.profiles = ProfilesAPI(self, self._api_helpers)
-        self.install = InstallAPI(self, self._api_helpers)
+        #: Used to install binaries, sources, deploy packages and more
+        self.install: InstallAPI = InstallAPI(self, self._api_helpers)
         self.graph = GraphAPI(self, self._api_helpers)
         #: Used to export recipes and pre-compiled package binaries to the Conan cache
         self.export: ExportAPI = ExportAPI(self, self._api_helpers)

{conan-2.24.0 → conan-2.25.1}/conan/api/model/list.py

@@ -41,10 +41,6 @@ class MultiPackagesList:
         for k, v in other.lists.items():
             self.lists.setdefault(k, PackagesList()).merge(v)
 
-    def keep_outer(self, other):
-        for namespace, other_pkg_list in other.lists.items():
-            self.lists.get(namespace, PackagesList()).keep_outer(other_pkg_list)
-
     @staticmethod
     def load(file):
         """ Create an instance of the class from a serialized JSON file path pointed by ``file``."""
@@ -96,7 +92,6 @@ class MultiPackagesList:
         if not os.path.isfile(graphfile):
             raise ConanException(f"Graph file not found: {graphfile}")
         try:
-            base_context = context.split("-")[0] if context else None
             graph = json.loads(load(graphfile))
             # Check if input json is a graph file
             if "graph" not in graph:
@@ -107,15 +102,7 @@ class MultiPackagesList:
                 )
 
             mpkglist = MultiPackagesList._define_graph(graph, graph_recipes, graph_binaries,
-                                                       context=base_context)
-            if context == "build-only":
-                host = MultiPackagesList._define_graph(graph, graph_recipes, graph_binaries,
-                                                       context="host")
-                mpkglist.keep_outer(host)
-            elif context == "host-only":
-                build = MultiPackagesList._define_graph(graph, graph_recipes, graph_binaries,
-                                                        context="build")
-                mpkglist.keep_outer(build)
+                                                       context=context)
             return mpkglist
         except JSONDecodeError as e:
             raise ConanException(f"Graph file invalid JSON: {graphfile}\n{e}")
@@ -130,6 +117,7 @@ class MultiPackagesList:
 
     @staticmethod
     def _define_graph(graph, graph_recipes=None, graph_binaries=None, context=None):
+        base_context = context.split("-")[0] if context else None
         pkglist = MultiPackagesList()
         cache_list = PackagesList()
         if graph_recipes is None and graph_binaries is None:
@@ -141,7 +129,7 @@ class MultiPackagesList:
 
         pkglist.lists["Local Cache"] = cache_list
         for node in graph["graph"]["nodes"].values():
-            if context and node['context'] != context:
+            if base_context and node['context'] != base_context:
                 continue
 
             # We need to add the python_requires too
@@ -189,8 +177,32 @@ class MultiPackagesList:
             if any(b == "*" or b == binary for b in binaries):
                 cache_list.add_ref(ref)  # Binary listed forces recipe listed
                 cache_list.add_pref(pref, node["info"])
+        # Now filter possible exclusive contexts once that we know how they are distributed
+        MultiPackagesList._filter_exclusive_context(pkglist, graph, context)
         return pkglist
 
+    @staticmethod
+    def _filter_exclusive_context(mpkglist, graph, context):
+        if context not in ("host-only", "build-only"):
+            return
+
+        pref_contexts = {}
+        for node in graph["graph"]["nodes"].values():
+            if node["package_id"] is not None:
+                pref = node["ref"] + ":" + node["package_id"]
+                pref_contexts.setdefault(pref, set()).add(node['context'])
+
+        opposite_context = "build" if context == "host-only" else "host"
+        for remote, pkglist in mpkglist.lists.items():
+            for pref, contexts in pref_contexts.items():
+                if opposite_context in contexts:
+                    pref = PkgReference.loads(pref)
+                    if pkglist.has_rref(pref.ref):
+                        rev_dict = pkglist.recipe_dict(pref.ref)
+                        rev_dict.get("packages", {}).pop(pref.package_id, None)
+                        if len(rev_dict.get("packages", {})) == 0:
+                            pkglist._data.pop(str(pref.ref), None)
+
 
 class PackagesList:
     """ A collection of recipes, revisions and packages."""
@@ -213,15 +225,6 @@ class PackagesList:
             return d
         recursive_dict_update(self._data, other._data)
 
-    def keep_outer(self, other):
-        assert isinstance(other, PackagesList)
-        if not self._data:
-            return
-
-        for ref, info in other._data.items():
-            if self._data.get(ref, {}) == info:
-                self._data.pop(ref)
-
     def split(self):
         """
         Returns a list of PackageList, split one per reference.
@@ -335,6 +338,10 @@ class PackagesList:
         """
         return self._data[str(ref)]["revisions"][ref.revision]
 
+    def has_rref(self, ref: RecipeReference) -> bool:
+        # Checks if the PackagesList contains the given RecipeReference.
+        return str(ref) in self._data and ref.revision in self._data[str(ref)].get("revisions", {})
+
     def package_dict(self, pref: PkgReference):
         """ Gives read/write access to the dictionary containing a specific PkgReference
         information

{conan-2.24.0 → conan-2.25.1}/conan/api/output.py

@@ -135,17 +135,17 @@ class ConanOutput:
     @classmethod
     def valid_log_levels(cls):
         return {"quiet": LEVEL_QUIET,  # -vquiet 80
-            "error": LEVEL_ERROR,  # -verror 70
-            "warning": LEVEL_WARNING,  # -vwaring 60
-            "notice": LEVEL_NOTICE,  # -vnotice 50
-            "status": LEVEL_STATUS,  # -vstatus 40
-            None: LEVEL_VERBOSE,  # -v 30
-            "verbose": LEVEL_VERBOSE,  # -vverbose 30
-            "debug": LEVEL_DEBUG,  # -vdebug 20
-            "v": LEVEL_DEBUG,  # -vv 20
-            "trace": LEVEL_TRACE,  # -vtrace 10
-            "vv": LEVEL_TRACE  # -vvv 10
-        }
+                "error": LEVEL_ERROR,  # -verror 70
+                "warning": LEVEL_WARNING,  # -vwaring 60
+                "notice": LEVEL_NOTICE,  # -vnotice 50
+                "status": LEVEL_STATUS,  # -vstatus 40
+                None: LEVEL_VERBOSE,  # -v 30
+                "verbose": LEVEL_VERBOSE,  # -vverbose 30
+                "debug": LEVEL_DEBUG,  # -vdebug 20
+                "v": LEVEL_DEBUG,  # -vv 20
+                "trace": LEVEL_TRACE,  # -vtrace 10
+                "vv": LEVEL_TRACE  # -vvv 10
+                }
 
     @classmethod
     def define_log_level(cls, v):

{conan-2.24.0 → conan-2.25.1}/conan/api/subapi/cache.py

@@ -6,13 +6,14 @@ import tempfile
 
 from conan.api.model import PackagesList
 from conan.api.output import ConanOutput
-from conan.internal.api.uploader import compress_files
+from conan.internal.api.uploader import compress_files, get_compress_level
 from conan.internal.cache.cache import PkgCache
 from conan.internal.cache.conan_reference_layout import (EXPORT_SRC_FOLDER, EXPORT_FOLDER,
                                                          SRC_FOLDER, METADATA,
                                                          DOWNLOAD_EXPORT_FOLDER)
 from conan.internal.cache.home_paths import HomePaths
 from conan.internal.cache.integrity_check import IntegrityChecker
+from conan.internal.paths import COMPRESSIONS
 from conan.internal.rest.download_cache import DownloadCache
 from conan.errors import ConanException
 from conan.api.model import PkgReference
@@ -23,6 +24,11 @@ from conan.internal.util.files import rmdir, mkdir, remove, save
 
 class CacheAPI:
     """ This CacheAPI is used to interact with the packages storage cache
+
+    Note that the Conan packages cache is exclusively **read-only** for user code. Only Conan
+    can write or modify the folders and files in the Conan cache. In general, when a method
+    returns a folder, it is mostly for debugging purposes and read-only access, but never to
+    modify the contents of the cache.
     """
 
     def __init__(self, conan_api, api_helpers):
@@ -30,42 +36,127 @@ class CacheAPI:
         self._api_helpers = api_helpers
 
     def export_path(self, ref: RecipeReference):
+        """Returns the path of the recipe conanfile and exported files in the Conan cache
+
+        This folder is exclusively for **read-only** access, typically for debugging purposes,
+        it is completely forbidden to modify any of its contents.
+
+        :param ref: RecipeReference. If it includes recipe revision, that exact revision will be
+           returned, if it doesn't include recipe revision, it will return the latest revision one.
+        :return: path to the folder, as a string
+        :raises: ConanExcepcion if the folder doesn't exist
+        """
+
         cache = PkgCache(self._conan_api.cache_folder, self._api_helpers.global_conf)
         ref = _resolve_latest_ref(cache, ref)
         ref_layout = cache.recipe_layout(ref)
         return _check_folder_existence(ref, "export", ref_layout.export())
 
     def recipe_metadata_path(self, ref: RecipeReference):
+        """Returns the path of the recipe metadata files in the Conan cache
+
+        Exceptionally, adding or modifying the files within this folder is allowed, as
+        the metadata files are not taken into account into the computation of the recipe hash
+        (recipe revision).
+
+        :param ref: RecipeReference. If it includes recipe revision, that exact revision will be
+           returned, if it doesn't include recipe revision, it will return the latest revision one.
+        :return: path to the folder, as a string
+        :raises: ConanExcepcion if the folder doesn't exist
+        """
         cache = PkgCache(self._conan_api.cache_folder, self._api_helpers.global_conf)
         ref = _resolve_latest_ref(cache, ref)
         ref_layout = cache.recipe_layout(ref)
         return _check_folder_existence(ref, "metadata", ref_layout.metadata())
 
     def export_source_path(self, ref: RecipeReference):
+        """Returns the path of the exported sources in the Conan cache
+
+        Note that the exported sources only exist in the cache when the package has been created
+        locally or built from source.
+
+        This folder is exclusively for **read-only** access, typically for debugging purposes,
+        it is completely forbidden to modify any of its contents.
+
+        :param ref: RecipeReference. If it includes recipe revision, that exact revision will be
+           returned, if it doesn't include recipe revision, it will return the latest revision one.
+        :return: path to the folder, as a string
+        :raises: ConanExcepcion if the folder doesn't exist
+        """
         cache = PkgCache(self._conan_api.cache_folder, self._api_helpers.global_conf)
         ref = _resolve_latest_ref(cache, ref)
         ref_layout = cache.recipe_layout(ref)
         return _check_folder_existence(ref, "export_sources", ref_layout.export_sources())
 
     def source_path(self, ref: RecipeReference):
+        """Returns the path of the temporary source folder in the Conan cache
+
+        Note that the source folder only exist in the cache when the package has been created
+        locally or built from source.
+
+        This folder is exclusively for **read-only** access, typically for debugging purposes,
+        it is completely forbidden to modify any of its contents.
+
+        :param ref: RecipeReference. If it includes recipe revision, that exact revision will be
+           returned, if it doesn't include recipe revision, it will return the latest revision one.
+        :return: path to the folder, as a string
+        :raises: ConanExcepcion if the folder doesn't exist
+        """
         cache = PkgCache(self._conan_api.cache_folder, self._api_helpers.global_conf)
         ref = _resolve_latest_ref(cache, ref)
         ref_layout = cache.recipe_layout(ref)
         return _check_folder_existence(ref, "source", ref_layout.source())
 
     def build_path(self, pref: PkgReference):
+        """Returns the path of the temporary build folder in the Conan cache
+
+        Note that the build folder only exist in the cache when the package has been created
+        locally or built from source.
+
+        This folder is exclusively for **read-only** access, typically for debugging purposes,
+        it is completely forbidden to modify any of its contents.
+
+        :param pref: PkgReference. If it includes recipe revision, that exact revision will be
+           returned, if it doesn't include recipe revision, it will return the latest revision one.
+           Exactly same behavior for the package revision.
+        :return: path to the folder, as a string
+        :raises: ConanExcepcion if the folder doesn't exist
+        """
         cache = PkgCache(self._conan_api.cache_folder, self._api_helpers.global_conf)
         pref = _resolve_latest_pref(cache, pref)
         ref_layout = cache.pkg_layout(pref)
         return _check_folder_existence(pref, "build", ref_layout.build())
 
     def package_metadata_path(self, pref: PkgReference):
+        """Returns the path of the package metadata folder in the Conan cache
+
+        Exceptionally, adding or modifying the files within this folder is allowed, as
+        the metadata files are not taken into account into the computation of the package hash
+        (package revision).
+
+       :param pref: PkgReference. If it includes recipe revision, that exact revision will be
+           returned, if it doesn't include recipe revision, it will return the latest revision one.
+           Exactly same behavior for the package revision.
+       :return: path to the folder, as a string
+       :raises: ConanExcepcion if the folder doesn't exist
+        """
         cache = PkgCache(self._conan_api.cache_folder, self._api_helpers.global_conf)
         pref = _resolve_latest_pref(cache, pref)
         ref_layout = cache.pkg_layout(pref)
         return _check_folder_existence(pref, "metadata", ref_layout.metadata())
 
     def package_path(self, pref: PkgReference):
+        """Returns the path of the package folder in the Conan cache
+
+        This folder is exclusively for **read-only** access, typically for debugging purposes,
+        it is completely forbidden to modify any of its contents.
+
+        :param pref: PkgReference. If it includes recipe revision, that exact revision will be
+           returned, if it doesn't include recipe revision, it will return the latest revision one.
+           Exactly same behavior for the package revision.
+        :return: path to the folder, as a string
+        :raises: ConanExcepcion if the folder doesn't exist
+        """
         cache = PkgCache(self._conan_api.cache_folder, self._api_helpers.global_conf)
         pref = _resolve_latest_pref(cache, pref)
         ref_layout = cache.pkg_layout(pref)
@@ -91,7 +182,7 @@ class CacheAPI:
             raise ConanException("There are corrupted artifacts, check the error logs")
 
     def clean(self, package_list, source=True, build=True, download=True, temp=True,
-              backup_sources=False):
+              backup_sources=False) -> None:
         """
         Remove non critical folders from the cache, like source, build and download (.tgz store)
         folders.
@@ -118,6 +209,12 @@ class CacheAPI:
                     info = os.path.join(folder, "p", "conaninfo.txt")
                     if not os.path.exists(manifest) or not os.path.exists(info):
                         rmdir(folder)
+
+        # Temporary name (not named) until we have clarity if this is the same as the "t"
+        # temporary (for exports) or not
+        if os.path.exists(os.path.join(cache.store, "d")):
+            rmdir(os.path.join(cache.store, "d"))
+
         if backup_sources:
             backup_files = self._conan_api.cache.get_backup_sources(package_list, exclude=False,
                                                                     only_upload=False)
@@ -142,13 +239,31 @@ class CacheAPI:
                 if download:
                     rmdir(pref_layout.download_package())
 
-    def save(self, package_list: PackagesList, tgz_path, no_source=False) -> None:
+    def save(self, package_list: PackagesList, path, no_source=False) -> None:
+        """Create a compressed archive with recipes and packages from the Conan cache that
+        can be later restored in another cache.
+
+        Do not manipulate the contents of the resulting archive, as it also contains metadata,
+        and modifying the contents would be equivalent to modify the Conan package cache, which
+        is forbidden.
+
+        :param package_list: PackagesList containing the recipes and packages to add
+           to the compressed archive
+        :param path: The archive file to generate. Based on the extension of the file, different
+           compression formats can be used (.tgz, .txz and .tzst, the latter only for Python>=3.14).
+        :param no_source: If True, the source folders in the cache will not be added to the archive.
+        :return:
+        """
         global_conf = self._api_helpers.global_conf
         cache = PkgCache(self._conan_api.cache_folder, global_conf)
         cache_folder = cache.store  # Note, this is not the home, but the actual package cache
         out = ConanOutput()
-        mkdir(os.path.dirname(tgz_path))
-        compresslevel = global_conf.get("core.gzip:compresslevel", check_type=int)
+        mkdir(os.path.dirname(path))
+        tgz_name = os.path.basename(path)
+        compressformat = next((e for e in COMPRESSIONS if tgz_name.endswith(e)), None)
+        if not compressformat:
+            raise ConanException(f"Unsupported compression format for {tgz_name}")
+        compresslevel = get_compress_level(compressformat, global_conf)
         tar_files: dict[str, str] = {}  # {path_in_tar: abs_path}
 
         for ref, packages in package_list.items():
@@ -162,12 +277,12 @@ class CacheAPI:
             for f in (EXPORT_FOLDER, EXPORT_SRC_FOLDER, SRC_FOLDER):
                 if f == SRC_FOLDER and no_source:
                     continue
-                path = os.path.join(cache_folder, recipe_folder, f)
-                if os.path.exists(path):
-                    tar_files[f"{recipe_folder}/{f}"] = path
-            path = os.path.join(cache_folder, recipe_folder, DOWNLOAD_EXPORT_FOLDER, METADATA)
-            if os.path.exists(path):
-                tar_files[f"{recipe_folder}/{DOWNLOAD_EXPORT_FOLDER}/{METADATA}"] = path
+                cachepath = os.path.join(cache_folder, recipe_folder, f)
+                if os.path.exists(cachepath):
+                    tar_files[f"{recipe_folder}/{f}"] = cachepath
+            cachepath = os.path.join(cache_folder, recipe_folder, DOWNLOAD_EXPORT_FOLDER, METADATA)
+            if os.path.exists(cachepath):
+                tar_files[f"{recipe_folder}/{DOWNLOAD_EXPORT_FOLDER}/{METADATA}"] = cachepath
 
             for pref in packages:
                 pref_layout = cache.pkg_layout(pref)
@@ -191,11 +306,18 @@ class CacheAPI:
         pkglist_path = os.path.join(tempfile.gettempdir(), "pkglist.json")
         save(pkglist_path, serialized)
         tar_files["pkglist.json"] = pkglist_path
-        compress_files(tar_files, os.path.basename(tgz_path), os.path.dirname(tgz_path),
-                       compresslevel, recursive=True)
+        compress_files(tar_files, tgz_name, os.path.dirname(path), compresslevel, recursive=True)
         remove(pkglist_path)
+        ConanOutput().success(f"Created cache save file: {path}")
 
     def restore(self, path) -> PackagesList:
+        """Restore a compressed archive with recipes and packages previously saved from another
+        Conan cache into the currently active Conan cache.
+
+        :param path: The archive file to restore. Based on the extension of the file, different
+           compression formats can be used (.tgz, .txz and .tzst, the latter only for Python>=3.14).
+        :return: a PackageLists with the recipes and packages that have been restored to the cache
+        """
         if not os.path.isfile(path):
             raise ConanException(f"Restore archive doesn't exist in {path}")
 
@@ -275,6 +397,7 @@ class CacheAPI:
         :param exclude: if True, exclude the sources that come from URLs present the
           core.sources:exclude_urls global conf
         :param only_upload: if True, only return the files for packages that are set to be uploaded
+        :return: A list of files that need to be uploaded
         """
         config = self._api_helpers.global_conf
         download_cache_path = config.get("core.sources:download_cache")
@@ -286,6 +409,8 @@ class CacheAPI:
         return download_cache.get_backup_sources_files(excluded_urls, package_list, only_upload)
 
     def path_to_ref(self, path):
+        # This method is explicitly not publicly documented, as mostly a command helper for
+        # debugging, it shouldn't be used in any real API usage
         cache = PkgCache(self._conan_api.cache_folder, self._api_helpers.global_conf)
         result = cache.path_to_ref(path)
         if result is None:

{conan-2.24.0 → conan-2.25.1}/conan/api/subapi/config.py

@@ -36,10 +36,25 @@ class ConfigAPI:
         """
         return self._conan_api.cache_folder
 
-    def install(self, path_or_url, verify_ssl, config_type=None, args=None,
-                source_folder=None, target_folder=None):
+    def install(self, path_or_url: str, verify_ssl, config_type=None, args=None,
+                source_folder=None, target_folder=None) -> None:
         """ install Conan configuration from a git repo, from a zip file in an http server
         or a local folder
+
+        Calling this method will cause a reinitilization of the full ConanAPI, with possible
+        invalidation of cached information, and references to objects from the ConanAPI might
+        become dangling or outdated.
+
+        :param path_or_url: path or url to install. It can be a http://.../somefile.zip, a
+            git repository URL, or a local folder
+        :param verify_ssl: Argument passed to python-requests library for SSL verification
+        :param config_type: type of configuration to install: "git", "dir", "file", "url"
+        :param args: additional arguments to pass to git repositories cloning
+        :param source_folder: If specified, install files from that folder of the origin only
+        :param target_folder: If the files are to be installed in a specific folder in the Conan
+            home. For example, if it is desired to install only profiles from a configuration and
+            using source_folder="profiles", it might be expected to use target_folder="profiles"
+            to keep the correct profile files location in the local home.
         """
         from conan.internal.api.config.config_installer import configuration_install
         cache_folder = self._conan_api.cache_folder
@@ -50,6 +65,25 @@ class ConfigAPI:
         self._conan_api.reinit()
 
     def install_package(self, require, lockfile=None, force=False, remotes=None, profile=None):
+        """ install Conan configuration from a Conan package
+
+        Calling this method will cause a reinitilization of the full ConanAPI, with possible
+        invalidation of cached information, and references to objects from the ConanAPI might
+        become dangling or outdated.
+
+        :param require: The package requirement to be installed. It can contain version range
+            expressions. If the revision is not specified, as a recipe ``requires``, it will
+            also resolve to the latest recipe-revision
+        :param lockfile: Lockfile to be used to constrain and lock the versions and recipe-revisions
+            from the input requirements, to the exact versions and revisions specified in the
+            lockfile
+        :param force: If the package has already been installed, nothing will be done unless
+            force is True
+        :param remotes: Remotes to look for the configuration package
+        :param profile: If specified, use that profile to resolve for profile-specific different
+            configurations, like depending on different settings.
+        :return: list of RecipeReferences of the installed configuration packages
+        """
         ConanOutput().warning("The 'conan config install-pkg' is experimental",
                               warn_tag="experimental")
         require = RecipeReference.loads(require)
@@ -60,6 +94,7 @@ class ConfigAPI:
 
     @staticmethod
     def load_conanconfig(path, remotes):
+        # Internal, do not document yet.
         if os.path.isdir(path):
             path = os.path.join(path, "conanconfig.yml")
         requested_requires, urls = loadconanconfig_yml(path)
@@ -71,6 +106,24 @@ class ConfigAPI:
         return requested_requires, remotes
 
     def install_conanconfig(self, path, lockfile=None, force=False, remotes=None, profile=None):
+        """ install Conan configuration from a Conan "conanconfig.yml" file
+
+        Calling this method will cause a reinitilization of the full ConanAPI, with possible
+        invalidation of cached information, and references to objects from the ConanAPI might
+        become dangling or outdated.
+
+        :param path: Path to the conanconfig.yml file containing the configuration packages
+            requirement definitions
+        :param lockfile: Lockfile to be used to constrain and lock the versions and recipe-revisions
+            from the input requirements, to the exact versions and revisions specified in the
+            lockfile
+        :param force: If the package has already been installed, nothing will be done unless
+            force is True
+        :param remotes: Remotes to look for the configuration package
+        :param profile: If specified, use that profile to resolve for profile-specific different
+            configurations, like depending on different settings.
+        :return: list of RecipeReferences of the installed configuration packages
+        """
         ConanOutput().warning("The 'conan config install-pkg' is experimental",
                               warn_tag="experimental")
         requested_requires, remotes = self.load_conanconfig(path, remotes)
@@ -148,9 +201,12 @@ class ConfigAPI:
         saveconanconfig(config_version_file, final_config_refs)
         return final_config_refs
 
-    def fetch_packages(self, refs, lockfile=None, remotes=None, profile=None):
-        """ install configuration stored inside a Conan package
-        The installation of configuration will reinitialize the full ConanAPI
+    def fetch_packages(self, requires, lockfile=None, remotes=None, profile=None):
+        """ get and download configuration packages into the Conan cache, without installing
+        such configuration in the current Conan home.
+
+        This shouldn't be necessary for regular Conan configuration, and used at the moment
+        exclusively for the "conan lock upgrade-config" experimental command.
         """
         conan_api = self._conan_api
         remotes = conan_api.remotes.list() if remotes is None else remotes
@@ -160,7 +216,7 @@ class ConfigAPI:
 
         ConanOutput().title("Fetching requested configuration packages")
         result = []
-        for ref in refs:
+        for ref in requires:
             # Computation of a very simple graph that requires "ref"
             # Need to convert input requires to RecipeReference
             conanfile = app.loader.load_virtual(requires=[ref])
@@ -192,21 +248,34 @@ class ConfigAPI:
 
     def get(self, name, default=None, check_type=None):
         """ get the value of a global.conf item
+
+        :param name: configuration value to return
+        :param default: default value to return if the configuration doesn't contain a value
+        :param check_type: check if value is of type check_type, only if the value is defined
         """
         return self._helpers.global_conf.get(name, default=default, check_type=check_type)
 
     def show(self, pattern) -> dict:
         """ get the values of global.conf for those configurations that matches the pattern
+        that have an actual user definition.
+
+        Values with no user definitions will be skipped from the returned value,
+        defaults for those confs won't be shown.
+
+        :param pattern: pattern to match against
+        :return: dict of configuration values
         """
         return self._helpers.global_conf.show(pattern)
 
     @staticmethod
-    def conf_list():
+    def conf_list() -> dict:
         """ list all the available built-in configurations
+
+        :return: A sorted dictionary with all possible built-in configurations
         """
         return BUILT_IN_CONFS.copy()
 
-    def clean(self):
+    def clean(self) -> None:
         """ reset the Conan home folder to a clean state, removing all the user
         custom configuration, custom files, and resetting modified files
         """
@@ -229,17 +298,21 @@ class ConfigAPI:
     @property
     def settings_yml(self):
         """ Get the contents of the settings.yml and user_settings.yml files,
-            which define the possible values for settings.
+        which define the possible values for settings.
+
+        Note that this is different from the settings present in a conanfile,
+        which represent the actual values for a specific package, while this
+        property represents the possible values for each setting.
 
-            Note that this is different from the settings present in a conanfile,
-            which represent the actual values for a specific package, while this
-            property represents the possible values for each setting.
+        This is intended to be a **read-only** value, do not try to attempt to modify,
+        inject or remove settings with this attribute.
 
-            :returns: A read-only object representing the settings scheme, with a
-                ``possible_values()`` method that returns a dictionary with the possible values for each setting,
-                and a ``fields`` property that returns an ordered list with the fields of each setting.
-                Note that it's possible to access nested settings using attribute access,
-                such as ``settings_yml.compiler.possible_values()``.
+        :returns: A read-only object representing the settings scheme, with a
+            ``possible_values()`` method that returns a dictionary with the possible
+            values for each setting, and a ``fields`` property that returns an ordered
+            list with the fields of each setting.
+            Note that it's possible to access nested settings using attribute access,
+            such as ``settings_yml.compiler.possible_values()``.
         """
 
         class SettingsYmlInterface:

{conan-2.24.0 → conan-2.25.1}/conan/api/subapi/download.py

@@ -24,13 +24,13 @@ class DownloadAPI:
         app = ConanBasicApp(self._conan_api)
         assert ref.revision, f"Reference '{ref}' must have revision"
         try:
-            app.cache.recipe_layout(ref)  # raises if not found
+            recipe_layout = app.cache.recipe_layout(ref)  # raises if not found
         except ConanException:
             pass
         else:
             output.info(f"Skip recipe {ref.repr_notime()} download, already in cache")
             if metadata:
-                app.remote_manager.get_recipe_metadata(ref, remote, metadata)
+                app.remote_manager.get_recipe_metadata(recipe_layout, ref, remote, metadata)
             return False
 
         output.info(f"Downloading recipe '{ref.repr_notime()}'")
@@ -40,11 +40,10 @@ class DownloadAPI:
             server_ref = app.remote_manager.get_recipe_revision(ref, remote)
             assert server_ref == ref
             ref.timestamp = server_ref.timestamp
-        app.remote_manager.get_recipe(ref, remote, metadata)
+        recipe_layout = app.remote_manager.get_recipe(ref, remote, metadata)
 
         # Download the sources too, don't be lazy
         output.info(f"Downloading '{str(ref)}' sources")
-        recipe_layout = app.cache.recipe_layout(ref)
         app.remote_manager.get_recipe_sources(ref, recipe_layout, remote)
         return True