Support an `async` entry point for commands #404

natecook1000 · 2022-02-11T20:11:26Z

Description

Adds an AsyncParsableCommand type that sports an run() async method, allowing for asynchronous code in a command line tool.

Detailed Design

This includes the new AsyncParsableCommand protocol, which provides a static func main() async entry point and can call through to the root command's or a subcommand's asynchronous run() method. For this asynchronous execution, the root command must conform to AsyncParsableCommand, but its subcommands can be a mix of asynchronous and synchronous commands.

/// A type that can be executed as part of a nested tree of commands.
public protocol AsyncParsableCommand: ParsableCommand {
  mutating func run() async throws
}

extension AsyncParsableCommand {
  public static func main() async { ... }
}

Due to an issue in Swift 5.5, you can only use @main on an AsyncParsableCommand root command starting in Swift 5.6. This PR also includes a workaround for clients that are using Swift 5.5. Declare a separate type that conforms to AsyncMainProtocol and add the @main attribute to that type. For example:

@main enum Main: AsyncMain {
    typealias Command = <#command#>
}

AsyncMainProtocol is deprecated for Swift 5.6.

Documentation Plan

There's a new example included (count-lines) that uses AsyncParsableCommand to read lines asynchronously, demonstrating the feature. A new guide for creating asynchronous commands is still TK.

Test Plan

As an entry point, this feature is tested by invoking the built executable via a new test in ArgumentParserExampleTests.

Source Impact

This change requires an upgrade in Swift versions to 5.5, but is otherwise source compatible.

Checklist

I've added at least one test that validates that my change is working, if appropriate
I've followed the code style of the rest of the project
I've read the Contribution Guidelines
I've updated the documentation if necessary

@main

Adds a new `AsyncParsableCommand` protocol, which provides a `static func main() async` entry point and can call through to the root command's or a subcommand's asynchronous `run()` method. For this asynchronous execution, the root command must conform to `AsyncParsableCommand`, but its subcommands can be a mix of asynchronous and synchronous commands. Due to an issue in Swift 5.5, you can only use `@main` on an `AsyncParsableCommand` root command starting in Swift 5.6. This change also includes a workaround for clients that are using Swift 5.5. Declare a separate type that conforms to `AsyncMainProtocol` and add the `@main` attribute to that type. ``` @main enum Main: AsyncMain { typealias Command = <#command#> } ```

natecook1000 · 2022-02-11T20:20:36Z

@swift-ci Please test

natecook1000 · 2022-02-11T20:26:15Z

@swift-ci Please test

jpsim · 2022-02-11T20:38:40Z

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.2


If this PR ends up changing the minimum supported Swift version from 5.2 to 5.5, that will be a breaking change for any consumers who support compiling with Swift < 5.5. Is the intention to ship this as part of a 2.0 release or is breaking Swift version support not considered a semver breaking change?

Good question, @jpsim! The plan is to ship this change as part of the 1.1.0 release. My understanding is that this isn't a source breaking change, since clients using older versions of Swift will just continue to get version 1.0.3. That said, I do have the wrong platform setting below — will update that. Thanks!

Is there a reason why we don't wrap the new stuff in #if swift(>=5.5), and in turn keep support for older Swift versions?

@ffried Not to say that you shouldn't, what are your use cases where you need to support older swift versions like 5.2?

@rauhul I don't have any myself. I was just wondering in case this is considered a breaking change.

