introduce sync command and deprecate install --sync

[radoering]

Pull Request Check List

As suggested in #9136 (comment). Still not sure about it and how much duplication in the docs would be needed.

Closes #9855

• Added tests for changed code.
• Updated documentation for changed code.

Summary by Sourcery

Introduce the sync command to synchronize the project's environment with the lock file. Deprecate the install --sync option in favor of the new command.

New Features:

• Add a sync command to synchronize the project's environment with the lock file, ensuring that the installed packages match the lock file.

Tests:

• Add tests for the new sync command.

[github-actions]

Deploy preview for website ready!

✅ Preview
https://website-a1uaufsh6-python-poetry.vercel.app

Built with commit 2812a1a.
This pull request is being automatically deployed with vercel-action

[trim21]

is it possible adding this to v1, too?

[radoering]

is it possible adding this to v1, too?

No, I do not think so. We will probably only do another 1.x release if there is a critical issue and we will not include new features in that case.

[abn]

@radoering a point of note here; we have until now avoided or tried to avoid cases where we have 2 ways to do the same thing via the CLI. This definitely breaks that model (we actually might have already broken it). I do not have a strong opinion on this as long as the underlying code is clearly an alias and documented as such. Wanted to note this here and want to make sure this is intentional.

[radoering]

as long as the underlying code is clearly an alias and documented as such.

Agreed.

Wanted to note this here and want to make sure this is intentional.

It stems from the wish of some users that --sync should be the default for install. On the one hand, I agree because I almost always use --sync myself and I think it is a good default for the majority of users. On the other hand, I do not think it works well with virtualenvs.create = false or virtualenvs.options.system-site-packages = true. See #9136 (comment) and the following discussion for details.

I added a note with some additional information to the docs.

[Secrus]

as long as the underlying code is clearly an alias and documented as such.

I have to disagree. If this is to be just an alias, I don't see a reason to make this change. Splitting the behavior makes more sense to me. install just installs the project (and we remove --sync from it) and sync installs and clears the env from everything that is not part of the project. That gives us more flexibility for future features (like #3033) while keeping the "alias" would be forcing us to dance around that and make it more difficult to maintain in the long run.

[abn]

@Secrus I do not disagree. My point, to be clearer is, if we are duplicating functionality I am not (personally) strongly opposed to a clearly documented alias. If we were splitting functionality, that is perfectly fine too, as long as we deprecate/remove the original. Whatever we choose, we just need to be clear on what and why.

On the other hand, I do not think it works well with virtualenvs.create = false or virtualenvs.options.system-site-packages = true.

@radoering If it were up-to me, I would just enforce virtual environments and be done with it. But I am sure some containers-don't-need-venv-footgun-warriors will be up in arms. I am surprised the system-site-packages case is impacted, as we should not be touching those packages at all. But then again, I guess detection is not always the easiest.

As I write this, I am weirdly becoming more opposed to the "sync" as a new command idea. I much rather have poetry install --sync as the default because not doing so is a bigger foot gun for majority of developers. I have had cases where I have myself had a stray package in my venv that allowed tests to pass and the CI failing because it was a transient dependency of another. Baby proofing the virtualenvs.create = false camp seems like a step in the wrong direction. It somehow feels like not doing sync as default for install is breaking the promise of the install install - at least philosophically.

All that said, I am open to see what the consensus between the rest of the maintainers is and go with it.

[Secrus]

LGTM

[radoering]

Just to check if Sourcery had noticed the missing implementation (or if it can extract the info from my comment or somewhere else 😉):

[radoering]

@sourcery-ai review

[sourcery-ai]

Reviewer's Guide by Sourcery

This pull request introduces the sync command and deprecates the install --sync option. The sync command synchronizes the project's environment with the lock file, ensuring that the installed packages match the locked versions. This change also updates the documentation to reflect the new command and the deprecation of the old option.

Sequence diagram: Package synchronization before and after changes

sequenceDiagram
    participant User
    participant Poetry
    participant Environment

    rect rgb(200, 200, 200)
    Note over User,Environment: Before (using install --sync)
    User->>Poetry: poetry install --sync
    Poetry->>Environment: Install packages from lock file
    Poetry->>Environment: Remove untracked packages
    end

    rect rgb(200, 255, 200)
    Note over User,Environment: After (using new sync command)
    User->>Poetry: poetry sync
    Poetry->>Environment: Install packages from lock file
    Poetry->>Environment: Remove untracked packages
    end

Loading

File-Level Changes

Change	Details	Files
Introduce sync command	Created the sync command to synchronize the environment with the lock file. Added documentation for the sync command. Added tests for the sync command. Updated the application to include the sync command.	src/poetry/console/commands/sync.py src/poetry/console/application.py docs/cli.md tests/console/commands/test_sync.py
Deprecate install --sync option	Marked the --sync option as deprecated in the install command. Updated the documentation to reflect the deprecation of install --sync. Added a deprecation warning to the install --sync command. Added tests to verify the deprecation warning.	src/poetry/console/commands/install.py docs/cli.md tests/console/commands/test_install.py
Introduce self sync command	Created the self sync command to synchronize Poetry's runtime environment. Added tests for the self sync command. Updated the application to include the self sync command.	src/poetry/console/commands/self/sync.py src/poetry/console/application.py tests/console/commands/self/test_sync.py
Deprecate self install --sync option	Marked the --sync option as deprecated in the self install command. Added a deprecation warning to the self install --sync command. Added tests to verify the deprecation warning.	src/poetry/console/commands/self/install.py tests/console/commands/self/test_install.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#9855	Make --sync the default behavior for installation	✅
#9855	Introduce a new sync command to replace install --sync	✅
#9855	Deprecate the --sync option on install command	✅

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time. You can also use
  this command to specify where the summary should be inserted.

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @radoering - I've reviewed your changes and they look great!

Here's what I looked at during the review

• 🟡 General issues: 1 issue found
• 🟢 Security: all looks good
• 🟢 Testing: all looks good
• 🟢 Complexity: all looks good
• 🟢 Documentation: all looks good

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

suggestion: Consider moving the deprecation date to a configuration constant

Hardcoded dates in strings make future updates more difficult and error-prone. Consider moving this to a constant or configuration value.

Suggested implementation:

    # Date after which the --sync option will be removed in the next minor release
    SYNC_OPTION_DEPRECATION_DATE = "June 2025"

    def handle(self) -> int:
        from poetry.core.masonry.utils.module import ModuleOrPackageNotFoundError

                " deprecated and slated for removal in the next minor release"
                f" after {self.SYNC_OPTION_DEPRECATION_DATE}, use the"

Note: If there are other parts of the codebase that need to reference this deprecation date, you might want to consider moving the constant to a more central location, such as a constants.py file or a configuration module. The exact location would depend on your project's structure and conventions.