Merge branch 'develop'

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Change Log
 
+## [Unreleased]
+
+### Added
+
+- Added a new, more efficient dependency resolver.
+- Added a new `init` command to generate a `pyproject.toml` file in existing projects.
+- Added a new setting `settings.virtualenvs.in-project` to make `poetry` create the project's virtualenv inside the project's directory.
+- Added the `--extras` and `--python` options to `debug:resolve` to help debug dependency resolution.
+- Added a `--src` option to new to create an `src` layout.
+- Added support for specifying the `platform` for dependencies.
+- Added the `--python` option to the `add` command.
+- Added the `--platform` option to the `add` command.
+- Added a `--develop` option to the install command to install path dependencies in development/editable mode.
+- Added a `develop` command to install the current project in development mode.
+
+### Changed
+
+- Improved the `show` command to make it easier to check if packages are properly installed.
+- The `script` command has been deprecated, use `run` instead.
+- The `publish` command no longer build packages by default. Use `--build` to retrieve the previous behavior.
+- Improved support for private repositories.
+- Expanded version constraints now keep the original version's precision.
+- The lock file hash no longer use the project's name and version.
+- The `LICENSE` file, or similar, is now automatically added to the built packages.
+
+### Fixed
+
+- Fixed the dependency resolver selecting incompatible packages.
+- Fixed override of dependency with dependency with extras in `dev-dependencies`.
+
+
 ## [0.9.1] - 2018-05-18
 
 ### Fixed

README.md

@@ -64,20 +64,20 @@ poetry self:update 0.8.0
 ```
 
 
-### Enable tab completion for Bash, Fish, or Zsh
+## Enable tab completion for Bash, Fish, or Zsh
 
 `poetry` supports generating completion scripts for Bash, Fish, and Zsh.
 See `poetry help completions` for full details, but the gist is as simple as using one of the following:
 
 ```bash
 # Bash
-poetry completions bash > /etc/bash_completion.d/pyproject.bash-completion
+poetry completions bash > /etc/bash_completion.d/poetry.bash-completion
 
 # Bash (macOS/Homebrew)
-poetry completions bash > $(brew --prefix)/etc/bash_completion.d/pyproject.bash-completion
+poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-completion
 
 # Fish
-poetry completions fish > ~/.config/fish/completions/pyproject.fish
+poetry completions fish > ~/.config/fish/completions/poetry.fish
 
 # Zsh
 poetry completions zsh > ~/.zfunc/_poetry
@@ -209,6 +209,32 @@ results in :
   - Installing oslo.utils (1.4.0)
 ```
 
+This is possible thanks to the efficient dependency resolver at the heart of Poetry.
+
+Here is a breakdown of what exactly happens here:
+
+`oslo.utils (1.4.0)` depends on:
+
+- `pbr (>=0.6,!=0.7,<1.0)`
+- `Babel (>=1.3)`
+- `six (>=1.9.0)`
+- `iso8601 (>=0.1.9)`
+- `oslo.i18n (>=1.3.0)`
+- `netaddr (>=0.7.12)`
+- `netifaces (>=0.10.4)`
+
+What interests us is `pbr (>=0.6,!=0.7,<1.0)`.
+
+At his point, poetry will choose `pbr==0.11.1` which is the latest version that matches the constraint.
+
+Next it will try to select `oslo.i18n==3.20.0` which is the latest version that matches `oslo.i18n (>=1.3.0)`.
+
+However this version requires `pbr (!=2.1.0,>=2.0.0)` which is incompatible with `pbr==0.11.1`,
+so `poetry` will try to find a version of `oslo.i18n` that satisfies `pbr (>=0.6,!=0.7,<1.0)`.
+
+By analyzing the releases of `oslo.i18n`, it will find `oslo.i18n==2.1.0` which requires `pbr (>=0.11,<2.0)`.
+At this point the rest of the resolution is straightforward since there is no more conflict.
+
 #### Install command
 
 When you specify a package to the `install` command it will add it as a wildcard
@@ -264,6 +290,24 @@ the `--name` option:
 poetry new my-folder --name my-package
 ```
 
+### init
+
+This command will help you create a `pyproject.toml` file interactively
+by prompting you to provide basic information about your package.
+
+It will interactively ask you to fill in the fields, while using some smart defaults.
+
+```bash
+poetry init
+```
+
+#### Options
+
+* `--name`: Name of the package.
+* `--description`: Description of the package.
+* `--author`: Author of the package.
+* `--dependency`: Package to require with a version constraint. Should be in format `foo:1.0.0`.
+* `--dev-dependency`: Development requirements, see `--require`.
 
 ### install
 

docs/docs/basic-usage.md

@@ -65,7 +65,7 @@ It will automatically find a suitable version constraint.
 ### Version constraints
 
 In our example, we are requesting the `pendulum` package with the version constraint `^1.4`.
-This means any version geater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`).
+This means any version greater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`).
 
 Please read [versions](/versions/) for more in-depth information on versions, how versions relate to each other, and on version constraints.
 
@@ -77,7 +77,7 @@ Please read [versions](/versions/) for more in-depth information on versions, ho
     When you specify a dependency in `pyproject.toml`, Poetry first take the name of the package
     that you have requested and searches for it in any repository you have registered using the `repositories` key.
     If you have not registered any extra repositories, or it does not find a package with that name in the
