feat!: Add enum type by nicolaassolini-qntm · Pull Request #1518 · Quantinuum/guppylang

nicolaassolini-qntm · 2026-02-19T11:59:33Z

This pull request introduces enums in guppy, with all the compilation pipeline required, as well as a refactor to avoid code duplication.

Replaced references to StructField with a new, more general CheckedField type across the codebase, allowing for more flexible handling of both struct fields and enum variants in diagnostics and error messages.
Improved error messages for attribute access, especially for enums, by distinguishing between "field or method" and "variant or method" in the AttributeNotFoundError.
Added support for the instantiation of Enum and the use of Enum methods.
Added test cases for Enum

BREAKING CHANGES: renamed guppylang-internals/src/guppylang_internals/tys/printing.py:_visit_OpaqueType_StructType in visit_OpaqueType_StructType_EnumType

BREAKING CHANGES: removed default value for class_type, field of DuplicateFieldError in guppylang_internals/definition/util.py

BREAKING CHANGE: Moved shared parsing logic for classes (parse_py_class, extract_generic_params, try_parse_generic_base, extract_generic_params, params_from_ast) into a new utility module, definition/util.py, and updated both enum.py, struct.py and function.py to use these utilities.

BREAKING CHANGE: Moved error classes and parsing functions from struct.py and function.py (RepeatedTypeParamError, DuplicateFieldError, RedundantParamsError)

BREAKING CHANGE: Defined UncheckedField and CheckedField instead of UncheckedStructField and StructField

Not a guppylang breaking change

