rules_python

The sphinxdocs project enables documentation generation using Sphinx within a Bazel environment. While it is optimized for documenting Starlark code, the core functionality is agnostic to the content being documented.

Key features include:

• Rules for running Sphinx.
• Rules for generating documentation specifically for Starlark code.
• A Sphinx plugin designed for documenting Starlark and Bazel objects.
• Rules for integrating builds with Read the Docs.

The rules_python repository contains integration code for interacting with PyPI and other compatible indexes. The current capabilities include:

• Package Downloading: Support for downloading packages using pip or repository_ctx.download.
• Index Interaction: Interacting with PyPI-compatible indexes that follow the [SimpleAPI] specification.
• Dependency Locking: Support for locking dependencies from requirements.in files or [PEP621] compliant pyproject.toml files.

The rules_python repository provides the core Python rules for Bazel, enabling Python development within a Bazel workspace. It includes standard rules for defining Python components and tools for managing package dependencies from PyPI or other indices.

Key components include:

• Core Rules: py_library, py_binary, and py_test.
• Dependency Management: Rules for integrating with PyPI and other package indices.
• Standards Support: Implementation of PEP440 and PEP509 via Starlark.

A simple label is a str or Label object that is not a direct select object.

Because select objects represent configuration-dependent values, they cannot undergo standard string manipulation. If an attribute requires a simple label, you cannot pass a select directly to it. However, if an alias is used, you can often pass a reference to that alias to maintain configurability.

The Gazelle plugin for rules_python is a build file generator for Bazel projects. It automates the creation of new BUILD or BUILD.bazel files and updates existing ones to include new sources, dependencies, and options based on Python language conventions.

Key Behaviors

• Non-destructive updates: Gazelle attempts to leave your manual edits to BUILD files intact, focusing updates specifically on py_* targets.
• Dependency management: Gazelle will remove dependencies that it identifies as unused. It is recommended to commit your work before running Gazelle so you can revert changes if necessary.
• Commands: While the gazelle program supports multiple commands, currently only the update command (which is the default) performs actions for Python code.

Precompiling is the process of compiling Python source files (.py) into bytecode (.pyc) at build time rather than at runtime.

Benefits:

• Improves runtime performance by skipping the compilation step when the application starts.

Costs/Trade-offs:

• Increased Runfiles Size: It approximately doubles the count and disk usage of runfiles because every .py file is accompanied by a .pyc file.
• Build Overhead: Requires an extra action during the build process, which can increase build times as the number of files grows.

A rule callable is a function that behaves like a Bazel rule. To be considered a rule callable, a function must:

• Accept a name argument and other common attributes.
• Return None (no return value).
• Create at least one target named after the provided name.

Note that there is usually an implicit interface regarding which specific attributes and values are accepted; you should refer to the specific API documentation for the rule you are using.

When managing PyPI dependencies, you may encounter complex scenarios that require specific handling:

• Circular Dependencies: Use specialized strategies if your Python dependency graph contains cycles.
• Multi-platform Dependencies: Handle packages that require different dependencies depending on the target operating system or architecture.
• Patching: Apply patches to third-party packages if they require fixes to work within the Bazel environment.