DOCSEARCHbyAlgolia
Submit Docs

Python Install Manager

repository·main·Indexed 43 days ago

https://github.com/python/pymanager

A tool for managing Python installations on Windows following PEP 773 principles. It provides programmatic interfaces for locating Python runtimes via find_one(), managing installation aliases, and a hierarchical configuration system that supports JSON files and the Windows Registry.

Tokens
7K
Snippets
27
Records
42
Agent score
51%

What's inside PyManager

  1. How Python Install Manager versioning works

    main

    PyManager uses a versioning scheme where the first part is a two-digit year and the second part increments with each release (e.g., YY.X).

    This scheme is used to:

    1. Avoid tying features to version numbers.
    2. Avoid direct association with specific Python releases.
    3. Maintain compatibility with MSI, which does not support major version fields over 256.

  2. Run the test suite locally

    main

    To run tests, you can build the native components separately using pymsbuild with the _msbuild_test.py configuration. This allows for faster iteration on Python code without a full rebuild. However, if you modify C++ files, you must run the pymsbuild step again.

    Steps:

    1. Install dependencies (pymsbuild, pytest).
    2. Build native components via pymsbuild.
    3. Run the test suite using pytest.
    python -m pip install pymsbuild pytest
python -m pymsbuild -c _msbuild_test.py
python -m pytest

  3. Build and run Python Install Manager locally

    main

    To build and run the project locally, you need pymsbuild and a Visual Studio installation that includes C/C++ compilers. Note that .py files are packaged into an extension module, so any modification to a source file requires a rebuild.

    To enable verbose debugging, set the %PYMANAGER_DEBUG% environment variable. This is equivalent to passing -vv and works even in contexts that do not accept options (like launching a runtime).

    python -m pip install pymsbuild
python -m pymsbuild
python-manager\py.exe ...

  4. Package the application into MSIX, APPXSYM, and MSI

    main

    To produce installer packages (MSIX, APPXSYM, and MSI), use the make-all.py script.

    Installation Note: MSIX packages must be signed before installation. You can use a self-signed certificate (added to Trusted Publishers) or perform a development install by:

    1. Renaming the .msix file to .zip and extracting it.
    2. Running Add-AppxPackage -Register <path to dir>\appxmanifest.xml via PowerShell.
    python -m pip install pymsbuild
python make-all.py

  5. How pymanager configuration is loaded and merged

    main

    pymanager uses a hierarchical configuration loading strategy. It starts with a global configuration and then layers multiple sources on top of it. The order of precedence (from lowest to highest) is:

    1. Global Config: Loaded from pymanager.json located in the package root or the Python executable's parent directory.
    2. Registry Overrides: If a registry_override_key is present in the configuration, settings are loaded from the Windows Registry. These settings are applied with overwrite=True.
    3. Base Config: Loaded from the file path specified in the base_config key.
    4. User Config: Loaded from the file path specified in the user_config key.
    5. Additional Config: Loaded from the file path specified in the additional_config key.
    6. Override File: A specific file passed during the load process, applied with overwrite=True.

    Merging Logic:

    • If a configuration key's schema defines merge=True, the new value is merged with the existing value (e.g., appending to a list) rather than replacing it.
    • If overwrite=True is used during a load or merge operation, existing values are replaced regardless of the schema's merge setting.
    • Keys starting with # are treated as comments and ignored.

  6. Configure authentication for downloads

    main

    When downloading packages from authenticated sources, pymanager looks for credentials in the following order:

    1. URL Authentication: Credentials embedded directly in the package URL.
    2. Environment Variables:
      • PYMANAGER_USERNAME
      • PYMANAGER_PASSWORD

    This is used internally by download_package via the _find_creds helper.

  7. Configure shebang behavior via templates

    main

    The script utility allows overriding shebang detection using shebang_templates defined in your configuration. This allows you to map specific shebang strings to specific Python installations or command patterns.

    Supported patterns for template replacement include:

    • py -V:<version>: Maps to a specific version.
    • pyw -V:<version>: Maps to a specific windowed version.
    • py -3: Maps to a PythonCore/3.x style installation.
    • pyw -3: Maps to a windowed PythonCore/3.x style installation.
    • py or pyw: Maps to the default runtime or windowed runtime respectively.

  8. Configuration Schema Features: Environment Variables and Paths

    main

    The configuration resolution process (resolve_config) supports advanced features via the schema:

    Environment Variable Expansion

    If a schema option includes "env", string values can use the %(VAR_NAME)% syntax to expand environment variables.

    • Example: "path": "%(HOME)%/data" will expand to the value of the HOME environment variable.
    • If an environment variable expands to an empty string, the configuration key is removed.

    Path Resolution

    If a schema option includes "path", the configuration value is treated as a path:

    • Relative Paths: If the value comes from a configuration file, it is resolved relative to the directory containing that file.
    • Environment Variables: If the value is expanded from an environment variable, it is resolved relative to the current working directory.

    URI Conversion

    If a schema option includes "uri", the value is converted to a URI string using .as_uri() if available, or cast to a string.

  9. Configure Windows Long Paths support

    main

    To ensure Python and its packages can handle file paths longer than 260 characters, you can enable Windows Long Paths support. This requires a system-wide registry change and a reboot to take effect.

    If you are using the CLI, you can trigger this configuration via the --configure flag. If the current user lacks administrative privileges, the tool will prompt you to rerun the command with elevated privileges.

    Manual Command: If the automatic configuration fails, rerun the command with administrative privileges:

    py install --configure

  10. Add the global commands directory to PATH

    main

    The Python Install Manager can add its global shortcuts directory to your Windows PATH environment variable. This enables versioned commands (e.g., python3.15.exe) to be executed directly from any terminal.

    Note:

    • Changes to PATH will take effect after opening a new terminal.
    • This directory is automatically removed if you run py uninstall --purge.

  11. Install from an offline index

    main

    You can generate an offline index of packages and install from it later. This is useful for environments without direct internet access.

    1. Generate the index: Use the --download flag with the install command. This will download the packages and create an index.json file in the specified directory.
    2. Install from the index: Use the -s (or --source) flag pointing to the directory containing the generated index.json.

    Example command to install from a local directory:

    py install -s .\path\to\download_dir [tags ...]
    py install -s .\%s [tags ...]

  12. Configure the application icon in pywicon.rc

    main

    The pywicon.rc configuration file defines the icon used by the application. It uses a specific format to specify an icon file and its discardable status.

    Key syntax:

    • 1 ICON DISCARDABLE "<path_to_icon>"

    Currently, the configuration points to _resources\pythonw.ico.

    1 ICON DISCARDABLE "_resources\pythonw.ico"