Skip to content

feat: read deploy config from [tool.posit.connect] in pyproject.toml #974

Closed

Description

@tdstein

Summary

Read deployment config from a [tool.posit.connect] table in pyproject.toml, and keep [tool.rsconnect] working as a legacy name.

deploy pyproject, write-manifest pyproject, and quickstart use [tool.rsconnect] today. Users increasingly deploy through posit-cli (posit connect ...), so a table named after the old CLI doesn't match the tool they run. [tool.posit.connect] names the product being deployed to rather than a particular CLI, and leaves [tool.posit] open for other Posit tools. posit-dev/connect#48550 will recommend this table in the Connect docs, so the name should be settled first.

Where this lives

posit-cli doesn't parse pyproject.toml. Its posit connect group re-registers rsconnect's Click commands unchanged (posit_cli/connect/__init__.py), so posit connect deploy pyproject runs rsconnect/pyproject.py. The change belongs here. As a result, rsconnect deploy pyproject will read [tool.posit.connect] too, so a project works the same with either CLI.

Behavior

  • Accept [tool.posit.connect] with the same fields as [tool.rsconnect]: app_mode, entrypoint, title, requirements_file.
  • [tool.posit.connect] is a nested table. Other keys or sub-tables under [tool.posit] are ignored, and [tool.posit] without a connect sub-table counts as absent. If tool.posit or tool.posit.connect exists but isn't a table, fail with the same not-a-table error used for [tool.rsconnect].
  • Keep reading [tool.rsconnect] when [tool.posit.connect] is absent, and log a deprecation warning (logger.warning, like the --override-python-version deprecation) telling the user to rename the table to [tool.posit.connect].
  • If both tables are present, fail with an RSConnectException naming both tables and telling the user to keep one. Merging the two would hide which values apply. Check this before validating either table's fields.
  • The -r flag still overrides requirements_file in either table.
  • quickstart templates write [tool.posit.connect].
  • Error messages and the minimum-config snippet in rsconnect/pyproject.py name [tool.posit.connect]. When neither table exists, the missing-section error also says [tool.rsconnect] is still accepted.
  • Errors about a table's contents (missing or invalid app_mode/entrypoint, unsupported app_mode) name the table that was actually read. PyprojectDeployTarget records which table that was, so the Unsupported app_mode '…' in [tool.…] messages in main.py don't hardcode [tool.rsconnect].

