:py:mod:`records` ================= .. py:module:: conda.models.records .. autoapi-nested-parse:: Implements the data model for conda packages. A PackageRecord is the record of a package present in a channel. A PackageCache is the record of a downloaded and cached package. A PrefixRecord is the record of a package installed into a conda environment. Object inheritance: .. autoapi-inheritance-diagram:: PackageRecord PackageCacheRecord PrefixRecord :top-classes: conda.models.records.PackageRecord :parts: 1 Classes ------- .. autoapisummary:: conda.models.records.LinkTypeField conda.models.records.NoarchField conda.models.records.TimestampField conda.models.records.Link conda.models.records._FeaturesField conda.models.records.ChannelField conda.models.records.SubdirField conda.models.records.FilenameField conda.models.records.PackageTypeField conda.models.records.PathData conda.models.records.PathDataV1 conda.models.records.PathsData conda.models.records.PackageRecord conda.models.records.Md5Field conda.models.records.PackageCacheRecord conda.models.records.SolvedRecord conda.models.records.PrefixRecord Attributes ---------- .. autoapisummary:: conda.models.records.EMPTY_LINK .. py:class:: LinkTypeField(enum_class, default=NULL, required=True, validation=None, in_dump=True, default_in_dump=True, nullable=False, immutable=False, aliases=()) Bases: :py:obj:`conda.auxlib.entity.EnumField` Fields are doing something very similar to boxing and unboxing of c#/java primitives. __set__ should take a "primitive" or "raw" value and create a "boxed" or "programmatically usable" value of it. While __get__ should return the boxed value, dump in turn should unbox the value into a primitive or raw value. :param types_: :type types_: primitive literal or type or sequence of types :param default: If default is callable, it's guaranteed to return a valid value at the time of Entity creation. :type default: any, callable, optional :param required: :type required: boolean, optional :param validation: :type validation: callable, optional :param dump: :type dump: boolean, optional .. py:method:: box(instance, instance_type, val) .. py:class:: NoarchField(enum_class, default=NULL, required=True, validation=None, in_dump=True, default_in_dump=True, nullable=False, immutable=False, aliases=()) Bases: :py:obj:`conda.auxlib.entity.EnumField` Fields are doing something very similar to boxing and unboxing of c#/java primitives. __set__ should take a "primitive" or "raw" value and create a "boxed" or "programmatically usable" value of it. While __get__ should return the boxed value, dump in turn should unbox the value into a primitive or raw value. :param types_: :type types_: primitive literal or type or sequence of types :param default: If default is callable, it's guaranteed to return a valid value at the time of Entity creation. :type default: any, callable, optional :param required: :type required: boolean, optional :param validation: :type validation: callable, optional :param dump: :type dump: boolean, optional .. py:method:: box(instance, instance_type, val) .. py:class:: TimestampField Bases: :py:obj:`conda.auxlib.entity.NumberField` Fields are doing something very similar to boxing and unboxing of c#/java primitives. __set__ should take a "primitive" or "raw" value and create a "boxed" or "programmatically usable" value of it. While __get__ should return the boxed value, dump in turn should unbox the value into a primitive or raw value. :param types_: :type types_: primitive literal or type or sequence of types :param default: If default is callable, it's guaranteed to return a valid value at the time of Entity creation. :type default: any, callable, optional :param required: :type required: boolean, optional :param validation: :type validation: callable, optional :param dump: :type dump: boolean, optional .. py:method:: _make_seconds(val) :staticmethod: .. py:method:: _make_milliseconds(val) :staticmethod: .. py:method:: box(instance, instance_type, val) .. py:method:: dump(instance, instance_type, val) .. py:method:: __get__(instance, instance_type) .. py:class:: Link(**kwargs) Bases: :py:obj:`conda.auxlib.entity.DictSafeMixin`, :py:obj:`conda.auxlib.entity.Entity` .. py:attribute:: source .. py:attribute:: type .. py:data:: EMPTY_LINK .. py:class:: _FeaturesField(**kwargs) Bases: :py:obj:`conda.auxlib.entity.ListField` Fields are doing something very similar to boxing and unboxing of c#/java primitives. __set__ should take a "primitive" or "raw" value and create a "boxed" or "programmatically usable" value of it. While __get__ should return the boxed value, dump in turn should unbox the value into a primitive or raw value. :param types_: :type types_: primitive literal or type or sequence of types :param default: If default is callable, it's guaranteed to return a valid value at the time of Entity creation. :type default: any, callable, optional :param required: :type required: boolean, optional :param validation: :type validation: callable, optional :param dump: :type dump: boolean, optional .. py:method:: box(instance, instance_type, val) .. py:method:: dump(instance, instance_type, val) .. py:class:: ChannelField(aliases=()) Bases: :py:obj:`conda.auxlib.entity.ComposableField` Fields are doing something very similar to boxing and unboxing of c#/java primitives. __set__ should take a "primitive" or "raw" value and create a "boxed" or "programmatically usable" value of it. While __get__ should return the boxed value, dump in turn should unbox the value into a primitive or raw value. :param types_: :type types_: primitive literal or type or sequence of types :param default: If default is callable, it's guaranteed to return a valid value at the time of Entity creation. :type default: any, callable, optional :param required: :type required: boolean, optional :param validation: :type validation: callable, optional :param dump: :type dump: boolean, optional .. py:method:: dump(instance, instance_type, val) .. py:method:: __get__(instance, instance_type) .. py:class:: SubdirField Bases: :py:obj:`conda.auxlib.entity.StringField` Fields are doing something very similar to boxing and unboxing of c#/java primitives. __set__ should take a "primitive" or "raw" value and create a "boxed" or "programmatically usable" value of it. While __get__ should return the boxed value, dump in turn should unbox the value into a primitive or raw value. :param types_: :type types_: primitive literal or type or sequence of types :param default: If default is callable, it's guaranteed to return a valid value at the time of Entity creation. :type default: any, callable, optional :param required: :type required: boolean, optional :param validation: :type validation: callable, optional :param dump: :type dump: boolean, optional .. py:method:: __get__(instance, instance_type) .. py:class:: FilenameField(aliases=()) Bases: :py:obj:`conda.auxlib.entity.StringField` Fields are doing something very similar to boxing and unboxing of c#/java primitives. __set__ should take a "primitive" or "raw" value and create a "boxed" or "programmatically usable" value of it. While __get__ should return the boxed value, dump in turn should unbox the value into a primitive or raw value. :param types_: :type types_: primitive literal or type or sequence of types :param default: If default is callable, it's guaranteed to return a valid value at the time of Entity creation. :type default: any, callable, optional :param required: :type required: boolean, optional :param validation: :type validation: callable, optional :param dump: :type dump: boolean, optional .. py:method:: __get__(instance, instance_type) .. py:class:: PackageTypeField Bases: :py:obj:`conda.auxlib.entity.EnumField` Fields are doing something very similar to boxing and unboxing of c#/java primitives. __set__ should take a "primitive" or "raw" value and create a "boxed" or "programmatically usable" value of it. While __get__ should return the boxed value, dump in turn should unbox the value into a primitive or raw value. :param types_: :type types_: primitive literal or type or sequence of types :param default: If default is callable, it's guaranteed to return a valid value at the time of Entity creation. :type default: any, callable, optional :param required: :type required: boolean, optional :param validation: :type validation: callable, optional :param dump: :type dump: boolean, optional .. py:method:: __get__(instance, instance_type) .. py:class:: PathData(**kwargs) Bases: :py:obj:`conda.auxlib.entity.Entity` .. py:attribute:: _path .. py:attribute:: prefix_placeholder .. py:attribute:: file_mode .. py:attribute:: no_link .. py:attribute:: path_type .. py:property:: path .. py:class:: PathDataV1(**kwargs) Bases: :py:obj:`PathData` .. py:attribute:: sha256 .. py:attribute:: size_in_bytes .. py:attribute:: inode_paths .. py:attribute:: sha256_in_prefix .. py:class:: PathsData(**kwargs) Bases: :py:obj:`conda.auxlib.entity.Entity` .. py:attribute:: paths_version .. py:attribute:: paths .. py:class:: PackageRecord(*args, **kwargs) Bases: :py:obj:`conda.auxlib.entity.DictSafeMixin`, :py:obj:`conda.auxlib.entity.Entity` Representation of a concrete package archive (tarball or .conda file). It captures all the relevant information about a given package archive, including its source, in the following attributes. Note that there are three subclasses, :class:`SolvedRecord`, :class:`PrefixRecord` and :class:`PackageCacheRecord`. These capture the same information, but are augmented with additional information relevant for these sources of packages. Further note that :class:`PackageRecord` makes use of its :attr:`_pkey` for comparison and hash generation. This means that for common operations, like comparisons between :class:`PackageRecord` s and reference of :class:`PackageRecord` s in mappings, _different_ objects appear identical. The fields taken into account are marked in the following list of attributes. The subclasses do not add further attributes to the :attr:`_pkey`. .. py:attribute:: name The name of the package. Part of the :attr:`_pkey`. .. py:attribute:: version The version of the package. Part of the :attr:`_pkey`. .. py:attribute:: build The build string of the package. Part of the :attr:`_pkey`. .. py:attribute:: build_number The build number of the package. Part of the :attr:`_pkey`. .. py:attribute:: channel The channel where the package can be found. .. py:attribute:: subdir The subdir, i.e. ``noarch`` or a platform (``linux-64`` or similar). Part of the :attr:`_pkey`. .. py:attribute:: fn The filename of the package. Only part of the :attr:`_pkey` if :ref:`separate_format_cache ` is ``true`` (default: ``false``). .. py:attribute:: md5 The md5 checksum of the package. .. py:attribute:: legacy_bz2_md5 If this is a ``.conda`` package and a corresponding ``.tar.bz2`` package exists, this may contain the md5 checksum of that package. .. py:attribute:: legacy_bz2_size If this is a ``.conda`` package and a corresponding ``.tar.bz2`` package exists, this may contain the size of that package. .. py:attribute:: url The download url of the package. .. py:attribute:: sha256 The sha256 checksum of the package. .. py:property:: channel_name :type: str | None The canonical name of the channel of this package. Part of the :attr:`_pkey`. :type: str .. py:property:: _pkey The components of the PackageRecord that are used for comparison and hashing. The :attr:`_pkey` is a tuple made up of the following fields of the :class:`PackageRecord`. Two :class:`PackageRecord` s test equal if their respective :attr:`_pkey` s are equal. The hash of the :class:`PackageRecord` (important for dictionary access) is the hash of the :attr:`_pkey`. The included fields are: * :attr:`channel_name` * :attr:`subdir` * :attr:`name` * :attr:`version` * :attr:`build_number` * :attr:`build` * :attr:`fn` only if :ref:`separate_format_cache ` is set to true (default: false) :type: tuple .. py:method:: __hash__() .. py:method:: __eq__(other) .. py:method:: dist_str(canonical_name: bool = True) -> str .. py:method:: dist_fields_dump() .. py:attribute:: arch .. py:attribute:: platform .. py:attribute:: depends .. py:attribute:: constrains .. py:attribute:: track_features .. py:attribute:: features .. py:attribute:: noarch .. py:attribute:: preferred_env .. py:attribute:: python_site_packages_path .. py:attribute:: license .. py:attribute:: license_family .. py:attribute:: package_type .. py:property:: is_unmanageable .. py:attribute:: timestamp .. py:property:: combined_depends .. py:attribute:: date .. py:attribute:: size .. py:method:: __str__() .. py:method:: to_match_spec() .. py:method:: to_simple_match_spec() .. py:property:: namekey .. py:property:: spec name=version=build :type: Return package spec .. py:property:: spec_no_build name=version :type: Return package spec without build .. py:method:: record_id() .. py:attribute:: metadata :type: set[str] .. py:method:: feature(feature_name) -> PackageRecord :classmethod: .. py:method:: virtual_package(name: str, version: str | None = None, build_string: str | None = None) -> PackageRecord :classmethod: Create a virtual package record. :param name: The name of the virtual package. :param version: The version of the virtual package, defaults to "0". :param build_string: The build string of the virtual package, defaults to "0". :return: A PackageRecord representing the virtual package. .. py:class:: Md5Field Bases: :py:obj:`conda.auxlib.entity.StringField` Fields are doing something very similar to boxing and unboxing of c#/java primitives. __set__ should take a "primitive" or "raw" value and create a "boxed" or "programmatically usable" value of it. While __get__ should return the boxed value, dump in turn should unbox the value into a primitive or raw value. :param types_: :type types_: primitive literal or type or sequence of types :param default: If default is callable, it's guaranteed to return a valid value at the time of Entity creation. :type default: any, callable, optional :param required: :type required: boolean, optional :param validation: :type validation: callable, optional :param dump: :type dump: boolean, optional .. py:method:: __get__(instance, instance_type) .. py:class:: PackageCacheRecord(*args, **kwargs) Bases: :py:obj:`PackageRecord` Representation of a package that has been downloaded or unpacked in the local package cache. Specialization of :class:`PackageRecord` that adds information for packages that exist in the local package cache, either as the downloaded package file, or unpacked in its own package dir, or both. Note that this class does not add new fields to the :attr:`PackageRecord._pkey` so that a pure :class:`PackageRecord` object that has the same ``_pkey`` fields as a different :class:`PackageCacheRecord` object (or, indeed, a :class:`PrefixRecord` object) will be considered equal and will produce the same hash. .. py:attribute:: package_tarball_full_path Full path to the local package file. .. py:attribute:: extracted_package_dir Full path to the local extracted package. .. py:attribute:: md5 The md5 checksum of the package. If the package file exists locally, this class can calculate a missing checksum on-the-fly. .. py:property:: is_fetched Whether the package file exists locally. :type: bool .. py:property:: is_extracted Whether the package has been extracted locally. :type: bool .. py:property:: tarball_basename The basename of the local package file. :type: str .. py:method:: _calculate_md5sum() .. py:class:: SolvedRecord(*args, **kwargs) Bases: :py:obj:`PackageRecord` Representation of a package that has been returned as part of a solver solution. This sits between :class:`PackageRecord` and :class:`PrefixRecord`, simply adding ``requested_spec`` (and ``requested_specs``) so they can be used in lockfiles without requiring the artifact on disk. .. py:attribute:: requested_spec The :class:`MatchSpec` that the user requested or ``None`` if the package it was installed as a dependency. .. py:attribute:: _requested_specs The :class:`MatchSpec` objects that the user requested or ``()`` if the package was installed as a dependency. See also `.requested_specs` property. .. py:property:: requested_specs :type: tuple[str, Ellipsis] This property will use 'requested_spec' as the source for 'requested_specs' for old `conda-meta/*.json` files that did not define the plural version. .. py:method:: dump() We need to expose _requested_specs as its public counterpart, and also expose single specs as a plural list for backwards compatibility. .. py:class:: PrefixRecord(*args, **kwargs) Bases: :py:obj:`SolvedRecord` Representation of a package that is installed in a local conda environmnet. Specialization of :class:`PackageRecord` that adds information for packages that are installed in a local conda environment or prefix. Note that this class does not add new fields to the :attr:`PackageRecord._pkey` so that a pure :class:`PackageRecord` object that has the same ``_pkey`` fields as a different :class:`PrefixRecord` object (or, indeed, a :class:`PackageCacheRecord` object) will be considered equal and will produce the same hash. Objects of this class are generally constructed from metadata in json files inside `$prefix/conda-meta`. .. py:attribute:: package_tarball_full_path The path to the originating package file, usually in the local cache. .. py:attribute:: extracted_package_dir The path to the extracted package directory, usually in the local cache. .. py:attribute:: files The list of all files comprising the package as relative paths from the prefix root. .. py:attribute:: paths_data List with additional information about the files, e.g. checksums and link type. .. py:attribute:: link Information about how the package was linked into the prefix. .. py:attribute:: auth Authentication information. .. py:method:: package_size(prefix_path: pathlib.Path) -> int Compute the installed size of this package within a prefix. This sums up the size_in_bytes of all non-softlink paths in paths_data, and stats the files on disk if size_in_bytes is missing and for the package's conda-meta JSON manifest. :returns: Total size in bytes of all files installed by this package.