feat!: Visibility annotations on Guppy functions

[maximilianruesch]

Allows adding visibilities to Guppy function with a keyword in the decorator, with non-given visibilities auto-inferred from the convention of whether there is a leading _ in the function name. E.g. (see test cases for more info):

@guppy(public=True)
def public_func() -> None:
    pass
@guppy(public=False)
def private_func() -> None:
    pass
@guppy
def inferred_public_func() -> None:
    pass
@guppy
def _inferred_private_func() -> None:
    pass

assert _visibility(public_func) == "Public"
assert _visibility(private_func) == "Private"
assert _visibility(public_func) == "Public"
assert _visibility(_private_func) == "Private"

This is provided for both definitions and declarations, and annotated visibilities are lowered to the corresponding HUGR function nodes.

Requires an update of hugr-py to include Quantinuum/hugr#2862.

Important

This changes the default visibility of function definitions without leading underscores to "Public", which is technically a breaking change, since now function names can clash. This is a problem as all functions defined at the file top level are considered global. Thus, defining both mod_a.f and mod_b.f clashes in name, since both functions claim the name "f" (see the failing tests for more info).

Closes #1482

BREAKING CHANGE:
Added required visibility parameters to functions in the compiler internals. No migration is required.

[hugrbot]

This PR contains breaking changes to the public Python API.

Breaking changes summary

guppylang-internals/src/guppylang_internals/nodes.py:658: NestedFunctionDef.__init__(visibility):
Parameter was added as required

guppylang-internals/src/guppylang_internals/nodes.py:686: CheckedNestedFunctionDef.__init__(captured):
Positional parameter was moved
Details: position: from 4 to 5 (+1)

guppylang-internals/src/guppylang_internals/nodes.py:686: CheckedNestedFunctionDef.__init__(visibility):
Parameter was added as required

guppylang-internals/src/guppylang_internals/definition/function.py:0: ParsedFunctionDef.__init__(docstring):
Positional parameter was moved
Details: position: from 5 to 6 (+1)

guppylang-internals/src/guppylang_internals/definition/function.py:0: ParsedFunctionDef.__init__(visibility):
Parameter was added as required

guppylang-internals/src/guppylang_internals/definition/function.py:0: ParsedFunctionDef.__init__(hugr_name):
Parameter was added as required

guppylang-internals/src/guppylang_internals/definition/function.py:0: CheckedFunctionDef.__init__(docstring):
Positional parameter was moved
Details: position: from 5 to 6 (+1)

guppylang-internals/src/guppylang_internals/definition/function.py:0: CheckedFunctionDef.__init__(cfg):
Positional parameter was moved
Details: position: from 6 to 8 (+2)

guppylang-internals/src/guppylang_internals/definition/function.py:0: CheckedFunctionDef.__init__(visibility):
Parameter was added as required

guppylang-internals/src/guppylang_internals/definition/function.py:0: CheckedFunctionDef.__init__(hugr_name):
Parameter was added as required

guppylang-internals/src/guppylang_internals/definition/function.py:0: CompiledFunctionDef.__init__(docstring):
Positional parameter was moved
Details: position: from 6 to 7 (+1)

guppylang-internals/src/guppylang_internals/definition/function.py:0: CompiledFunctionDef.__init__(cfg):
Positional parameter was moved
Details: position: from 7 to 9 (+2)

guppylang-internals/src/guppylang_internals/definition/function.py:0: CompiledFunctionDef.__init__(func_def):
Positional parameter was moved
Details: position: from 8 to 10 (+2)

guppylang-internals/src/guppylang_internals/definition/function.py:0: CompiledFunctionDef.__init__(visibility):
Parameter was added as required

guppylang-internals/src/guppylang_internals/definition/function.py:0: CompiledFunctionDef.__init__(hugr_name):
Parameter was added as required

guppylang-internals/src/guppylang_internals/definition/declaration.py:0: CheckedFunctionDecl.__init__(visibility):
Parameter was added as required

guppylang-internals/src/guppylang_internals/definition/declaration.py:0: CompiledFunctionDecl.__init__(visibility):
Parameter was added as required

[github-actions]

Bencher Report

Branch	mr/feat/visibility-annotation
Testbed	Linux

Click to view all benchmark results

Benchmark	Latency	Benchmark Result microseconds (µs) (Result Δ%)	Upper Boundary microseconds (µs) (Limit %)
tests/benchmarks/test_big_array.py::test_big_array_check	📈 view plot 🚷 view threshold	701,172.94 µs (-9.90%) Baseline: 778,252.62 µs	817,165.25 µs (85.81%)
tests/benchmarks/test_big_array.py::test_big_array_compile	📈 view plot 🚷 view threshold	1,886,520.90 µs (-0.17%) Baseline: 1,889,676.28 µs	1,984,160.09 µs (95.08%)
tests/benchmarks/test_big_array.py::test_big_array_executable	📈 view plot 🚷 view threshold	7,686,320.51 µs (+2.22%) Baseline: 7,519,587.60 µs	7,895,566.98 µs (97.35%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_check	📈 view plot 🚷 view threshold	54,868.23 µs (+0.85%) Baseline: 54,407.89 µs	57,128.28 µs (96.04%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_compile	📈 view plot 🚷 view threshold	110,343.58 µs (+0.69%) Baseline: 109,583.77 µs	115,062.96 µs (95.90%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_executable	📈 view plot 🚷 view threshold	589,815.87 µs (-0.49%) Baseline: 592,701.35 µs	622,336.41 µs (94.77%)
tests/benchmarks/test_prelude.py::test_import_guppy	📈 view plot 🚷 view threshold	50.31 µs (-0.89%) Baseline: 50.77 µs	53.31 µs (94.39%)

🐰 View full continuous benchmarking report in Bencher

[github-actions]

Bencher Report

Branch	mr/feat/visibility-annotation
Testbed	Linux

Click to view all benchmark results

Benchmark	hugr_bytes	Benchmark Result bytes x 1e3 (Result Δ%)	Upper Boundary bytes x 1e3 (Limit %)	hugr_nodes	Benchmark Result nodes (Result Δ%)	Upper Boundary nodes (Limit %)
tests/benchmarks/test_big_array.py::test_big_array_compile	📈 view plot 🚷 view threshold	141.80 x 1e3 (+0.57%) Baseline: 140.99 x 1e3	142.40 x 1e3 (99.58%)	📈 view plot 🚷 view threshold	6,592.00 (0.00%) Baseline: 6,592.00	6,657.92 (99.01%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_compile	📈 view plot 🚷 view threshold	18.15 x 1e3 (-0.10%) Baseline: 18.17 x 1e3	18.35 x 1e3 (98.91%)	📈 view plot 🚷 view threshold	608.00 (0.00%) Baseline: 608.00	614.08 (99.01%)

🐰 View full continuous benchmarking report in Bencher

[maximilianruesch]

The corresponding issue has been reworked into the auto-collection / export feature, and with #1495 there is a way to mark symbols as public (by including them as a library interface). Thus, I consider this PR stale and work may begin from somewhat of a scratch anyway.