diff --git a/.cirrus.yml b/.cirrus.yml new file mode 100644 index 00000000000..98088aa6e02 --- /dev/null +++ b/.cirrus.yml @@ -0,0 +1,44 @@ +freebsd_instance: + image_family: freebsd-12-1-snap + +test_task: + name: "Tests / FreeBSD / " + env: + matrix: + - PYTHON: python2.7 + - PYTHON: python3.5 + - PYTHON: python3.6 + - PYTHON: python3.7 + - PYTHON: python3.8 + python_script: + - PYPACKAGE=$(printf '%s' $PYTHON | tr -d '.') + - SQLPACKAGE=$(printf '%s-sqlite3' $PYPACKAGE | sed 's/thon//') + - pkg install -y git-lite $PYPACKAGE $SQLPACKAGE + pip_script: + - $PYTHON -m ensurepip + - $PYTHON -m pip install -U pip tox poetry + - poetry config virtualenvs.in-project true + tox_script: $PYTHON -m tox -e py -- -q --junitxml=junit.xml tests + on_failure: + annotate_failure_artifacts: + path: junit.xml + format: junit + type: text/xml + +release_task: + name: "Release / FreeBSD" + only_if: $CIRRUS_TAG != '' + freebsd_instance: + matrix: + - image_family: freebsd-12-1-snap + - image_family: freebsd-11-3-snap + python_script: pkg install -y python3 python27 python35 python36 python37 python38 + pip_script: + - python2.7 -m ensurepip + - python3.5 -m ensurepip + - python3.6 -m ensurepip + - python3.7 -m ensurepip + - python3.8 -m ensurepip + build_script: ./make-nix-release.sh + archive_artifacts: + path: "releases/*" diff --git a/.flake8 b/.flake8 new file mode 100644 index 00000000000..5c25c0bb778 --- /dev/null +++ b/.flake8 @@ -0,0 +1,21 @@ +[flake8] +max-line-length = 88 +ignore = E501, E203, W503 +per-file-ignores = __init__.py:F401 +exclude = + .git + __pycache__ + setup.py + build + dist + releases + .venv + .tox + .mypy_cache + .pytest_cache + .vscode + .github + poetry/utils/_compat.py + tests/fixtures/ + tests/repositories/fixtures/ + tests/utils/fixtures/ diff --git a/.github/ISSUE_TEMPLATE/---bug-report.md b/.github/ISSUE_TEMPLATE/---bug-report.md index df8dd248c70..05288e74fef 100644 --- a/.github/ISSUE_TEMPLATE/---bug-report.md +++ b/.github/ISSUE_TEMPLATE/---bug-report.md @@ -2,7 +2,7 @@ name: "\U0001F41E Bug Report" about: Did you find a bug? title: '' -labels: 'Bug' +labels: Bug, Triage assignees: '' --- @@ -16,8 +16,8 @@ assignees: '' --> -- [ ] I am on the [latest](https://github.com/sdispater/poetry/releases/latest) Poetry version. -- [ ] I have searched the [issues](https://github.com/sdispater/poetry/issues) of this repo and believe that this is not a duplicate. +- [ ] I am on the [latest](https://github.com/python-poetry/poetry/releases/latest) Poetry version. +- [ ] I have searched the [issues](https://github.com/python-poetry/poetry/issues) of this repo and believe that this is not a duplicate. - [ ] If an exception occurs when executing a command, I executed it again in debug mode (`-vvv` option). -- [ ] I have searched the [issues](https://github.com/sdispater/poetry/issues) of this repo and believe that this is not a duplicate. +- [ ] I have searched the [issues](https://github.com/python-poetry/poetry/issues) of this repo and believe that this is not a duplicate. ## Issue diff --git a/.github/ISSUE_TEMPLATE/---everything-else.md b/.github/ISSUE_TEMPLATE/---everything-else.md index 7c798fe0052..9f33742156a 100644 --- a/.github/ISSUE_TEMPLATE/---everything-else.md +++ b/.github/ISSUE_TEMPLATE/---everything-else.md @@ -13,8 +13,8 @@ assignees: '' -- [ ] I have searched the [issues](https://github.com/sdispater/poetry/issues) of this repo and believe that this is not a duplicate. -- [ ] I have searched the [documentation](https://poetry.eustace.io/docs/) and believe that my question is not covered. +- [ ] I have searched the [issues](https://github.com/python-poetry/poetry/issues) of this repo and believe that this is not a duplicate. +- [ ] I have searched the [documentation](https://python-poetry.org/docs/) and believe that my question is not covered. ## Issue - \ No newline at end of file + diff --git a/.github/ISSUE_TEMPLATE/---feature-request.md b/.github/ISSUE_TEMPLATE/---feature-request.md index 5959f5e25f3..6a984e925c5 100644 --- a/.github/ISSUE_TEMPLATE/---feature-request.md +++ b/.github/ISSUE_TEMPLATE/---feature-request.md @@ -2,7 +2,7 @@ name: "\U0001F381 Feature Request" about: Do you have ideas for new features and improvements? title: '' -labels: 'Feature' +labels: Feature, Triage assignees: '' --- @@ -16,8 +16,8 @@ assignees: '' --> -- [ ] I have searched the [issues](https://github.com/sdispater/poetry/issues) of this repo and believe that this is not a duplicate. -- [ ] I have searched the [documentation](https://poetry.eustace.io/docs/) and believe that my question is not covered. +- [ ] I have searched the [issues](https://github.com/python-poetry/poetry/issues) of this repo and believe that this is not a duplicate. +- [ ] I have searched the [documentation](https://python-poetry.org/docs/) and believe that my question is not covered. ## Feature Request diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000000..82577fb2a8a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,7 @@ +# Ref: https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser +blank_issues_enabled: true +contact_links: +- name: '💬 Discord Server' + url: https://discordapp.com/invite/awxPgve + about: | + Chat with the community, ask questions and learn about best practices. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index df0e1a01b20..bdba9f27880 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,11 +1,13 @@ # Pull Request Check List -This is just a reminder about the most common mistakes. Please make sure that you tick all *appropriate* boxes. But please read our [contribution guide](https://poetry.eustace.io/docs/contributing/) at least once, it will save you unnecessary review cycles! +Resolves: #issue-number-here + + - [ ] Added **tests** for changed code. - [ ] Updated **documentation** for changed code. -**Note**: If your Pull Request introduces a new feature or changes the current behavior, it should be based -on the `develop` branch. If it's a bug fix or only a documentation update, it should be based on the `master` branch. + -If you have *any* questions to *any* of the points above, just **submit and ask**! This checklist is here to *help* you, not to deter you from contributing! + diff --git a/.github/stale.yml b/.github/stale.yml new file mode 100644 index 00000000000..612d8f63135 --- /dev/null +++ b/.github/stale.yml @@ -0,0 +1,25 @@ +exemptProjects: true +exemptMilestones: true + +staleLabel: stale + +markComment: > + This issue has been automatically marked as stale because it has not had + recent activity. It will be closed if no further activity occurs. Thank you + for your contributions. + +closeComment: > + Closing this issue automatically because it has not had any activity since + it has been marked as stale. If you think it is still relevant and should + be addressed, feel free to open a new one. + +pulls: + markComment: > + This pull request has been automatically marked as stale because it has not had + recent activity. It will be closed if no further activity occurs. Thank you + for your contributions. + + closeComment: > + Closing this pull request automatically because it has not had any activity since + it has been marked as stale. If you think it is still relevant and should + be addressed, feel free to open a new one. diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index f7bcfaaeeea..23fb3c1e204 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -1,4 +1,4 @@ -name: Main +name: Tests on: [push, pull_request] @@ -7,90 +7,64 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 - - name: Set up Python 3.7 + - uses: actions/checkout@v2 + - name: Set up Python 3.8 uses: actions/setup-python@v1 with: - python-version: 3.7 + python-version: 3.8 - name: Linting run: | pip install pre-commit pre-commit run --all-files - Linux: + Tests: needs: Linting - runs-on: ubuntu-latest + name: ${{ matrix.os }} / ${{ matrix.python-version }} + runs-on: ${{ matrix.os }}-latest strategy: matrix: - python-version: [2.7, 3.5, 3.6, 3.7] - + os: [Ubuntu, MacOS, Windows] + python-version: [2.7, 3.5, 3.6, 3.7, 3.8] steps: - - uses: actions/checkout@v1 - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v1 - with: - python-version: ${{ matrix.python-version }} - - name: Install Poetry - run: | - python get-poetry.py --preview -y - source $HOME/.poetry/env - - name: Install dependencies - run: | - source $HOME/.poetry/env - poetry install - - name: Test - run: | - source $HOME/.poetry/env - poetry run pytest -q tests + - uses: actions/checkout@v2 - MacOS: - needs: Linting - runs-on: macos-latest - strategy: - matrix: - python-version: [2.7, 3.5, 3.6, 3.7] + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v1 + with: + python-version: ${{ matrix.python-version }} - steps: - - uses: actions/checkout@v1 - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v1 - with: - python-version: ${{ matrix.python-version }} - - name: Install Poetry - run: | - python get-poetry.py --preview -y - source $HOME/.poetry/env - - name: Install dependencies - run: | - source $HOME/.poetry/env - poetry install - - name: Test - run: | - source $HOME/.poetry/env - poetry run pytest -q tests + - name: Get full Python version + id: full-python-version + shell: bash + run: echo ::set-output name=version::$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))") - Windows: - needs: Linting - runs-on: windows-latest - strategy: - matrix: - python-version: [2.7, 3.5, 3.6, 3.7] + - name: Install poetry + shell: bash + run: | + curl -fsS -o get-poetry.py https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py + python get-poetry.py -y + echo "::set-env name=PATH::$HOME/.poetry/bin:$PATH" - steps: - - uses: actions/checkout@v1 - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v1 - with: - python-version: ${{ matrix.python-version }} - - name: Install Poetry - run: | - python get-poetry.py --preview -y - SET PATH=%USERPROFILE%\\.poetry\\bin;%PATH% - - name: Install dependencies - run: | - SET PATH=%USERPROFILE%\\.poetry\\bin;%PATH% - poetry install - - name: Test - run: | - SET PATH=%USERPROFILE%\\.poetry\\bin;%PATH% - poetry run pytest -q tests + - name: Configure poetry + shell: bash + run: poetry config virtualenvs.in-project true + + - name: Set up cache + uses: actions/cache@v2 + id: cache + with: + path: .venv + key: venv-${{ runner.os }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }} + + - name: Ensure cache is healthy + if: steps.cache.outputs.cache-hit == 'true' + shell: bash + run: poetry run pip --version >/dev/null 2>&1 || rm -rf .venv + + - name: Install dependencies + shell: bash + run: poetry install + + - name: Run pytest + shell: bash + run: poetry run pytest -v tests diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 00000000000..b17802b2ebd --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,257 @@ +name: Release + +on: + push: + tags: + - '*.*.*' + +jobs: + + Linux: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + - name: Get tag + id: tag + run: | + echo ::set-output name=tag::${GITHUB_REF#refs/tags/} + - name: Building release + run: | + make linux_release + - name: Upload release file + uses: actions/upload-artifact@v1 + with: + name: poetry-${{ steps.tag.outputs.tag }}-linux.tar.gz + path: releases/poetry-${{ steps.tag.outputs.tag }}-linux.tar.gz + - name: Upload checksum file + uses: actions/upload-artifact@v1 + with: + name: poetry-${{ steps.tag.outputs.tag }}-linux.sha256sum + path: releases/poetry-${{ steps.tag.outputs.tag }}-linux.sha256sum + + MacOS: + runs-on: macos-latest + + steps: + - uses: actions/checkout@v2 + - name: Get tag + id: tag + run: | + echo ::set-output name=tag::${GITHUB_REF#refs/tags/} + - name: Set up Python 3.8 + uses: actions/setup-python@v1 + with: + python-version: "3.8" + - name: Install Poetry + run: | + python get-poetry.py --preview -y + source $HOME/.poetry/env + - name: Install dependencies + run: | + source $HOME/.poetry/env + poetry install --no-dev + - name: Preparing Python executables + run: | + curl -L https://github.com/sdispater/python-binaries/releases/download/2.7.17/python-2.7.17.macos.tar.xz -o python-2.7.17.tar.xz + curl -L https://github.com/sdispater/python-binaries/releases/download/3.5.9/python-3.5.9.macos.tar.xz -o python-3.5.9.tar.xz + curl -L https://github.com/sdispater/python-binaries/releases/download/3.6.8/python-3.6.8.macos.tar.xz -o python-3.6.8.tar.xz + curl -L https://github.com/sdispater/python-binaries/releases/download/3.7.6/python-3.7.6.macos.tar.xz -o python-3.7.6.tar.xz + curl -L https://github.com/sdispater/python-binaries/releases/download/3.8.2/python-3.8.2.macos.tar.xz -o python-3.8.2.tar.xz + tar -zxf python-2.7.17.tar.xz + tar -zxf python-3.5.9.tar.xz + tar -zxf python-3.6.8.tar.xz + tar -zxf python-3.7.6.tar.xz + tar -zxf python-3.8.2.tar.xz + - name: Build specific release + run: | + source $HOME/.poetry/env + poetry run python sonnet make release --ansi -P "2.7:python-2.7.17/bin/python" -P "3.5:python-3.5.9/bin/python" -P "3.6:python-3.6.8/bin/python" -P "3.7:python-3.7.6/bin/python" -P "3.8:python-3.8.2/bin/python" + - name: Upload release file + uses: actions/upload-artifact@v1 + with: + name: poetry-${{ steps.tag.outputs.tag }}-darwin.tar.gz + path: releases/poetry-${{ steps.tag.outputs.tag }}-darwin.tar.gz + - name: Upload checksum file + uses: actions/upload-artifact@v1 + with: + name: poetry-${{ steps.tag.outputs.tag }}-darwin.sha256sum + path: releases/poetry-${{ steps.tag.outputs.tag }}-darwin.sha256sum + + Windows: + runs-on: windows-latest + + steps: + - uses: actions/checkout@v2 + - name: Get tag + id: tag + shell: bash + run: | + echo ::set-output name=tag::${GITHUB_REF#refs/tags/} + - name: Set up Python 3.8 + uses: actions/setup-python@v1 + with: + python-version: "3.8" + - name: Install Poetry + run: | + python get-poetry.py --preview -y + $env:Path += ";$env:Userprofile\.poetry\bin" + - name: Install dependencies + run: | + $env:Path += ";$env:Userprofile\.poetry\bin" + poetry install --no-dev + - name: Preparing Python executables + run: | + Invoke-WebRequest https://github.com/sdispater/python-binaries/releases/download/2.7.17/python-2.7.17.windows.tar.xz -O python-2.7.17.tar.xz + Invoke-WebRequest https://github.com/sdispater/python-binaries/releases/download/3.5.4/python-3.5.4.windows.tar.xz -O python-3.5.4.tar.xz + Invoke-WebRequest https://github.com/sdispater/python-binaries/releases/download/3.6.8/python-3.6.8.windows.tar.xz -O python-3.6.8.tar.xz + Invoke-WebRequest https://github.com/sdispater/python-binaries/releases/download/3.7.6/python-3.7.6.windows.tar.xz -O python-3.7.6.tar.xz + Invoke-WebRequest https://github.com/sdispater/python-binaries/releases/download/3.8.2/python-3.8.2.windows.tar.xz -O python-3.8.2.tar.xz + 7z x python-2.7.17.tar.xz + 7z x python-3.5.4.tar.xz + 7z x python-3.6.8.tar.xz + 7z x python-3.7.6.tar.xz + 7z x python-3.8.2.tar.xz + 7z x python-2.7.17.tar + 7z x python-3.4.4.tar + 7z x python-3.5.4.tar + 7z x python-3.6.8.tar + 7z x python-3.7.6.tar + 7z x python-3.8.2.tar + - name: Build specific release + run: | + $env:Path += ";$env:Userprofile\.poetry\bin" + poetry run python sonnet make release --ansi -P "2.7:python-2.7.17\python.exe" -P "3.5:python-3.5.4\python.exe" -P "3.6:python-3.6.8\python.exe" -P "3.7:python-3.7.6\python.exe" -P "3.8:python-3.8.2\python.exe" + - name: Upload release file + uses: actions/upload-artifact@v1 + with: + name: poetry-${{ steps.tag.outputs.tag }}-win32.tar.gz + path: releases/poetry-${{ steps.tag.outputs.tag }}-win32.tar.gz + - name: Upload checksum file + uses: actions/upload-artifact@v1 + with: + name: poetry-${{ steps.tag.outputs.tag }}-win32.sha256sum + path: releases/poetry-${{ steps.tag.outputs.tag }}-win32.sha256sum + + Release: + needs: [Linux, MacOS, Windows] + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + - name: Get tag + id: tag + run: | + echo ::set-output name=tag::${GITHUB_REF#refs/tags/} + - name: Download Linux release file + uses: actions/download-artifact@master + with: + name: poetry-${{ steps.tag.outputs.tag }}-linux.tar.gz + path: releases/ + - name: Download Linux checksum file + uses: actions/download-artifact@master + with: + name: poetry-${{ steps.tag.outputs.tag }}-linux.sha256sum + path: releases/ + - name: Download MacOS release file + uses: actions/download-artifact@master + with: + name: poetry-${{ steps.tag.outputs.tag }}-darwin.tar.gz + path: releases/ + - name: Download MacOS checksum file + uses: actions/download-artifact@master + with: + name: poetry-${{ steps.tag.outputs.tag }}-darwin.sha256sum + path: releases/ + - name: Download Windows release file + uses: actions/download-artifact@master + with: + name: poetry-${{ steps.tag.outputs.tag }}-win32.tar.gz + path: releases/ + - name: Download Windows checksum file + uses: actions/download-artifact@master + with: + name: poetry-${{ steps.tag.outputs.tag }}-win32.sha256sum + path: releases/ + - name: Create Release + id: create_release + uses: actions/create-release@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag_name: ${{ steps.tag.outputs.tag }} + release_name: ${{ steps.tag.outputs.tag }} + draft: false + prerelease: false + - name: Upload Linux release file asset + uses: actions/upload-release-asset@v1.0.1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: releases/poetry-${{ steps.tag.outputs.tag }}-linux.tar.gz + asset_name: poetry-${{ steps.tag.outputs.tag }}-linux.tar.gz + asset_content_type: application/gzip + - name: Upload Linux checksum file asset + uses: actions/upload-release-asset@v1.0.1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: releases/poetry-${{ steps.tag.outputs.tag }}-linux.sha256sum + asset_name: poetry-${{ steps.tag.outputs.tag }}-linux.sha256sum + asset_content_type: text/plain + - name: Upload MacOS release file asset + uses: actions/upload-release-asset@v1.0.1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: releases/poetry-${{ steps.tag.outputs.tag }}-darwin.tar.gz + asset_name: poetry-${{ steps.tag.outputs.tag }}-darwin.tar.gz + asset_content_type: application/gzip + - name: Upload MacOS checksum file asset + uses: actions/upload-release-asset@v1.0.1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: releases/poetry-${{ steps.tag.outputs.tag }}-darwin.sha256sum + asset_name: poetry-${{ steps.tag.outputs.tag }}-darwin.sha256sum + asset_content_type: text/plain + - name: Upload Windows release file asset + uses: actions/upload-release-asset@v1.0.1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: releases/poetry-${{ steps.tag.outputs.tag }}-win32.tar.gz + asset_name: poetry-${{ steps.tag.outputs.tag }}-win32.tar.gz + asset_content_type: application/gzip + - name: Upload Windows checksum file asset + uses: actions/upload-release-asset@v1.0.1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ steps.create_release.outputs.upload_url }} + asset_path: releases/poetry-${{ steps.tag.outputs.tag }}-win32.sha256sum + asset_name: poetry-${{ steps.tag.outputs.tag }}-win32.sha256sum + asset_content_type: text/plain + - name: Install Poetry + run: | + python get-poetry.py --preview -y + - name: Install dependencies + run: | + source $HOME/.poetry/env + poetry install --no-dev + - name: Build project for distribution + run: | + source $HOME/.poetry/env + poetry run poetry build + - name: Publish to PyPI + env: + POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }} + run: | + source $HOME/.poetry/env + poetry run poetry publish diff --git a/.gitignore b/.gitignore index 8a80bb89e32..fcbd92e97a3 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,8 @@ # Packages *.egg -*.egg-info +!/tests/**/*.egg +/*.egg-info /dist/* build _build diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b9a75affdb4..79b09408ed4 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,26 @@ repos: -- repo: https://github.com/ambv/black + - repo: https://github.com/psf/black rev: stable hooks: - - id: black - language_version: python3.6 + - id: black + + - repo: https://gitlab.com/pycqa/flake8 + rev: 3.7.8 + hooks: + - id: flake8 + + - repo: https://github.com/timothycrosley/isort + rev: 4.3.21-2 + hooks: + - id: isort + additional_dependencies: [toml] + exclude: ^.*/?setup\.py$ + + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v2.3.0 + hooks: + - id: trailing-whitespace + exclude: ^tests/.*/fixtures/.* + - id: end-of-file-fixer + exclude: ^tests/.*/fixtures/.* + - id: debug-statements diff --git a/CHANGELOG.md b/CHANGELOG.md index fc28d7e1a93..0ab3d8d7e6c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,132 @@ # Change Log -## [Unreleased] +## [1.1.0a1] - 2020-03-27 + +This release **must** be downloaded via the `get-poetry.py` script and not via the `self update` command. + +### Added + +- Added a new `--dry-run` option to the `publish` command ([#2199](https://github.com/python-poetry/poetry/pull/2199)). + +### Changed + +- The core features of Poetry have been extracted in to a separate library: `poetry-core` ([#2212](https://github.com/python-poetry/poetry/pull/2212)). +- The build backend is no longer `poetry.masonry.api` but `poetry.core.masonry.api` which requires `poetry-core>=1.0.0a5` ([#2212](https://github.com/python-poetry/poetry/pull/2212)). +- The exceptions are now beautifully displayed in the terminal with various level of details depending on the verbosity ([2230](https://github.com/python-poetry/poetry/pull/2230)). + + +## [1.0.9] - 2010-06-09 + +### Fixed + +- Fixed an issue where packages from custom indices where continuously updated ([#2525](https://github.com/python-poetry/poetry/pull/2525)). +- Fixed errors in the way Python environment markers were parsed and generated ([#2526](https://github.com/python-poetry/poetry/pull/2526)). + + +## [1.0.8] - 2020-06-05 + +### Fixed + +- Fixed a possible error when installing the root package ([#2505](https://github.com/python-poetry/poetry/pull/2505)). +- Fixed an error where directory and VCS dependencies were not installed ([#2505](https://github.com/python-poetry/poetry/pull/2505)). + + +## [1.0.7] - 2020-06-05 + +### Fixed + +- Fixed an error when trying to execute some packages `setup.py` file ([#2349](https://github.com/python-poetry/poetry/pull/2349)). + + +## [1.0.6] - 2020-06-05 + +### Changed + +- The `self update` command has been updated in order to handle future releases of Poetry ([#2429](https://github.com/python-poetry/poetry/pull/2429)). + +### Fixed + +- Fixed an error were a new line was not written when displaying the virtual environment's path with `env info` ([#2196](https://github.com/python-poetry/poetry/pull/2196)). +- Fixed a misleading error message when the `packages` property was empty ([#2265](https://github.com/python-poetry/poetry/pull/2265)). +- Fixed shell detection by using environment variables ([#2147](https://github.com/python-poetry/poetry/pull/2147)). +- Fixed the removal of VCS dependencies ([#2239](https://github.com/python-poetry/poetry/pull/2239)). +- Fixed generated wheel ABI tags for Python 3.8 ([#2121](https://github.com/python-poetry/poetry/pull/2121)). +- Fixed a regression when building stub-only packages ([#2000](https://github.com/python-poetry/poetry/pull/2000)). +- Fixed errors when parsing PEP-440 constraints with whitespace ([#2347](https://github.com/python-poetry/poetry/pull/2347)). +- Fixed PEP 508 representation of VCS dependencies ([#2349](https://github.com/python-poetry/poetry/pull/2349)). +- Fixed errors when source distributions were read-only ([#1140](https://github.com/python-poetry/poetry/pull/1140)). +- Fixed dependency resolution errors and inconsistencies with directory, file and VCS dependencies ([#2398](https://github.com/python-poetry/poetry/pull/2398)). +- Fixed custom repositories information not being properly locked ([#2484](https://github.com/python-poetry/poetry/pull/2484)). + + +## [1.0.5] - 2020-02-29 + +### Fixed + +- Fixed an error when building distributions if the `git` executable was not found ([#2105](https://github.com/python-poetry/poetry/pull/2105)). +- Fixed various errors when reading Poetry's TOML files by upgrading [tomlkit](https://github.com/sdispater/tomlkit). + + +## [1.0.4] - 2020-02-28 + +### Fixed + +- Fixed the PyPI URL used when installing packages ([#2099](https://github.com/python-poetry/poetry/pull/2099)). +- Fixed errors when the author's name contains special characters ([#2006](https://github.com/python-poetry/poetry/pull/2006)). +- Fixed VCS excluded files detection when building wheels ([#1947](https://github.com/python-poetry/poetry/pull/1947)). +- Fixed packages detection when building sdists ([#1626](https://github.com/python-poetry/poetry/pull/1626)). +- Fixed the local `.venv` virtual environment not being displayed in `env list` ([#1762](https://github.com/python-poetry/poetry/pull/1762)). +- Fixed incompatibilities with the most recent versions of `virtualenv` ([#2096](https://github.com/python-poetry/poetry/pull/2096)). +- Fixed Poetry's own vendor dependencies being retrieved when updating dependencies ([#1981](https://github.com/python-poetry/poetry/pull/1981)). +- Fixed encoding of credentials in URLs ([#1911](https://github.com/python-poetry/poetry/pull/1911)). +- Fixed url constraints not being accepted in multi-constraints dependencies ([#2035](https://github.com/python-poetry/poetry/pull/2035)). +- Fixed an error where credentials specified via environment variables were not retrieved ([#2061](https://github.com/python-poetry/poetry/pull/2061)). +- Fixed an error where git dependencies referencing tags were not locked to the corresponding commit ([#1948](https://github.com/python-poetry/poetry/pull/1948)). +- Fixed an error when parsing packages `setup.py` files ([#2041](https://github.com/python-poetry/poetry/pull/2041)). +- Fixed an error when parsing some git URLs ([#2018](https://github.com/python-poetry/poetry/pull/2018)). + + +## [1.0.3] - 2020-01-31 + +### Fixed + +- Fixed an error which caused the configuration environment variables (like `POETRY_HTTP_BASIC_XXX_PASSWORD`) to not be used ([#1909](https://github.com/python-poetry/poetry/pull/1909)). +- Fixed an error where the `--help` option was not working ([#1910](https://github.com/python-poetry/poetry/pull/1910)). +- Fixed an error where packages from private indices were not decompressed properly ([#1851](https://github.com/python-poetry/poetry/pull/1851)). +- Fixed an error where the version of some PEP-508-formatted wheel dependencies was not properly retrieved ([#1932](https://github.com/python-poetry/poetry/pull/1932)). +- Fixed internal regexps to avoid potential catastrophic backtracking errors ([#1913](https://github.com/python-poetry/poetry/pull/1913)). +- Fixed performance issues when custom indices were defined in the `pyproject.toml` file ([#1892](https://github.com/python-poetry/poetry/pull/1892)). +- Fixed the `get_requires_for_build_wheel()` function of `masonry.api` which wasn't returning the proper result ([#1875](https://github.com/python-poetry/poetry/pull/1875)). + + +## [1.0.2] - 2020-01-10 + +### Fixed + +- Reverted a previous fix ([#1796](https://github.com/python-poetry/poetry/pull/1796)) which was causing errors for projects with file and/or directory dependencies ([#1865](https://github.com/python-poetry/poetry/pull/1865)). + + +## [1.0.1] - 2020-01-10 + +### Fixed + +- Fixed an error in `env use` where the wrong Python executable was being used to check compatibility ([#1736](https://github.com/python-poetry/poetry/pull/1736)). +- Fixed an error where VCS dependencies were not properly categorized as development dependencies ([#1725](https://github.com/python-poetry/poetry/pull/1725)). +- Fixed an error where some shells would no longer be usable after using the `shell` command ([#1673](https://github.com/python-poetry/poetry/pull/1673)). +- Fixed an error where explicitly included files where not included in wheel distributions ([#1750](https://github.com/python-poetry/poetry/pull/1750)). +- Fixed an error where some Git dependencies url were not properly parsed ([#1756](https://github.com/python-poetry/poetry/pull/1756)). +- Fixed an error in the `env` commands on Windows if the path to the executable contained a space ([#1774](https://github.com/python-poetry/poetry/pull/1774)). +- Fixed several errors and UX issues caused by `keyring` on some systems ([#1788](https://github.com/python-poetry/poetry/pull/1788)). +- Fixed errors when trying to detect installed packages ([#1786](https://github.com/python-poetry/poetry/pull/1786)). +- Fixed an error when packaging projects where Python packages were not properly detected ([#1592](https://github.com/python-poetry/poetry/pull/1592)). +- Fixed an error where local file dependencies were exported as editable when using the `export` command ([#1840](https://github.com/python-poetry/poetry/pull/1840)). +- Fixed the way environment markers are propagated and evaluated when resolving dependencies ([#1829](https://github.com/python-poetry/poetry/pull/1829), [#1789](https://github.com/python-poetry/poetry/pull/1789)). +- Fixed an error in the PEP-508 compliant representation of directory and file dependencies ([#1796](https://github.com/python-poetry/poetry/pull/1796)). +- Fixed an error where invalid virtual environments would be silently used. They will not be recreated and a warning will be displayed ([#1797](https://github.com/python-poetry/poetry/pull/1797)). +- Fixed an error where dependencies were not properly detected when reading the `setup.py` file in some cases ([#1764](https://github.com/python-poetry/poetry/pull/1764)). + + +## [1.0.0] - 2019-12-12 ### Added @@ -18,9 +144,11 @@ - Full environment markers are now supported for dependencies via the `markers` property. - Added the ability to specify git dependencies directly in `add`, it no longer requires the `--git` option. - Added the ability to specify path dependencies directly in `add`, it no longer requires the `--path` option. -- Added support for url dependencies ([#1260](https://github.com/sdispater/poetry/pull/1260)). -- Publishing to PyPI using [API tokens](https://pypi.org/help/#apitoken) is now supported ([#1275](https://github.com/sdispater/poetry/pull/1275)). +- Added support for url dependencies ([#1260](https://github.com/python-poetry/poetry/pull/1260)). +- Publishing to PyPI using [API tokens](https://pypi.org/help/#apitoken) is now supported ([#1275](https://github.com/python-poetry/poetry/pull/1275)). - Licenses can now be identified by their full name. +- Added support for custom certificate authority and client certificates for private repositories. +- Poetry can now detect and use Conda environments. ### Changed @@ -33,8 +161,16 @@ - The `--git` option of the `add` command has been removed. - The `--path` option of the `add` command has been removed. - The `add` command will now automatically select the latest prerelease if only prereleases are available. -- The `add` command can now update a dependencies if an explicit constraint is given ([#1221](https://github.com/sdispater/poetry/pull/1221)). +- The `add` command can now update a dependencies if an explicit constraint is given ([#1221](https://github.com/python-poetry/poetry/pull/1221)). - Removed the `--develop` option from the `install` command. +- Improved UX when searching for packages in the `init` command. +- The `shell` command has been improved. +- The `poetry run` command now uses `os.execvp()` rather than spawning a new subprocess. +- Specifying dependencies with `allows-prereleases` in the `pyproject.toml` file is deprecated for consistency with the `add` command. Use `allow-prereleases` instead. +- Improved the error message when the lock file is invalid. +- Whenever Poetry needs to use the "system" Python, it will now call `sys.executable` instead of the `python` command. +- Improved the error message displayed on conflicting Python requirements ([#1681](https://github.com/python-poetry/poetry/pull/1681)). +- Improved the `site-packages` directory detection ([#1683](https://github.com/python-poetry/poetry/pull/1683)). ### Fixed @@ -42,6 +178,27 @@ - The `pyproject.toml` configuration is now properly validated. - Fixed installing Poetry-based packages breaking with `pip`. - Fixed packages with empty markers being added to the lock file. +- Fixed invalid lock file generation in some cases. +- Fixed local version identifier handling in wheel file names. +- Fixed packages with invalid metadata triggering an error instead of being skipped. +- Fixed the generation of invalid lock files in some cases. +- Git dependencies are now properly locked to a specific revision when specifying a branch or a tag. +- Fixed the behavior of the `~=` operator. +- Fixed dependency resolution for conditional development dependencies. +- Fixed generated dependency constraints when they contain inequality operators. +- The `run` command now properly handles the `--` separator. +- Fixed some issues with `path` dependencies being seen as `git` dependencies. +- Fixed various issues with the way `extra` markers in dependencies were handled. +- Fixed the option conflicts in the `run` command. +- Fixed wrong latest version being displayed when executing `show -l`. +- Fixed `TooManyRedirects` errors being raised when resolving dependencies. +- Fixed custom indices dependencies being constantly updated. +- Fixed the behavior of the `--install` option of the debug resolve command. +- Fixed an error in `show` when using the `-o/--outdated` option. +- Fixed PEP 508 url dependency handling. +- Fixed excluded files via the `exclude` being included in distributions. +- Fixed an error in `env use` if the `virtualenvs.in-project` setting is activated ([#1682](https://github.com/python-poetry/poetry/pull/1682)) +- Fixed handling of `empty` and `any` markers in unions of markers ([#1650](https://github.com/python-poetry/poetry/pull/1650)). ## [0.12.17] - 2019-07-03 @@ -725,56 +882,67 @@ Initial release -[Unreleased]: https://github.com/sdispater/poetry/compare/0.12.17...develop -[0.12.17]: https://github.com/sdispater/poetry/releases/tag/0.12.17 -[0.12.16]: https://github.com/sdispater/poetry/releases/tag/0.12.16 -[0.12.15]: https://github.com/sdispater/poetry/releases/tag/0.12.15 -[0.12.14]: https://github.com/sdispater/poetry/releases/tag/0.12.14 -[0.12.13]: https://github.com/sdispater/poetry/releases/tag/0.12.13 -[0.12.12]: https://github.com/sdispater/poetry/releases/tag/0.12.12 -[0.12.11]: https://github.com/sdispater/poetry/releases/tag/0.12.11 -[0.12.10]: https://github.com/sdispater/poetry/releases/tag/0.12.10 -[0.12.9]: https://github.com/sdispater/poetry/releases/tag/0.12.9 -[0.12.8]: https://github.com/sdispater/poetry/releases/tag/0.12.8 -[0.12.7]: https://github.com/sdispater/poetry/releases/tag/0.12.7 -[0.12.6]: https://github.com/sdispater/poetry/releases/tag/0.12.6 -[0.12.5]: https://github.com/sdispater/poetry/releases/tag/0.12.5 -[0.12.4]: https://github.com/sdispater/poetry/releases/tag/0.12.4 -[0.12.3]: https://github.com/sdispater/poetry/releases/tag/0.12.3 -[0.12.2]: https://github.com/sdispater/poetry/releases/tag/0.12.2 -[0.12.1]: https://github.com/sdispater/poetry/releases/tag/0.12.1 -[0.12.0]: https://github.com/sdispater/poetry/releases/tag/0.12.0 -[0.11.5]: https://github.com/sdispater/poetry/releases/tag/0.11.5 -[0.11.4]: https://github.com/sdispater/poetry/releases/tag/0.11.4 -[0.11.3]: https://github.com/sdispater/poetry/releases/tag/0.11.3 -[0.11.2]: https://github.com/sdispater/poetry/releases/tag/0.11.2 -[0.11.1]: https://github.com/sdispater/poetry/releases/tag/0.11.1 -[0.11.0]: https://github.com/sdispater/poetry/releases/tag/0.11.0 -[0.10.3]: https://github.com/sdispater/poetry/releases/tag/0.10.3 -[0.10.2]: https://github.com/sdispater/poetry/releases/tag/0.10.2 -[0.10.1]: https://github.com/sdispater/poetry/releases/tag/0.10.1 -[0.10.0]: https://github.com/sdispater/poetry/releases/tag/0.10.0 -[0.9.1]: https://github.com/sdispater/poetry/releases/tag/0.9.1 -[0.9.0]: https://github.com/sdispater/poetry/releases/tag/0.9.0 -[0.8.6]: https://github.com/sdispater/poetry/releases/tag/0.8.6 -[0.8.5]: https://github.com/sdispater/poetry/releases/tag/0.8.5 -[0.8.4]: https://github.com/sdispater/poetry/releases/tag/0.8.4 -[0.8.3]: https://github.com/sdispater/poetry/releases/tag/0.8.3 -[0.8.2]: https://github.com/sdispater/poetry/releases/tag/0.8.2 -[0.8.1]: https://github.com/sdispater/poetry/releases/tag/0.8.1 -[0.8.0]: https://github.com/sdispater/poetry/releases/tag/0.8.0 -[0.7.1]: https://github.com/sdispater/poetry/releases/tag/0.7.1 -[0.7.0]: https://github.com/sdispater/poetry/releases/tag/0.7.0 -[0.6.5]: https://github.com/sdispater/poetry/releases/tag/0.6.5 -[0.6.4]: https://github.com/sdispater/poetry/releases/tag/0.6.4 -[0.6.3]: https://github.com/sdispater/poetry/releases/tag/0.6.3 -[0.6.2]: https://github.com/sdispater/poetry/releases/tag/0.6.2 -[0.6.1]: https://github.com/sdispater/poetry/releases/tag/0.6.1 -[0.6.0]: https://github.com/sdispater/poetry/releases/tag/0.6.0 -[0.5.0]: https://github.com/sdispater/poetry/releases/tag/0.5.0 -[0.4.2]: https://github.com/sdispater/poetry/releases/tag/0.4.2 -[0.4.1]: https://github.com/sdispater/poetry/releases/tag/0.4.1 -[0.4.0]: https://github.com/sdispater/poetry/releases/tag/0.4.0 -[0.3.0]: https://github.com/sdispater/poetry/releases/tag/0.3.0 -[0.2.0]: https://github.com/sdispater/poetry/releases/tag/0.2.0 -[0.1.0]: https://github.com/sdispater/poetry/releases/tag/0.1.0 +[Unreleased]: https://github.com/python-poetry/poetry/compare/1.1.0a1...develop +[1.1.0a1]: https://github.com/python-poetry/poetry/releases/tag/1.1.0a1 +[1.0.9]: https://github.com/python-poetry/poetry/releases/tag/1.0.9 +[1.0.8]: https://github.com/python-poetry/poetry/releases/tag/1.0.8 +[1.0.7]: https://github.com/python-poetry/poetry/releases/tag/1.0.7 +[1.0.6]: https://github.com/python-poetry/poetry/releases/tag/1.0.6 +[1.0.5]: https://github.com/python-poetry/poetry/releases/tag/1.0.5 +[1.0.4]: https://github.com/python-poetry/poetry/releases/tag/1.0.4 +[1.0.3]: https://github.com/python-poetry/poetry/releases/tag/1.0.3 +[1.0.2]: https://github.com/python-poetry/poetry/releases/tag/1.0.2 +[1.0.1]: https://github.com/python-poetry/poetry/releases/tag/1.0.1 +[1.0.0]: https://github.com/python-poetry/poetry/releases/tag/1.0.0 +[0.12.17]: https://github.com/python-poetry/poetry/releases/tag/0.12.17 +[0.12.16]: https://github.com/python-poetry/poetry/releases/tag/0.12.16 +[0.12.15]: https://github.com/python-poetry/poetry/releases/tag/0.12.15 +[0.12.14]: https://github.com/python-poetry/poetry/releases/tag/0.12.14 +[0.12.13]: https://github.com/python-poetry/poetry/releases/tag/0.12.13 +[0.12.12]: https://github.com/python-poetry/poetry/releases/tag/0.12.12 +[0.12.11]: https://github.com/python-poetry/poetry/releases/tag/0.12.11 +[0.12.10]: https://github.com/python-poetry/poetry/releases/tag/0.12.10 +[0.12.9]: https://github.com/python-poetry/poetry/releases/tag/0.12.9 +[0.12.8]: https://github.com/python-poetry/poetry/releases/tag/0.12.8 +[0.12.7]: https://github.com/python-poetry/poetry/releases/tag/0.12.7 +[0.12.6]: https://github.com/python-poetry/poetry/releases/tag/0.12.6 +[0.12.5]: https://github.com/python-poetry/poetry/releases/tag/0.12.5 +[0.12.4]: https://github.com/python-poetry/poetry/releases/tag/0.12.4 +[0.12.3]: https://github.com/python-poetry/poetry/releases/tag/0.12.3 +[0.12.2]: https://github.com/python-poetry/poetry/releases/tag/0.12.2 +[0.12.1]: https://github.com/python-poetry/poetry/releases/tag/0.12.1 +[0.12.0]: https://github.com/python-poetry/poetry/releases/tag/0.12.0 +[0.11.5]: https://github.com/python-poetry/poetry/releases/tag/0.11.5 +[0.11.4]: https://github.com/python-poetry/poetry/releases/tag/0.11.4 +[0.11.3]: https://github.com/python-poetry/poetry/releases/tag/0.11.3 +[0.11.2]: https://github.com/python-poetry/poetry/releases/tag/0.11.2 +[0.11.1]: https://github.com/python-poetry/poetry/releases/tag/0.11.1 +[0.11.0]: https://github.com/python-poetry/poetry/releases/tag/0.11.0 +[0.10.3]: https://github.com/python-poetry/poetry/releases/tag/0.10.3 +[0.10.2]: https://github.com/python-poetry/poetry/releases/tag/0.10.2 +[0.10.1]: https://github.com/python-poetry/poetry/releases/tag/0.10.1 +[0.10.0]: https://github.com/python-poetry/poetry/releases/tag/0.10.0 +[0.9.1]: https://github.com/python-poetry/poetry/releases/tag/0.9.1 +[0.9.0]: https://github.com/python-poetry/poetry/releases/tag/0.9.0 +[0.8.6]: https://github.com/python-poetry/poetry/releases/tag/0.8.6 +[0.8.5]: https://github.com/python-poetry/poetry/releases/tag/0.8.5 +[0.8.4]: https://github.com/python-poetry/poetry/releases/tag/0.8.4 +[0.8.3]: https://github.com/python-poetry/poetry/releases/tag/0.8.3 +[0.8.2]: https://github.com/python-poetry/poetry/releases/tag/0.8.2 +[0.8.1]: https://github.com/python-poetry/poetry/releases/tag/0.8.1 +[0.8.0]: https://github.com/python-poetry/poetry/releases/tag/0.8.0 +[0.7.1]: https://github.com/python-poetry/poetry/releases/tag/0.7.1 +[0.7.0]: https://github.com/python-poetry/poetry/releases/tag/0.7.0 +[0.6.5]: https://github.com/python-poetry/poetry/releases/tag/0.6.5 +[0.6.4]: https://github.com/python-poetry/poetry/releases/tag/0.6.4 +[0.6.3]: https://github.com/python-poetry/poetry/releases/tag/0.6.3 +[0.6.2]: https://github.com/python-poetry/poetry/releases/tag/0.6.2 +[0.6.1]: https://github.com/python-poetry/poetry/releases/tag/0.6.1 +[0.6.0]: https://github.com/python-poetry/poetry/releases/tag/0.6.0 +[0.5.0]: https://github.com/python-poetry/poetry/releases/tag/0.5.0 +[0.4.2]: https://github.com/python-poetry/poetry/releases/tag/0.4.2 +[0.4.1]: https://github.com/python-poetry/poetry/releases/tag/0.4.1 +[0.4.0]: https://github.com/python-poetry/poetry/releases/tag/0.4.0 +[0.3.0]: https://github.com/python-poetry/poetry/releases/tag/0.3.0 +[0.2.0]: https://github.com/python-poetry/poetry/releases/tag/0.2.0 +[0.1.0]: https://github.com/python-poetry/poetry/releases/tag/0.1.0 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000000..b9cdf3d9041 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,76 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at sebastien@eustace.io. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0a818ca4e84..0b184a286ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,18 +20,18 @@ The following is a set of guidelines for contributing to Poetry on GitHub. These 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 related reports. -Before creating bug reports, please check [this list](#before-submitting-a-bug-report) to be sure that you need to create one. When you are creating a bug report, please include as many details as possible. Fill out the [required template](https://github.com/sdispater/poetry/blob/master/.github/ISSUE_TEMPLATE/1_Bug_report.md), the information it asks helps the maintainers resolve the issue faster. +Before creating bug reports, please check [this list](#before-submitting-a-bug-report) to be sure that you need to create one. When you are creating a bug report, please include as many details as possible. Fill out the [required template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/---bug-report.md), the information it asks helps the maintainers resolve the issue faster. > **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. #### Before submitting a bug report -* **Check the [FAQs on the official website](https://poetry.eustace.io)** for a list of common questions and problems. -* **Check that your issue does not already exist in the [issue tracker](https://github.com/sdispater/poetry/issues)**. +* **Check the [FAQs on the official website](https://python-poetry.org/docs/faq)** for a list of common questions and problems. +* **Check that your issue does not already exist in the [issue tracker](https://github.com/python-poetry/poetry/issues)**. #### How do I submit a bug report? -Bugs are tracked on the [official issue tracker](https://github.com/sdispater/poetry/issues) where you can create a new one and provide the following information by filling in [the template](https://github.com/sdispater/poetry/blob/master/.github/ISSUE_TEMPLATE/1_Bug_report.md). +Bugs are tracked on the [official issue tracker](https://github.com/python-poetry/poetry/issues) where you can create a new one and provide the following information by filling in [the template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/---bug-report.md). Explain the problem and include additional details to help maintainers reproduce the problem: @@ -60,17 +60,16 @@ Include details about your configuration and environment: This section guides you through submitting an enhancement suggestion for Poetry, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions. -Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-an-enhancement-suggestion). Fill in [the template](https://github.com/sdispater/poetry/blob/master/.github/ISSUE_TEMPLATE/2_Feature_request.md), including the steps that you imagine you would take if the feature you're requesting existed. +Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-an-enhancement-suggestion). Fill in [the template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/---feature-request.md), including the steps that you imagine you would take if the feature you're requesting existed. #### Before submitting an enhancement suggestion -* **Check the [FAQs on the official website](https://poetry.eustace.io) for a list of common questions and problems. -* **Check that your issue does not already exist in the [issue tracker](https://github.com/sdispater/poetry/issues). - +* **Check the [FAQs on the official website](https://python-poetry.org/docs/faq)** for a list of common questions and problems. +* **Check that your issue does not already exist in the [issue tracker](https://github.com/python-poetry/poetry/issues)**. #### How do I submit an Enhancement suggestion? -Enhancement suggestions are tracked on the [official issue tracker](https://github.com/sdispater/poetry/issues) where you can create a new one and provide the following information: +Enhancement suggestions are tracked on the [official issue tracker](https://github.com/python-poetry/poetry/issues) where you can create a new one and provide the following information: * **Use a clear and descriptive title** for the issue to identify the suggestion. * **Provide a step-by-step description of the suggested enhancement** in as many details as possible. @@ -82,12 +81,12 @@ Enhancement suggestions are tracked on the [official issue tracker](https://gith #### Local development -You will need Poetry to start contributing on the Poetry codebase. Refer to the [documentation](https://poetry.eustace.io/docs/#introduction) to start using Poetry. +You will need Poetry to start contributing on the Poetry codebase. Refer to the [documentation](https://python-poetry.org/docs/#introduction) to start using Poetry. You will first need to clone the repository using `git` and place yourself in its directory: ```bash -$ git clone git@github.com:sdispater/poetry.git +$ git clone git@github.com:python-poetry/poetry.git $ cd poetry ``` @@ -99,9 +98,12 @@ $ poetry install $ poetry run pytest tests/ ``` -Poetry uses the [black](https://github.com/ambv/black) coding style and you must ensure that your +Poetry uses the [black](https://github.com/psf/black) coding style and you must ensure that your code follows it. If not, the CI will fail and your Pull Request will not be merged. +Similarly, the import statements are sorted with [isort](https://github.com/timothycrosley/isort) +and special care must be taken to respect it. If you don't, the CI will fail as well. + To make sure that you don't accidentally commit code that does not follow the coding style, you can install a pre-commit hook that will check that everything is in order: @@ -109,11 +111,17 @@ install a pre-commit hook that will check that everything is in order: $ poetry run pre-commit install ``` +You can also run it anytime using: + +```bash +$ poetry run pre-commit run --all-files +``` + Your code must always be accompanied by corresponding tests, if tests are not present your code will not be merged. #### Pull requests -* Fill in [the required template](https://github.com/sdispater/poetry/blob/master/.github/PULL_REQUEST_TEMPLATE.md) +* Fill in [the required template](https://github.com/python-poetry/poetry/blob/master/.github/PULL_REQUEST_TEMPLATE.md) * Be sure that your pull request contains tests that cover the changed or added code. * If your changes warrant a documentation change, the pull request must also update the documentation. diff --git a/Makefile b/Makefile index be0b5a76d7b..ccb529f1f0a 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ # This file is part of Poetry -# https://github.com/sdispater/poetry +# https://github.com/python-poetry/poetry # Licensed under the MIT license: # http://www.opensource.org/licenses/MIT-license @@ -47,8 +47,15 @@ wheel: @poetry build -v linux_release: - docker pull quay.io/pypa/manylinux1_x86_64 - docker run --rm -v `pwd`:/io quay.io/pypa/manylinux1_x86_64 /io/make-linux-release.sh + docker pull quay.io/pypa/manylinux2010_x86_64 + docker run --rm -i -v `pwd`:/io \ + -e PYTHON=/opt/python/cp37-cp37m/bin/python \ + -e PYTHON27=/opt/python/cp27-cp27m/bin/python \ + -e PYTHON35=/opt/python/cp35-cp35m/bin/python \ + -e PYTHON36=/opt/python/cp36-cp36m/bin/python \ + -e PYTHON37=/opt/python/cp37-cp37m/bin/python \ + -e PYTHON38=/opt/python/cp38-cp38/bin/python \ + quay.io/pypa/manylinux2010_x86_64 sh -c "cd /io && ./make-nix-release.sh" # run tests against all supported python versions tox: diff --git a/README.md b/README.md index 3da71ff42ae..4d1a0a68f6a 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,13 @@ Poetry helps you declare, manage and install dependencies of Python projects, ensuring you have the right stack everywhere. -![Poetry Install](https://raw.githubusercontent.com/sdispater/poetry/master/assets/install.gif) +![Poetry Install](https://raw.githubusercontent.com/python-poetry/poetry/master/assets/install.gif) It supports Python 2.7 and 3.4+. -[![Unix Build Status](https://img.shields.io/travis/sdispater/poetry.svg?label=Unix)](https://travis-ci.org/sdispater/poetry) -[![Windows Build Status](https://img.shields.io/appveyor/ci/sdispater/poetry.svg?label=Windows)](https://ci.appveyor.com/project/sdispater/poetry) +[![Tests Status](https://github.com/python-poetry/poetry/workflows/Tests/badge.svg?branch=master&event=push)](https://github.com/python-poetry/poetry/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush) + +The [complete documentation](https://python-poetry.org/docs/) is available on the [official website](https://python-poetry.org). ## Installation @@ -17,11 +18,18 @@ from the rest of your system by vendorizing its dependencies. This is the recommended way of installing `poetry`. ```bash -curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python +curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python ``` Alternatively, you can download the `get-poetry.py` file and execute it separately. +The setup script must be able to find one of following executables in your shell's path environment: + +- `python` (which can be a py3 or py2 interpreter) +- `python3` +- `py.exe -3` (Windows) +- `py.exe -2` (Windows) + If you want to install prerelease versions, you can do so by passing `--preview` to `get-poetry.py`: ```bash @@ -45,25 +53,29 @@ which might cause conflicts. ## Updating `poetry` -Updating poetry to the latest stable version is as simple as calling the `self:update` command. +Updating poetry to the latest stable version is as simple as calling the `self update` command. ```bash -poetry self:update +poetry self update ``` If you want to install prerelease versions, you can use the `--preview` option. ```bash -poetry self:update --preview +poetry self update --preview ``` And finally, if you want to install a specific version you can pass it as an argument -to `self:update`. +to `self update`. ```bash -poetry self:update 0.8.0 +poetry self update 1.0.0 ``` +*Note:* + + If you are still on poetry version < 1.0 use `poetry self:update` instead. + ## Enable tab completion for Bash, Fish, or Zsh @@ -74,17 +86,27 @@ See `poetry help completions` for full details, but the gist is as simple as usi # Bash poetry completions bash > /etc/bash_completion.d/poetry.bash-completion -# Bash (macOS/Homebrew) +# Bash (Homebrew) poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-completion # Fish poetry completions fish > ~/.config/fish/completions/poetry.fish +# Fish (Homebrew) +poetry completions fish > (brew --prefix)/share/fish/vendor_completions.d/poetry.fish + # Zsh poetry completions zsh > ~/.zfunc/_poetry -# Zsh (macOS/Homebrew) +# Zsh (Homebrew) poetry completions zsh > $(brew --prefix)/share/zsh/site-functions/_poetry + +# Zsh (Oh-My-Zsh) +mkdir $ZSH/plugins/poetry +poetry completions zsh > $ZSH/plugins/poetry/_poetry + +# Zsh (prezto) +poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry ``` *Note:* you may need to restart your shell in order for the changes to take @@ -119,8 +141,8 @@ authors = [ readme = 'README.md' # Markdown files are supported -repository = "https://github.com/sdispater/poetry" -homepage = "https://github.com/sdispater/poetry" +repository = "https://github.com/python-poetry/poetry" +homepage = "https://github.com/python-poetry/poetry" keywords = ['packaging', 'poetry'] @@ -130,7 +152,7 @@ toml = "^0.9" # Dependencies with extras requests = { version = "^2.13", extras = [ "security" ] } # Python specific dependencies with prereleases allowed -pathlib2 = { version = "^2.2", python = "~2.7", allows-prereleases = true } +pathlib2 = { version = "^2.2", python = "~2.7", allow-prereleases = true } # Git dependencies cleo = { git = "https://github.com/sdispater/cleo.git", branch = "master" } @@ -239,599 +261,8 @@ so `poetry` will try to find a version of `oslo.i18n` that satisfies `pbr (>=0.6 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 -dependency. This means that **any** version of this package can be installed which -can lead to compatibility issues. - -Also, you have to explicitly tell it to not update the locked packages when you -install new ones. This should be the default. - -#### Uninstall command - -The `uninstall` command will only remove the package specified but not its dependencies -if they are no longer needed. - -You either have to use `sync` or `clean` to fix that. - -#### Too limited in scope - -Finally, the `Pipfile` is just a replacement from `requirements.txt` and, in the end, you will still need to -populate your `setup.py` file (or `setup.cfg`) with the exact same dependencies you declared in your `Pipfile`. -So, in the end, you will still need to manage a few configuration files to properly setup your project. - - -## Commands - - -### new - -This command will help you kickstart your new Python project by creating -a directory structure suitable for most projects. - -```bash -poetry new my-package -``` - -will create a folder as follows: - -```text -my-package -├── pyproject.toml -├── README.rst -├── my_package -│ └── __init__.py -└── tests - ├── __init__.py - └── test_my_package -``` - -If you want to name your project differently than the folder, you can pass -the `--name` option: - -```bash -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 directory, resolves the dependencies, -and installs them. - -```bash -poetry install -``` - -If there is a `poetry.lock` file in the current directory, -it will use the exact versions from there instead of resolving them. -This ensures that everyone using the library will get the same versions of the dependencies. - -If there is no `poetry.lock` file, Poetry will create one after dependency resolution. - -You can specify to the command that you do not want the development dependencies installed by passing -the `--no-dev` option. - -```bash -poetry install --no-dev -``` - -You can also specify the extras you want installed -by passing the `-E|--extras` option (See [Extras](#extras) for more info) - -```bash -poetry install --extras "mysql pgsql" -poetry install -E mysql -E pgsql -``` - -By default `poetry` will install your project's package everytime you run `install`: - -```bash -$ poetry install -Installing dependencies from lock file - -Nothing to install or update - - - Installing (x.x.x) - -``` - -If you want to skip this installation, use the `--no-root` option. - -```bash -poetry install --no-root -``` - -#### Options - -* `--no-dev`: Do not install dev dependencies. -* `--no-root`: Do not install the root package (your project). -* `-E|--extras`: Features to install (multiple values allowed). - -### update - -In order to get the latest versions of the dependencies and to update the `poetry.lock` file, -you should use the `update` command. - -```bash -poetry update -``` - -This will resolve all dependencies of the project and write the exact versions into `poetry.lock`. - -If you just want to update a few packages and not all, you can list them as such: - -```bash -poetry update requests toml -``` - -#### Options - -* `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose). -* `--no-dev` : Do not install dev dependencies. -* `--lock` : Do not perform install (only update the lockfile). - -### add - -The `add` command adds required packages to your `pyproject.toml` and installs them. - -If you do not specify a version constraint, -poetry will choose a suitable one based on the available package versions. - -```bash -poetry add requests pendulum -``` - -#### Options - -* `--D|dev`: Add package as development dependency. -* `--optional` : Add as an optional dependency. -* `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose). - - -### remove - -The `remove` command removes a package from the current -list of installed packages - -```bash -poetry remove pendulum -``` - -#### Options - -* `--D|dev`: Removes a package from the development dependencies. -* `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose). - - -### show - -To list all of the available packages, you can use the `show` command. - -```bash -poetry show -``` - -If you want to see the details of a certain package, you can pass the package name. - -```bash -poetry show pendulum - -name : pendulum -version : 1.4.2 -description : Python datetimes made easy - -dependencies: - - python-dateutil >=2.6.1 - - tzlocal >=1.4 - - pytzdata >=2017.2.2 -``` - -#### Options - -* `--no-dev`: Do not list the dev dependencies. -* `--tree`: List the dependencies as a tree. -* `-l|--latest`: Show the latest version. -* `-o|--outdated`: Show the latest version but only for packages that are outdated. - - -### build - -The `build` command builds the source and wheels archives. - -```bash -poetry build -``` - -Note that, at the moment, only pure python wheels are supported. - -#### Options - -* `-f|--format`: Limit the format to either wheel or sdist. - -### publish - -This command builds (if not already built) and publishes the package to the remote repository. - -It will automatically register the package before uploading if this is the first time it is submitted. - -```bash -poetry publish -``` - -#### Options - -* `-r|--repository`: The repository to register the package to (default: `pypi`). -Should match a repository name set by the [`config`](#config) command. -* `--username (-u)`: The username to access the repository. -* `--password (-p)`: The password to access the repository. - - -### `config` - -The `config` command allows you to edit poetry config settings and repositories. - -```bash -poetry config --list -``` - -#### Usage - -````bash -poetry config [options] [setting-key] [setting-value1] ... [setting-valueN] -```` - -`setting-key` is a configuration option name and `setting-value1` is a configuration value. - -#### Modifying repositories - -In addition to modifying the config section, -the config command also supports making changes to the repositories section by using it the following way: - -```bash -poetry config repositories.foo https://foo.bar/simple/ -``` - -This will set the url for repository `foo` to `https://foo.bar/simple/`. - -If you want to store your credentials for a specific repository, you can do so easily: - -```bash -poetry config http-basic.foo username password -``` - -If you do not specify the password you will be prompted to write it. - -#### Options - -* `--unset`: Remove the configuration element named by `setting-key`. -* `--list`: Show the list of current config variables. - -### search - -This command searches for packages on a remote index. - -```bash -poetry search requests pendulum -``` - -#### Options - -* `-N|--only-name`: Search only in name. - -### lock - -This command locks (without installing) the dependencies specified in `pyproject.toml`. - -```bash -poetry lock -``` - -### export - -This command exports the lock file to other formats. - -```bash -poetry export -f requirements.txt > requirements.txt -``` - -#### Options - -* `--format (-f)`: the format to export to. Currently, only - `requirements.txt` is supported. -* `--output (-o)`: the name of the output file. If omitted, print to standard - output. - - -## The `pyproject.toml` file - -The `tool.poetry` section of the `pyproject.toml` file is composed of multiple sections. - -#### name - -The name of the package. **Required** - -#### version - -The version of the package. **Required** - -This should follow [semantic versioning](http://semver.org/). However it will not be enforced and you remain -free to follow another specification. - -#### description - -A short description of the package. **Required** - -#### license - -The license of the package. - -The recommended notation for the most common licenses is (alphabetical): - -* Apache-2.0 -* BSD-2-Clause -* BSD-3-Clause -* BSD-4-Clause -* GPL-2.0 -* GPL-2.0+ -* GPL-3.0 -* GPL-3.0+ -* LGPL-2.1 -* LGPL-2.1+ -* LGPL-3.0 -* LGPL-3.0+ -* MIT - -Optional, but it is highly recommended to supply this. -More identifiers are listed at the [SPDX Open Source License Registry](https://www.spdx.org/licenses/). - -#### authors - -The authors of the package. **Required** - -This is a list of authors and should contain at least one author. Authors must be in the form `name `. - -#### readme - -The readme file of the package. **Required** - -The file can be either `README.rst` or `README.md`. - -#### homepage - -An URL to the website of the project. **Optional** - -#### repository - -An URL to the repository of the project. **Optional** - -#### documentation - -An URL to the documentation of the project. **Optional** - -#### keywords - -A list of keywords (max: 5) that the package is related to. **Optional** - -#### include and exclude - -A list of patterns that will be included in the final package. - -You can explicitly specify to Poetry that a set of globs should be ignored or included for the purposes of packaging. -The globs specified in the exclude field identify a set of files that are not included when a package is built. - -If a VCS is being used for a package, the exclude field will be seeded with the VCS’ ignore settings (`.gitignore` for git for example). - -```toml -[tool.poetry] -# ... -include = ["package/**/*.py", "package/**/.c"] -``` - -```toml -exclude = ["package/excluded.py"] -``` - -### `dependencies` and `dev-dependencies` - -Poetry is configured to look for dependencies on [PyPi](https://pypi.org) by default. -Only the name and a version string are required in this case. - -```toml -[tool.poetry.dependencies] -requests = "^2.13.0" -``` - -If you want to use a private repository, you can add it to your `pyproject.toml` file, like so: - -```toml -[[tool.poetry.source]] -name = 'private' -url = 'http://example.com/simple' -``` - -Be aware that declaring the python version for which your package -is compatible is mandatory: - -```toml -[tool.poetry.dependencies] -python = "^3.6" -``` - -#### Caret requirement - -**Caret requirements** allow SemVer 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. -In this case, if we 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: - -```text -^1.2.3 := >=1.2.3 <2.0.0 -^1.2 := >=1.2.0 <2.0.0 -^1 := >=1.0.0 <2.0.0 -^0.2.3 := >=0.2.3 <0.3.0 -^0.0.3 := >=0.0.3 <0.0.4 -^0.0 := >=0.0.0 <0.1.0 -^0 := >=0.0.0 <1.0.0 -``` - -#### Tilde requirements - -**Tilde requirements** specify a minimal version with some ability to update. -If you specify a major, minor, and patch version or only a major and minor version, only patch-level changes are allowed. -If you only specify a major version, then minor- and patch-level changes are allowed. - -`~1.2.3` is an example of a tilde requirement. - -```text -~1.2.3 := >=1.2.3 <1.3.0 -~1.2 := >=1.2.0 <1.3.0 -~1 := >=1.0.0 <2.0.0 -``` - -#### Wildcard requirements - -**Wildcard requirements** allow for any version where the wildcard is positioned. - -`*`, `1.*` and `1.2.*` are examples of wildcard requirements. - -```text -* := >=0.0.0 -1.* := >=1.0.0 <2.0.0 -1.2.* := >=1.2.0 <1.3.0 -``` - -#### Inequality requirements - -**Inequality requirements** allow manually specifying a version range or an exact version to depend on. - -Here are some examples of inequality requirements: - -```text ->= 1.2.0 -> 1 -< 2 -!= 1.2.3 -``` - -#### Multiple requirements - -Multiple version requirements can also be separated with a comma, e.g. `>= 1.2, < 1.5`. - -#### `git` dependencies - -To depend on a library located in a `git` repository, -the minimum information you need to specify is the location of the repository with the git key: - -```toml -[tool.poetry.dependencies] -requests = { git = "https://github.com/requests/requests.git" } -``` - -Since we haven’t specified any other information, -Poetry assumes that we intend to use the latest commit on the `master` branch to build our project. -You can combine the `git` key with the `rev`, `tag`, or `branch` keys to specify something else. -Here's an example of specifying that you want to use the latest commit on a branch named `next`: - -```toml -[tool.poetry.dependencies] -requests = { git = "https://github.com/kennethreitz/requests.git", branch = "next" } -``` - -#### Python restricted dependencies - -You can also specify that a dependency should be installed only for specific Python versions: - -```toml -[tool.poetry.dependencies] -pathlib2 = { version = "^2.2", python = "~2.7" } -``` - -```toml -[tool.poetry.dependencies] -pathlib2 = { version = "^2.2", python = ["~2.7", "^3.2"] } -``` - -### `scripts` - -This section describe the scripts or executable that will be installed when installing the package - -```toml -[tool.poetry.scripts] -poetry = 'poetry.console:run' -``` - -After installing a package with the above toml, `poetry` will be a global command available from the command line that will execute `console.run` in the `poetry` package. - -### `extras` - -Poetry supports extras to allow expression of: - -* optional dependencies, which enhance a package, but are not required; and -* clusters of optional dependencies. - -```toml -[tool.poetry] -name = "awesome" - -[tool.poetry.dependencies] -# These packages are mandatory and form the core of this package’s distribution. -mandatory = "^1.0" - -# A list of all of the optional dependencies, some of which are included in the -# below `extras`. They can be opted into by apps. -psycopg2 = { version = "^2.7", optional = true } -mysqlclient = { version = "^1.3", optional = true } - -[tool.poetry.extras] -mysql = ["mysqlclient"] -pgsql = ["psycopg2"] -``` - -When installing packages, you can specify extras by using the `-E|--extras` option: - -```bash -poetry install --extras "mysql pgsql" -poetry install -E mysql -E pgsql -``` - -### `plugins` - -Poetry supports arbitrary plugins which work similarly to -[setuptools entry points](http://setuptools.readthedocs.io/en/latest/setuptools.html). -To match the example in the setuptools documentation, you would use the following: - -```toml -[tool.poetry.plugins] # Optional super table - -[tool.poetry.plugins."blogtool.parsers"] -".rst" = "some_module::SomeClass" -``` - ## Resources -* [Official Website](https://poetry.eustace.io) -* [Issue Tracker](https://github.com/sdispater/poetry/issues) +* [Official Website](https://python-poetry.org) +* [Issue Tracker](https://github.com/python-poetry/poetry/issues) +* [Discord](https://discordapp.com/invite/awxPgve) diff --git a/docs/docs/basic-usage.md b/docs/docs/basic-usage.md index a9fd808f3f5..48fc8f480e7 100644 --- a/docs/docs/basic-usage.md +++ b/docs/docs/basic-usage.md @@ -69,14 +69,15 @@ It will automatically find a suitable version constraint **and install** the pac In our example, we are requesting the `pendulum` package with the version constraint `^1.4`. 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](/docs/versions/) for more in-depth information on versions, how versions relate to each other, and on version constraints. +Please read [Dependency specification](/docs/dependency-specification) for more in-depth information on versions, +how versions relate to each other, and on the different ways you can specify dependencies. !!!note **How does Poetry download the right files?** - When you specify a dependency in `pyproject.toml`, Poetry first take the name of the package + When you specify a dependency in `pyproject.toml`, Poetry first takes 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 back on PyPI. @@ -133,6 +134,15 @@ the dependencies installed are still working even if your dependencies released For libraries it is not necessary to commit the lock file. +### Installing dependencies only + +The current project is installed in [editable](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs) mode by default. + +If you want to install the dependencies only, run the `install` command with the `--no-root` flag: + +```bash +poetry install --no-root +``` ## Updating dependencies to their latest versions @@ -147,107 +157,3 @@ and update the lock file with the new versions. Poetry will display a **Warning** when executing an install command if `poetry.lock` and `pyproject.toml` are not synchronized. - - -## Poetry and virtualenvs - -When you execute the `install` command (or any other "install" commands like `add` or `remove`), -Poetry will check if it's currently inside a virtualenv and, if not, will use an existing one -or create a brand new one for you to always work isolated from your global Python installation. - -By default, Poetry will use the currently activated Python version -to create the virtualenv for the current project. - -To easily switch between Python versions, it is recommended to -use [pyenv](https://github.com/pyenv/pyenv) or similar tools. - -For instance, if your project is Python 2.7 only, a standard workflow -would be: - -```bash -pyenv install 2.7.15 -pyenv local 2.7.15 # Activate Python 2.7 for the current project -poetry install -``` - -However, this might not be feasible for your system, especially Windows where `pyenv`, -is not available. To circumvent that you can use the `env use` command to tell -Poetry which Python version to use for the current project. - -```bash -poetry env use /full/path/to/python -``` - -If you have the python executable in your `PATH` you can use it: - -```bash -poetry env use python3.7 -``` - -You can even just use the minor Python version in this case: - -```bash -poetry env use 3.7 -``` - -If you want to disable the explicitly activated virtualenv, you can use the -special `system` Python version to retrieve the default behavior: - -```bash -poetry env use system -``` - -If you want to get basic information about the currently activated virtualenv, -you can use the `env info` command: - -```bash -poetry env info -``` - -will output something similar to this: - -```text -Virtualenv -Python: 3.7.1 -Implementation: CPython -Path: /path/to/poetry/cache/virtualenvs/test-O3eWbxRl-py3.7 -Valid: True - -System -Platform: darwin -OS: posix -Python: /path/to/main/python -``` - -If you only want to know the path to the virtualenv, you can pass the `--path` option -to `env info`: - -```bash -poetry env info --path -``` - -You can also list all the virtualenvs associated with the current virtualenv -with the `env list` command: - -```bash -poetry env list -``` - -will output something like the following: - -```text -test-O3eWbxRl-py2.7 -test-O3eWbxRl-py3.6 -test-O3eWbxRl-py3.7 (Activated) -``` - -Finally, you can delete existing virtualenvs by using `env remove`: - -```bash -poetry env remove /full/path/to/python -poetry env remove python3.7 -poetry env remove 3.7 -poetry env remove test-O3eWbxRl-py3.7 -``` - -If your remove the currently activated virtualenv, it will be automatically deactivated. diff --git a/docs/docs/cli.md b/docs/docs/cli.md index b938c4d6839..3f60e585e05 100644 --- a/docs/docs/cli.md +++ b/docs/docs/cli.md @@ -3,18 +3,9 @@ You've already learned how to use the command-line interface to do some things. This chapter documents all the available commands. -To get help from the command-line, simply call `poetry` or `poetry list` to see the complete list of commands, +To get help from the command-line, simply call `poetry` to see the complete list of commands, then `--help` combined with any of those can give you more information. -As `Poetry` uses [cleo](https://github.com/sdispater/cleo) you can call commands by short name if it's not ambiguous. - -```bash -poetry up -``` - -calls `poetry update`. - - ## Global options * `--verbose (-v|vv|vvv)`: Increase the verbosity of messages: "-v" for normal output, "-vv" for more verbose output and "-vvv" for debug. @@ -121,6 +112,13 @@ the `--no-dev` option. poetry install --no-dev ``` +If you want to remove old dependencies no longer present in the lock file, use the +`--remove-untracked` option. + +```bash +poetry install --remove-untracked +``` + You can also specify the extras you want installed by passing the `--E|--extras` option (See [Extras](#extras) for more info) @@ -135,7 +133,7 @@ By default `poetry` will install your project's package everytime you run `insta $ poetry install Installing dependencies from lock file -Nothing to install or update +No dependencies to install or update - Installing (x.x.x) @@ -170,6 +168,11 @@ If you just want to update a few packages and not all, you can list them as such poetry update requests toml ``` +Note that this will not update versions for dependencies outside their version constraints specified +in the `pyproject.toml` file. In other terms, `poetry update foo` will be a no-op if the version constraint +specified for `foo` is `~2.3` or `2.3` and `2.4` is available. In order for `foo` to be updated, you must +update the constraint, for example `^2.3`. You can do this using the `add` command. + ### Options * `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose). @@ -209,12 +212,18 @@ You can also add `git` dependencies: poetry add git+https://github.com/sdispater/pendulum.git ``` +or use ssh instead of https: + +```bash +poetry add git+ssh://git@github.com/sdispater/pendulum.git +``` + If you need to checkout a specific branch, tag or revision, you can specify it when using `add`: ```bash -poetry add git+https://github.com/sdispater/pendulum.git@develop -poetry add git+https://github.com/sdispater/pendulum.git@2.0.5 +poetry add git+https://github.com/sdispater/pendulum.git#develop +poetry add git+https://github.com/sdispater/pendulum.git#2.0.5 ``` or make them point to a local directory or file: @@ -225,7 +234,7 @@ poetry add ../my-package/dist/my-package-0.1.0.tar.gz poetry add ../my-package/dist/my_package-0.1.0.whl ``` -Path dependencies pointing to a local directory will be installed in editable mode (i.e. setuptools "develop mode"). +Path dependencies pointing to a local directory will be installed in editable mode (i.e. setuptools "develop mode"). It means that changes in the local directory will be reflected directly in environment. If you don't want the dependency to be installed in editable mode you can specify it in the `pyproject.toml` file: @@ -250,6 +259,7 @@ poetry add "git+https://github.com/pallets/flask.git@1.1.1[dotenv,dev]" * `--path`: The path to a dependency. * `--optional` : Add as an optional dependency. * `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose). +* `--lock` : Do not perform install (only update the lockfile). ## remove @@ -310,7 +320,7 @@ Note that, at the moment, only pure python wheels are supported. ### Options -* `--format (-F)`: Limit the format to either wheel or sdist. +* `--format (-f)`: Limit the format to either `wheel` or `sdist`. ## publish @@ -330,6 +340,7 @@ It can also build the package if you pass it the `--build` option. Should match a repository name set by the [`config`](#config) command. * `--username (-u)`: The username to access the repository. * `--password (-p)`: The password to access the repository. +* `--dry-run`: Perform all actions except upload the package. ## config @@ -420,13 +431,30 @@ poetry lock ## version -This command shows the current version of the project or bumps the version of +This command shows the current version of the project or bumps the version of the project and writes the new version back to `pyproject.toml` if a valid bump rule is provided. -The new version should ideally be a valid semver string or a valid bump rule: +The new version should ideally be a valid [semver](https://semver.org/) string or a valid bump rule: `patch`, `minor`, `major`, `prepatch`, `preminor`, `premajor`, `prerelease`. +The table below illustrates the effect of these rules with concrete examples. + +| rule | before | after | +|------------|---------------|---------------| +| major | 1.3.0 | 2.0.0 | +| minor | 2.1.4 | 2.2.0 | +| patch | 4.1.1 | 4.1.2 | +| premajor | 1.0.2 | 2.0.0-alpha.0 | +| preminor | 1.0.2 | 1.1.0-alpha.0 | +| prepatch | 1.0.2 | 1.0.3-alpha.0 | +| prerelease | 1.0.2 | 1.0.3-alpha.0 | +| prerelease | 1.0.3-alpha.0 | 1.0.3-alpha.1 | +| prerelease | 1.0.3-beta.0 | 1.0.3-beta.1 | + +## Options + +* `--short (-s)`: Output the version number only. ## export @@ -442,8 +470,8 @@ poetry export -f requirements.txt > requirements.txt ### Options -* `--format (-f)`: The format to export to. Currently, only - `requirements.txt` is supported. +* `--format (-f)`: The format to export to (default: `requirements.txt`). + Currently, only `requirements.txt` is supported. * `--output (-o)`: The name of the output file. If omitted, print to standard output. * `--dev`: Include development dependencies. @@ -456,106 +484,16 @@ poetry export -f requirements.txt > requirements.txt The `env` command regroups sub commands to interact with the virtualenvs associated with a specific project. -### env use - -The `env use` command tells Poetry which Python version -to use for the current project. - -```bash -poetry env use /full/path/to/python -``` - -If you have the python executable in your `PATH` you can use it: - -```bash -poetry env use python3.7 -``` - -You can even just use the minor Python version in this case: - -```bash -poetry env use 3.7 -``` - -If you want to disable the explicitly activated virtualenv, you can use the -special `system` Python version to retrieve the default behavior: - -```bash -poetry env use system -``` - -### env info - -The `env info` command displays basic information about the currently activated virtualenv: - -```bash -poetry env info -``` - -will output something similar to this: - -```text -Virtualenv -Python: 3.7.1 -Implementation: CPython -Path: /path/to/poetry/cache/virtualenvs/test-O3eWbxRl-py3.7 -Valid: True - -System -Platform: darwin -OS: posix -Python: /path/to/main/python -``` - -If you only want to know the path to the virtualenv, you can pass the `--path` option -to `env info`: - -```bash -poetry env info --path -``` - -#### Options - -* `--path`: Only display the path of the virtualenv. +See [Managing environments](/docs/managing-environments.md) for more information about these commands. +## cache -### env list +The `cache` command regroups sub commands to interact with Poetry's cache. -The `env list` command lists all the virtualenvs associated with the current virtualenv. +### cache list -```bash -poetry env list -``` - -will output something like the following: - -```text -test-O3eWbxRl-py2.7 -test-O3eWbxRl-py3.6 -test-O3eWbxRl-py3.7 (Activated) -``` - -#### Options - -* `--full-path`: Display the full path of the virtualenvs. - -### env remove - -The `env remove` command deletes virtualenvs associated with the current project: - -```bash -poetry env remove /full/path/to/python -``` - -Similarly to `env use`, you can either pass `python3.7`, `3.7` or the name of -the virtualenv (as returned by `env list`): +The `cache list` command lists Poetry's available caches. ```bash -poetry env remove python3.7 -poetry env remove 3.7 -poetry env remove test-O3eWbxRl-py3.7 +poetry cache list ``` - -!!!note - - If your remove the currently activated virtualenv, it will be automatically deactivated. diff --git a/docs/docs/configuration.md b/docs/docs/configuration.md index 7e4b84388de..88d38bd03ee 100644 --- a/docs/docs/configuration.md +++ b/docs/docs/configuration.md @@ -100,11 +100,11 @@ Defaults to one of the following directories: - macOS: `~/Library/Caches/pypoetry` - Windows: `C:\Users\\AppData\Local\pypoetry\Cache` -- Unix: `~/.cache/pypoetry/virtualenvs` +- Unix: `~/.cache/pypoetry` ### `virtualenvs.create`: boolean -Create a new virtualenv if one doesn't already exist. +Create a new virtual environment if one doesn't already exist. Defaults to `true`. ### `virtualenvs.in-project`: boolean @@ -114,7 +114,7 @@ Defaults to `false`. ### `virtualenvs.path`: string -Directory where virtualenvs will be created. +Directory where virtual environments will be created. Defaults to `{cache-dir}/virtualenvs` (`{cache-dir}\virtualenvs` on Windows). ### `repositories.`: string diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md index defa0ab2bc4..568877b4a4f 100644 --- a/docs/docs/contributing.md +++ b/docs/docs/contributing.md @@ -1,121 +1 @@ -# Contributing to Poetry - -First off, thank for taking the time to contribute! - -The following is a set of guidelines for contributing to Poetry on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. - -#### Table of Contents - -[How to contribute](#how-to-contribute) - - * [Reporting bugs](#reporting-bugs) - * [Suggesting enhancements](#suggesting-enhancements) - * [Contributing to code](#contributing-to-code) - - -## How to contribute - -### 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 related reports. - -Before creating bug reports, please check [this list](#before-submitting-a-bug-report) to be sure that you need to create one. When you are creating a bug report, please include as many details as possible. Fill out the [required template](https://github.com/sdispater/poetry/blob/master/.github/ISSUE_TEMPLATE/1_Bug_report.md), the information it asks helps the maintainers resolve the issue faster. - -!!!note - - If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. - -#### Before submitting a bug report - -* **Check the [FAQs on the official website](https://poetry.eustace.io)** for a list of common questions and problems. -* **Check that your issue does not already exist in the [issue tracker](https://github.com/sdispater/poetry/issues)**. - -#### How do I submit a bug report - -Bugs are tracked on the [official issue tracker](https://github.com/sdispater/poetry/issues) where you can create a new one and provide the following information by filling in [the template](https://github.com/sdispater/poetry/blob/master/.github/ISSUE_TEMPLATE/1_Bug_report.md). - -Explain the problem and include additional details to help maintainers reproduce the problem: - -* **Use a clear and descriptive title** for the issue to identify the problem. -* **Describe the exact steps which reproduce the problem** in as many details as possible. -* **Provide your pyproject.toml file** in a [Gist](https://gist.github.com) after removing potential private information (like private package repositories). -* **Provide specific examples to demonstrate the steps to reproduce the issue**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. -* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. -* **Explain which behavior you expected to see instead and why.** -* **If the problem is an unexpected error being raised**, execute the corresponding command in **debug** mode (the `-vvv` option). - -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 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 doesn't happen? -* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens. - -Include details about your configuration and environment: - -* **Which version of Poetry are you using?** You can get the exact version by running `poetry -V` in your terminal. -* **Which Python version Poetry has been installed for?** Execute the `debug:info` to get the information. -* **What's the name and version of the OS you're using**? - - -### Suggesting enhancements - -This section guides you through submitting an enhancement suggestion for Poetry, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions. - -Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-an-enhancement-suggestion). Fill in [the template](https://github.com/sdispater/poetry/blob/master/.github/ISSUE_TEMPLATE/2_Feature_request.md), including the steps that you imagine you would take if the feature you're requesting existed. - -#### Before submitting an enhancement suggestion - -* **Check the [FAQs on the official website](https://poetry.eustace.io)** for a list of common questions and problems. -* **Check that your issue does not already exist in the [issue tracker](https://github.com/sdispater/poetry/issues)**. - - -#### How do I submit an enhancement suggestion? - -Enhancement suggestions are tracked on the [official issue tracker](https://github.com/sdispater/poetry/issues) where you can create a new one and provide the following information: - -* **Use a clear and descriptive title** for the issue to identify the suggestion. -* **Provide a step-by-step description of the suggested enhancement** in as many details as possible. -* **Provide specific examples to demonstrate the steps**.. -* **Describe the current behavior** and **explain which behavior you expected to see instead** and why. - - -### Contributing to code - -#### Local development - -You will need Poetry to start contributing on the Poetry codebase. Refer to the [documentation](https://poetry.eustace.io/docs/#introduction) to start using Poetry. - -You will first need to clone the repository using `git` and place yourself in its directory: - -```bash -$ git clone git@github.com:sdispater/poetry.git -$ cd poetry -``` - -Now, you will need to install the required dependency for Poetry and be sure that the current -tests are passing on your machine: - -```bash -$ poetry install -$ poetry run pytest tests/ -``` - -Poetry uses the [black](https://github.com/ambv/black) coding style and you must ensure that your -code follows it. If not, the CI will fail and your Pull Request will not be merged. - -To make sure that you don't accidently commit code that does not follow the coding style, you can -install a pre-commit hook that will check that everything is in order: - -```bash -$ poetry run pre-commit install -``` - -Your code must always be accompanied by corresponding tests, if tests are not present your code -will not be merged. - -#### Pull requests - -* Fill in [the required template](https://github.com/sdispater/poetry/blob/master/.github/PULL_REQUEST_TEMPLATE.md) -* Be sure that you pull request contains tests that cover the changed or added code. -* If you changes warrant a documentation change, the pull request must also update the documentation. +{!../CONTRIBUTING.md!} diff --git a/docs/docs/versions.md b/docs/docs/dependency-specification.md similarity index 70% rename from docs/docs/versions.md rename to docs/docs/dependency-specification.md index 7769471a498..257b585b5a3 100644 --- a/docs/docs/versions.md +++ b/docs/docs/dependency-specification.md @@ -1,6 +1,7 @@ -# Versions and constraints +# Dependency specification -Poetry recommends following [semantic versioning](https://semver.org) but will not enforce it. +Dependencies for a project can be specified in various forms, which depend on the type +of the dependency and on the optional constraints that might be needed for it to be installed. ## Version constraints @@ -41,7 +42,7 @@ If you only specify a major version, then minor- and patch-level changes are all ### Wildcard requirements -**Wildcard requirements** allow for any 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. @@ -74,7 +75,7 @@ If other dependencies require a different version, the solver will ultimately fa Multiple version requirements can also be separated with a comma, e.g. `>= 1.2, < 1.5`. -### `git` dependencies +## `git` dependencies To depend on a library located in a `git` repository, the minimum information you need to specify is the location of the repository with the git key: @@ -85,16 +86,24 @@ requests = { git = "https://github.com/requests/requests.git" } ``` Since we haven’t specified any other information, -Poetry assumes that we intend to use the latest commit on the `master` branch to build our project. -You can combine the `git` key with the `rev`, `tag`, or `branch` keys to specify something else. -Here's an example of specifying that you want to use the latest commit on a branch named `next`: +Poetry assumes that we intend to use the latest commit on the `master` branch +to build our project. + +You can combine the `git` key with the `branch` key to use another branch. +Alternatively, use `rev` or `tag` to pin a dependency to a specific commit hash +or tagged ref, respectively. For example: ```toml [tool.poetry.dependencies] +# Get the latest revision on the branch named "next" requests = { git = "https://github.com/kennethreitz/requests.git", branch = "next" } +# Get a revision by its commit hash +flask = { git = "https://github.com/pallets/flask.git", rev = "38eb5d3b" } +# Get a revision by its tag +numpy = { git = "https://github.com/numpy/numpy.git", tag = "v0.13.2" } ``` -### `path` dependencies +## `path` dependencies To depend on a library located in a local directory or file, you can use the `path` property: @@ -108,14 +117,8 @@ 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. - - -### `url` dependencies +## `url` dependencies To depend on a library located on a remote archive, you can use the `url` property: @@ -133,7 +136,7 @@ poetry add https://example.com/my-package-0.1.0.tar.gz ``` -### Python restricted dependencies +## Python restricted dependencies You can also specify that a dependency should be installed only for specific Python versions: @@ -147,7 +150,7 @@ pathlib2 = { version = "^2.2", python = "~2.7" } pathlib2 = { version = "^2.2", python = "~2.7 || ^3.2" } ``` -### Using environment markers +## Using environment markers If you need more complex install conditions for your dependencies, Poetry supports [environment markers](https://www.python.org/dev/peps/pep-0508/#environment-markers) @@ -159,7 +162,7 @@ pathlib2 = { version = "^2.2", markers = "python_version ~= '2.7' or sys_platfor ``` -### Multiple constraints dependencies +## Multiple constraints dependencies Sometimes, one of your dependency may have different version ranges depending on the target Python versions. @@ -176,6 +179,34 @@ foo = [ ] ``` +## Expanded dependency specification syntax + +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. + +An example where this might be useful is the following: + +```toml +[tool.poetry.dev-dependencies] +black = {version = "19.10b0", allow-prereleases = true, python = "^3.6", markers = "platform_python_implementation == 'CPython'} +``` + +As a single line, this is a lot to digest. To make this a little bit easier to +work with, you can do the following: + +```toml +[tool.poetry.dev-dependencies.black] +version = "19.10b0" +allow-prereleases = true +python = "^3.6" +markers = "platform_python_implementation == 'CPython'" +``` + +All of the same information is still present, and ends up providing the exact +same specification. It's simply split into multiple, slightly more readable, +lines. + !!!note The constraints **must** have different requirements (like `python`) diff --git a/docs/docs/faq.md b/docs/docs/faq.md index 11da2f94986..4d464d7ebc0 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -42,8 +42,8 @@ So, in your `pyproject.toml` file, add this section if it does not already exist ```toml [build-system] -requires = ["poetry>=0.12"] -build-backend = "poetry.masonry.api" +requires = ["poetry-core>=1.0.0"] +build-backend = "poetry.core.masonry.api" ``` And use a `tox.ini` configuration file similar to this: @@ -60,14 +60,14 @@ commands = poetry run pytest tests/ ``` -## I don't want Poetry to manage my virtualenvs. Can I disable it? +## I don't want Poetry to manage my virtual environments. Can I disable it? -While Poetry automatically creates virtualenvs to always work isolated +While Poetry automatically creates virtual environments to always work isolated from the global Python installation, there are valid reasons why it's not necessary and is an overhead, like when working with containers. In this case, you can disable this feature by setting the `virtualenvs.create` setting to `false`: ```bash -poetry config settings.virtualenvs.create false +poetry config virtualenvs.create false ``` diff --git a/docs/docs/index.md b/docs/docs/index.md index 66fb0ade021..9fe5b372c61 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -16,14 +16,19 @@ Poetry provides a custom installer that will install `poetry` isolated from the rest of your system by vendorizing its dependencies. This is the recommended way of installing `poetry`. +### osx / linux / bashonwindows install instructions ```bash -curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python +curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python +``` +### windows powershell install instructions +```powershell +(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python ``` !!! note You only need to install Poetry once. It will automatically pick up the current - Python version and use it to [create virtualenvs](/docs/basic-usage/#poetry-and-virtualenvs) accordingly. + Python version and use it to [create virtualenvs](/docs/managing-environments.md) accordingly. The installer installs the `poetry` tool to Poetry's `bin` directory. On Unix it is located at `$HOME/.poetry/bin` and on Windows at `%USERPROFILE%\.poetry\bin`. @@ -117,30 +122,34 @@ pipx uninstall poetry ## Updating `poetry` -Updating poetry to the latest stable version is as simple as calling the `self:update` command. +Updating Poetry to the latest stable version is as simple as calling the `self update` command. ```bash -poetry self:update +poetry self update ``` -If you want to install prerelease versions, you can use the `--preview` option. +If you want to install pre-release versions, you can use the `--preview` option. ```bash -poetry self:update --preview +poetry self update --preview ``` -And finally, if you want to install a specific version you can pass it as an argument -to `self:update`. +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 +poetry self update 0.8.0 ``` !!!note - The `self:update` command will only work if you used the recommended + The `self update` command will only work if you used the recommended installer to install Poetry. +!!!note + + If you are still on poetry version < 1.0 use `poetry self:update` instead. + ## Enable tab completion for Bash, Fish, or Zsh @@ -152,12 +161,15 @@ See `poetry help completions` for full details, but the gist is as simple as usi # Bash poetry completions bash > /etc/bash_completion.d/poetry.bash-completion -# Bash (macOS/Homebrew) +# Bash (Homebrew) poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-completion # Fish poetry completions fish > ~/.config/fish/completions/poetry.fish +# Fish (Homebrew) +poetry completions fish > (brew --prefix)/share/fish/vendor_completions.d/poetry.fish + # Zsh poetry completions zsh > ~/.zfunc/_poetry @@ -165,6 +177,9 @@ poetry completions zsh > ~/.zfunc/_poetry mkdir $ZSH/plugins/poetry poetry completions zsh > $ZSH/plugins/poetry/_poetry +# prezto +poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry + ``` !!! note diff --git a/docs/docs/libraries.md b/docs/docs/libraries.md index 0bbb7f6afed..db4822c342d 100644 --- a/docs/docs/libraries.md +++ b/docs/docs/libraries.md @@ -2,11 +2,6 @@ This chapter will tell you how to make your library installable through Poetry. -## Every project is a package - -As soon as you have a `pyproject.toml` in a directory, that directory is a package. -However, to make it accessible to others you will need to package and publish it. - ## Versioning @@ -14,7 +9,7 @@ While Poetry does not enforce any convention regarding package versioning, it **strongly** recommends to follow [semantic versioning](https://semver.org). This has many advantages for the end users and allows them to set appropriate -[version constraints](/docs/versions/). +[version constraints](/docs/dependency-specification/#version-constraints). ## Lock file diff --git a/docs/docs/managing-environments.md b/docs/docs/managing-environments.md new file mode 100644 index 00000000000..8a1475f7c45 --- /dev/null +++ b/docs/docs/managing-environments.md @@ -0,0 +1,121 @@ +# Managing environments + +Poetry makes project environment isolation one of its core features. + +What this means is that it will always work isolated from your global Python installation. +To achieve this, it will first check if it's currently running inside a virtual environment. +If it is, it will use it directly without creating a new one. But if it's not, it will use +one that it has already created or create a brand new one for you. + +By default, Poetry will try to use the currently activated Python version +to create the virtual environment for the current project. + +However, for various reasons, this Python version might not be compatible +with the `python` requirement of the project. In this case, Poetry will try +to find one that is and use it. If it's unable to do so then you will be prompted +to activate one explicitly, see [Switching environments](#switching-between-environments). + +!!!note + + To easily switch between Python versions, it is recommended to + use [pyenv](https://github.com/pyenv/pyenv) or similar tools. + + For instance, if your project is Python 2.7 only, a standard workflow + would be: + + ```bash + pyenv install 2.7.15 + pyenv local 2.7.15 # Activate Python 2.7 for the current project + poetry install + ``` + +## Switching between environments + +Sometimes this might not be feasible for your system, especially Windows where `pyenv` +is not available, or you simply prefer to have a more explicit control over your environment. +For this specific purpose, you can use the `env use` command to tell Poetry +which Python version to use for the current project. + +```bash +poetry env use /full/path/to/python +``` + +If you have the python executable in your `PATH` you can use it: + +```bash +poetry env use python3.7 +``` + +You can even just use the minor Python version in this case: + +```bash +poetry env use 3.7 +``` + +If you want to disable the explicitly activated virtual environment, you can use the +special `system` Python version to retrieve the default behavior: + +```bash +poetry env use system +``` + +## Displaying the environment information + +If you want to get basic information about the currently activated virtual environment, +you can use the `env info` command: + +```bash +poetry env info +``` + +will output something similar to this: + +```text +Virtual environment +Python: 3.7.1 +Implementation: CPython +Path: /path/to/poetry/cache/virtualenvs/test-O3eWbxRl-py3.7 +Valid: True + +System +Platform: darwin +OS: posix +Python: /path/to/main/python +``` + +If you only want to know the path to the virtual environment, you can pass the `--path` option +to `env info`: + +```bash +poetry env info --path +``` + +## Listing the environments associated with the project + +You can also list all the virtual environments associated with the current virtual environment +with the `env list` command: + +```bash +poetry env list +``` + +will output something like the following: + +```text +test-O3eWbxRl-py2.7 +test-O3eWbxRl-py3.6 +test-O3eWbxRl-py3.7 (Activated) +``` + +## Deleting the environments + +Finally, you can delete existing virtual environments by using `env remove`: + +```bash +poetry env remove /full/path/to/python +poetry env remove python3.7 +poetry env remove 3.7 +poetry env remove test-O3eWbxRl-py3.7 +``` + +If you remove the currently activated virtual environment, it will be automatically deactivated. diff --git a/docs/docs/pyproject.md b/docs/docs/pyproject.md index 679ad824a22..46cc1132148 100644 --- a/docs/docs/pyproject.md +++ b/docs/docs/pyproject.md @@ -27,19 +27,23 @@ The recommended notation for the most common licenses is (alphabetical): * BSD-2-Clause * BSD-3-Clause * BSD-4-Clause -* GPL-2.0 -* GPL-2.0+ -* GPL-3.0 -* GPL-3.0+ -* LGPL-2.1 -* LGPL-2.1+ -* LGPL-3.0 -* LGPL-3.0+ +* GPL-2.0-only +* GPL-2.0-or-later +* GPL-3.0-only +* GPL-3.0-or-later +* LGPL-2.1-only +* LGPL-2.1-or-later +* LGPL-3.0-only +* LGPL-3.0-or-later * MIT Optional, but it is highly recommended to supply this. More identifiers are listed at the [SPDX Open Source License Registry](https://www.spdx.org/licenses/). +!!!note + + If your project is proprietary and does not use a specific licence, you can set this value as `Proprietary`. + ## authors The authors of the package. **Required** @@ -127,11 +131,11 @@ it by using `format`: # ... packages = [ { include = "my_package" }, - { include = "tests", format = "sdist" }, + { include = "my_other_package", format = "sdist" }, ] ``` -From now on, only the `sdist` build archive will include the `tests` package. +From now on, only the `sdist` build archive will include the `my_other_package` package. !!!note @@ -264,7 +268,7 @@ any custom url in the `urls` section. ```toml [tool.poetry.urls] -"Bug Tracker" = "https://github.com/sdispater/poetry/issues" +"Bug Tracker" = "https://github.com/python-poetry/poetry/issues" ``` If you publish you package on PyPI, they will appear in the `Project Links` section. @@ -274,16 +278,22 @@ If you publish you package on PyPI, they will appear in the `Project Links` sect [PEP-517](https://www.python.org/dev/peps/pep-0517/) introduces a standard way to define alternative build systems to build a Python project. -Poetry is compliant with PEP-517 so if you use Poetry to manage your Python -project you should reference it in the `build-system` section of the `pyproject.toml` -file like so: +Poetry is compliant with PEP-517, by providing a lightweight core library, +so if you use Poetry to manage your Python project you should reference +it in the `build-system` section of the `pyproject.toml` file like so: ```toml [build-system] -requires = ["poetry>=0.12"] -build-backend = "poetry.masonry.api" +requires = ["poetry_core>=1.0.0"] +build-backend = "poetry.core.masonry.api" ``` !!!note When using the `new` or `init` command this section will be automatically added. + + +!!!note + + If your `pyproject.toml` file still references `poetry` directly as a build backend, + you should update it to reference `poetry_core` instead. diff --git a/docs/docs/repositories.md b/docs/docs/repositories.md index 73fb42f321b..d281f6ca77a 100644 --- a/docs/docs/repositories.md +++ b/docs/docs/repositories.md @@ -71,9 +71,19 @@ export POETRY_HTTP_BASIC_PYPI_USERNAME=username export POETRY_HTTP_BASIC_PYPI_PASSWORD=password ``` -See [Using environment variables](/configuration#using-environment-variables) for more information +See [Using environment variables](/docs/configuration/#using-environment-variables) for more information on how to configure Poetry with environment variables. +#### Custom certificate authority and mutual TLS authentication +Poetry supports repositories that are secured by a custom certificate authority as well as those that require +certificate-based client authentication. The following will configure the "foo" repository to validate the repository's +certificate using a custom certificate authority and use a client certificate (note that these config variables do not +both need to be set): +```bash + poetry config certificates.foo.cert /path/to/ca.pem + poetry config certificates.foo.client-cert /path/to/client.pem +``` + ### Install dependencies from a private repository Now that you can publish to your private repository, you need to be able to @@ -105,8 +115,10 @@ From now on, Poetry will also look for packages in your private repository. If your private repository requires HTTP Basic Auth be sure to add the username and password to your `http-basic` configuration using the example above (be sure to use the -same name that is in the `tool.poetry.source` section). Poetry will use these values -to authenticate to your private repository when downloading or looking for packages. +same name that is in the `tool.poetry.source` section). If your repository requires either +a custom certificate authority or client certificates, similarly refer to the example above to configure the +`certificates` section. Poetry will use these values to authenticate to your private repository when downloading or +looking for packages. ### Disabling the PyPI repository diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index ce69e560176..c35ef9579b4 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -14,7 +14,8 @@ nav: - Commands: cli.md - Configuration: configuration.md - Repositories: repositories.md - - Versions: versions.md + - Managing environments: managing-environments.md + - Dependency specification: dependency-specification.md - The pyproject.toml file: pyproject.md - Contributing: contributing.md - FAQ: faq.md @@ -25,3 +26,5 @@ markdown_extensions: - pymdownx.superfences - toc: permalink:  + - markdown_include.include: + base_path: docs diff --git a/docs/theme/main.html b/docs/theme/main.html index 7183cdfa01d..83151151ff6 100644 --- a/docs/theme/main.html +++ b/docs/theme/main.html @@ -6,7 +6,7 @@
-
+
    diff --git a/docs/theme/nav.html b/docs/theme/nav.html index 864a0f3acef..e9d2b383844 100644 --- a/docs/theme/nav.html +++ b/docs/theme/nav.html @@ -1,8 +1,4 @@ -{%- if nav_item.url %} {{ nav_item.title }} -{%- else %} -{{ nav_item.title }} -{%- endif %} {%- if nav_item == page or nav_item.children %}