Files

  • rsconnect/pyproject.py: read_tool_rsconnect, resolve_pyproject_deploy_target, and the error types and snippet.
  • rsconnect/main.py: help text for deploy pyproject, write-manifest pyproject, and quickstart, plus the Unsupported app_mode errors in deploy pyproject and write-manifest pyproject.
  • rsconnect/quickstart/templates/*/pyproject.toml.tmpl, and the template-registry comment in rsconnect/quickstart/quickstart.py
  • docs/deploying.md, docs/CHANGELOG.md
  • Tests: tests/test_deploy_pyproject.py, tests/test_write_manifest_pyproject.py, tests/test_quickstart.py, tests/test_connect_cloud.py

Acceptance criteria

  • deploy pyproject and write-manifest pyproject produce the same result from [tool.posit.connect] as from the same fields in [tool.rsconnect].
  • Projects that only have [tool.rsconnect] keep working, and log a deprecation warning that names [tool.posit.connect] as the replacement.
  • Having both tables fails with a clear error, even when one of them is incomplete.
  • Errors about a table's contents name the table that was read.
  • With neither table, the error shows a [tool.posit.connect] snippet and mentions that [tool.rsconnect] is still accepted.
  • quickstart writes [tool.posit.connect], and the generated project deploys.
  • Docs and the changelog describe the new name and the legacy one.

Follow-up

After this is released, posit-cli should raise its rsconnect-python>=1.33 minimum to the release that includes it, and update its docs to show [tool.posit.connect].

Out of scope

  • The rsconnect quickstart --help hint appended to config errors is wrong for posit-cli users. Track that separately.

Decided

  • The table is [tool.posit.connect]. We considered [tool.posit-cli], which ties the config to one CLI, and a bare [tool.posit], which would claim the whole Posit namespace for Connect deploy settings.
  • [tool.rsconnect] logs a deprecation warning starting with this change. When to remove it can follow the rsconnect-python CLI deprecation (posit-dev/connect#46116).

Activity

  1. changed the title [-]feat: read deploy config from [tool.posit-connect] in pyproject.toml[/-] [+]feat: read deploy config from [tool.posit-cli] in pyproject.toml[/+] on Nov 12, 2026
  2. added
    enhancementNew feature or request
    ready-for-agentFully specified, ready for an autonomous coding agent
    and removed
    needs-triageMaintainer needs to evaluate this issue
    on Nov 12, 2026
  3. tdstein commented on Nov 12, 2026

    @tdstein
    CollaboratorAuthor

    This was generated by AI during triage.

    Agent Brief

    Category: enhancement
    Summary: Read pyproject deployment config from [tool.posit.connect], keeping [tool.rsconnect] as a legacy name.

    Current behavior:
    deploy pyproject and write-manifest pyproject read deployment config only from [tool.rsconnect]. Both commands go through one reader (read_tool_rsconnect, called by resolve_pyproject_deploy_target). A project with only [tool.posit.connect] fails with "The [tool.rsconnect] section is missing" (reproduced with rsconnect write-manifest pyproject). quickstart templates write [tool.rsconnect]. The Unsupported app_mode '…' in [tool.rsconnect] message is hardcoded in the resolver and again in both CLI commands.

    Desired behavior:

    • [tool.posit.connect] accepts the same fields as [tool.rsconnect]: app_mode, entrypoint, title, requirements_file. Both tables resolve to identical deploy targets.
    • [tool.posit.connect] is a nested table: ignore other keys or sub-tables under [tool.posit], and treat [tool.posit] without a connect sub-table as absent. If tool.posit or tool.posit.connect exists but isn't a TOML table, raise InvalidPyprojectConfigError naming the offending key.
    • [tool.rsconnect] is used only when [tool.posit.connect] is absent. When it is used, log a deprecation warning with logger.warning (the same mechanism as the existing --override-python-version deprecation, not Python's warnings.warn) telling the user to rename [tool.rsconnect] to [tool.posit.connect]. Log it once per command run, and only after the table has been read successfully, so an invalid config shows only the error.
    • If both tables exist, fail with an error that names both tables and tells the user to keep one. Check this before validating either table's fields, so the both-tables error wins even if one table is incomplete. Never merge the two tables.
    • The -r flag still overrides requirements_file from whichever table was read.
    • Errors about a table's contents (not a table, missing or empty app_mode/entrypoint, unsupported app_mode) name the table that was actually read.
    • When neither table exists, the missing-section error shows a minimum snippet using [tool.posit.connect] and says [tool.rsconnect] is still accepted.
    • quickstart templates write [tool.posit.connect], and the help text for deploy pyproject, write-manifest pyproject, and quickstart names [tool.posit.connect].
    • docs/deploying.md and the changelog describe [tool.posit.connect], with [tool.rsconnect] as the legacy name.

    Key interfaces:

    • PyprojectDeployTarget records which table it was read from (e.g. the table name), so callers can quote it in errors instead of hardcoding [tool.rsconnect].
    • The pyproject config reader returns the mapping from whichever table applies. Renaming read_tool_rsconnect is fine; update its tests to match.
    • InvalidPyprojectConfigError and UnsupportedAppModeError stay separate types. The CLI appends the quickstart hint only for the former.

    Acceptance criteria:

    • deploy pyproject and write-manifest pyproject produce the same result from [tool.posit.connect] as from the same fields in [tool.rsconnect] (parametrize the existing tests over both table names).
    • Projects with only [tool.rsconnect] keep working and produce the same result, plus a single deprecation warning that names [tool.posit.connect] as the replacement.
    • Projects using [tool.posit.connect] log no deprecation warning.
    • [tool.posit] with other keys but no connect sub-table falls back to [tool.rsconnect] (or the missing-section error); tool.posit = "x" and tool.posit.connect = "x" raise the not-a-table error.
    • Both tables present → error naming [tool.posit.connect] and [tool.rsconnect], including when one of them is incomplete.
    • Unsupported or invalid field errors name the table that was read.
    • Neither table → error shows a [tool.posit.connect] snippet and mentions that [tool.rsconnect] is still accepted.
    • -r overrides requirements_file in either table.
    • quickstart output has [tool.posit.connect] and no [tool.rsconnect], and the generated project passes write-manifest pyproject.
    • just lint and just test pass.

    Out of scope:

    • Removing [tool.rsconnect] support (may follow the rsconnect-python CLI deprecation, posit-dev/connect#46116).
    • Changing the rsconnect quickstart --help hint appended to config errors.
    • Any change to posit-cli itself (raising its minimum version, updating its docs).
    • Reading any other tool tables or adding new config fields.
  4. self-assigned this
    on Nov 12, 2026
  5. changed the title [-]feat: read deploy config from [tool.posit-cli] in pyproject.toml[/-] [+]feat: read deploy config from [tool.posit.connect] in pyproject.toml[/+] on Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or requestready-for-agentFully specified, ready for an autonomous coding agent

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions