whl2conda.api.stdrename¶

def download_mappings(
    url: str = NAME_MAPPINGS_DOWNLOAD_URL,
    *,
    etag: str = "",
    timeout: float = 20.0,
) -> DownloadedMappings:
    """
    Download pypi to conda name mappings from github

    Args:
        url: download url of mappings file on github
        etag: ETag from previous download
        timeout: max seconds to wait for connection

    Returns:
        Mapping table and HTTP headers.

    Raises:
        NotModified: if etag was specified and content has not changed
        HttpError: other HTTP errors (e.g. 404 etc)
        URLError: connection errors
    """

    req = urllib.request.Request(
        url,
        headers={"User-Agent": f"whl2conda/{__version__}"},
    )
    if etag:
        req.add_header("If-None-Match", f'"{etag}"')

    try:
        with urllib.request.urlopen(req, timeout=timeout) as response:
            headers = response.headers
            content = response.read()
            mappings = json.loads(content)
    except HTTPError as err:
        if err.status == HTTPStatus.NOT_MODIFIED:  # type: ignore
            raise NotModified(
                url,
                err.code,
                err.reason,
                err.headers,
                err.fp,
            ) from err
        raise

    return DownloadedMappings(url, headers, mappings)

def load_std_renames(
    *,
    update: bool = False,
) -> dict[str, str]:
    """
    Load standard pypi to conda package rename table.

    A copy of this table is kept in a local a cache
    file (see [user_stdrenames_path][(m).])
    The table will be read from that file, it it exists, otherwise the
    table included in this package will be copied to the
    user cache file.

    Arguments:
        update: if true, this will update the table from online
            list generated from conda-forge and saves it as the
            new cached copy.

    Returns:
        Dictionary of pypi to conda package name mappings. The
        returned dictionary will also contain the entries "$etag",
        "$date" and "$source" taken from the downloaded web file
        from which it was computed.
    """
    # Look for local copy of stdrenames
    local_std_rename_file = user_stdrenames_path()
    if not local_std_rename_file.exists():
        resources = importlib.resources.files('whl2conda.api')
        s = resources.joinpath("stdrename.json").read_text("utf8")
        local_std_rename_file.parent.mkdir(parents=True, exist_ok=True)
        local_std_rename_file.write_text(s, "utf8")

    if update:
        update_renames_file(local_std_rename_file)

    s = local_std_rename_file.read_text("utf8")
    return json.loads(s)

def parse_datetime(s: str) -> datetime.datetime | None:
    """Parse datetime string from HTTP header

    Returns None if string is empty or time is malformed.
    """
    try:
        return parsedate_to_datetime(s)
    except Exception:  # pylint: disable=broad-exception-caught
        return None

def process_name_mapping_dict(mappings: DownloadedMappings) -> dict[str, str]:
    """
    Convert name mapping table from github to simple rename table.

    This only returns mappings where the name is different.

    Args:
        mappings: downlaoded mappings

    Returns:
        dictionary mapping pypi to conda package names
    """
    renames: dict[str, str] = {
        "$source": mappings.url,
        "$date": mappings.datestr or formatdate(usegmt=True),
        "$etag": mappings.etag,
        "$max-age": str(max(mappings.max_age, DEFAULT_MIN_EXPIRATION)),
    }
    for entry in mappings.mappings:
        pypi_name = entry.get("pypi_name")
        conda_name = entry.get("conda_name")
        if pypi_name and conda_name and pypi_name != conda_name:
            renames[pypi_name] = conda_name
    return renames

def update_renames_file(
    renames_file: Path | str,
    *,
    url: str = NAME_MAPPINGS_DOWNLOAD_URL,
    min_expiration: int = DEFAULT_MIN_EXPIRATION,
    dry_run: bool = False,
) -> bool:
    """
    Update standard renames file from github if changed

    This will only download new data if the existing
    data has passed its expiration.

    Args:
        renames_file: path to renames file, which does not have to
            exist initially
        url: url of name mapping file to download. This file is
            expected to contain a JSON array of dictionary
            containing "pypi_name" and "conda_name" entries.
        min_expiration: minimum seconds before existing data expires.
            Default is 5 minutes.
        dry_run: does not update the file, but still does download
            and returns True if file would change

    Returns:
        True if file was updated. False if file has not expired yet
        or upstream data has not changed.
    """
    renames_path = Path(renames_file).expanduser()

    etag = ""
    if renames_path.is_file():
        # check expiration information from existing file
        current_renames = json.loads(renames_path.read_text("utf8"))
        if date := parse_datetime(current_renames.get("$date", "")):
            try:
                max_age = int(current_renames.get("$max-age", 0))
            except Exception:  # pylint: disable=broad-exception-caught
                max_age = 0
            max_age = max(min_expiration, max_age)
            if (date.timestamp() + max_age) > time.time():
                # Not expired yet
                return False
        etag = current_renames.get("$etag")

    try:
        downloaded = download_mappings(url=url, etag=etag)
    except NotModified:
        return False

    new_renames = process_name_mapping_dict(downloaded)
    if not dry_run:
        renames_path.parent.mkdir(parents=True, exist_ok=True)
        renames_path.write_text(
            json.dumps(new_renames, sort_keys=True, indent=2),
            encoding="utf8",
        )

    return True

def user_stdrenames_path() -> Path:
    r"""Path to user's cached copy of standard pypi to conda renames file

    The location of this file depends on the operating system:

    * Linux: ~/.cache/whl2conda/stdrename.json
    * MacOS: ~/Library/Caches/whl2conda/stdrename.json
    * Windows: ~\AppData\Local\whl2conda\Cache\stdrename.json
    """
    return user_cache_path("whl2conda").joinpath("stdrename.json")