feat: add python functools reduce (#613)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: kvz

CHANGELOG.md

@@ -23,6 +23,10 @@ Ideas that will be planned and find their way into a release at one point
   - [ ] Java
   - [ ] Haskell
 
+## main
+
+- Added a first `python/functools` harvest covering `reduce`.
+
 ## v3.0.33
 
 Released: 2026-03-30. [Diff](https://github.com/locutusjs/locutus/compare/v3.0.32...v3.0.33).

docs/non-php-api-signatures.snapshot

@@ -283,6 +283,7 @@ src/python/_helpers/_calendar.ts :: export function normalizeWeekWidth(value: un
 src/python/_helpers/_calendar.ts :: export function pythonWeekday(year: number, month: number, day: number): number
 src/python/_helpers/_calendar.ts :: export function timeTupleToUnixSeconds( year: number, month: number, day: number, hour: number, minute: number, second: number, ): number
 src/python/_helpers/_calendar.ts :: export function toCalendarInteger(value: unknown, functionName: string): number
+src/python/_helpers/_functools.ts :: export function pythonReduce( func: (accumulator: unknown, value: unknown) => unknown, iterable: unknown, initializer: unknown = noInitializer, ): unknown
 src/python/_helpers/_itertools.ts :: export function itertoolsAccumulate( iterable: unknown, func: ((accumulator: unknown, value: unknown) => unknown) | undefined, ): unknown[]
 src/python/_helpers/_itertools.ts :: export function itertoolsBatched(iterable: unknown, n: unknown): unknown[][]
 src/python/_helpers/_itertools.ts :: export function itertoolsChain(iterables: unknown[]): unknown[]
@@ -356,6 +357,7 @@ src/python/calendar/weekday.ts :: export function weekday(year: unknown, month:
 src/python/calendar/weekheader.ts :: export function weekheader(width: unknown): string
 src/python/difflib/get_close_matches.ts :: export function get_close_matches( word: string, possibilities: string[] | unknown, n: number = 3, cutoff: number = 0.6, ): string[]
 src/python/difflib/ndiff.ts :: export function ndiff( a: string[] | unknown, b: string[] | unknown, linejunk: LineJunkPredicate = null, charjunk: CharJunkPredicate = isCharacterJunk, ): string[]
+src/python/functools/reduce.ts :: export function reduce( func: (accumulator: unknown, value: unknown) => unknown, iterable: unknown, initializer?: unknown, ): unknown
 src/python/itertools/accumulate.ts :: export function accumulate(iterable: unknown, func?: (accumulator: unknown, value: unknown) => unknown): unknown[]
 src/python/itertools/batched.ts :: export function batched(iterable: unknown, n: unknown): unknown[][]
 src/python/itertools/chain.ts :: export function chain(...iterables: unknown[]): unknown[]

docs/prompts/LOG.md

@@ -3244,3 +3244,29 @@ LLMs log key learnings, progress, and next steps in one `### Iteration ${increme
 - Key learnings:
   - The generated standalone test path will expose symbol collisions that the source/module variants can miss, so alias-like function names need helper internals with distinct names.
   - `bisect` is a good example of a small Python module where strict target-definition work pays off: once the inventory and wishlist are explicit, the harvest becomes a narrow parity exercise rather than guesswork.
+
+### Iteration 160
+
+2026-03-30
+
+- **Area: Product (Python functools harvest 1)**
+- Plan:
+  - Ship the smallest high-value `functools` addition first, centered on `reduce`.
+  - Keep parity strict by teaching the Python translator only the narrow callback form this harvest actually needs.
+- Progress:
+  - Added `src/python/functools/reduce.ts` plus a shared `_functools` helper that preserves Python-style omitted-initializer semantics, including the empty-sequence error path.
+  - Added `src/python/functools/index.ts`, updated `src/python/index.ts`, and wired both Rosetta maps so the new function is part of the public surface.
+  - Extended `test/parity/lib/languages/python.ts` with a focused `reduce` callback translation path, allowing simple JS arrow reducers like `(a, b) => a + b` to execute as native Python lambdas during parity.
+  - Added focused util coverage, generated tests, website pages, and removed the stale `functools/reduce` wishlist entry from the upstream-surface inventory now that it is shipped.
+- Validation:
+  - `corepack yarn exec vitest run test/util/python-functools-harvest-1.vitest.ts`
+  - `corepack yarn test:parity python/functools/reduce --no-cache`
+  - `node scripts/rmrf.ts test/generated && corepack yarn build:tests`
+  - `corepack yarn exec vitest run test/generated/python/functools/*.vitest.ts`
+  - `corepack yarn injectweb && corepack yarn website:verify`
+  - `corepack yarn fix:api:snapshot:nonphp`
+  - `corepack yarn fix:type:contracts`
+  - `corepack yarn check`
+- Key learnings:
+  - Higher-order APIs need parity-safe examples or translator support; `reduce` is a good case where a tiny callback bridge is cleaner than contorting the docs.
+  - For shipped backlog items, the upstream-surface inventory needs the corresponding `wanted` decision removed immediately or CI will correctly flag stale policy drift.

docs/upstream-surface-inventory.yml

@@ -1487,10 +1487,6 @@ python:
       default:
         decision: skip_runtime_model
         note: Most functools exports are decorators, wrappers, or callable factories rather than plain values.
-      decisions:
-        reduce:
-          decision: wanted
-          note: Left-folding over plain iterables is a strong portability target.
     itertools:
       title: itertools module
       default:

src/python/_helpers/_functools.ts

@@ -0,0 +1,48 @@
+export const noInitializer = Symbol('noInitializer')
+
+export function pythonReduce(
+  func: (accumulator: unknown, value: unknown) => unknown,
+  iterable: unknown,
+  initializer: unknown = noInitializer,
+): unknown {
+  const iterator = toIterator(iterable, 'reduce')
+  let accumulator: unknown
+
+  if (initializer !== noInitializer) {
+    accumulator = initializer
+  } else {
+    const first = iterator.next()
+    if (first.done) {
+      throw new TypeError('reduce() of empty sequence with no initial value')
+    }
+    accumulator = first.value
+  }
+
+  while (true) {
+    const next = iterator.next()
+    if (next.done) {
+      return accumulator
+    }
+
+    accumulator = func(accumulator, next.value)
+  }
+}
+
+function toIterator(iterable: unknown, functionName: string): Iterator<unknown> {
+  if (typeof iterable === 'string') {
+    return iterable[Symbol.iterator]()
+  }
+
+  if ((typeof iterable === 'object' || typeof iterable === 'function') && iterable !== null) {
+    const iterableValue = iterable as {
+      [Symbol.iterator]?: () => Iterator<unknown>
+    }
+    const iteratorFactory = iterableValue[Symbol.iterator]
+
+    if (typeof iteratorFactory === 'function') {
+      return iteratorFactory.call(iterableValue)
+    }
+  }
+
+  throw new TypeError(`${functionName}() expected an iterable`)
+}

src/python/functools/index.ts

@@ -0,0 +1 @@
+export { reduce } from './reduce.ts'

src/python/functools/reduce.ts

@@ -0,0 +1,18 @@
+import { noInitializer, pythonReduce } from '../_helpers/_functools.ts'
+
+export function reduce(
+  func: (accumulator: unknown, value: unknown) => unknown,
+  iterable: unknown,
+  initializer?: unknown,
+): unknown {
+  //      discuss at: https://locutus.io/python/functools/reduce/
+  // parity verified: Python 3.12
+  //     original by: Kevin van Zonneveld (https://kvz.io)
+  //          note 1: Reduces Python iterables to one plain value using a caller-provided combining function.
+  //       example 1: reduce((a, b) => a + b, [1, 2, 3, 4])
+  //       returns 1: 10
+  //       example 2: reduce((a, b) => a + b, 'abc')
+  //       returns 2: 'abc'
+
+  return arguments.length >= 3 ? pythonReduce(func, iterable, initializer) : pythonReduce(func, iterable, noInitializer)
+}

src/python/index.ts

@@ -1,6 +1,7 @@
 export * as bisect from './bisect/index.ts'
 export * as calendar from './calendar/index.ts'
 export * as difflib from './difflib/index.ts'
+export * as functools from './functools/index.ts'
 export * as itertools from './itertools/index.ts'
 export * as math from './math/index.ts'
 export * as operator from './operator/index.ts'

src/rosetta.yml

@@ -353,6 +353,9 @@ sequence_interpose:
 enumerable_reduce_while:
   - elixir/Enum/reduce_while
 
+enumerable_reduce:
+  - python/functools/reduce
+
 enumerable_zip:
   - ruby/Array/zip
   - elixir/Enum/zip

test/generated/python/functools/reduce.vitest.ts

@@ -0,0 +1,64 @@
+// warning: This file is auto generated by `yarn build:tests`
+// Do not edit by hand!
+
+import { createRequire } from 'node:module'
+import { describe, it, expect } from 'vitest'
+
+process.env.TZ = 'UTC'
+const __locutus_source_fn = require('../../../../src/python/functools/reduce.ts').reduce
+const __locutus_source_module_url = new URL("../../../../src/python/functools/reduce.ts", import.meta.url)
+const __locutus_source_require = createRequire(__locutus_source_module_url)
+const __locutus_func_name = "reduce"
+const __locutus_module_js_code = "\"use strict\";\nObject.defineProperty(exports, \"__esModule\", { value: true });\nexports.reduce = reduce;\nconst _functools_ts_1 = require(\"../_helpers/_functools.ts\");\nfunction reduce(func, iterable, initializer) {\n    //      discuss at: https://locutus.io/python/functools/reduce/\n    // parity verified: Python 3.12\n    //     original by: Kevin van Zonneveld (https://kvz.io)\n    //          note 1: Reduces Python iterables to one plain value using a caller-provided combining function.\n    //       example 1: reduce((a, b) => a + b, [1, 2, 3, 4])\n    //       returns 1: 10\n    //       example 2: reduce((a, b) => a + b, 'abc')\n    //       returns 2: 'abc'\n    return arguments.length >= 3 ? (0, _functools_ts_1.pythonReduce)(func, iterable, initializer) : (0, _functools_ts_1.pythonReduce)(func, iterable, _functools_ts_1.noInitializer);\n}"
+const __locutus_standalone_ts_code = "// python/_helpers/_functools (Locutus helper dependency)\nconst noInitializer = Symbol('noInitializer');\nfunction pythonReduce(func, iterable, initializer = noInitializer) {\n    const iterator = toIterator(iterable, 'reduce');\n    let accumulator;\n    if (initializer !== noInitializer) {\n        accumulator = initializer;\n    }\n    else {\n        const first = iterator.next();\n        if (first.done) {\n            throw new TypeError('reduce() of empty sequence with no initial value');\n        }\n        accumulator = first.value;\n    }\n    while (true) {\n        const next = iterator.next();\n        if (next.done) {\n            return accumulator;\n        }\n        accumulator = func(accumulator, next.value);\n    }\n}\nfunction toIterator(iterable, functionName) {\n    if (typeof iterable === 'string') {\n        return iterable[Symbol.iterator]();\n    }\n    if ((typeof iterable === 'object' || typeof iterable === 'function') && iterable !== null) {\n        const iterableValue = iterable;\n        const iteratorFactory = iterableValue[Symbol.iterator];\n        if (typeof iteratorFactory === 'function') {\n            return iteratorFactory.call(iterableValue);\n        }\n    }\n    throw new TypeError(`${functionName}() expected an iterable`);\n}\n// python/functools/reduce (target function module)\nfunction reduce(func, iterable, initializer) {\n    //      discuss at: https://locutus.io/python/functools/reduce/\n    // parity verified: Python 3.12\n    //     original by: Kevin van Zonneveld (https://kvz.io)\n    //          note 1: Reduces Python iterables to one plain value using a caller-provided combining function.\n    //       example 1: reduce((a, b) => a + b, [1, 2, 3, 4])\n    //       returns 1: 10\n    //       example 2: reduce((a, b) => a + b, 'abc')\n    //       returns 2: 'abc'\n    return arguments.length >= 3 ? pythonReduce(func, iterable, initializer) : pythonReduce(func, iterable, noInitializer);\n}"
+const __locutus_standalone_js_code = "// python/_helpers/_functools (Locutus helper dependency)\nconst noInitializer = Symbol('noInitializer');\nfunction pythonReduce(func, iterable, initializer = noInitializer) {\n    const iterator = toIterator(iterable, 'reduce');\n    let accumulator;\n    if (initializer !== noInitializer) {\n        accumulator = initializer;\n    }\n    else {\n        const first = iterator.next();\n        if (first.done) {\n            throw new TypeError('reduce() of empty sequence with no initial value');\n        }\n        accumulator = first.value;\n    }\n    while (true) {\n        const next = iterator.next();\n        if (next.done) {\n            return accumulator;\n        }\n        accumulator = func(accumulator, next.value);\n    }\n}\nfunction toIterator(iterable, functionName) {\n    if (typeof iterable === 'string') {\n        return iterable[Symbol.iterator]();\n    }\n    if ((typeof iterable === 'object' || typeof iterable === 'function') && iterable !== null) {\n        const iterableValue = iterable;\n        const iteratorFactory = iterableValue[Symbol.iterator];\n        if (typeof iteratorFactory === 'function') {\n            return iteratorFactory.call(iterableValue);\n        }\n    }\n    throw new TypeError(`${functionName}() expected an iterable`);\n}\n// python/functools/reduce (target function module)\nfunction reduce(func, iterable, initializer) {\n    //      discuss at: https://locutus.io/python/functools/reduce/\n    // parity verified: Python 3.12\n    //     original by: Kevin van Zonneveld (https://kvz.io)\n    //          note 1: Reduces Python iterables to one plain value using a caller-provided combining function.\n    //       example 1: reduce((a, b) => a + b, [1, 2, 3, 4])\n    //       returns 1: 10\n    //       example 2: reduce((a, b) => a + b, 'abc')\n    //       returns 2: 'abc'\n    return arguments.length >= 3 ? pythonReduce(func, iterable, initializer) : pythonReduce(func, iterable, noInitializer);\n}"
+
+const __locutus_eval_function = (compiledCode: string): ((...args: unknown[]) => unknown) => {
+  const evaluator = new Function('require', compiledCode + '\nreturn ' + __locutus_func_name + ';')
+  return evaluator(__locutus_source_require) as (...args: unknown[]) => unknown
+}
+const __locutus_eval_module_export = (compiledCode: string, exportName: string): ((...args: unknown[]) => unknown) => {
+  const module = { exports: {} as { [key: string]: unknown } }
+  const exports = module.exports
+  const evaluator = new Function('exports', 'module', 'require', compiledCode)
+  evaluator(exports, module, __locutus_source_require)
+  return module.exports[exportName] as (...args: unknown[]) => unknown
+}
+const __locutus_module_js_fn = __locutus_eval_module_export(__locutus_module_js_code, __locutus_func_name)
+const __locutus_standalone_ts_fn = __locutus_eval_function(__locutus_standalone_ts_code)
+const __locutus_standalone_js_fn = __locutus_eval_function(__locutus_standalone_js_code)
+
+describe('src/python/functools/reduce.ts (tested in test/generated/python/functools/reduce.vitest.ts)', function () {
+  it('should pass example 1', function () {
+    const expected = 10
+    const __locutus_variants: Array<{ name: string; fn: (...args: unknown[]) => unknown }> = [
+      { name: "source", fn: __locutus_source_fn },
+      { name: "module-js", fn: __locutus_module_js_fn },
+      { name: "standalone-ts", fn: __locutus_standalone_ts_fn },
+      { name: "standalone-js", fn: __locutus_standalone_js_fn },
+    ]
+    const __locutus_run_example = (reduce: typeof __locutus_source_fn) => {
+      return reduce((a, b) => a + b, [1, 2, 3, 4])
+    }
+    for (const __locutus_variant of __locutus_variants) {
+      const result = __locutus_run_example(__locutus_variant.fn as typeof __locutus_source_fn)
+      expect(result).toEqual(expected)
+    }
+  })
+  it('should pass example 2', function () {
+    const expected = 'abc'
+    const __locutus_variants: Array<{ name: string; fn: (...args: unknown[]) => unknown }> = [
+      { name: "source", fn: __locutus_source_fn },
+      { name: "module-js", fn: __locutus_module_js_fn },
+      { name: "standalone-ts", fn: __locutus_standalone_ts_fn },
+      { name: "standalone-js", fn: __locutus_standalone_js_fn },
+    ]
+    const __locutus_run_example = (reduce: typeof __locutus_source_fn) => {
+      return reduce((a, b) => a + b, 'abc')
+    }
+    for (const __locutus_variant of __locutus_variants) {
+      const result = __locutus_run_example(__locutus_variant.fn as typeof __locutus_source_fn)
+      expect(result).toEqual(expected)
+    }
+  })
+})