Usage of older Swift versions like 5.1/5.2 is higher than you might think (15% of this survey's respondents).

That might be a convincing enough reason to upgrade. IMO we (the community + apple package owners) should come up with some guidelines for version support. I think NIO announced they will support only the latest 2 swift versions. (Though I might be mis-remembering).

@Lukasa what is swift-nio's policy for swift version support and do you consider dropping support for a swift version a breaking change?

We are proposing to support the latest Swift version and the two versions prior. We do not consider dropping Swift versions to be a breaking change, because as @natecook1000 says, SwiftPM takes the tools version into account when resolving what version of a package will be used. Users silently get the last version that supported their Swift version.

SwiftPM takes the tools version into account when resolving what version of a package will be used. Users silently get the last version that supported their Swift version

This is a big surprise to me since it means SwiftPM needs to check out multiple versions of a dependency in order to identify which on is the last to be compatible with the current swift version. Until today I thought SwiftPM just looked at the git tags to determine which version of a dependency to resolve.

If this is the case, then I have no objections to versioning this with 1.1.0.

@rauhul it'd be great if there were guidelines for Swift version support for Swift library authors.

@jpsim This seems like a good conversation to start on the swift forums, I'm 100% certain people have opinions... (for better or worse)

A fun irony here is that we discussed the tools version change, but I missed that this also added a platforms stanza, and while changing the tools version isn't breaking, changing the platforms stanza very much is.

natecook1000 · 2022-02-15T18:20:22Z

@swift-ci Please test

natecook1000 · 2022-02-15T20:50:01Z

@swift-ci Please test

rauhul · 2022-02-16T03:23:36Z

@swift-ci Please test

natecook1000 · 2022-02-18T15:27:05Z

@swift-ci Please test macOS platform

rauhul · 2022-02-22T01:50:28Z

Package.swift

@@ -14,6 +14,7 @@ import PackageDescription

 var package = Package(


@natecook1000 can we take this opportunity to make the indentation 2 spaces?

Oh sure. It should be 4 in code samples and example code and 2 everywhere else.

rauhul · 2022-02-22T01:51:07Z

@swift-ci please test

natecook1000 · 2022-02-23T19:59:10Z

@swift-ci Please test macOS platform

natecook1000 · 2022-03-02T05:31:59Z

@swift-ci Please test macOS platform

Jerry-Carter · 2022-03-05T05:36:31Z

Shifted our test platform to 5.6 for our async version. Wanted to let you know that we've been able to considerably simplify our code around swift-argument-parser. This is looking good, Nate.

natecook1000 · 2022-03-11T16:13:49Z

@swift-ci Please test

Blackjacx · 2022-03-14T00:11:58Z

I refactored my App Store Connect API tool with using the async branch and integrating async/await using the async branch of the argument parser was sooooo satisfying. Good job everyone 👍🏼 hope this makes it in the official release soon. It is soo soo great :)

For the interested of you here are some links: twitter.com/Blackjacxxx/status/1411730725393555456

natecook1000 · 2022-03-14T22:12:34Z

@swift-ci Please test

This fixes the build with CMake after apple#404.

This fixes the build with CMake after #404.

@option

* 'main' of github.com:apple/swift-argument-parser: (114 commits) Fix `AsyncParseableCommand` hierarchy (apple#436) Add experimental manual page generation (apple#332) Improving edit distance string extension (apple#446) List valid options in error messages for enum array argument (apple#445) Remove LinuxMain.swift (apple#367) Hide hidden subcommands from completions (apple#443) Update changelog for 1.1.2 release (apple#441) Fix error message for @option array without values (apple#435) Fix Repeat's endless printing (apple#437) build: statically link ArgumentParserToolInfo always (apple#424) Update changelog for the 1.1.1 release (apple#428) build: complete the changes from apple#423 (apple#425) Remove platform requirement from Package.swift (apple#427) build: repair the build after apple#404 (apple#423) Fix broken links/incorrect variance calculation (apple#422) Update changelog for the 1.1.0 release (apple#421) Update documentation (apple#420) Make `@OptionGroup(visibility:)` a public API (apple#419) Support an `async` entry point for commands (apple#404) Fix a typo and template links (apple#418) ...

natecook1000 force-pushed the async branch from 5c1d30f to eee7edc Compare February 11, 2022 20:19

natecook1000 linked an issue Feb 11, 2022 that may be closed by this pull request

Swift Concurrency support #368

Closed

natecook1000 removed a link to an issue Feb 11, 2022

Swift Concurrency support #368

Closed

natecook1000 linked an issue Feb 11, 2022 that may be closed by this pull request

Add support for async/await where available #326

Closed

natecook1000 mentioned this pull request Feb 11, 2022

Add support for async/await where available #326

Closed

Merge branch 'main' into async

d664ed7

jpsim reviewed Feb 11, 2022

View reviewed changes

natecook1000 mentioned this pull request Feb 14, 2022

Async branch not working with Xcode 13 Beta 5 #345

Closed

natecook1000 added 2 commits February 15, 2022 12:19

Update platforms and simplify example availability

0463e7e

Merge branch 'main' into async

882c922

Simplify availability of examples

610dff8

Merge branch 'main' into async

5ade2c1

Merge branch 'main' into async

723868a

rauhul reviewed Feb 22, 2022

View reviewed changes

Make it easier to see example test output

31e6061

natecook1000 force-pushed the async branch from 503f2a9 to 31e6061 Compare March 2, 2022 05:34

natecook1000 added 2 commits March 11, 2022 10:13

Only run count-lines tests when building on macOS 12

c2e364c

Merge branch 'main' into async

3cad8ef

Blackjacx mentioned this pull request Mar 14, 2022

Implement Async Await Blackjacx/Assist#35

Closed

Merge branch 'main' into async

1830d73

natecook1000 merged commit 1141ed1 into main Mar 14, 2022

natecook1000 deleted the async branch March 14, 2022 23:14

compnerd added a commit to compnerd/swift-argument-parser that referenced this pull request Mar 15, 2022

build: repair the build after apple#404

10cbbdf

This fixes the build with CMake after apple#404.

compnerd mentioned this pull request Mar 15, 2022

build: repair the build after #404 #423

Merged

4 tasks

natecook1000 pushed a commit that referenced this pull request Mar 15, 2022

build: repair the build after #404 (#423)

7dd164a

This fixes the build with CMake after #404.

uhooi mentioned this pull request Jul 2, 2022

Bump Swift Argument Parser from 1.0.1 to 1.1.3 uhooi/swift-output-uhooi#19

Merged

ZachNagengast mentioned this pull request Feb 13, 2024

Refactor SimilarityIndex initialization sync and setupDimension method public ZachNagengast/similarity-search-kit#35

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support an `async` entry point for commands #404

Support an `async` entry point for commands #404

natecook1000 commented Feb 11, 2022 •

edited

natecook1000 commented Feb 11, 2022

natecook1000 commented Feb 11, 2022

jpsim Feb 11, 2022

natecook1000 Feb 11, 2022

ffried Feb 11, 2022

rauhul Feb 12, 2022

ffried Feb 12, 2022

rauhul Feb 15, 2022 •

edited

Lukasa Feb 15, 2022

jpsim Feb 15, 2022

rauhul Feb 15, 2022

Lukasa Mar 16, 2022

natecook1000 commented Feb 15, 2022

natecook1000 commented Feb 15, 2022

rauhul commented Feb 16, 2022

natecook1000 commented Feb 18, 2022

rauhul Feb 22, 2022

natecook1000 Mar 1, 2022

rauhul commented Feb 22, 2022

natecook1000 commented Feb 23, 2022

natecook1000 commented Mar 2, 2022

Jerry-Carter commented Mar 5, 2022

natecook1000 commented Mar 11, 2022

Blackjacx commented Mar 14, 2022

natecook1000 commented Mar 14, 2022

		@@ -14,6 +14,7 @@ import PackageDescription

		var package = Package(

Support an async entry point for commands #404

Support an async entry point for commands #404

Conversation

natecook1000 commented Feb 11, 2022 • edited

Description

Detailed Design

Documentation Plan

Test Plan

Source Impact

Checklist

natecook1000 commented Feb 11, 2022

natecook1000 commented Feb 11, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rauhul Feb 15, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

natecook1000 commented Feb 15, 2022

natecook1000 commented Feb 15, 2022

rauhul commented Feb 16, 2022

natecook1000 commented Feb 18, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rauhul commented Feb 22, 2022

natecook1000 commented Feb 23, 2022

natecook1000 commented Mar 2, 2022

Jerry-Carter commented Mar 5, 2022

natecook1000 commented Mar 11, 2022

Blackjacx commented Mar 14, 2022

natecook1000 commented Mar 14, 2022

Support an `async` entry point for commands #404

Support an `async` entry point for commands #404

natecook1000 commented Feb 11, 2022 •

edited

rauhul Feb 15, 2022 •

edited