Doc revisions1

Pipfile

@@ -21,6 +21,7 @@ gunicorn = {version = "*", markers="sys_platform == 'linux'"}
 parse = "*"
 importlib-metadata = {version = "*", markers="python_version < '3.8'"}
 colorama= {version = "*", markers="sys_platform == 'win32'"}
+myst-parser = "*"
 
 [packages]
 

docs/commands.md

@@ -0,0 +1,45 @@
+.. _commands:
+
+# Pipenv Commands
+
+The commands reference for pipenv (incomplete)
+
+## pipenv install
+
+``$ pipenv install`` is used for installing packages into the pipenv virtual environment
+and updating your Pipfile.
+
+Along with the basic installation command, which takes the form::
+
+ $ pipenv install [package names]
+
+The user can provide these additional parameters:
+
+ - ``--python`` — Performs the installation in a virtualenv using the provided Python interpreter.
+
+ .. warning:: None of the above commands should be used together. They are also
+ **destructive** and will delete your current virtualenv before replacing
+ it with an appropriately versioned one.
+
+ - ``--dev`` — Install both ``develop`` and ``default`` packages from ``Pipfile``.
+ - ``--system`` — Install packages to the system site-packages rather than into your virtualenv.
+ - ``--deploy`` — Verifies the _meta hash of the lock file is up to date with the ``Pipfile``, aborts install if not.
+ - ``--ignore-pipfile`` — Ignore the ``Pipfile`` and install from the ``Pipfile.lock``.
+ - ``--skip-lock`` — Ignore the ``Pipfile.lock`` and install from the ``Pipfile``. In addition, do not write out a ``Pipfile.lock`` reflecting changes to the ``Pipfile``.
+
+
+## pipenv uninstall
+
+``$ pipenv uninstall`` supports all of the parameters in `pipenv install <#pipenv-install>`_,
+as well as two additional options, ``--all`` and ``--all-dev``.
+
+ - ``--all`` — This parameter will purge all files from the virtual environment,
+ but leave the Pipfile untouched.
+
+ - ``--all-dev`` — This parameter will remove all of the development packages from
+ the virtual environment, and remove them from the Pipfile.
+
+
+## pipenv lock
+
+``$ pipenv lock`` is used to create a ``Pipfile.lock``, which declares **all** dependencies (and sub-dependencies) of your project, their latest available versions, and the current hashes for the downloaded files. This ensures repeatable, and most importantly *deterministic*, builds.

docs/conf.py

@@ -46,12 +46,29 @@
  "sphinx.ext.todo",
  "sphinx.ext.coverage",
  "sphinx.ext.viewcode",
+ "myst_parser",
  "sphinx_click",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+myst_enable_extensions = [
+ "amsmath",
+ "colon_fence",
+ "deflist",
+ "dollarmath",
+ "fieldlist",
+ "html_admonition",
+ "html_image",
+ "linkify",
+ "replacements",
+ "smartquotes",
+ "strikethrough",
+ "substitution",
+ "tasklist",
+]
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #

docs/docker.md

@@ -0,0 +1,113 @@
+# Pipenv and Docker Containers
+
+In general, you should not have Pipenv inside a linux container image, since
+it is a build tool. If you want to use it to build, and install the run time
+dependencies for your application, you can use a multistage build for creating
+a virtual environment with your dependencies.
+
+In this approach, Pipenv in installed in the base layer and it is used to create the virtual
+environment. In a later stage, in a ``runtime`` layer the virtual environment
+is copied from the base layer, the layer containing pipenv and other build
+dependencies is discarded.
+
+This results in a smaller image, which can still run your application.
+Here is an example ``Dockerfile``, which you can use as a starting point for
+doing a multistage build for your application:
+
+ FROM docker.io/python:3.9 AS builder
+
+ RUN pip install --user pipenv
+
+ # Tell pipenv to create venv in the current directory
+ ENV PIPENV_VENV_IN_PROJECT=1
+
+ # Pipfile contains requests
+ ADD Pipfile.lock Pipfile /usr/src/
+
+ WORKDIR /usr/src
+
+ # NOTE: If you install binary packages required for a python module, you need
+ # to install them again in the runtime. For example, if you need to install pycurl
+ # you need to have pycurl build dependencies libcurl4-gnutls-dev and libcurl3-gnutls
+ # In the runtime container you need only libcurl3-gnutls
+
+ # RUN apt install -y libcurl3-gnutls libcurl4-gnutls-dev
+
+ RUN /root/.local/bin/pipenv sync
+
+ RUN /usr/src/.venv/bin/python -c "import requests; print(requests.__version__)"
+
+ FROM docker.io/python:3.9 AS runtime
+
+ RUN mkdir -v /usr/src/.venv
+
+ COPY --from=builder /usr/src/.venv/ /usr/src/.venv/
+
+ RUN /usr/src/.venv/bin/python -c "import requests; print(requests.__version__)"
+
+ # HERE GOES ANY CODE YOU NEED TO ADD TO CREATE YOUR APPLICATION'S IMAGE
+ # For example
+ # RUN apt install -y libcurl3-gnutls
+ # RUN adduser --uid 123123 coolio
+ # ADD run.py /usr/src/
+
+ WORKDIR /usr/src/
+
+ USER coolio
+
+ CMD ["./.venv/bin/python", "-m", "run.py"]
+
+```{note}
+ Pipenv is not meant to run as root. However, in the multistage build above
+ it is done nevertheless. A calculated risk, since the intermediate image
+ is discarded.
+ The runtime image later shows that you should create a user and user it to
+ run your application.
+ **Once again, you should not run pipenv as root (or Admin on Windows) normally.
+ This could lead to breakage of your Python installation, or even your complete
+ OS.**
+```
+
+When you build an image with this example (assuming requests is found in Pipfile), you
+will see that ``requests`` is installed in the ``runtime`` image:
+
+ $ sudo docker build --no-cache -t oz/123:0.1 .
+ Sending build context to Docker daemon 1.122MB
+ Step 1/12 : FROM docker.io/python:3.9 AS builder
+ ---> 81f391f1a7d7
+ Step 2/12 : RUN pip install --user pipenv
+ ---> Running in b83ed3c28448
+ ... trimmed ...
+ ---> 848743eb8c65
+ Step 4/12 : ENV PIPENV_VENV_IN_PROJECT=1
+ ---> Running in 814e6f5fec5b
+ Removing intermediate container 814e6f5fec5b
+ ---> 20167b4a13e1
+ Step 5/12 : ADD Pipfile.lock Pipfile /usr/src/
+ ---> c7632cb3d5bd
+ Step 6/12 : WORKDIR /usr/src
+ ---> Running in 1d75c6cfce10
+ Removing intermediate container 1d75c6cfce10
+ ---> 2dcae54cc2e5
+ Step 7/12 : RUN /root/.local/bin/pipenv sync
+ ---> Running in 1a00b326b1ee
+ Creating a virtualenv for this project...
+ ... trimmed ...
+ ✔ Successfully created virtual environment!
+ Virtualenv location: /usr/src/.venv
+ Installing dependencies from Pipfile.lock (fe5a22)...
+ ... trimmed ...
+ Step 8/12 : RUN /usr/src/.venv/bin/python -c "import requests; print(requests.__version__)"
+ ---> Running in 3a66e3ce4a11
+ 2.27.1
+ Removing intermediate container 3a66e3ce4a11
+ ---> 1db657d0ac17
+ Step 9/12 : FROM docker.io/python:3.9 AS runtime
+ ... trimmed ...
+ Step 12/12 : RUN /usr/src/venv/bin/python -c "import requests; print(requests.__version__)"
+ ---> Running in fa39ba4080c5
+ 2.27.1
+ Removing intermediate container fa39ba4080c5
+ ---> 2b1c90fd414e
+ Successfully built 2b1c90fd414e
+ Successfully tagged oz/123:0.1

