wirely 0.1.0__tar.gz → 0.1.2__tar.gz

wirely-0.1.2/CHANGELOG.md

@@ -0,0 +1,244 @@
+# Changelog
+
+## 0.1.2 - 2026-10-10
+
+### Breaking changes and migration
+
+#### Optional parameter forwarding
+
+Replace implicit forwarding with `Foo?: parameter_option(Foo)` in node
+arguments.
+
+#### Node instance syntax
+
+Replace parameter parentheses with braces, parameter `=` with `:`, and
+remove the final semicolon. Every node instance needs braces:
+
+| Before | After |
+| --- | --- |
+| `node n: T(P = value);` | `node n: T { P: value }` |
+| `node n: T;` | `node n: T {}` |
+| `node n: T();` | `node n: T {}` |
+
+#### Connector syntax
+
+Use `multi value`, `multi event`, and `multi resource` instead of `list value`,
+`list event`, and `list resource` in input declarations.
+
+Use `default input` and `default output` instead of `implicit input` and
+`implicit output` in connector declarations, connection endpoints, and
+procedure bindings.
+
+#### Library and function names
+
+Update node types and function calls as follows:
+
+| In 0.1.1 | In 0.1.2 |
+| --- | --- |
+| `ExtProg.LaunchOnEvent` | `Process.LaunchOnEvent` |
+| `MQTT.EventEmitter` | `MQTT.EventSender` |
+| `KNX.EventEmitter` | `KNX.EventSender` |
+| `Time.DelayChange` | `Time.DebounceStable` |
+| `Std.Delay` | `Std.DelayOneStep` |
+| `Time.IsBetween` | `Time.IsInDailyInterval` |
+| `Std.OptionUnwrapOrDefault` | `Std.OptionUnwrapOr` |
+
+#### Attribute names
+
+Separate qualified attribute names with `.` instead of `::`.
+
+#### Library settings
+
+String settings are now library enums. For example, replace
+`ActiveState: "Low"` with `ActiveState: GPIO.ActiveState.Low`:
+
+| Node type | Parameter | Enum type |
+| --- | --- | --- |
+| `GPIO.Output` | `ActiveState` | `GPIO.ActiveState` |
+| `GPIO.Output` | `Drive` | `GPIO.Drive` |
+| `GPIO.Output` | `Bias` | `GPIO.Bias` |
+| `Std.DetectEdge` | `EdgeType` | `Std.EdgeType` |
+| `KNX.Connection` | `Protocol` | `KNX.Protocol` |
+| MQTT nodes | `Format` | `MQTT.Format` |
+
+Member names match the former strings.
+
+`TwoN.Connection` requires an absolute `UsernamePasswordFile`. To read a
+file beside the calling source file, use:
+
+```wirely
+UsernamePasswordFile:
+  Path.Join(Path.Parent(Path.SourceFile()), "credentials.txt"),
+```
+
+#### Time values
+
+Replace `TimeOfDay_AddWrap(time, offset)` with
+`TimeOfDay.WrappingAdd(time, duration)`, for example
+`TimeOfDay.WrappingAdd("23:30", "PT1H")`.
+
+`TimeOfDay` strings use two-digit hours and minutes, optionally followed by
+seconds and up to nine fraction digits, such as `"08:00:30.125"`. `"24:00"`
+is the end of the day.
+
+Replace `MonotonicTime.Invalid` with `Option[MonotonicTime]` and `None`.
+`Time.MonotonicTimeReached` takes `value Option[MonotonicTime]`.
+
+#### Stricter checks
+
+- Every input except `multi` inputs needs a source, including resource
+  inputs that nothing uses.
+- Each state and temporary variable needs exactly one producing procedure.
+- `assert` is a keyword; write `r#assert` to use it as an identifier.
+
+### Added
+
+- Write procedure bodies in Wirely, in node types or at the program root.
+  Bodies assign each output once and support `let`, `if`, and expressions:
+
+  ```wirely
+  procedure run
+    depends on Enabled, default input as input
+    produces default output as output
+  {
+    output = if Enabled { input } else { Fallback };
+  }
+  ```
+
+  See [procedure bodies](doc/language.md#procedure-bodies).
+- Declare compile-time constants with `constant Name: Type = expression;`
+  and check conditions with `assert condition, "message";`.
+- Expressions support ordering comparisons, equality for all value types
+  (and for types at compile time), struct field access, and compile-time
+  integer arithmetic. Integer types provide wrapping, saturating, and
+  checked arithmetic and conversions such as `uint8.CheckedFrom(value)`.
+  Options support `IsSome`, `IsNone`, `UnwrapOr(fallback)`,
+  `if let Some(x) = value { ... } else { ... }`, and compile-time
+  `Unwrap()`.
+- Declare `native function` and `native constant function` in libraries.
+  See [native functions](doc/language.md#native-functions).
+- The `std` library provides arithmetic and conversions for `Duration`,
+  `MonotonicTime`, and `TimeOfDay`. See [value types](doc/value-types.md).
+- The `path` library provides `Path.Join`, `Path.Parent`, and
+  `Path.SourceFile`.
+- `wirely run-service --state-directory DIR` serves local control sockets
+  for status, pausing, stepping, and state snapshots; `wirely client` sends
+  these requests. See
+  [local sockets](doc/control-protocol.md#local-sockets).
+- `wirely.compiler.attribute_editing` adds, sets, and removes attributes
+  while preserving source formatting.
+
+## 0.1.1 - 2026-10-04
+
+### Breaking changes and migration
+
+#### Library names
+
+Update node types, named arguments, and connection endpoints as follows.
+Names are case-sensitive.
+
+| In 0.1.0 | In 0.1.1 |
+| --- | --- |
+| `Std.DebugInput` | `Std.DebugValueSource` |
+| `Std.DebugPrinter` | `Std.DebugValuePrinter` |
+| `MQTT.Server` | `MQTT.Connection` |
+| MQTT client input `Server` | `Broker` |
+| `TwoN.Device` node type | `TwoN.Connection` |
+| TwoN connection parameter `Hostname` | `Host` |
+| `Time.TriggerAt` parameter `Type` | `OutputType` |
+| `Time.TriggerAt` parameter `Value` | `OutputValue` |
+| `Time.DelayChange` parameter `Time` | `Duration` |
+| `Std.Delay` parameter `initialValue` | `InitialValue` |
+| `Time.IsBetween` parameters `start`, `end` | `Start`, `End` |
+
+Rename the parameter `type` to `Type` on `Std.Delay`,
+`Std.TwoStageValueForward`, `Std.DebugValuePrinter`, `Std.DebugEventPrinter`,
+`Std.DebugValueSource`, and `Std.DebugEventSource`.
+
+The MQTT input rename applies to `ValueOptionProvider`, `ValueProvider`,
+`EventEmitter`, and `EventReceiver`. For example, change
+`connect broker -> publisher.Server;` to
+`connect broker -> publisher.Broker;`.
+
+#### Resource connectors
+
+Replace integration-specific connector kinds in custom node declarations:
+
+| In 0.1.0 | In 0.1.1 |
+| --- | --- |
+| `knx_bus` | `resource KNX.Bus` |
+| `mqtt_server` | `resource MQTT.Broker` |
+| `two_n_device` | `resource TwoN.Device` |
+
+Custom libraries can declare their own opaque resources with
+`resource type Name;`. See [resource connectors](doc/language.md#opaque-resource-connectors).
+
+#### Runtime types
+
+`String` and `List[T]` are now enforced as parameter-only types, including
+options containing them.
+
+#### Procedure bindings and state dependencies
+
+Add `as "key"` aliases to implicit connectors and complex references in
+`depends on` and `produces`. Simple identifiers use their own names.
+Procedures that read previous state must declare that dependency explicitly;
+state changes only rerun procedures that depend on them. For example:
+
+```wirely
+native procedure run
+  depends on implicit input as "input", last_value.old as "previous"
+  produces implicit output as "output", last_value as "next";
+```
+
+See [state and execution](doc/language.md#state-and-execution).
+
+#### String escapes
+
+Quoted strings use Rust-style escapes. Replace Python-style Unicode escapes
+such as `\u0041` or `\U0001F600` with `\u{41}` or `\u{1F600}`. Use raw
+strings such as `r"C:\logs\wirely"` to preserve literal backslashes.
+
+### Added
+
+- Integer literals accept unary `+` and `-`, including hexadecimal and
+  octal literals, such as `-42`, `-0x2a`, and `-0o52`.
+- Use `()` for unit values and `Some(value)` for present optional values;
+  `None` represents absence.
+- Declare named enum types with explicit integer representations and member
+  values, and use qualified literals such as `Mode.Heat`:
+
+  ```wirely
+  enum type Mode: uint8 {
+    Off = 0,
+    Heat = 1,
+  }
+  ```
+
+- Declare named struct types and construct values by field name:
+
+  ```wirely
+  struct type Reading {
+    temperature: int16,
+    valid: boolean,
+  }
+  node reading: Std.Constant(
+    Type = Reading,
+    Value = Reading { valid: true, temperature: 215 }
+  );
+  ```
+
+  See [types and literals](doc/language.md#parameters-types-and-literals).
+- Connect previous-step state directly with
+  `connect last_value.old -> target;`. Use `last_value.new` in connections
+  or procedure dependencies to read this step's value after its writer.
+  `.old` reads the initial value on the first step.
+- Attach compiler attributes with `#[...]` and `#![...]`. Set node
+  coordinates with `#[position(x = 120, y = -40.5)]` before a node
+  declaration. See [attributes](doc/language.md#attributes).
+
+## 0.1.0
+
+Initial release: typed node graphs, value and event connections, stateful
+execution, composite and native nodes, and bundled KNX, MQTT, GPIO, 2N,
+time, memory, CSV, and external-command libraries.

{wirely-0.1.0 → wirely-0.1.2}/MANIFEST.in

@@ -1,10 +1,12 @@
+include CHANGELOG.md
 recursive-include doc *.md
 recursive-include examples *.wrl
 recursive-include test *.py *.wrl
-include test/username_password.txt
+include test/wrl/username_password.txt
 include tools/build-pex
 include tools/git_write_wd_tree.py
 include tools/run-tests
+include tools/run-tests-dependencies
 include tools/setup-venv
 include tools/test-gitlab-ci
 include tools/wirely

{wirely-0.1.0/wirely.egg-info → wirely-0.1.2}/PKG-INFO

@@ -1,33 +1,37 @@
 Metadata-Version: 2.4
 Name: wirely
-Version: 0.1.0
+Version: 0.1.2
 Summary: Node-based language and runtime for low-level home automation
 Author: Steffen Kieß
 License: MIT
+Project-URL: Repository, https://github.com/steffen-kiess/wirely
+Project-URL: Issues, https://github.com/steffen-kiess/wirely/issues
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: lark
-Requires-Dist: sdnotify
+Requires-Dist: lark>=1.1.5
+Requires-Dist: sdnotify>=0.3.0
+Requires-Dist: cbor2>=5.4.5
 Provides-Extra: knx
 Requires-Dist: xknx<4,>=3.0; extra == "knx"
 Provides-Extra: mqtt
 Requires-Dist: aiomqtt<3,>=2.3; extra == "mqtt"
 Provides-Extra: two-n
 Requires-Dist: aiohttp<4,>=3.12; extra == "two-n"
-Requires-Dist: cryptography; extra == "two-n"
+Requires-Dist: cryptography>=38.0.0; extra == "two-n"
 Provides-Extra: graphviz
-Requires-Dist: graphviz; extra == "graphviz"
+Requires-Dist: graphviz>=0.20.1; extra == "graphviz"
 Provides-Extra: gpio
 Requires-Dist: gpiod<3,>=2.1; extra == "gpio"
 Provides-Extra: all
 Requires-Dist: wirely[gpio,graphviz,knx,mqtt,two-n]; extra == "all"
 Provides-Extra: test
-Requires-Dist: pyOpenSSL; extra == "test"
+Requires-Dist: pyOpenSSL>=23.0.0; extra == "test"
 Provides-Extra: pex
 Requires-Dist: pex; extra == "pex"
 Provides-Extra: dev
 Requires-Dist: wirely[pex,test]; extra == "dev"
+Requires-Dist: uv; extra == "dev"
 Dynamic: license-file
 
 Wirely
@@ -42,7 +46,8 @@ these signals; it does not model higher-level concepts such as rooms,
 as Home Assistant does.
 
 See the [language documentation](doc/language.md) for how to write Wirely
-programs.
+programs and the [changelog](CHANGELOG.md) for release notes and migration
+steps.
 
 Installation
 ------------
@@ -62,6 +67,9 @@ wirely compile program.wrl
 python3 -m wirely compile program.wrl
 ```
 
+Use `wirely compile --dump-program program.wrl` to print the compiled
+runtime program, including its variables, configuration, and procedures.
+
 Install optional integrations as needed:
 
 ```
@@ -84,7 +92,7 @@ checkout launchers:
 
 ```
 tools/setup-venv
-tools/wirely compile test/simple.wrl
+tools/wirely compile test/wrl/simple.wrl
 tools/run-tests
 ```
 
@@ -92,3 +100,41 @@ The launchers use `venv/bin/python` when available. Otherwise, they warn and
 use the current Python interpreter. `tools/wirely` accepts the same arguments
 as `wirely` and runs the source in this checkout from any working directory.
 The test suite also requires `knxd` and `mosquitto`.
+
+Pass test names to run a selection, and add `--timings` to list durations
+slowest first:
+
+```
+tools/run-tests --timings unit/types unit/equality
+```
+
+To check that compilation does not depend on declaration order, set
+`WIRELY_COMPILER_SHUFFLE_SEED` to an integer. The compiler then shuffles
+declarations, node parameters, struct literal fields, and procedure
+bindings with that seed; connections keep their relative order. Also set
+`WIRELY_COMPILER_SHUFFLE_LAYOUT=1` to shuffle struct fields and enum
+members, which changes serialization and enum default values. Negative
+tests may report different diagnostics in this mode.
+
+```
+WIRELY_COMPILER_SHUFFLE_SEED=1 tools/run-tests
+```
+
+Test dependency and Python versions in temporary environments:
+
+```
+tools/run-tests-dependencies --versions min --python min
+tools/run-tests-dependencies --versions max --python max
+tools/run-tests-dependencies --versions all-min --python 3.11
+```
+
+`--versions` defaults to `min`: minimum direct dependencies, with latest
+compatible transitive dependencies. `all-min` also minimizes transitive
+dependencies; `max` selects the newest compatible dependency set.
+
+`--python` accepts a uv version request or an executable name/path and
+defaults to the interpreter running the script. `min` selects the latest
+compatible patch of the oldest supported CPython minor; `max` selects the
+newest compatible stable CPython available through the installed uv.
+uv can download missing interpreters. `tools/run-tests --python PATH` runs
+tests using a specified Python executable.

{wirely-0.1.0 → wirely-0.1.2}/README.md

@@ -10,7 +10,8 @@ these signals; it does not model higher-level concepts such as rooms,
 as Home Assistant does.
 
 See the [language documentation](doc/language.md) for how to write Wirely
-programs.
+programs and the [changelog](CHANGELOG.md) for release notes and migration
+steps.
 
 Installation
 ------------
@@ -30,6 +31,9 @@ wirely compile program.wrl
 python3 -m wirely compile program.wrl
 ```
 
+Use `wirely compile --dump-program program.wrl` to print the compiled
+runtime program, including its variables, configuration, and procedures.
+
 Install optional integrations as needed:
 
 ```
@@ -52,7 +56,7 @@ checkout launchers:
 
 ```
 tools/setup-venv
-tools/wirely compile test/simple.wrl
+tools/wirely compile test/wrl/simple.wrl
 tools/run-tests
 ```
 
@@ -60,3 +64,41 @@ The launchers use `venv/bin/python` when available. Otherwise, they warn and
 use the current Python interpreter. `tools/wirely` accepts the same arguments
 as `wirely` and runs the source in this checkout from any working directory.
 The test suite also requires `knxd` and `mosquitto`.
+
+Pass test names to run a selection, and add `--timings` to list durations
+slowest first:
+
+```
+tools/run-tests --timings unit/types unit/equality
+```
+
+To check that compilation does not depend on declaration order, set
+`WIRELY_COMPILER_SHUFFLE_SEED` to an integer. The compiler then shuffles
+declarations, node parameters, struct literal fields, and procedure
+bindings with that seed; connections keep their relative order. Also set
+`WIRELY_COMPILER_SHUFFLE_LAYOUT=1` to shuffle struct fields and enum
+members, which changes serialization and enum default values. Negative
+tests may report different diagnostics in this mode.
+
+```
+WIRELY_COMPILER_SHUFFLE_SEED=1 tools/run-tests
+```
+
+Test dependency and Python versions in temporary environments:
+
+```
+tools/run-tests-dependencies --versions min --python min
+tools/run-tests-dependencies --versions max --python max
+tools/run-tests-dependencies --versions all-min --python 3.11
+```
+
+`--versions` defaults to `min`: minimum direct dependencies, with latest
+compatible transitive dependencies. `all-min` also minimizes transitive
+dependencies; `max` selects the newest compatible dependency set.
+
+`--python` accepts a uv version request or an executable name/path and
+defaults to the interpreter running the script. `min` selects the latest
+compatible patch of the oldest supported CPython minor; `max` selects the
+newest compatible stable CPython available through the installed uv.
+uv can download missing interpreters. `tools/run-tests --python PATH` runs
+tests using a specified Python executable.

wirely-0.1.2/doc/README.md

@@ -0,0 +1,17 @@
+# Wirely documentation
+
+Wirely programs are graphs of typed nodes written in `.wrl` files. Start with
+the [language guide](language.md) to learn how to declare nodes and connect
+them. Then use the [library reference](libraries.md) to find the nodes supplied
+with Wirely. The [value type reference](value-types.md) describes the types
+used by parameters, connectors, and state.
+
+The [binary program format proposal](bytecode-format.md) describes program
+tables, value encodings, and optional debugging information.
+
+For `.wrl` formatting and naming, follow the
+[Wirely style guide](wirely-style.md).
+
+To implement nodes and procedures in Python, use the
+[native Python implementation guide](native-python.md). For Python
+contributions, follow the [Python style guide](python-style.md).