BEGIN_COMMIT_OVERRIDE
feat: Add enum type (#1518)
END_COMMIT_OVERRIDE

…arsing and checking (#1419) * Added a new module `guppylang_internals/definition/enum.py` containing `RawEnumDef`, `ParsedEnumDef`, and `CheckedEnumDef`(WIP) * Added a `guppylang_internals/definition/util.py` module with common function and classes used by `enum.py`, `struct.py` and `function.py` * Improved error diagnostics for unexpected statements in enum and struct definitions by adding contextual help messages BREAKING CHANGE: Refactoring and code organization: * Moved shared parsing logic for classes (`parse_py_class`, `extract_generic_params`, `try_parse_generic_base`, `extract_generic_params`, `params_from_ast`) into a new utility module, `definition/util.py`, and updated both `enum.py`, `struct.py` and `function.py` to use these utilities. * Moved error classes and parsing functions from `struct.py` and `function.py` (`RepeatedTypeParamError`, `DuplicateFieldError`, `RedundantParamsError`) * Defined UncheckedField and CheckedField instead of UncheckedStructField and StructField --------- Co-authored-by: tatiana-s <tatiana.sedelnikov@quantinuum.com> Co-authored-by: Mark Koch <48097969+mark-koch@users.noreply.github.com>

# PR 1: Minimal Enum Infrastructure ## Summary This PR implements the minimal foundation for enum support with recursion checking. **Implements**: Issue #1423 (check_not_recursive for enum) **Related**: Issue #1333 (Enums tracking), Issue #1422 (Future cleanup) ## Changes ### New Files - `guppylang-internals/src/guppylang_internals/definition/enum.py` (~300 lines) - `ParsedEnumDef`, `CheckedEnumDef` classes - `UncheckedEnumVariant`, `EnumVariant` classes - `check_not_recursive()` function ### Modified Files - `guppylang-internals/src/guppylang_internals/tys/ty.py` - Added `EnumType` class (~50 lines) - Updated `ParametrizedType` TypeAlias - Added forward references ### Tests - `tests/error/enum_errors/test_recursive_minimal.py` - Manual test for direct recursion detection ## What This Enables ✅ Basic enum type definitions ✅ Recursion checking (prevents infinite loops) ✅ Type system integration ✅ Foundation for future enum features ## What's NOT Included (Future PRs) ❌ `@guppy.enum` decorator (PR 3) ❌ Enhanced error messages (PR 2) ❌ Auto-generated constructors (PR 3) ❌ DefId refactoring (PR 4) ## Testing ```bash # Run minimal test python tests/error/enum_errors/test_recursive_minimal.py # Check for syntax errors python -m py_compile guppylang-internals/src/guppylang_internals/definition/enum.py ``` ## Next Steps After this PR: - PR 2 will add better error handling - PR 3 will add the decorator and full API - PR 4 will replace the hacky implementation with DefId approach ``` --------- Co-authored-by: nicolaassolini-qntm <nicola.assolini@quantinuum.com> Co-authored-by: tatiana-s <tatiana.sedelnikov@quantinuum.com> Co-authored-by: Mark Koch <48097969+mark-koch@users.noreply.github.com> Co-authored-by: Craig Roy <craig.roy@quantinuum.com> Co-authored-by: Craig Roy <croyzor@users.noreply.github.com>

…n enums and structs, added two error tests (#1470) BREAKING CHANGES removed default value for `class_type`, field of `DuplicateFieldError` in `guppylang_internals/definition/util.py` --------- Co-authored-by: tatiana-s <tatiana.sedelnikov@quantinuum.com>

…AndDrop after rebase

…1505) BREAKING CHANGES: renamed `guppylang-internals/src/guppylang_internals/tys/printing.py:_visit_OpaqueType_StructType` in `visit_OpaqueType_StructType_EnumType` Co-authored-by: tatiana-s <tatiana.sedelnikov@quantinuum.com>

hugrbot · 2026-02-19T12:00:19Z

This PR contains breaking changes to the public Python API.

Breaking changes summary

guppylang-internals/src/guppylang_internals/definition/struct.py:0: UncheckedStructField:
Public object was removed

guppylang-internals/src/guppylang_internals/definition/struct.py:0: StructField:
Public object was removed

guppylang-internals/src/guppylang_internals/definition/struct.py:0: RedundantParamsError:
Public object was removed

guppylang-internals/src/guppylang_internals/definition/struct.py:0: try_parse_generic_base:
Public object was removed

guppylang-internals/src/guppylang_internals/definition/struct.py:0: RepeatedTypeParamError:
Public object was removed

guppylang-internals/src/guppylang_internals/definition/struct.py:0: params_from_ast:
Public object was removed

guppylang-internals/src/guppylang_internals/checker/errors/type_errors.py:130: AttributeNotFoundError.span_label:
Attribute value was changed:
Old: '`{ty}` has no attribute `{attribute}`'
New: '`{ty}` has no {element_name} `{attribute}`'

guppylang-internals/src/guppylang_internals/tys/ty.py:791: ParametrizedType:
Attribute value was changed:
Old: FunctionType | TupleType | OpaqueType | StructType
New: FunctionType | TupleType | OpaqueType | StructType | EnumType

github-actions · 2026-02-19T12:02:08Z

Bencher Report

Branch	feat/guppy-enum
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	694,387.79 µs (-0.93%) Baseline: 700,885.50 µs	735,929.78 µs (94.36%)
tests/benchmarks/test_big_array.py::test_big_array_compile	📈 view plot 🚷 view threshold	1,854,297.87 µs (-0.61%) Baseline: 1,865,766.49 µs	1,959,054.81 µs (94.65%)
tests/benchmarks/test_big_array.py::test_big_array_executable	📈 view plot 🚷 view threshold	8,020,212.00 µs (+0.22%) Baseline: 8,002,520.26 µs	8,402,646.27 µs (95.45%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_check	📈 view plot 🚷 view threshold	49,214.70 µs (-56.76%) Baseline: 113,828.95 µs	119,520.40 µs (41.18%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_compile	📈 view plot 🚷 view threshold	104,295.60 µs (-1.04%) Baseline: 105,388.64 µs	110,658.07 µs (94.25%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_executable	📈 view plot 🚷 view threshold	596,349.55 µs (-1.15%) Baseline: 603,269.57 µs	633,433.05 µs (94.15%)
tests/benchmarks/test_prelude.py::test_import_guppy	📈 view plot 🚷 view threshold	51.81 µs (-3.38%) Baseline: 53.62 µs	56.30 µs (92.01%)

🐰 View full continuous benchmarking report in Bencher

codecov-commenter · 2026-02-19T12:02:39Z

Codecov Report

❌ Patch coverage is 97.75910% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.53%. Comparing base (436d032) to head (b99c771).

Files with missing lines	Patch %	Lines
...ternals/src/guppylang_internals/definition/enum.py	97.26%	4 Missing ⚠️
...ternals/src/guppylang_internals/definition/util.py	97.39%	3 Missing ⚠️
.../guppylang_internals/checker/errors/type_errors.py	90.90%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1518      +/-   ##
==========================================
+ Coverage   93.43%   93.53%   +0.10%     
==========================================
  Files         128      130       +2     
  Lines       12056    12291     +235     
==========================================
+ Hits        11264    11496     +232     
- Misses        792      795       +3

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

github-actions · 2026-02-20T15:59:21Z

Bencher Report

Branch	feat/guppy-enum
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.79 x 1e3 (-0.01%) Baseline: 141.81 x 1e3	143.23 x 1e3 (99.00%)	📈 view plot 🚷 view threshold	6,620.00 (0.00%) Baseline: 6,620.00	6,686.20 (99.01%)
tests/benchmarks/test_ctrl_flow.py::test_many_ctrl_flow_compile	📈 view plot 🚷 view threshold	17.57 x 1e3 (-0.09%) Baseline: 17.59 x 1e3	17.76 x 1e3 (98.93%)	📈 view plot 🚷 view threshold	581.00 (0.00%) Baseline: 581.00	586.81 (99.01%)

🐰 View full continuous benchmarking report in Bencher

)

tatiana-s

Since this has mostly been reviewed already, looks good to me besides a few smaller comments - regarding the PR title, I think something like "feat!: Add enum type" seems better for the release summary as the rest of the current title is a bit redundant

nicolaassolini-qntm and others added 5 commits February 9, 2026 13:59

fix: rename parameter from StructField to CheckedField in FieldAccess…

ca54c87

…AndDrop after rebase

nicolaassolini-qntm marked this pull request as ready for review February 19, 2026 12:26

nicolaassolini-qntm requested review from a team, aborgna-q, croyzor, doug-q, mark-koch and ss2165 as code owners February 19, 2026 12:26

Merge remote-tracking branch 'origin/main' into feat/guppy-enum

94c4d1f

nicolaassolini-qntm force-pushed the feat/guppy-enum branch from 84bd91d to 94c4d1f Compare February 20, 2026 15:56

aborgna-q removed request for aborgna-q, croyzor, doug-q and ss2165 February 20, 2026 15:58

kkoci and others added 2 commits February 23, 2026 14:11

feat: Improve defining enum variants (#1520)

e951a2e

fix: Correctly return GlobalName with location in ExprSynthesizer (#1537

5f1f0dd

)

nicolaassolini-qntm requested a review from tatiana-s March 4, 2026 14:43

tatiana-s approved these changes Mar 17, 2026

View reviewed changes

tatiana-s reviewed Mar 17, 2026

View reviewed changes

Comment thread guppylang-internals/src/guppylang_internals/tys/ty.py Outdated

nicolaassolini-qntm added 3 commits March 17, 2026 17:16

review fixes

b72723a

Merge branch 'main' into feat/guppy-enum

66ef01e

removed a duplicated function after merge with main

b99c771

nicolaassolini-qntm changed the title ~~feat!: added Enum to guppy, including a new type, with parsing, checking and compilation~~ feat!: Add enum type Mar 18, 2026

nicolaassolini-qntm added this pull request to the merge queue Mar 18, 2026

Merged via the queue into main with commit 57c75db Mar 18, 2026
12 checks passed

nicolaassolini-qntm deleted the feat/guppy-enum branch March 18, 2026 10:55

This was referenced Mar 17, 2026

chore: release guppylang-internals 0.31.0 #1519

Merged

chore: release guppylang 0.21.10 #1526

Merged

hugrbot mentioned this pull request Apr 21, 2026

chore: release guppylang 0.21.8 #1686

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat!: Add enum type#1518

feat!: Add enum type#1518
nicolaassolini-qntm merged 11 commits intomainfrom
feat/guppy-enum

nicolaassolini-qntm commented Feb 19, 2026 •

edited by croyzor

Loading

Uh oh!

hugrbot commented Feb 19, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Feb 19, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Feb 19, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Feb 20, 2026 •

edited

Loading

Uh oh!

tatiana-s left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

nicolaassolini-qntm commented Feb 19, 2026 • edited by croyzor Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugrbot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bencher Report

Uh oh!

codecov-commenter commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bencher Report

Uh oh!

tatiana-s left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nicolaassolini-qntm commented Feb 19, 2026 •

edited by croyzor

Loading

hugrbot commented Feb 19, 2026 •

edited

Loading

github-actions Bot commented Feb 19, 2026 •

edited

Loading

codecov-commenter commented Feb 19, 2026 •

edited

Loading

github-actions Bot commented Feb 20, 2026 •

edited

Loading