conan 2.23.0__tar.gz → 2.25.0__tar.gz

{conan-2.23.0/conan.egg-info → conan-2.25.0}/PKG-INFO

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

{conan-2.23.0 → conan-2.25.0}/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.23.0'
+__version__ = '2.25.0'
 conan_version = Version(__version__)

{conan-2.23.0 → conan-2.25.0}/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)
@@ -74,13 +75,16 @@ class ConanAPI:
         self.upload: UploadAPI = UploadAPI(self, self._api_helpers)
         #: Used to download recipes and packages from remotes
         self.download: DownloadAPI = DownloadAPI(self)
-        self.cache = CacheAPI(self, self._api_helpers)
-        self.lockfile = LockfileAPI(self)
+        #: Used to interact wit the packages storage cache
+        self.cache: CacheAPI = CacheAPI(self, self._api_helpers)
+        #: Used to read and manage lockfile files
+        self.lockfile: LockfileAPI = LockfileAPI(self)
         self.local = LocalAPI(self, self._api_helpers)
-        self.audit = AuditAPI(self)
+        #: Used to check vulnerabilities of dependencies
+        self.audit: AuditAPI = AuditAPI(self)
         # Now, lazy loading of editables
         self.workspace = WorkspaceAPI(self)
-        self.report = ReportAPI(self, self._api_helpers)
+        self.report: ReportAPI = ReportAPI(self, self._api_helpers)
 
     @property
     def home_folder(self) -> str:

{conan-2.23.0 → conan-2.25.0}/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."""
@@ -203,6 +215,7 @@ class PackagesList:
 
     def merge(self, other):
         assert isinstance(other, PackagesList)
+
         def recursive_dict_update(d, u):  # TODO: repeated from conandata.py
             for k, v in u.items():
                 if isinstance(v, dict):
@@ -212,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.
@@ -334,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.23.0 → conan-2.25.0}/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.23.0 → conan-2.25.0}/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
@@ -22,48 +23,140 @@ 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):
         self._conan_api = conan_api
         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)
@@ -71,17 +164,29 @@ class CacheAPI:
             return ref_layout.finalize()
         return _check_folder_existence(pref, "package", ref_layout.package())
 
-    def check_integrity(self, package_list):
-        """Check if the recipes and packages are corrupted (it will raise a ConanExcepcion)"""
+    def check_integrity(self, package_list, return_pkg_list=False):
+        """
+        Check if the recipes and packages are corrupted
+
+        :param package_list: PackagesList to check
+        :param return_pkg_list: If True, return a PackagesList with corrupted artifacts
+        :return: PackagesList with corrupted artifacts if return_pkg_list is True
+        :raises: ConanExcepcion if there are corrupted artifacts and return_pkg_list is False
+        """
         cache = PkgCache(self._conan_api.cache_folder, self._api_helpers.global_conf)
         checker = IntegrityChecker(cache)
-        checker.check(package_list)
+        corrupted_pkg_list = checker.check(package_list)
+        if return_pkg_list:
+            return corrupted_pkg_list
+        if corrupted_pkg_list:
+            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.
+
         :param package_list: the package lists that should be cleaned
         :param source: boolean, remove the "source" folder if True
         :param build: boolean, remove the "build" folder if True
@@ -104,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)
@@ -128,13 +239,31 @@ class CacheAPI:
                 if download:
                     rmdir(pref_layout.download_package())
 
-    def save(self, package_list, tgz_path, no_source=False):
+    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():
@@ -148,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)
@@ -177,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.
 
-    def restore(self, path):
+        :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}")
 
@@ -253,11 +389,15 @@ class CacheAPI:
 
     def get_backup_sources(self, package_list=None, exclude=True, only_upload=True):
         """Get list of backup source files currently present in the cache,
-        either all of them if no argument, or filtered by those belonging to the references in the package_list
-
-        @param package_list: a PackagesList object to filter backup files from (The files should have been downloaded form any of the references in the package_list)
-        @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
+        either all of them if no argument, or filtered by those belonging to the references
+        in the package_list
+
+        :param package_list: a PackagesList object to filter backup files from (The files should
+          have been downloaded form any of the references in the package_list)
+        :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")
@@ -269,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: