Airspeed Velocity (ASV)

Common errors

• ImportError: No module named 'asv_runner'

  cause This error occurs when the 'asv_runner' module is not installed or not found in the Python environment.
  fix Ensure that the 'asv' package is installed correctly by running 'pip install asv'.

• AttributeError: 'NoneType' object has no attribute 'group'

  cause This error occurs when a regular expression search returns 'None', and the code attempts to call the 'group()' method on it.
  fix Check if the regular expression search result is not 'None' before calling 'group()'. For example: 'match = re.search(pattern, string); if match: result = match.group()'.

• ModuleNotFoundError: No module named 'asv'

  cause This error occurs when the 'asv' module is not installed or not found in the Python environment.
  fix Install the 'asv' package using 'pip install asv'.

• asv: command not found

  cause This error occurs when the 'asv' command-line tool is not installed or not found in the system's PATH.
  fix Ensure that the 'asv' package is installed and that the installation directory is included in the system's PATH.

• asv: error: unrecognized arguments

  cause This error occurs when invalid or unrecognized arguments are passed to the 'asv' command.
  fix Check the 'asv' command-line interface documentation for the correct usage and available arguments.

Warnings

• breaking Changing benchmark names, class names, or parameter names within your `benchmarks.py` files can invalidate historical data in ASV's reports. This makes it difficult to compare new results with past performance for the renamed benchmarks, essentially starting a new series.
  Fix: Carefully consider benchmark naming conventions from the start. If changes are necessary, acknowledge that historical data for that specific benchmark series will be lost or fragmented. Documentation advises on pitfalls of changing `benchmark_name` attributes.
• gotcha ASV is fundamentally a command-line tool (`asv quickstart`, `asv run`, `asv publish`, etc.). It's not typically imported as a Python library for direct programmatic use in application code. Attempting `import asv` to access benchmark running logic directly is not the intended usage model for most users.
  Fix: Interact with ASV via its command-line interface. Benchmark definitions are Python code, but the execution and reporting are driven by the `asv` command.
• gotcha When configuring benchmark dependencies, `asv.conf.json` can specify `environment_matrix` settings (e.g., Python versions, specific package versions). If you also use `conda` or `mamba` with an `environment.yml` file, the explicit dependencies listed in `environment_matrix` within `asv.conf.json` will override those in `environment.yml`.
  Fix: Be mindful of the precedence: `environment_matrix` in `asv.conf.json` takes priority. Ensure your dependency specifications are consistent or intentionally configured across both files if you use both methods.
• gotcha ASV relies on Git or Mercurial for tracking project history and associating benchmark results with specific commits. While it can run benchmarks locally, its primary strength—historical performance tracking—requires an initialized Git or Mercurial repository.
  Fix: Ensure your project is under version control (Git or Mercurial) and that the `repo` path in `asv.conf.json` correctly points to your repository.
• gotcha The acronym 'ASV' is also used in other contexts, such as Adaptive Servo-Ventilation (medical devices for sleep apnea) and ASV Inventions (motorcycle parts). When searching for or discussing the Python benchmarking tool, ensure the context is clear to avoid confusion.
  Fix: Specify 'Python asv' or 'Airspeed Velocity' when referring to this library.

Install

• pip install asv Install latest version

Imports

• asv
  wrong:

  import asv; asv.run()

  correct:

  asv <command>

  ASV is primarily a command-line interface (CLI) tool. While it uses Python for defining benchmarks, its core functionality is exposed via shell commands like `asv run`, `asv publish`, etc., rather than direct programmatic Python imports in user applications.

Quickstart

To get started, navigate to your project directory (or a new directory for benchmarks) and run `asv quickstart` to set up the basic configuration and an example benchmark file. Then, define your benchmarks in Python files within the `benchmarks/` directory, typically as classes with `time_` or `mem_` prefixed methods. Finally, execute `asv run` to collect benchmark data and `asv publish` to generate the interactive web report, which can be viewed with `asv browse`.

# 1. Initialize a new ASV benchmark suite
# Run this in your project's root or a dedicated benchmark directory.
asv quickstart

# 2. Add a benchmark to benchmarks/benchmarks.py (example content below)
# Create or edit 'benchmarks/benchmarks.py' with content like:
# import numpy as np
# 
# class TimeSuite:
#     def setup(self):
#         self.x = np.random.rand(1000, 1000)
# 
#     def time_sum_array(self):
#         np.sum(self.x)
# 
#     def time_dot_product(self):
#         np.dot(self.x, self.x)
# 
#     def teardown(self):
#         self.x = None
# 
# class MemSuite:
#     def mem_full_array(self):
#         return np.random.rand(1000, 1000)

# 3. Run the benchmarks
asv run

# 4. Publish the results to a web frontend
asv publish

# 5. Open the results in a web browser
asv browse