-    repositories you have specified, it falls bask on PyPI.
+    repositories you have specified, it falls back on PyPI.
 
     When Poetry finds the right package, it then attempts to find the best match
     for the version constraint you have specified.
@@ -143,7 +143,7 @@ and update the lock file with the new versions.
 
 !!!note
 
-    Poetry will display a Warning when executing an install command if `pyproject.lock` and `pyproject.toml`
+    Poetry will display a **Warning** when executing an install command if `pyproject.lock` and `pyproject.toml`
     are not synchronized.
 
 
@@ -159,5 +159,5 @@ or create a brand new one for you to always work isolated from your global Pytho
     `poetry` has been installed.
 
     What this means is if you project is Python 2.7 only you should
-    install `poetry` for you global Python 2.7 executable and use
+    install `poetry` for your global Python 2.7 executable and use
     it to manage your project.

docs/docs/cli.md

@@ -54,6 +54,26 @@ the `--name` option:
 poetry new my-folder --name my-package
 ```
 
+## init
+
+This command will help you create a `pyproject.toml` file interactively
+by prompting you to provide basic information about your package.
+
+It will interactively ask you to fill in the fields, while using some smart defaults.
+
+```bash
+poetry init
+```
+
+### Options
+
+* `--name`: Name of the package.
+* `--description`: Description of the package.
+* `--author`: Author of the package.
+* `--dependency`: Package to require with a version constraint. Should be in format `foo:1.0.0`.
+* `--dev-dependency`: Development requirements, see `--require`.
+
+
 ## install
 
 The `install` command reads the `pyproject.toml` file from the current project,
@@ -206,14 +226,16 @@ Note that, at the moment, only pure python wheels are supported.
 
 ## publish
 
-This command builds (if not already built) and publishes the package to the remote repository.
+This command publishes the package, previously built with the [`build`](#build) command, to the remote repository.
 
 It will automatically register the package before uploading if this is the first time it is submitted.
 
 ```bash
 poetry publish
 ```
 
+It can also build the package if you pass it the `--build` option.
+
 ### Options
 
 * `--repository (-r)`: The repository to register the package to (default: `pypi`).
@@ -269,11 +291,7 @@ The `run` command executes the given command inside the project's virtualenv.
 poetry run python -V
 ```
 
-Note that this command has no option.
-
-## script
-
-The `script` executes one of the scripts defined in `pyproject.toml`.
+It can also executes one of the scripts defined in `pyproject.toml`.
 
 So, if you have a script defined like this:
 
@@ -285,7 +303,7 @@ my-script = "my_module:main"
 You can execute it like so:
 
 ```bash
-poetry script my-script
+poetry run my-script
 ```
 
 Note that this command has no option.

docs/docs/faq.md

@@ -0,0 +1,34 @@
+# FAQ
+
+## 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, sometimes, with some specific set 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 downloading 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 not way around it.
+
+!!!note
+
+    Once Poetry has cached the releases' information, the dependency resolution process
+    will be much faster.
+
+## Why are unbound version constraints a bad idea?
+
+A version constraint without an upper bound such as `*` or `>=3.4` will allow updates to any future version of the dependency.
+This includes major versions breaking backward compatibility.
+
+Once a release of your package is published, you cannot tweak its dependencies anymore in case a dependency breaks BC
+- you have to do a new release but the previous one stays broken.
+
+The only good alternative is to 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 should use `~3.4` which allows all versions `<4.0`.
+The `^` operator works very well with libraries following [semantic versioning](https://semver.org).

docs/docs/index.md

@@ -60,9 +60,40 @@ If you want to install prerelease versions, you can use the `--preview` option.
 poetry self:update --preview
 ```
 
-And finally, if you want to install a spcific version you can pass it as an argument
+And finally, if you want to install a specific version you can pass it as an argument
 to `self:update`.
 
 ```bash
 poetry self:update 0.8.0
 ```
+
+
+## Enable tab completion for Bash, Fish, or Zsh
+
+`poetry` supports generating completion scripts for Bash, Fish, and Zsh.
+See `poetry help completions` for full details, but the gist is as simple as using one of the following:
+
+
+```bash
+# Bash
+poetry completions bash > /etc/bash_completion.d/poetry.bash-completion
+
+# Bash (macOS/Homebrew)
+poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-completion
+
+# Fish
+poetry completions fish > ~/.config/fish/completions/poetry.fish
+
+# Zsh
+poetry completions zsh > ~/.zfunc/_poetry
+```
+
+!!! note
+
+    You may need to restart your shell in order for the changes to take effect.
+
+For `zsh`, you must then add the following line in your `~/.zshrc` before `compinit`:
+
+```bash
+fpath+=~/.zfunc
+```

docs/docs/versions.md

@@ -108,6 +108,13 @@ my-package = { path = "../my-package/" }
 my-package = { path = "../my-package/dist/my-package-0.1.0.tar.gz" }
 ```
 
+!!!note
+
+    You can install path dependencies in editable/development mode.
+    Just pass `--develop my-package` (repeatable as much as you want) to
+    the `install` command.
+
+
 ### Python restricted dependencies
 
 You can also specify that a dependency should be installed only for specific Python versions:

docs/mkdocs.yml

@@ -15,6 +15,7 @@ pages:
   - Repositories: repositories.md
   - Versions: versions.md
   - The pyproject.toml file: pyproject.md
+  - FAQ: faq.md
 
 markdown_extensions:
   - codehilite