docs(hugr-py): docstrings for builder #1231

ss2165 · 2024-06-27T09:15:56Z

first commit just copies in the docs building infrastructure from guppy, the rest add docstrings by file. There are some minor refactor commits towards the end that I couldn't untangle from the docs.

Closes #1214

To build docs:

cd hugr-py
poetry install --with=docs
cd docs
./build.sh
open build/api-docs/index.html

codecov · 2024-06-27T09:19:27Z

Codecov Report

Attention: Patch coverage is 97.30942% with 6 lines in your changes missing coverage. Please review.

Project coverage is 86.98%. Comparing base (f158384) to head (006b94c).
Report is 2 commits behind head on main.

Files	Patch %	Lines
hugr-py/src/hugr/ops.py	93.75%	5 Missing ⚠️
hugr-py/src/hugr/tys.py	96.29%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1231      +/-   ##
==========================================
+ Coverage   86.91%   86.98%   +0.07%     
==========================================
  Files          99      102       +3     
  Lines       19023    19108      +85     
  Branches    17015    17015              
==========================================
+ Hits        16533    16622      +89     
+ Misses       1713     1709       -4     
  Partials      777      777

Flag	Coverage Δ
python	`91.16% <97.30%> (+0.57%)`	⬆️
rust	`86.47% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

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

based on guppylang repository

add namespace in conftest.oy to allow `Dfg` use in HUGR doctests

globals bad turns out!

mostly line too long

non-breaking change! also run poetry update

acl-cqc

Looks good so far but I'll stop partway through. (A lot of .css which I have really not looked at at all....)

hugr-py/src/hugr/cfg.py

acl-cqc · 2024-07-01T10:42:26Z

hugr-py/src/hugr/cfg.py

+    being an :class:`CFG <hugr.ops.CFG>`.
+
+    Args:
+        input_types: The input types for the CFG, outputs are propagated through


To me this suggests that you provide outputs and then they are propagated through (...)

I think you mean something like "outputs are computed from the values supplied to the exit block" (or "will be computed"...)

hugr-py/src/hugr/cfg.py

acl-cqc · 2024-07-01T10:45:39Z

hugr-py/src/hugr/cfg.py

    exit: Node

-    def __init__(self, input_types: TypeRow) -> None:
-        root_op = ops.CFG(inputs=input_types)
+    def __init__(self, *input_types: Type) -> None:


I think this is a breaking change, right? Previously you could have passed in a TypeRow (as a single value, containing multiple types), but now you'd have to do *row

there have been no releases of this so im not counting breaking changes

Co-authored-by: Alan Lawrence <[email protected]>

cqc-alec

Phew, nice work! Mostly very minor things.

hugr-py/src/hugr/conftest.py

hugr-py/src/hugr/function.py

hugr-py/src/hugr/cfg.py

hugr-py/src/hugr/ops.py

hugr-py/docs/api-docs/_templates/autosummary/class.rst

Co-authored-by: Alec Edgington <[email protected]>

🤖 I have created a release *beep* *boop* --- ## [0.3.0](hugr-py-v0.2.1...hugr-py-v0.3.0) (2024-07-03) ### ⚠ BREAKING CHANGES * * `add_child_op`(`_with_parent`), etc., gone; use `add_child_node`(`_with_parent`) with an (impl Into-)OpType. * `get_nodetype` gone - use `get_optype`. * `NodeType` gone - use `OpType` directly. * Various (Into<)Option<ExtensionSet> params removed from builder methods especially {cfg_,dfg_}builder. * `input_extensions` removed from serialization schema. * the Signature class is gone, but it's not clear how or why you might have been using it... * TailLoop node and associated builder functions now require specifying an ExtensionSet; extension/validate.rs deleted; some changes to Hugrs validated/rejected when the `extension_inference` feature flag is turned on * Type::validate takes extra bool (allow_rowvars); renamed {FunctionType, PolyFuncType}::(validate=>validate_var_len). ### Features * Allow "Row Variables" declared as List<Type> ([#804](#804)) ([3ea4834](3ea4834)) * **hugr-py:** add builders for Conditional and TailLoop ([#1210](#1210)) ([43569a4](43569a4)) * **hugr-py:** add CallIndirect, LoadFunction, Lift, Alias ([#1218](#1218)) ([db09193](db09193)), closes [#1213](#1213) * **hugr-py:** add values and constants ([#1203](#1203)) ([f7ea178](f7ea178)), closes [#1202](#1202) * **hugr-py:** automatically add state order edges for inter-graph edges ([#1165](#1165)) ([5da06e1](5da06e1)) * **hugr-py:** builder for function definition/declaration and call ([#1212](#1212)) ([af062ea](af062ea)) * **hugr-py:** builder ops separate from serialised ops ([#1140](#1140)) ([342eda3](342eda3)) * **hugr-py:** CFG builder ([#1192](#1192)) ([c5ea47f](c5ea47f)), closes [#1188](#1188) * **hugr-py:** define type hierarchy separate from serialized ([#1176](#1176)) ([10f4c42](10f4c42)) * **hugr-py:** only require input type annotations when building ([#1199](#1199)) ([2bb079f](2bb079f)) * **hugr-py:** python hugr builder ([#1098](#1098)) ([23408b5](23408b5)) * **hugr-py:** store children in node weight ([#1160](#1160)) ([1cdaeed](1cdaeed)), closes [#1159](#1159) * **hugr-py:** ToNode interface to treat builders as nodes ([#1193](#1193)) ([1da33e6](1da33e6)) * Validate Extensions using hierarchy, ignore input_extensions, RIP inference ([#1142](#1142)) ([8bec8e9](8bec8e9)) ### Bug Fixes * Add some validation for const nodes ([#1222](#1222)) ([c05edd3](c05edd3)) * **hugr-py:** more ruff lints + fix some typos ([#1246](#1246)) ([f158384](f158384)) * **py:** get rid of pydantic config deprecation warnings ([#1084](#1084)) ([52fcb9d](52fcb9d)) ### Documentation * **hugr-py:** add docs link to README ([#1259](#1259)) ([d2a9148](d2a9148)) * **hugr-py:** build and publish docs ([#1253](#1253)) ([902fc14](902fc14)) * **hugr-py:** docstrings for builder ([#1231](#1231)) ([3e4ac18](3e4ac18)) ### Code Refactoring * Remove "Signature" from hugr-py ([#1186](#1186)) ([65718f7](65718f7)) * Remove NodeType and input_extensions ([#1183](#1183)) ([ea5213d](ea5213d)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: hugrbot <[email protected]> Co-authored-by: Seyon Sivarajah <[email protected]>

ss2165 force-pushed the ss/docstrings branch 7 times, most recently from f891beb to 045f885 Compare June 28, 2024 15:31

ss2165 added 20 commits June 28, 2024 16:32

docs: add docs build infrastructure

72b6d3b

based on guppylang repository

docs: enable doctests in pytest

169c1a3

docs: add docstrings to node_port

7ae8adf

docs: for utils.py

49222e8

docs: add tys.py

d62ce5a

docs: add exceptions.py

4e3fb73

ci: add no cover pragmas

c0bafc5

docs: add ops.py

b73e421

docs: add val.py

dc96da1

docs: impl repr for kinds

cafb929

docs: add hugr.py

2b1706c

add namespace in conftest.oy to allow `Dfg` use in HUGR doctests

refator: use standard import pattern in dfg.py

b1e549c

refactor: use *args pattern in Cfg constructor

95c8e8f

refactor: remove singleton ops

dcdace5

globals bad turns out!

refactor: don't include empty rows in ops repr

4283bd0

[REVERTME] turn off source to speed up docs builds

a3286a0

docs: get rid of some sphinx warnings

b0cc8f1

refactor: separate inputs to insert_tail_loop

772e89c

refactor: couple of nicer reprs in ops

98454df

docs: add dfg.py

88f3459

ss2165 force-pushed the ss/docstrings branch from 045f885 to 88f3459 Compare June 28, 2024 15:35

docs: add cfg.py

3577090

ss2165 added 7 commits July 1, 2024 10:54

Merge branch 'ss/more-ruff' into ss/docstrings

833c0f3

refactor: apply ruff fixes

fa5b9f4

mostly line too long

fix: apply some fixes suggested by ruff+pycodestyle

b7fabeb

exclude annoying things from docstyle

e5f20a6

Merge branch 'main' into ss/docstrings

9a26771

docs: fix some typos

65c9f83

docs: add fullstop to alias desc in schema

fdc8d12

non-breaking change! also run poetry update

acl-cqc reviewed Jul 1, 2024

View reviewed changes

ss2165 and others added 4 commits July 1, 2024 11:54

typo

f7d2ead

Co-authored-by: Alan Lawrence <[email protected]>

docs: reword type propagation

1cb6ec3

docs: remove unused newline

4806552

docs: remove some unnecessary announcements

c3d6986

cqc-alec reviewed Jul 1, 2024

View reviewed changes

hugr-py/docs/api-docs/_templates/autosummary/class.rst Show resolved Hide resolved

ss2165 and others added 7 commits July 1, 2024 17:24

Review proof read edits

36a222e

Co-authored-by: Alec Edgington <[email protected]>

refactor: simplify import lines

4f30040

refactor: enforce bijection in initial bimap

737e738

ise -> ize

a957c98

refactor: remove extension delta from Dfg

621b255

docstring fix

cc62d49

test: add NotBijection test

006b94c

ss2165 requested a review from cqc-alec July 1, 2024 16:35

ss2165 enabled auto-merge July 1, 2024 16:37

cqc-alec approved these changes Jul 2, 2024

View reviewed changes

ss2165 added this pull request to the merge queue Jul 2, 2024

Merged via the queue into main with commit 3e4ac18 Jul 2, 2024
22 checks passed

ss2165 deleted the ss/docstrings branch July 2, 2024 07:52

hugrbot mentioned this pull request Jul 1, 2024

chore(main): release hugr-py 0.3.0 #1092

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(hugr-py): docstrings for builder #1231

docs(hugr-py): docstrings for builder #1231

ss2165 commented Jun 27, 2024 •

edited

Loading

codecov bot commented Jun 27, 2024 •

edited

Loading

acl-cqc left a comment

acl-cqc Jul 1, 2024

acl-cqc Jul 1, 2024

ss2165 Jul 1, 2024

cqc-alec left a comment

docs(hugr-py): docstrings for builder #1231

docs(hugr-py): docstrings for builder #1231

Conversation

ss2165 commented Jun 27, 2024 • edited Loading

codecov bot commented Jun 27, 2024 • edited Loading

Codecov Report

acl-cqc left a comment

Choose a reason for hiding this comment

acl-cqc Jul 1, 2024

Choose a reason for hiding this comment

acl-cqc Jul 1, 2024

Choose a reason for hiding this comment

ss2165 Jul 1, 2024

Choose a reason for hiding this comment

cqc-alec left a comment

Choose a reason for hiding this comment

ss2165 commented Jun 27, 2024 •

edited

Loading

codecov bot commented Jun 27, 2024 •

edited

Loading