# Tools Directory

This folder contains various command-line tools that are used to facilitate different development tasks. Below is a brief description of each command available in this directory.

## Update Conda Environment Files

This command is used to update the Conda environment files in the project. It automatically adds new dependencies to the Conda files, removes deleted dependencies, and updates the version of existing dependencies. The source of the dependencies is the `pyproject.toml` file, which specifies the following dependencies:

- `build-system.requires`: Python dependencies required for building
- `project.dependencies`: Python dependencies required for running
- `external.build-requires`: External dependencies required for building
- `external.host-requires`: External dependencies required for running


Within an active virtual environment where `grayskull` and `conda-lock` are installed, run the following command:

```bash
tools/update-conda.py
```

## Update Meson Build Files

This command is used to updates the Meson build files in the project. It automatically adds new source files (py, pyx) to the Meson files and removes deleted source files. This command is useful when adding or removing source files from the project.

Within an active virtual environment where Meson is installed, run the following command:

```bash
tools/update-meson.py
```

Note that this script does not handling adding dependencies, those still must be done manually.

## Find Outdated Deprecations

Code that is deprecated can be safely removed one year after the first stable release containing the deprecation. This command searches for deprecated code in the source folder and prints all old deprecations.

Within an active virtual environment where `pygithub` and `tqdm` is installed, run the following command:

```bash
tools/check_deprecations.py <optional path to source folder>
```

It is recommended to pass a subfolder of the source folder to the script to avoid checking the entire source folder, which most likely triggers a rate limit on the GitHub API.
Alternatively, you can pass a [GitHub token](https://github.com/settings/tokens) via the `--token` argument to avoid the rate limit.

## Update Version Number

Increments the version number in the project. This command is useful when releasing a new version of the project.

Set `SAGE_ROOT` to the root directory of the Sage project and run the following command:

```bash
tools/update_version
```

## Generate cython header files for flint

The flint-autogen directory contains a script (`flint_autogen.py`)
that will automatically generate the pxd files in
`SAGE_ROOT/src/sage/libs/flint`. It requires gitpython to be
installed, and for `FLINT_GIT_DIR` to be set to a clone of the flint
git repository.

Example:

```bash
# don't forget to install gitpython first
cd flint-autogen
FLINT_GIT_DIR=/path/to/flint.git python flint_autogen.py
```

## Check status of ruff config

The `tools/check_ruff.py` script lists any ruff linter prefixes or rules that already pass on the entire codebase.
This script can be run from the root directory of the Sage repo as `tools/check_ruff.py prefix` to check rule prefixes, or `tools/check_ruff.py rule` to check individual rules.
Such rules are usually safe to add to the ruff config in `pyproject.toml`, but manual checking what the rule does and considering its relevance to Sage should still be done (for example, do not enable linter rules that are specific to a library that Sage does not use).

## Generate cython header files for flint

The flint-autogen directory contains a script (`flint_autogen.py`)
that will automatically generate the pxd files in
`SAGE_ROOT/src/sage/libs/flint`. It requires gitpython to be
installed, and for `FLINT_GIT_DIR` to be set to a clone of the flint
git repository.

Example:

```bash
# don't forget to install gitpython first
cd flint-autogen
FLINT_GIT_DIR=/path/to/flint.git python flint_autogen.py
```

## Update Type Stubs

This command updates the type stubs (`.pyi` files) in the source folder based on the corresponding Cython files (`.pyx` files).

It supports two modes of operation:
- Check mode: Compares the existing type stubs with the generated ones and reports any differences without making changes. This is useful for verifying wether the type stubs are in sync with the Cython files.

  ```bash
  uv run tools/update_typestubs.py check <path to Cython file.pyx>
  ```

- Write mode: Generates new type stubs which is handy to initially create type stubs for Cython files that do not have them yet. The created type stubs are pretty basic, and do not include detailed type information (e.g., specific types for function parameters and return types). One can then manually edit the generated type stubs to add more specific type information, or use AI tools to assist in refining the type annotations.

  ```bash
  uv run tools/update_typestubs.py write <path to Cython file.pyx>
  ```