docs/index.md

@@ -0,0 +1,73 @@
+# Pipenv: Python Dev Workflow for Humans
+[![pypi version](https://img.shields.io/pypi/v/pipenv.svg)](https://pypi.python.org/pypi/pipenv) [![MIT License](https://img.shields.io/pypi/l/pipenv.svg)](https://pypi.python.org/pypi/pipenv) [![Supported Versions](https://img.shields.io/pypi/pyversions/pipenv.svg)](https://pypi.python.org/pypi/pipenv)
+
+**Pipenv** is a Python virtualenv management tool that supports a multitude of systems and nicely bridges the gaps between pip, pyenv and virtualenv.
+*Linux, macOS, and Windows are all first-class citizens in pipenv.*
+
+It automatically creates and manages a virtualenv for your projects, as well as adds/removes packages from your ``Pipfile`` as you install/uninstall packages. It also generates the ever-important ``Pipfile.lock``, which is used to produce deterministic builds.
+
+Pipenv is primarily meant to provide users and developers of applications with an easy method to setup a working environment.
+
+The problems that Pipenv seeks to solve are multi-faceted:
+
+- You no longer need to use ``pip`` and ``virtualenv`` separately. They work together.
+- Managing a ``requirements.txt`` file with package hashes can be problematic. Pipenv uses ``Pipfile`` and ``Pipfile.lock`` to separate abstract dependency declarations from the last tested combination.
+- Hashes are documented in the lock file, always. Security considerations are put first.
+- Strongly encourage the use of the latest versions of dependencies to minimize security risks [arising from outdated components](https://www.owasp.org/index.php/Top_10-2017_A9-Using_Components_with_Known_Vulnerabilities).
+- Gives you insight into your dependency graph (e.g. ``$ pipenv graph``).
+- Streamline development workflow by supporting local customizations with ``.env`` files.
+
+
+## Install Pipenv Today!
+
+The recommended way to install pipenv on most platforms is to install from pypi using ``pip``:
+
+ $ pip install --user pipenv
+
+More detailed installation instructions can be found in the :ref:`installing-pipenv` chapter.
+
+✨🍰✨
+
+## Pipenv Features
+
+- Enables truly *deterministic builds*, while easily specifying *only what you want*.
+- Generates and checks file hashes for locked dependencies when installing from ``Pipfile.lock``.
+- Automatically install required Python version when ``pyenv`` is available.
+- Automatically finds your project home, recursively, by looking for a ``Pipfile``.
+- Automatically generates a ``Pipfile``, if one doesn't exist.
+- Automatically creates a virtualenv in a standard customizable location.
+- Automatically adds/removes packages to a ``Pipfile`` when they are installed or uninstalled.
+- Automatically loads ``.env`` files to support customization and overrides.
+
+
+
+## Pipenv Documentation
+
+```{toctree}
+---
+caption: Pipenv Documentation
+maxdepth: 2
+---
+installation
+quickstart
+workflows
+pipfile
+commands
+specifiers
+shell
+docker
+advanced
+cli
+diagnose
+changelog
+```
+
+## Contribution Guides
+
+```{toctree}
+---
+caption: Contributing to Pipenv
+maxdepth: 2
+---
+dev/contributing
+```