Poetry documentation proofread (#10354)

Author: deronnax

docs/basic-usage.md

@@ -89,7 +89,7 @@ Poetry will not install a Python interpreter for you.
 
 ### Initialising a pre-existing project
 
-Instead of creating a new project, Poetry can be used to 'initialise' a pre-populated
+Instead of creating a new project, Poetry can be used to 'initialize' a pre-populated
 directory. To interactively create a `pyproject.toml` file in directory `pre-existing-project`:
 
 ```bash

docs/building-extension-modules.md

@@ -79,7 +79,7 @@ script = "relative/path/to/build-extension.py"
 ```
 
 {{% note %}}
-The name of the build script is arbitrary. Common practice has been to name it `build.py`, however this is not
+The name of the build script is arbitrary. Common practice has been to name it `build.py`, however, this is not
 mandatory. You **should** consider [using a subdirectory]({{< relref "#can-i-store-the-build-script-in-a-subdirectory" >}})
 if feasible.
 {{% /note %}}
@@ -322,7 +322,7 @@ def build():
     maturin("build", "-r", *cargo_args)
 
     # We won't use the wheel built by maturin directly since
-    # we want Poetry to build it but, we need to retrieve the
+    # we want Poetry to build it, but we need to retrieve the
     # compiled extensions from the maturin wheel.
     wheel = next(iter(wheels_dir.glob("*.whl")))
     with zipfile.ZipFile(wheel.as_posix()) as whl:

docs/cli.md

@@ -213,7 +213,7 @@ If necessary the build process happens in an isolated environment.
 
 {{% note %}}
 When using `--local-version`, the identifier must be [PEP 440](https://peps.python.org/pep-0440/#local-version-identifiers)
-compliant. This is useful for adding build numbers, platform specificities etc. for private packages.
+compliant. This is useful for adding build numbers, platform specificities, etc. for private packages.
 
 `--local-version` is deprecated and will be removed in a future version of Poetry.
 Use `--config-settings local-version=<version>` instead.
@@ -717,7 +717,7 @@ Should match a repository name set by the [`config`](#config) command.
 * `--password (-p)`: The password to access the repository.
 * `--cert`: Certificate authority to access the repository.
 * `--client-cert`: Client certificate to access the repository.
-* `--dist-dir`: Dist directory where built artifact are stored. Default is `dist`.
+* `--dist-dir`: Dist directory where built artifacts are stored. Default is `dist`.
 * `--build`: Build the package before publishing.
 * `--dry-run`: Perform all actions except upload the package.
 * `--skip-existing`: Ignore errors from files already existing in the repository.
@@ -852,7 +852,7 @@ poetry search requests pendulum
 PyPI no longer allows for the search of packages without a browser. Please use https://pypi.org/search
 (via a browser) instead.
 
-For more information please see [warehouse documentation](https://warehouse.pypa.io/api-reference/xml-rpc.html#deprecated-methods)
+For more information, please see [warehouse documentation](https://warehouse.pypa.io/api-reference/xml-rpc.html#deprecated-methods)
 and this [discussion](https://discuss.python.org/t/fastly-interfering-with-pypi-search/73597/6).
 {{% /note %}}
 

docs/configuration.md

@@ -382,7 +382,7 @@ The directory in which Poetry managed Python versions are installed to.
 Do not download entire wheels to extract metadata but use
 [HTTP range requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests)
 to only download the METADATA files of wheels.
-Especially with slow network connections this setting can speed up dependency resolution significantly.
+Especially with slow network connections, this setting can speed up dependency resolution significantly.
 If the cache has already been filled or the server does not support HTTP range requests,
 this setting makes no difference.
 

docs/contributing.md

@@ -23,7 +23,7 @@ your best judgement, and feel free to propose changes to this document in a pull
 ### Reporting bugs
 
 This section guides you through submitting a bug report for Poetry.
-Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find
+Following these guidelines helps maintainers and the community understands your report, reproduces the behavior, and finds
 related reports.
 
 #### Before submitting a bug report
@@ -66,7 +66,7 @@ and under which conditions it normally happens.
 
 Provide more context by answering these questions:
 
-* **Did the problem start happening recently** (e.g. after updating to a new version of Poetry) or was this always a
+* **Did the problem start happening recently** (e.g., after updating to a new version of Poetry) or was this always a
 problem?
 * If the problem started happening recently, **can you reproduce the problem in an older version of Poetry?** What's the
 most recent version in which the problem does not happen?
@@ -144,7 +144,7 @@ Poetry's development toolchain requires Python 3.9 or newer.
 {{% /note %}}
 
 You should first fork the Poetry repository and then clone it locally, so that you can make pull requests against the
-project. If you are new to Git and pull request based development, GitHub provides a
+project. If you are new to Git and pull request-based development, GitHub provides a
 [guide](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) you will find helpful.
 
 Next, you should install Poetry's dependencies, and run the test suite to make sure everything is working as expected:

docs/dependency-specification.md

@@ -41,7 +41,7 @@ to [PEP 508](https://peps.python.org/pep-0508/).
 In many cases, `tool.poetry.dependencies` can be replaced with `project.dependencies`.
 However, there are some cases where you might still need to use `tool.poetry.dependencies`.
 For example, if you want to define additional information that is not required for building
-but only for locking (for example an explicit source), you can enrich dependency
+but only for locking (for example, an explicit source), you can enrich dependency
 information in the `tool.poetry` section.
 
 ```toml
@@ -99,7 +99,7 @@ If you only specify a major, and minor version, then minor- and patch-level chan
 
 ### Wildcard requirements
 
-**Wildcard requirements** allow for the latest (dependency dependent) version where the wildcard is positioned.
+**Wildcard requirements** allow for the latest (dependency-dependent) version where the wildcard is positioned.
 
 `*`, `1.*` and `1.2.*` are examples of wildcard requirements.
 
@@ -133,7 +133,7 @@ You can specify the exact version of a package.
 `1.2.3` is an example of an exact version specification.
 
 This will tell Poetry to install this version and this version only.
-If other dependencies require a different version, the solver will ultimately fail and abort any install or update procedures.
+If other dependencies require a different version, the solver will ultimately fail and abort any installation or update procedures.
 
 Exact versions can also be specified with `==` according to [PEP 440](https://peps.python.org/pep-0440/).
 
@@ -147,7 +147,7 @@ Not supported in `project.dependencies`.
 When using `poetry add` such constraints are automatically converted into an equivalent constraint.
 {{% /warning %}}
 
-**Caret requirements** allow [SemVer](https://semver.org/) compatible updates to a specified version. An update is allowed if the new version number does not modify the left-most non-zero digit in the major, minor, patch grouping. For instance, if we previously ran `poetry add requests@^2.13.0` and wanted to update the library and ran `poetry update requests`, poetry would update us to version `2.14.0` if it was available, but would not update us to `3.0.0`. If instead we had specified the version string as `^0.1.13`, poetry would update to `0.1.14` but not `0.2.0`. `0.0.x` is not considered compatible with any other version.
+**Caret requirements** allow [SemVer](https://semver.org/) compatible updates to a specified version. An update is allowed if the new version number does not modify the left-most non-zero digit in the major, minor, patch grouping. For instance, if we previously ran `poetry add requests@^2.13.0` and wanted to update the library and ran `poetry update requests`, poetry would update us to version `2.14.0` if it was available, but would not update us to `3.0.0`. If instead, we had specified the version string as `^0.1.13`, poetry would update to `0.1.14` but not `0.2.0`. `0.0.x` is not considered compatible with any other version.
 
 Here are some more examples of caret requirements and the versions that would be allowed with them:
 
@@ -281,7 +281,7 @@ Since we haven’t specified any other information,
 Poetry assumes that we intend to use the latest commit on the `main` branch
 to build our project.
 
-You can explicit specify which branch, commit hash or tagged ref should be usd:
+You can explicitly specify which branch, commit hash or tagged ref should be usd:
 
 {{< tabs tabTotal="2" tabID1="git-rev-project" tabID2="git-rev-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}
 
@@ -346,7 +346,7 @@ The corresponding `add` call looks like this:
 poetry add "git+https://github.com/myorg/mypackage_with_subdirs.git#subdirectory=subdir"
 ```
 
-To use an SSH connection, for example in the case of private repositories, use the following example syntax:
+To use an SSH connection, for example, in the case of private repositories, use the following example syntax:
 
 {{< tabs tabTotal="2" tabID1="git-ssh-project" tabID2="git-ssh-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}
 
@@ -424,7 +424,7 @@ my-package = { path = "../my-package/", develop = true }
 my-package = { path = "../my-package/dist/my-package-0.1.0.tar.gz" }
 ```
 
-To install directory path dependencies in editable mode use the `develop` keyword and set it to `true`.
+To install directory path dependencies in editable mode, use the `develop` keyword and set it to `true`.
 {{< /tab >}}
 {{< /tabs >}}
 
@@ -679,11 +679,11 @@ priority = "explicit"
 
 ## Multiple constraints dependencies
 
-Sometimes, one of your dependency may have different version ranges depending
+Sometimes, one of your dependencies may have different version ranges depending
 on the target Python versions.
 
 Let's say you have a dependency on the package `foo` which is only compatible
-with Python 3.6-3.7 up to version 1.9, and compatible with Python 3.8+ from version 2.0:
+with Python 3.6–3.7 up to version 1.9, and compatible with Python 3.8+ from version 2.0:
 you would declare it like so:
 
 {{< tabs tabTotal="2" tabID1="multiple-constraints-project" tabID2="multiple-constraints-poetry" tabName1="[project]" tabName2="[tool.poetry]">}}
@@ -718,8 +718,8 @@ otherwise it will cause an error when resolving dependencies.
 ### Combining git / url / path dependencies with source repositories
 
 Direct origin (`git`/ `url`/ `path`) dependencies can satisfy the requirement of a dependency that
-doesn't explicitly specify a source, even when mutually exclusive markers are used. For instance
-in the following example the url package will also be a valid solution for the second requirement:
+doesn't explicitly specify a source, even when mutually exclusive markers are used. For instance,
+in the following example, the url package will also be a valid solution for the second requirement:
 ```toml
 foo = [
     { platform = "darwin", url = "https://example.com/example-1.0-py3-none-any.whl" },
@@ -728,7 +728,7 @@ foo = [
 ```
 
 Sometimes you may instead want to use a direct origin dependency for specific conditions
-(i.e. a compiled package that is not available on PyPI for a certain platform/architecture) while
+(i.e., a compiled package that is not available on PyPI for a certain platform/architecture) while
 falling back on source repositories in other cases. In this case you should explicitly ask for your
 dependency to be satisfied by another `source`. For example:
 ```toml
@@ -742,7 +742,7 @@ foo = [
 
 In the case of more complex dependency specifications, you may find that you
 end up with lines which are very long and difficult to read. In these cases,
-you can shift from using "inline table" syntax, to the "standard table" syntax.
+you can shift from using "inline table" syntax to the "standard table" syntax.
 
 An example where this might be useful is the following:
 

docs/faq.md

@@ -14,17 +14,17 @@ menu:
 ### Why is the dependency resolution process slow?
 
 While the dependency resolver at the heart of Poetry is highly optimized and
-should be fast enough for most cases, with certain sets of dependencies
+should be fast enough for most cases, with certain sets of dependencies,
 it can take time to find a valid solution.
 
 This is due to the fact that not all libraries on PyPI have properly declared their metadata
 and, as such, they are not available via the PyPI JSON API. At this point, Poetry has no choice
 but to download the packages and inspect them to get the necessary information. This is an expensive
 operation, both in bandwidth and time, which is why it seems this is a long process.
 
-At the moment there is no way around it. However, if you notice that Poetry
+At the moment, there is no way around it. However, if you notice that Poetry
 is downloading many versions of a single package, you can lessen the workload
-by constraining that one package in your pyproject.toml more narrowly. That way
+by constraining that one package in your pyproject.toml more narrowly. That way,
 Poetry does not have to sift through so many versions of it, which may speed up
 the locking process considerably in some cases.
 
@@ -40,7 +40,7 @@ Poetry uses "major.minor.micro" version identifiers as mentioned in
 
 Version bumps are done similar to Python's versioning:
 * A major version bump (incrementing the first number) is only done for breaking changes
-  if a deprecation cycle is not possible and many users have to perform some manual steps
+  if a deprecation cycle is not possible, and many users have to perform some manual steps
   to migrate from one version to the next one.
 * A minor version bump (incrementing the second number) may include new features as well
   as new deprecations and drop features deprecated in an earlier minor release.
@@ -64,22 +64,22 @@ Once a release of your package is published, you cannot tweak its dependencies a
 – you have to do a new release but the previous one stays broken.
 (Users can still work around the broken dependency by restricting it by themselves.)
 
-To avoid such issues you can define an upper bound on your constraints,
+To avoid such issues, you can define an upper bound on your constraints,
 which you can increase in a new release after testing that your package is compatible
 with the new major version of your dependency.
 
-For example instead of using `>=3.4` you can use `^3.4` which allows all versions `<4.0`.
+For example, instead of using `>=3.4` you can use `^3.4` which allows all versions `<4.0`.
 The `^` operator works very well with libraries following [semantic versioning](https://semver.org).
 
 However, when defining an upper bound, users of your package are not able to update
 a dependency beyond the upper bound even if it does not break anything
 and is fully compatible with your package.
-You have to release a new version of your package with an increased upper bound first.
+You have to release a new version of your package with an increased upper-bound first.
 
-If your package will be used as a library in other packages, it might be better to avoid
+If your package is used as a library in other packages, it might be better to avoid
 upper bounds and thus unnecessary dependency conflicts (unless you already know for sure
 that the next release of the dependency will break your package).
-If your package will be used as an application, it might be worth to define an upper bound.
+If your package is used as an application, it might be worth defining an upper bound.
 
 ### Is tox supported?
 
@@ -125,7 +125,7 @@ commands =
 ```
 
 `tox` will create an `sdist` package of the project and uses `pip` to install it in a fresh environment.
-Thus, dependencies are resolved by `pip` in the first place. But afterward we run Poetry,
+Thus, dependencies are resolved by `pip` in the first place. But afterward, we run Poetry,
  which will install the locked dependencies into the environment.
 
 #### Use case #3
@@ -171,7 +171,7 @@ dependencies specified in `poetry.lock` into [Nox](https://nox.thea.codes/en/sta
 ### I don't want Poetry to manage my virtual environments. Can I disable it?
 
 While Poetry automatically creates virtual environments to always work isolated
-from the global Python installation, there are rare scenarios where the use a Poetry managed
+from the global Python installation, there are rare scenarios where the use of a Poetry managed
 virtual environment is not possible or preferred.
 
 In this case, you can disable this feature by setting the `virtualenvs.create` setting to `false`:
@@ -189,7 +189,7 @@ The Poetry team strongly encourages the use of a virtual environment.
 
 ### Why is Poetry telling me that the current project's supported Python range is not compatible with one or more packages' Python requirements?
 
-Unlike `pip`, Poetry doesn't resolve for just the Python in the current environment. Instead it makes sure that a dependency
+Unlike `pip`, Poetry doesn't resolve for just the Python in the current environment. Instead, it makes sure that a dependency
 is resolvable within the given Python version range in `pyproject.toml`.
 
 Assume you have the following `pyproject.toml`:
@@ -200,15 +200,15 @@ python = "^3.7"
 ```
 
 This means your project aims to be compatible with any Python version >=3.7,<4.0. Whenever you try to add a dependency
-whose Python requirement doesn't match the whole range Poetry will tell you this, e.g.:
+whose Python requirement doesn't match the whole range, Poetry will tell you this, e.g.:
 
 ```
 The current project's supported Python range (>=3.7.0,<4.0.0) is not compatible with some of the required packages Python requirement:
     - scipy requires Python >=3.7,<3.11, so it will not be installable for Python >=3.11,<4.0.0
 ```
 
 Usually you will want to match the supported Python range of your project with the upper bound of the failing dependency.
-Alternatively you can tell Poetry to install this dependency [only for a specific range of Python versions]({{< relref "dependency-specification#multiple-constraints-dependencies" >}}),
+Alternatively, you can tell Poetry to install this dependency [only for a specific range of Python versions]({{< relref "dependency-specification#multiple-constraints-dependencies" >}}),
 if you know that it's not needed in all versions.
 
 If you do not want to set an upper bound in the metadata when building your project,
@@ -228,7 +228,7 @@ python = ">=3.7,<3.11"  # used for locking dependencies
 
 This is done to be compliant with the broader Python ecosystem.
 
-For example, if Poetry builds a distribution for a project that uses a version that is not valid according to
+For example, if Poetry builds a distribution for a project that uses a version that is not valid, according to
 [PEP 440](https://peps.python.org/pep-0440), third party tools will be unable to parse the version correctly.