mkwhl 0.2.4

Python wheel creation utility

Create Python wheel based on pyproject.toml configuration and/or provided arguments. Wheels can be created by:

• running command line tool

• pyproject.toml build backend

• calling mkwhl.create_wheel function

Goal of this project is to provide simple and minimal utility based on accepted PEPs. Usage of pyproject.toml should not be mandatory and each pyproject.toml property should be overridable by provided arguments. Functionality should not depend on specific project’s repository layout. User is responsible for providing correct configuration/arguments (e.g. python/abi/platform tags) without additional “automatic” detection.

Requirements

• python >=3.10

Install

$ pip install mkwhl

Command line tool

Usage:

$ mkwhl --help

pyproject.toml build backend

mkwhl implements build backend according to PEP517 and PEP660. To use mkwhl as build backend, add following to pyproject.toml:

[build-system]
requires = ["mkwhl"]
build-backend = "mkwhl"

Wheel will be build based on pyproject.toml project metadata and additional [tool.mkwhl] properties:

• src-dir (string)

  Source root directory. If this property is not set, existence of src_py or src directory is checked and used if available.

• license-path (string)

  Optional path to license file.

• src-include-patterns (list of strings)

  List of strings used as pathlib.Path.glob patterns applied to src_dir. These patterns specify which files should be included as part of built wheel. If not set, ['**/*'] is assumed.

• src-exclude-patterns (list of strings)

  List of strings used as pathlib.Path.glob patterns applied to src_dir. These patterns specify which files should not be included as part of built wheel. This patterns take priority over src-include-patterns. If not set, ['**/__pycache__/**/*'] is assumed.

• ‘python-tag’ (string)

  Python tag (see binary distribution format). If not set, py3 is assumed.

• ‘abi-tag’ (string)

  ABI tag (see binary distribution format). If not set, none is assumed.

• build-tag (integer)

  Optional build tag (see binary distribution format).

• ‘platform-tag’ (string)

  Python tag (see binary distribution format). If not set, any is assumed.

• ‘is-purelib’ (boolean)

  Is purelib (see binary distribution format). If not set, true is assumed.

Python API

In addition to command line interface and build backend, package mkwhl exposes single function:

def create_wheel(src_dir: Path,
                 build_dir: Path,
                 *,
                 name: str | None = None,
                 version: str | None = None,
                 description: str | None = None,
                 readme_path: Path | None = None,
                 requires_python: str | None = None,
                 license: str | None = None,
                 license_path: Path | None = None,
                 authors: list[tuple[str | None, str | None]] | None = None,
                 maintainers: list[tuple[str | None, str | None]] | None = None,
                 keywords: list[str] | None = None,
                 classifiers: list[str] | None = None,
                 urls: dict[str, str] | None = None,
                 scripts: dict[str, str] | None = None,
                 gui_scripts: dict[str, str] | None = None,
                 dependencies: list[str] | None = None,
                 optional_dependencies: dict[str, list[str]] | None = None,
                 conf_path: Path | None = Path('pyproject.toml'),
                 editable: bool = False,
                 src_include_patterns: typing.Iterable[str] = ['**/*'],
                 src_exclude_patterns: typing.Iterable[str] = ['**/__pycache__/**/*'],
                 build_tag: int | None = None,
                 python_tag: str = 'py3',
                 abi_tag: str = 'none',
                 platform_tag: str = 'any',
                 is_purelib: bool = True,
                 ) -> str:
    """Create wheel and return wheel name

    Argument `src_dir` is path to source root directory.

    Argument `build_dir` is path to directory where resulting wheel will be
    created.

    If one of arguments `name`, `version`, `description`, `readme_path`,
    `requires_python`, `license`, `authors`, `maintainers`, `keywords`,
    `classifiers`, `urls`, `scripts`, `gui_scripts`, `dependencies` or
    `optional_dependencies` is ``None``, associated resulting property is
    set based on project configuration read from pyproject.

    Arguments `authors` and `maintainers` are structured as list of tuples
    where first tuple element represents name and second tuple element
    represents email.

    If `conf_path` is ``None``, resulting wheel will be created based only
    on provided arguments without parsing of pyproject configuration.

    Arguments `src_include_patterns` and `src_exclude_patterns` provide
    list of strings used as `pathlib.Path.glob` patterns applied to
    `src_dir`. Include patterns specify all files that will be included in
    resulting wheel. All files specified by exclude patterns will not be
    included in resulting wheel, even if same file is specified by include
    pattern.

    """

License

mkwhl - python wheel creation utility

Copyright (C) 2023 Bozo Kopic

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.