feat: add pypi_packages formula DSL

Signed-off-by: botantony <[email protected]>

Author: botantony

Library/Homebrew/ast_constants.rb

@@ -43,6 +43,7 @@
   [{ name: :cxxstdlib_check, type: :method_call }],
   [{ name: :link_overwrite, type: :method_call }],
   [{ name: :fails_with, type: :method_call }, { name: :fails_with, type: :block_call }],
+  [{ name: :pypi_packages, type: :method_call }],
   [{ name: :resource, type: :block_call }],
   [{ name: :patch, type: :method_call }, { name: :patch, type: :block_call }],
   [{ name: :needs, type: :method_call }],

Library/Homebrew/formula.rb

@@ -42,6 +42,7 @@
 require "api"
 require "api_hashable"
 require "utils/output"
+require "pypi_packages"
 
 # A formula provides instructions and metadata for Homebrew to install a piece
 # of software. Every Homebrew formula is a {Formula}.
@@ -219,6 +220,9 @@ class Formula
   sig { returns(T.any(BuildOptions, Tab)) }
   attr_reader :build
 
+  sig { returns(PypiPackages) }
+  attr_reader :pypi_packages_info
+
   # Whether this formula should be considered outdated
   # if the target of the alias it was installed with has since changed.
   # Defaults to true.
@@ -267,6 +271,8 @@ def initialize(name, path, spec, alias_path: nil, tap: nil, force_bottle: false)
       Tap.from_path(path)
     end
 
+    @pypi_packages_info = T.let(PypiPackages.from_json_file(@tap, @name), PypiPackages)
+
     @full_name = T.let(T.must(full_name_with_optional_tap(name)), String)
     @full_alias_name = T.let(full_name_with_optional_tap(@alias_name), T.nilable(String))
 
@@ -584,6 +590,47 @@ def bottle_for_tag(tag = nil)
   # @see .api_source
   delegate api_source: :"self.class"
 
+  # Information about PyPI packages for this formula.
+  # @!method pypi_packages
+  # @see .pypi_packages
+  delegate pypi_packages: :"self.class"
+
+  # TODO: add docs
+  # @api public
+  sig {
+    params(
+      package_name:        T.nilable(String),
+      extra_packages:      T.nilable(T.any(String, T::Array[String])),
+      exclude_packages:    T.nilable(T.any(String, T::Array[String])),
+      dependencies:        T.nilable(T.any(String, T::Array[String])),
+      needs_manual_update: T::Boolean,
+    ).void
+  }
+  def pypi_packages(
+    package_name: nil,
+    extra_packages: nil,
+    exclude_packages: nil,
+    dependencies: nil,
+    needs_manual_update: false
+  )
+    if needs_manual_update
+      @pypi_packages_info = PypiPackages.new needs_manual_update: true
+      return
+    end
+
+    if [package_name, extra_packages, exclude_packages, dependencies].all?(&:nil?)
+      raise ArgumentError, "must provide at least one argument"
+    end
+
+    # Sadly `v1, v2, v3 = [v1, v2, v3].map { |x| Array(x) }` does not work
+    # for typechecker
+    extra_packages = Array(extra_packages)
+    exclude_packages = Array(exclude_packages)
+    dependencies = Array(dependencies)
+
+    @pypi_packages_info = PypiPackages.new(package_name:, extra_packages:, exclude_packages:, dependencies:)
+  end
+
   sig { returns(Formula) }
   def fully_loaded_formula
     @fully_loaded_formula ||= if loaded_from_stub?

Library/Homebrew/pypi_packages.rb

@@ -0,0 +1,71 @@
+# typed: strict
+# frozen_string_literal: true
+
+# Helper class for `pypi_packages` DSL.
+# @api internal
+class PypiPackages
+  sig { returns(T.nilable(String)) }
+  attr_reader :package_name
+
+  sig { returns(T::Array[String]) }
+  attr_reader :extra_packages
+
+  sig { returns(T::Array[String]) }
+  attr_reader :exclude_packages
+
+  sig { returns(T::Array[String]) }
+  attr_reader :dependencies
+
+  sig { params(tap: T.nilable(Tap), formula_name: String).returns(T.attached_class) }
+  def self.from_json_file(tap, formula_name)
+    list_entry = tap&.pypi_formula_mappings&.fetch(formula_name, nil)
+
+    return new(defined_pypi_mapping: false) unless list_entry.present?
+
+    case T.cast(list_entry, T.any(FalseClass, String, T::Hash[String, T.any(String, T::Array[String])]))
+    when false
+      new needs_manual_update: true
+    when String
+      new package_name: list_entry
+    when Hash
+      package_name = list_entry["package_name"]
+      extra_packages = list_entry.fetch("extra_packages", [])
+      exclude_packages = list_entry.fetch("exclude_packages", [])
+      dependencies = list_entry.fetch("dependencies", [])
+
+      new package_name:, extra_packages:, exclude_packages:, dependencies:
+    end
+  end
+
+  sig {
+    params(
+      package_name:         T.nilable(String),
+      extra_packages:       T::Array[String],
+      exclude_packages:     T::Array[String],
+      dependencies:         T::Array[String],
+      needs_manual_update:  T::Boolean,
+      defined_pypi_mapping: T::Boolean,
+    ).void
+  }
+  def initialize(
+    package_name: nil,
+    extra_packages: [],
+    exclude_packages: [],
+    dependencies: [],
+    needs_manual_update: false,
+    defined_pypi_mapping: true
+  )
+    @package_name = T.let(package_name, T.nilable(String))
+    @extra_packages = T.let(extra_packages, T::Array[String])
+    @exclude_packages = T.let(exclude_packages, T::Array[String])
+    @dependencies = T.let(dependencies, T::Array[String])
+    @needs_manual_update = T.let(needs_manual_update, T::Boolean)
+    @defined_pypi_mapping = defined_pypi_mapping
+  end
+
+  sig { returns(T::Boolean) }
+  def defined_pypi_mapping? = @defined_pypi_mapping
+
+  sig { returns(T::Boolean) }
+  def needs_manual_update? = @needs_manual_update
+end

Library/Homebrew/utils/pypi.rb

@@ -237,23 +237,16 @@ def self.update_python_resources!(formula, version: nil, package_name: nil, extr
                                     exclude_packages: nil, dependencies: nil, install_dependencies: false,
                                     print_only: false, silent: false, verbose: false,
                                     ignore_errors: false, ignore_non_pypi_packages: false)
-    auto_update_list = formula.tap&.pypi_formula_mappings
-    if auto_update_list.present? && auto_update_list.key?(formula.full_name) &&
-       package_name.blank? && extra_packages.blank? && exclude_packages.blank?
-
-      list_entry = auto_update_list[formula.full_name]
-      case list_entry
-      when false
-        unless print_only
-          odie "The resources for \"#{formula.name}\" need special attention. Please update them manually."
-        end
-      when String
-        package_name = list_entry
-      when Hash
-        package_name = list_entry["package_name"]
-        extra_packages = list_entry["extra_packages"]
-        exclude_packages = list_entry["exclude_packages"]
-        dependencies = list_entry["dependencies"]
+    list_entry = formula.pypi_packages_info
+    if list_entry.defined_pypi_mapping? && package_name.blank? && extra_packages.blank? && exclude_packages.blank?
+
+      if list_entry.needs_manual_update? && !print_only
+        odie "The resources for \"#{formula.name}\" need special attention. Please update them manually."
+      else
+        package_name = list_entry.package_name
+        extra_packages = list_entry.extra_packages
+        exclude_packages = list_entry.exclude_packages
+        dependencies = list_entry.dependencies
       end
     end