:py:mod:`prefix_data` ===================== .. py:module:: conda.core.prefix_data .. autoapi-nested-parse:: Tools for managing the packages installed within an environment. Classes ------- .. autoapisummary:: conda.core.prefix_data.PrefixDataType conda.core.prefix_data.PrefixData Functions --------- .. autoapisummary:: conda.core.prefix_data.get_conda_anchor_files_and_records conda.core.prefix_data.python_record_for_prefix conda.core.prefix_data.get_python_version_for_prefix conda.core.prefix_data.delete_prefix_from_linked_data Attributes ---------- .. autoapisummary:: conda.core.prefix_data.T .. py:data:: T .. py:class:: PrefixDataType Bases: :py:obj:`type` Basic caching of PrefixData instance objects. .. py:method:: __call__(prefix_path: conda.common.path.PathType, interoperability: bool | None = None) -> PrefixData Call self as a function. .. py:class:: PrefixData(prefix_path: conda.common.path.PathType, interoperability: bool | None = None) The PrefixData class aims to be the representation of the state of a conda environment on disk. The directory where the environment lives is called prefix. This class supports different types of tasks: - Reading and querying `conda-meta/*.json` files as `PrefixRecord` objects - Reading and writing environment-specific configuration (env vars, state file, nonadmin markers, etc) - Existence checks and validations of name, path, and magic files / markers - Exposing non-conda packages installed in prefix as `PrefixRecord`, via the plugin system .. py:property:: name :type: str Returns the name of the environment, if available. If the environment doesn't live in one the configured `envs_dirs`, an empty string is returned. The construct `prefix_data.name or prefix_data.prefix_path` can be helpful in those cases. .. py:property:: is_writable :type: bool | None | conda.auxlib._Null Check whether the configured path is writable. This is assessed by checking whether `conda-meta/history` is writable. It if is, it is assumed that the rest of the directory tree is writable too. Note: The value is cached in the instance. Use `.assert_writable()` for a non- cached check. .. py:property:: created :type: datetime.datetime | None Returns the time when the environment was created, as evidenced by the `conda-meta` directory creation time (if available). Falls back to `conda-meta/created_at`. This may return None in the following cases: - If the environment doesn't exist. - If the creation time cannot be determined. This can happen for existing environments created with conda versions before 25.11 in Linux systems, where the 'birthtime' metadata is only available in kernels 4.11+, and not implemented in Python as of Python 3.14. .. py:property:: last_modified :type: datetime.datetime | None Returns the time when the environment was last modified, as evidenced by the `conda-meta/history` file modification time. If the environment does not exist, returns None. .. py:property:: _pip_interop_enabled .. py:property:: _prefix_records :type: dict[str, conda.models.records.PrefixRecord] | None .. py:property:: _python_pkg_record :type: conda.models.records.PrefixRecord | None Return the prefix record for the package python. .. py:attribute:: _cache_ :type: dict[tuple[pathlib.Path, bool | None], PrefixData] .. py:method:: from_name(name: str, **kwargs) -> PrefixData :classmethod: Creates a PrefixData instance from an environment name. The name will be validated with `PrefixData.validate_name()` if it does not exist. :param name: The name of the environment. Must not contain path separators (/, \). :raises CondaValueError: If `name` contains a path separator. .. py:method:: from_context(validate: bool = False, **kwargs) -> PrefixData :classmethod: Creates a PrefixData instance from the path specified by `context.target_prefix`. The path and name will be validated with `PrefixData.validate_path()` and `PrefixData.validate_name()`, respectively, if `validate` is `True`. :param validate: Whether the path and name should be validated. Useful for environments about to be created. :param kwargs: Additional keyword arguments to pass to the constructor. .. py:method:: __eq__(other: Any) -> bool Return self==value. .. py:method:: exists() -> bool Check whether the PrefixData path exists and is a directory. .. py:method:: is_environment() -> bool Check whether the PrefixData path is a valida conda environment. This is assessed by checking if `conda-meta/history` marker file exists. .. py:method:: is_frozen() -> bool Check whether the environment is marked as frozen, as per CEP 22. This is assessed by checking if `conda-meta/frozen` marker file exists. .. py:method:: is_base() -> bool Check whether the configured path refers to the `base` environment. .. py:method:: assert_exists() -> None Check whether the environment path exists. :raises EnvironmentLocationNotFound: If the check returns False. .. py:method:: assert_environment() -> None Check whether the environment path exists and is a valid conda environment. :raises DirectoryNotACondaEnvironmentError: If the check returns False. .. py:method:: assert_writable() -> None Check whether the environment path is a valid conda environment and is writable. :raises EnvironmentNotWritableError: If the check returns False. .. py:method:: assert_not_frozen() -> None Check whether the environment path is a valid conda environment and is not marked as frozen (as per CEP 22). :raises EnvironmentIsFrozenError: If the environment is marked as frozen. .. py:method:: validate_path(expand_path: bool = False) -> None Validate the path of the environment. It runs the following checks: - Make sure the path does not contain `:` or `;` (OS-dependent). - Disallow immediately nested environments (e.g. `$CONDA_ROOT` and `$CONDA_ROOT/my-env`). - Warn if there are spaces in the path. :param expand_path: Whether to process `~` and environment variables in the string. The expanded value will replace `.prefix_path`. :raises CondaValueError: If the environment contains `:`, `;`, or is nested. .. py:method:: validate_name(allow_base: bool = False) -> None Validate the name of the environment. :param allow_base: Whether to allow `base` as a valid name. :raises CondaValueError: If the name is protected, or if it contains disallowed characters (`/`, ` `, `:`, `#`). .. py:method:: load() -> None .. py:method:: reload() -> PrefixData .. py:method:: _get_json_fn(prefix_record: conda.models.records.PrefixRecord) -> str .. py:method:: insert(prefix_record: conda.models.records.PrefixRecord, remove_auth: bool = True) -> None .. py:method:: remove(package_name: str) -> None .. py:method:: get(package_name: str, default: T = NULL) -> conda.models.records.PackageRecord | T .. py:method:: iter_records() -> collections.abc.Iterable[conda.models.records.PrefixRecord] .. py:method:: iter_records_sorted() -> collections.abc.Iterable[conda.models.records.PrefixRecord] .. py:method:: map_records() -> frozendict.frozendict[str, conda.models.records.PrefixRecord] Map the records to a frozendict of name -> record. :return: A mapping of name -> record. .. py:method:: all_subdir_urls() -> set[str] .. py:method:: query(package_ref_or_match_spec: conda.models.records.PackageRecord | conda.models.match_spec.MatchSpec | str) -> collections.abc.Iterable[conda.models.records.PrefixRecord] .. py:method:: get_conda_packages() -> list[conda.models.records.PrefixRecord] Get conda packages sorted alphabetically by name. :return: Sorted conda package records .. py:method:: get_python_packages() -> list[conda.models.records.PrefixRecord] Get Python packages (installed via pip) sorted alphabetically by name. :return: Sorted Python package records .. py:method:: _load_single_record(prefix_record_json_path: conda.common.path.PathType) -> None .. py:method:: _load_site_packages() -> dict[str, conda.models.records.PrefixRecord] .. py:method:: _get_environment_state_file() -> dict[str, dict[str, str]] .. py:method:: _write_environment_state_file(state: dict[str, dict[str, str]]) -> None .. py:method:: _ensure_no_reserved_env_vars(env_vars_names: collections.abc.Iterable[str]) -> None Ensure that the set of env_var_names does not contain any reserved env vars. Will raise an OperationNotAllowed if a reserved env var is found. .. py:method:: get_environment_env_vars() -> dict[str, str] | dict[bytes, bytes] .. py:method:: set_environment_env_vars(env_vars: dict[str, str]) -> dict[str, str] | None .. py:method:: unset_environment_env_vars(env_vars: list[str]) -> dict[str, str] | None .. py:method:: set_creation_time() -> None Writes a .creation-time file in conda-meta with the current timestamp, meant to be used by .created property as a fallback. .. py:method:: set_nonadmin() -> None Creates $PREFIX/.nonadmin if sys.prefix/.nonadmin exists (on Windows). .. py:method:: get_pinned_specs() -> tuple[conda.models.match_spec.MatchSpec] Find pinned specs from file and return a tuple of MatchSpec. .. py:function:: get_conda_anchor_files_and_records(site_packages_short_path: conda.common.path.PathType, python_records: collections.abc.Iterable[conda.models.records.PrefixRecord]) -> dict[conda.common.path.PathType, conda.models.records.PrefixRecord] Return the anchor files for the conda records of python packages. .. py:function:: python_record_for_prefix(prefix: os.PathLike) -> conda.models.records.PrefixRecord | None For the given conda prefix, return the PrefixRecord of the Python installed in that prefix. .. py:function:: get_python_version_for_prefix(prefix: os.PathLike) -> str | None For the given conda prefix, return the version of the Python installation in that prefix. .. py:function:: delete_prefix_from_linked_data(path: str | os.PathLike | pathlib.Path) -> bool Here, path may be a complete prefix or a dist inside a prefix