Poetry: Documentation missing for installation via pip + pyproject.toml

[TheButlah]

• [X] I have searched the issues of this repo and believe that this is not a duplicate.

Issue

With pip 19, support was introduced for installing dependencies using the pyproject.toml file, as specified in PEP 518. This means that the expected behavior when installing a package that uses poetry as its build system with pip is, I assume, equivalent to performing poetry install, although this is not made explicit in the documentation.

However, when running pip install ., I am not 100% sure whether or not the dependencies installed are the newest satisfying those listed in pyproject.toml, or if they are the exact versions specified in poetry.lock. My understanding is that poetry install installs the dependencies in poetry.lock, but I have no clue if that applies when installing via pip and pyproject.toml.

I suspect that the desired behavior is to bypass poetry.lock and use the highest version satisfying the constraints of the pyproject.toml file, as when pip installing a package that uses poetry, it is supposed to be used as a library rather than an application, and therefore does not have a consistent environment, which was the whole point of poetry.lock.

Furthermore, I'd like to know if the intended behavior is to install directly into the environment that pip was invoked in, or if poetry creates a new venv like when typically doing poetry install. I suspect that the intended behavior is for poetry to treat this as if it were installing without a venv, as whoever invoked pip may or may not have pip in its own venv and poetry should respect that without introducing another venv.

Could I have someone clarify exactly how all this works? And then could that clarification be added into the documentation?

[mikerhodes]

I have also been working with the combination of pip and poetry. As well as pip install, I've also been using pip wheel to create Docker images. I like that this combination potentially leads to poetry not needing to have code written so it can do every task itself 😄

Similar documentation as mentioned in the original post (e.g., for the use (or not) of poetry.lock) would be super-useful for wheel too. My experiments indicate, but would be nice to know for sure:

• That poetry.lock is not used. FWIW ideally we would use poetry.lock to ensure that production images match the SHAs etc we expect.
• I can't see a way to supply poetry arguments like --no-root via pip.
• I am not sure yet whether the --index-url on the pip wheel in the first build stage below makes its way through to Poetry or whether entries in pyproject.toml are required.

As an example, the essentials of my Dockerfile are (using two stages as the first stage ends up needing private repo secrets):

# Stage 1 build to allow pulling from private repos requiring creds
FROM python:3.8.0-buster AS builder
ARG PYPI_URL='https://pypi.org/simple'
ARG PACKAGE_NAME

RUN mkdir -p /build/dist /build/${PACKAGE_NAME}
COPY pyproject.toml /build
COPY poetry.lock /build
COPY ${PACKAGE_NAME}/*.py /build/${PACKAGE_NAME}/
RUN pip wheel -w /build/dist --index-url ${PYPI_URL} /build

# Stage 2 build: copy and install wheels from stage 1 (`builder`).
FROM python:3.8.0-slim-buster as production-image

COPY --from=builder [ "/build/dist/*.whl", "/install/" ]
RUN pip install --no-index /install/*.whl \
    && rm -rf /install

CMD [ "my-package-script" ]

I'm not completely convinced that use of pip isn't overkill here tbh, but it's useful to show what can be done with the PEP 517 builds.