Merge pull request #32 from enpaul/enp/docs

Beta > Alpha

.coveragerc

@@ -0,0 +1,7 @@
+[run]
+branch = True
+
+[report]
+exclude_lines =
+    \.\.\.
+    pass

.github/scripts/setup-env.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+#
+# Environment setup script for the local project. Intended to be used with automation
+# to create a repeatable local environment for tests to be run in. The python env
+# this script creates can be accessed at the location defined by the CI_VENV variable
+# below.
+
+set -e;
+
+# ##### Prereqs #####
+#
+# Set global vars for usage in the script, create the cache directory so we can rely
+# on that existing, then dump some diagnostic info for later reference.
+#
+CI_VENV=$HOME/ci;
+CI_CACHE=$HOME/.cache;
+CI_CACHE_GET_POETRY="$CI_CACHE/get-poetry.py";
+CI_POETRY=$HOME/.poetry/bin/poetry;
+CI_VENV_PIP="$CI_VENV/bin/pip";
+CI_VENV_PIP_VERSION=19.3.1;
+CI_VENV_TOX="$CI_VENV/bin/tox";
+
+mkdir --parents "$CI_CACHE";
+
+command -v python;
+python --version;
+
+# ##### Install Poetry #####
+#
+# Download the poetry install script to the cache directory and then install poetry.
+# After dump the poetry version for later reference.
+#
+curl https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py \
+  --output "$CI_CACHE_GET_POETRY" \
+  --silent \
+  --show-error \
+  --location;
+python "$CI_CACHE_GET_POETRY" --yes 1>/dev/null;
+
+python "$CI_POETRY" --version --no-ansi;
+
+# ##### Setup Runtime Venv #####
+#
+# Create a virtual environment for poetry to use, upgrade pip in that venv to a pinned
+# version, then install the current project to the venv.
+#
+# Note 1: Poetry, Tox, and this project plugin all use pip under the hood for package
+#         installation. This means that even though we are creating up to eight venvs
+#         during a given CI run they all share the same download cache.
+# Note 2: The "VIRTUAL_ENV=$CI_VENV" prefix on the poetry commands below sets the venv
+#         that poetry will use for operations. There is no CLI flag for poetry that
+#         directs it to use a given environment, but if it finds itself in an existing
+#         environment it will use it and skip environment creation.
+#
+python -m venv "$CI_VENV";
+
+$CI_VENV_PIP install "pip==$CI_VENV_PIP_VERSION" \
+  --upgrade \
+  --quiet;
+
+VIRTUAL_ENV=$CI_VENV "$CI_POETRY" install \
+  --extras poetry \
+  --quiet \
+  --no-ansi \
+  &>/dev/null;
+
+# ##### Print Debug Info #####
+#
+# Print the pip and tox versions (which will include registered plugins)
+#
+$CI_VENV_PIP --version;
+echo "tox $($CI_VENV_TOX --version)";

.github/workflows/ci.yaml

@@ -0,0 +1,72 @@
+---
+name: CI
+on:
+  pull_request:
+    types: ["opened", "synchronize"]
+  push:
+    branches: ["devel"]
+jobs:
+  Test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python:
+          - version: 3.6
+            toxenv: py36
+          - version: 3.7
+            toxenv: py37
+          - version: 3.8
+            toxenv: py38
+          - version: 3.9
+            toxenv: py39
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Setup:python${{ matrix.python.version }}
+        uses: actions/setup-python@v1
+        with:
+          python-version: ${{ matrix.python.version }}
+      - name: Setup:cache
+        uses: actions/cache@v2
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.cache/pypoetry/cache
+            ~/.poetry
+          # Including the hashed poetry.lock in the cache slug ensures that the cache
+          # will be invalidated, and thus all packages will be redownloaded, if the
+          # lockfile is updated
+          key: ${{ runner.os }}-${{ matrix.python.toxenv }}-${{ hashFiles('**/poetry.lock') }}
+      - name: Setup:env
+        run: .github/scripts/setup-env.sh
+      - name: Run:${{ matrix.python.toxenv }}
+        run: $HOME/ci/bin/tox \
+          -e ${{ matrix.python.toxenv }} \
+          --require-poetry
+  Check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Setup:python3.8
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.8
+      - name: Setup:cache
+        uses: actions/cache@v2
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.cache/pypoetry/cache
+            ~/.poetry
+          # Hardcoded 'py38' slug here lets this cache piggyback on the 'py38' cache
+          # that is generated for the tests above
+          key: ${{ runner.os }}-py38-${{ hashFiles('**/poetry.lock') }}
+      - name: Setup:env
+        run: .github/scripts/setup-env.sh
+      - name: Run:static
+        run: $HOME/ci/bin/tox -e static --require-poetry
+      - name: Run:static-tests
+        run: $HOME/ci/bin/tox -e static-tests --require-poetry
+      - name: Run:security
+        run: $HOME/ci/bin/tox -e security --require-poetry

.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+---
+# All of the pre-commit hooks here actually use the `pytyhon` pre-commit language
+# setting. However, for the python language setting, pre-commit will create and manage
+# a cached virtual environment for each hook ID and do a bare `pip install <repo>` into
+# the venv to setup the hook. This can result in conflicting dependency versions between
+# the version installed to the pre-commit venv and the version installed to the Poetry
+# venv specified in the lockfile.
+#
+# The solution is to specify `language: system` for all hooks and then install the
+# required dependencies to the Poetry venv. The `system` language skips the isolated
+# venv creation and looks for the entrypoint specified by the hook in the global
+# environment which, if running in the Poetry venv, will find the entrypoint provided
+# by the Poetry-managed dependency.
+#
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.3.0
+    hooks:
+      - id: end-of-file-fixer
+        language: system
+      - id: fix-encoding-pragma
+        args:
+          - "--remove"
+        language: system
+      - id: trailing-whitespace
+        language: system
+      - id: check-merge-conflict
+        language: system
+
+  - repo: https://github.com/psf/black
+    rev: 20.8b1
+    hooks:
+      - id: black
+        language: system
+
+  - repo: https://github.com/asottile/blacken-docs
+    rev: v1.8.0
+    hooks:
+      - id: blacken-docs
+        language: system
+
+  - repo: https://github.com/asottile/reorder_python_imports
+    rev: v2.3.6
+    hooks:
+      - id: reorder-python-imports
+        args:
+          - "--unclassifiable-application-module=tox_poetry_installer"
+        language: system

.pylintrc

@@ -0,0 +1,427 @@
+[MASTER]
+
+# A comma-separated list of package or module names from where C extensions may
+# be loaded. Extensions are loading into the active Python interpreter and may
+# run arbitrary code
+extension-pkg-whitelist=
+
+# Add files or directories to the blacklist. They should be base names, not
+# paths.
+ignore=
+
+# Add files or directories matching the regex patterns to the blacklist. The
+# regex matches against base names, not paths.
+ignore-patterns=
+
+# Python code to execute, usually for sys.path manipulation such as
+# pygtk.require().
+#init-hook=
+
+# Use multiple processes to speed up Pylint.
+jobs=1
+
+# List of plugins (as comma separated values of python modules names) to load,
+# usually to register additional checkers.
+load-plugins=
+
+# Pickle collected data for later comparisons.
+persistent=yes
+
+# Specify a configuration file.
+#rcfile=
+
+# Allow loading of arbitrary C extensions. Extensions are imported into the
+# active Python interpreter and may run arbitrary code.
+unsafe-load-any-extension=no
+
+
+[MESSAGES CONTROL]
+
+# Only show warnings with the listed confidence levels. Leave empty to show
+# all. Valid levels: HIGH, INFERENCE, INFERENCE_FAILURE, UNDEFINED
+confidence=
+
+# Disable the message, report, category or checker with the given id(s). You
+# can either give multiple identifiers separated by comma (,) or put this
+# option multiple times (only on the command line, not in the configuration
+# file where it should appear only once).You can also use "--disable=all" to
+# disable everything first and then reenable specific checks. For example, if
+# you want to run only the similarities checker, you can use "--disable=all
+# --enable=similarities". If you want to run only the classes checker, but have
+# no Warning level messages displayed, use"--disable=all --enable=classes
+# --disable=W"
+disable=logging-fstring-interpolation, logging-format-interpolation, bad-continuation, line-too-long
+#print-statement,parameter-unpacking,unpacking-in-except,old-raise-syntax,backtick,long-suffix,old-ne-operator,old-octal-literal,import-star-module-level,raw-checker-failed,bad-inline-option,locally-disabled,locally-enabled,file-ignored,suppressed-message,useless-suppression,deprecated-pragma,apply-builtin,basestring-builtin,buffer-builtin,cmp-builtin,coerce-builtin,execfile-builtin,file-builtin,long-builtin,raw_input-builtin,reduce-builtin,standarderror-builtin,unicode-builtin,xrange-builtin,coerce-method,delslice-method,getslice-method,setslice-method,no-absolute-import,old-division,dict-iter-method,dict-view-method,next-method-called,metaclass-assignment,indexing-exception,raising-string,reload-builtin,oct-method,hex-method,nonzero-method,cmp-method,input-builtin,round-builtin,intern-builtin,unichr-builtin,map-builtin-not-iterating,zip-builtin-not-iterating,range-builtin-not-iterating,filter-builtin-not-iterating,using-cmp-argument,eq-without-hash,div-method,idiv-method,rdiv-method,exception-message-attribute,invalid-str-codec,sys-max-int,bad-python3-import,deprecated-string-function,deprecated-str-translate-call,
+
+# Enable the message, report, category or checker with the given id(s). You can
+# either give multiple identifier separated by comma (,) or put this option
+# multiple time (only on the command line, not in the configuration file where
+# it should appear only once). See also the "--disable" option for examples.
+enable=
+
+
+[REPORTS]
+
+# Python expression which should return a note less than 10 (10 is the highest
+# note). You have access to the variables errors warning, statement which
+# respectively contain the number of errors / warnings messages and the total
+# number of statements analyzed. This is used by the global evaluation report
+# (RP0004).
+evaluation=10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)
+
+# Template used to display messages. This is a python new-style format string
+# used to format the message information. See doc for all details
+#msg-template=
+
+# Set the output format. Available formats are text, parseable, colorized, json
+# and msvs (visual studio).You can also give a reporter class, eg
+# mypackage.mymodule.MyReporterClass.
+output-format=text
+
+# Tells whether to display a full report or only the messages
+reports=no
+
+# Activate the evaluation score.
+score=yes
+
+
+[REFACTORING]
+
+# Maximum number of nested blocks for function / method body
+max-nested-blocks=5
+
+
+[BASIC]
+
+# Naming hint for argument names
+argument-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Regular expression matching correct argument names
+argument-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Naming hint for attribute names
+attr-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Regular expression matching correct attribute names
+attr-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Bad variable names which should always be refused, separated by a comma
+bad-names=foo,bar,baz,toto,tutu,tata
+
+# Naming hint for class attribute names
+class-attribute-name-hint=([A-Za-z_][A-Za-z0-9_]{2,30}|(__.*__))$
+
+# Regular expression matching correct class attribute names
+class-attribute-rgx=([A-Za-z_][A-Za-z0-9_]{2,30}|(__.*__))$
+
+# Naming hint for class names
+class-name-hint=[A-Z_][a-zA-Z0-9]+$
+
+# Regular expression matching correct class names
+class-rgx=[A-Z_][a-zA-Z0-9]+$
+
+# Naming hint for constant names
+const-name-hint=(([A-Z_][A-Z0-9_]*)|(__.*__))$
+
+# Regular expression matching correct constant names
+const-rgx=(([A-Z_][A-Z0-9_]*)|(__.*__))$
+
+# Minimum line length for functions/classes that require docstrings, shorter
+# ones are exempt.
+docstring-min-length=-1
+
+# Naming hint for function names
+function-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Regular expression matching correct function names
+function-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Good variable names which should always be accepted, separated by a comma
+good-names=_,ip,ap
+
+# Include a hint for the correct naming format with invalid-name
+include-naming-hint=no
+
+# Naming hint for inline iteration names
+inlinevar-name-hint=[A-Za-z_][A-Za-z0-9_]*$
+
+# Regular expression matching correct inline iteration names
+inlinevar-rgx=[A-Za-z_][A-Za-z0-9_]*$
+
+# Naming hint for method names
+method-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Regular expression matching correct method names
+method-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Naming hint for module names
+module-name-hint=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$
+
+# Regular expression matching correct module names
+module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$
+
+# Colon-delimited sets of names that determine each other's naming style when
+# the name regexes allow several styles.
+name-group=
+
+# Regular expression which should only match function or class names that do
+# not require a docstring.
+no-docstring-rgx=^_
+
+# List of decorators that produce properties, such as abc.abstractproperty. Add
+# to this list to register other decorators that produce valid properties.
+property-classes=abc.abstractproperty
+
+# Naming hint for variable names
+variable-name-hint=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+# Regular expression matching correct variable names
+variable-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
+
+
+[MISCELLANEOUS]
+
+# List of note tags to take in consideration, separated by a comma.
+#notes=FIXME,XXX,TODO
+notes=XXX
+
+
+[LOGGING]
+
+# Logging modules to check that the string format arguments are in logging
+# function parameter format
+logging-modules=logging
+
+
+[SIMILARITIES]
+
+# Ignore comments when computing similarities.
+ignore-comments=yes
+
+# Ignore docstrings when computing similarities.
+ignore-docstrings=yes
+
+# Ignore imports when computing similarities.
+ignore-imports=yes
+
+# Minimum lines number of a similarity.
+min-similarity-lines=10
+
+
+[VARIABLES]
+
+# List of additional names supposed to be defined in builtins. Remember that
+# you should avoid to define new builtins when possible.
+additional-builtins=
+
+# Tells whether unused global variables should be treated as a violation.
+allow-global-unused-variables=yes
+
+# List of strings which can identify a callback function by name. A callback
+# name must start or end with one of those strings.
+callbacks=cb_,_cb
+
+# A regular expression matching the name of dummy variables (i.e. expectedly
+# not used).
+dummy-variables-rgx=_+$|(_[a-zA-Z0-9_]*[a-zA-Z0-9]+?$)|dummy|^ignored_|^unused_
+
+# Argument names that match this expression will be ignored. Default to name
+# with leading underscore
+ignored-argument-names=_.*|^ignored_|^unused_|^fxt_
+
+# Tells whether we should check for unused import in __init__ files.
+init-import=no
+
+# List of qualified module names which can have objects that can redefine
+# builtins.
+redefining-builtins-modules=six.moves,future.builtins
+
+
+[SPELLING]
+
+# Spelling dictionary name. Available dictionaries: none. To make it working
+# install python-enchant package.
+spelling-dict=
+
+# List of comma separated words that should not be checked.
+spelling-ignore-words=
+
+# A path to a file that contains private dictionary; one word per line.
+spelling-private-dict-file=
+
+# Tells whether to store unknown words to indicated private dictionary in
+# --spelling-private-dict-file option instead of raising a message.
+spelling-store-unknown-words=no
+
+
+[FORMAT]
+
+# Expected format of line ending, e.g. empty (any line ending), LF or CRLF.
+expected-line-ending-format=
+
+# Regexp for a line that is allowed to be longer than the limit.
+ignore-long-lines=^\s*(# )?<?https?://\S+>?$
+
+# Number of spaces of indent required inside a hanging  or continued line.
+indent-after-paren=4
+
+# String used as indentation unit. This is usually "    " (4 spaces) or "\t" (1
+# tab).
+indent-string='    '
+
+# Maximum number of characters on a single line.
+max-line-length=100
+
+# Maximum number of lines in a module
+max-module-lines=1000
+
+# List of optional constructs for which whitespace checking is disabled. `dict-
+# separator` is used to allow tabulation in dicts, etc.: {1  : 1,\n222: 2}.
+# `trailing-comma` allows a space between comma and closing bracket: (a, ).
+# `empty-line` allows space-only lines.
+no-space-check=trailing-comma,dict-separator
+
+# Allow the body of a class to be on the same line as the declaration if body
+# contains single statement.
+single-line-class-stmt=no
+
+# Allow the body of an if to be on the same line as the test if there is no
+# else.
+single-line-if-stmt=no
+
+
+[TYPECHECK]
+
+# List of decorators that produce context managers, such as
+# contextlib.contextmanager. Add to this list to register other decorators that
+# produce valid context managers.
+contextmanager-decorators=contextlib.contextmanager
+
+# List of members which are set dynamically and missed by pylint inference
+# system, and so shouldn't trigger E1101 when accessed. Python regular
+# expressions are accepted.
+generated-members=
+
+# Tells whether missing members accessed in mixin class should be ignored. A
+# mixin class is detected if its name ends with "mixin" (case insensitive).
+ignore-mixin-members=yes
+
+# This flag controls whether pylint should warn about no-member and similar
+# checks whenever an opaque object is returned when inferring. The inference
+# can return multiple potential results while evaluating a Python object, but
+# some branches might not be evaluated, which results in partial inference. In
+# that case, it might be useful to still emit no-member and other checks for
+# the rest of the inferred objects.
+ignore-on-opaque-inference=yes
+
+# List of class names for which member attributes should not be checked (useful
+# for classes with dynamically set attributes). This supports the use of
+# qualified names.
+ignored-classes=optparse.Values,thread._local,_thread._local
+
+# List of module names for which member attributes should not be checked
+# (useful for modules/projects where namespaces are manipulated during runtime
+# and thus existing member attributes cannot be deduced by static analysis. It
+# supports qualified module names, as well as Unix pattern matching.
+ignored-modules=
+
+# Show a hint with possible names when a member name was not found. The aspect
+# of finding the hint is based on edit distance.
+missing-member-hint=yes
+
+# The minimum edit distance a name should have in order to be considered a
+# similar match for a missing member name.
+missing-member-hint-distance=1
+
+# The total number of similar names that should be taken in consideration when
+# showing a hint for a missing member.
+missing-member-max-choices=1
+
+
+[CLASSES]
+
+# List of method names used to declare (i.e. assign) instance attributes.
+defining-attr-methods=__init__,__new__,setUp
+
+# List of member names, which should be excluded from the protected access
+# warning.
+exclude-protected=_asdict,_fields,_replace,_source,_make
+
+# List of valid names for the first argument in a class method.
+valid-classmethod-first-arg=cls
+
+# List of valid names for the first argument in a metaclass class method.
+valid-metaclass-classmethod-first-arg=mcs
+
+
+[IMPORTS]
+
+# Allow wildcard imports from modules that define __all__.
+allow-wildcard-with-all=no
+
+# Analyse import fallback blocks. This can be used to support both Python 2 and
+# 3 compatible code, which means that the block might have code that exists
+# only in one or another interpreter, leading to false positives when analysed.
+analyse-fallback-blocks=no
+
+# Deprecated modules which should not be used, separated by a comma
+deprecated-modules=regsub,TERMIOS,Bastion,rexec
+
+# Create a graph of external dependencies in the given file (report RP0402 must
+# not be disabled)
+ext-import-graph=
+
+# Create a graph of every (i.e. internal and external) dependencies in the
+# given file (report RP0402 must not be disabled)
+import-graph=
+
+# Create a graph of internal dependencies in the given file (report RP0402 must
+# not be disabled)
+int-import-graph=
+
+# Force import order to recognize a module as part of the standard
+# compatibility libraries.
+known-standard-library=
+
+# Force import order to recognize a module as part of a third party library.
+known-third-party=enchant
+
+
+[DESIGN]
+
+# Maximum number of arguments for function / method
+max-args=7
+
+# Maximum number of attributes for a class (see R0902).
+max-attributes=7
+
+# Maximum number of boolean expressions in a if statement
+max-bool-expr=5
+
+# Maximum number of branch for function / method body
+max-branches=12
+
+# Maximum number of locals for function / method body
+max-locals=15
+
+# Maximum number of parents for a class (see R0901).
+max-parents=7
+
+# Maximum number of public methods for a class (see R0904).
+max-public-methods=20
+
+# Maximum number of return / yield for function / method body
+max-returns=6
+
+# Maximum number of statements in function / method body
+max-statements=50
+
+# Minimum number of public methods for a class (see R0903).
+min-public-methods=2
+
+
+[EXCEPTIONS]
+
+# Exceptions that will emit a warning when being caught. Defaults to
+# "Exception"
+overgeneral-exceptions=Exception

CODE_OF_CONDUCT.md

@@ -0,0 +1,129 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible 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.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders 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, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

Makefile

@@ -0,0 +1,36 @@
+# tox-poetry-installer makefile
+
+.PHONY: help
+# Put it first so that "make" without argument is like "make help"
+# Adapted from:
+# https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
+help: ## List Makefile targets
+	$(info Makefile documentation)
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-10s\033[0m %s\n", $$1, $$2}'
+
+clean-tox:
+	rm --recursive --force ./.mypy_cache
+	rm --recursive --force ./.tox
+	rm --recursive --force tests/__pycache__/
+	rm --recursive --force .pytest_cache/
+	rm --force .coverage
+
+clean-py:
+	rm --recursive --force ./dist
+	rm --recursive --force ./build
+	rm --recursive --force ./*.egg-info
+	rm --recursive --force ./**/__pycache__/
+
+clean: clean-tox clean-py; ## Clean temp build/cache files and directories
+
+wheel: ## Build Python binary distribution wheel package
+	poetry build --format wheel
+
+source: ## Build Python source distribution package
+	poetry build --format sdist
+
+test: ## Run the project testsuite(s)
+	poetry run tox --recreate
+
+publish: wheel source ## Build and upload to pypi (requires $PYPI_API_KEY be set)
+	@poetry publish --username __token__ --password $(PYPI_API_KEY)

README.md

@@ -1,62 +1,568 @@
 # tox-poetry-installer
 
-A [Tox](https://tox.readthedocs.io/en/latest/) plugin for installing Tox environment
-dependencies using [Poetry](https://python-poetry.org/) from the Poetry lockfile.
+A plugin for [Tox](https://tox.readthedocs.io/en/latest/) that allows test environment
+dependencies to be installed using [Poetry](https://python-poetry.org/) from its lockfile.
 
-⚠️ **This project is a very, very early prototype and should not be used in any production
-capacity.**
+⚠️ **This project is beta software and is under active development** ⚠️
+
+[![ci-status](https://github.com/enpaul/tox-poetry-installer/workflows/CI/badge.svg?event=push)](https://github.com/enpaul/tox-poetry-installer/actions)
+[![pypi-version](https://img.shields.io/pypi/v/tox-poetry-installer)](https://pypi.org/project/tox-poetry-installer/)
+[![pypi-downloads](https://img.shields.io/pypi/dm/tox-poetry-installer)](https://libraries.io/pypi/tox-poetry-installer)
+[![license](https://img.shields.io/pypi/l/tox-poetry-installer)](https://opensource.org/licenses/MIT)
+[![python-versions](https://img.shields.io/pypi/pyversions/tox-poetry-installer)](https://www.python.org)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+**Documentation**
+
+* [Introduction](#introduction)
+  * [Install](#install)
+  * [Quick Start](#quick-start)
+  * [Why would I use this?](#why-would-i-use-this) (What problems does this solve?)
+* [Reference](#reference)
+  * [Configuration Options](#configuration-options)
+  * [Command-line Arguments](#command-line-arguments)
+  * [Errors](#errors)
+  * [Advanced Usage](#advanced-usage)
+* [Developing](#developing)
+* [Contributing](#contributing)
+* [Roadmap](#roadmap)
+  * [Path to Beta](#path-to-beta)
+  * [Path to Stable](#path-to-stable)
+
+Related resources:
+* [Poetry Python Project Manager](https://python-poetry.org/)
+* [Tox Automation Project](https://tox.readthedocs.io/en/latest/)
+* [Other Tox plugins](https://tox.readthedocs.io/en/latest/plugins.html)
+
+Similar projects:
+* [Poetry Dev-Dependencies Tox Plugin](https://github.com/sinoroc/tox-poetry-dev-dependencies)
+* [Poetry Tox Plugin](https://github.com/tkukushkin/tox-poetry)
 
 
-## Why would I use this?
+## Introduction
 
-[The point of using a lockfile is to create reproducable builds](https://docs.gradle.org/current/userguide/dependency_locking.html). One of the main points of Tox is to [allow a Python
-package to be built and tested in multiple environments](https://tox.readthedocs.io/en/latest/#what-is-tox). However, in the Tox configuration file the dependencies are specified with
-standard dynamic ranges and passed directly to Pip. This means that the reproducability
-a lockfile brings to a project is circumvented when running the tests.
+This is a plugin to unify two great projects in the Python ecosystem: the
+[Tox](https://tox.readthedocs.io/en/latest/) automation project and the
+[Poetry](https://python-poetry.org) project/dependency manager. Specifically it allows
+the repeatable dependency resolution and installation tools that Poetry uses to benefit
+the isolated environments that Tox uses to run automated tests. The motivation to write
+this plugin came from a need for a single source of truth for the versions of all
+packages that should be installed to an environment.
 
-The obvious solution to this problem is to add the dependencies required for testing to the
-lockfile as development dependencies so that they are locked along with the primary dependencies
-of the project. The only remaining question however, is how to install the dev-dependencies from
-the lockfile into the Tox environment when Tox sets it up. [For very good reason](https://dev.to/elabftw/stop-using-sudo-pip-install-52mn) Tox uses independent
-[virtual environments](https://docs.python.org/3/tutorial/venv.html) for each environment a
-project defines, so there needs to be a way to install a locked dependency into a Tox
-environment.
+When in use this plugin will allow a Tox environment to install its required
+dependencies using the versions specified in the Poetry lockfile. This eliminates
+needing to specify package versions in multiple places as well as ensures that the Tox
+environment has the exact same versions of a given package as the Poetry environment.
+This reduces (or hopefully eliminates) hard to debug problems caused by subtle
+differences in the dependency graph of the active development environment (the one managed
+by Poetry) and the automated test environment(s) created by Tox.
 
-This is where this plugin comes in.
+To learn more about the problems this plugin aims to solve jump ahead to
+[What problems does this solve?](#why-would-i-use-this).
+Otherwise keep reading to get started.
 
-Traditionally Tox environments specify dependencies and their corresponding versions inline in
-[PEP-440](https://www.python.org/dev/peps/pep-0440/) format like below:
+### Install
+
+The recommended way to install the plugin is to add it to a project's `pyproject.toml`
+and lockfile using Poetry:
+
+```bash
+poetry add tox-poetry-installer[poetry] --dev
+```
+
+**WARNING:** The below installation methods are vulnerable to the
+[transient dependency issues this plugin aims to avoid](#why-would-i-use-this). It is
+always recommended to install dependencies using Poetry whenever possible.
+
+The plugin can also be installed with pip directly, though it is recommended to always
+install to a virtual environment and pin to a specific version:
+
+```bash
+source my-venv/bi/activate
+pip install tox-poetry-installer[poetry] == 0.6.0
+```
+
+The plugin can also be installed using the Tox
+[`requires`]((https://tox.readthedocs.io/en/latest/config.html#conf-requires))
+configuration option. Note however that dependencies installed via the `requires` option
+are not handled by the plugin and will be installed the same way as a `pip install ...`
+above. For this reason it is also recommended to always pin to a specific version when
+using this installation method:
+
+```ini
+# tox.ini
+[tox]
+requires
+    tox-poetry-installer[poetry] == 0.6.0
+```
+
+Check that the plugin is registered by checking the Tox version:
+
+```
+~ $: poetry run tox --version
+3.20.0 imported from .venv/lib64/python3.8/site-packages/tox/__init__.py
+registered plugins:
+    tox-poetry-installer-0.6.0 at .venv/lib64/python3.8/site-packages/tox_poetry_installer.py
+```
+
+**NOTE:** Installing the `tox-poetry-installer[poetry]` extra will add the `poetry`
+package as a managed environment dependency which can cause problems when the Poetry
+installation is externally managed (such as in a CI or container environment). See
+[Advanced Usage](#installing-alongside-an-existing-poetry-installation) for more
+information on this use case.
+
+### Quick Start
+
+Before making any changes to `tox.ini` the project is already benefiting from having
+the plugin installed: all dependencies of the root project package are installed using
+the Poetry backend to all Tox environments that install the root package without any
+configuration changes.
+
+To add dependencies from the lockfile to a Tox environment, add the option
+[`locked_deps`](#locked_deps) to the environment configuration and list names of
+dependencies (with no version specifier) under it:
 
 ```ini
 [testenv]
-description = Run the tests
+description = Some very cool tests
+locked_deps =
+    black
+    pylint
+    mypy
+commands = ...
+```
+
+The standard [`deps`](https://tox.readthedocs.io/en/latest/config.html#conf-deps) option
+can be used in parallel with the `locked_deps` option to install unlocked dependencies
+(dependencies not in the lockfile) alongside locked dependencies:
+
+```ini
+[testenv]
+description = Some very cool tests
+locked_deps =
+    black
+    pylint
+    mypy
+deps =
+    pytest == 6.1.1
+    pytest-cov >= 2.10, <2.11
+commands = ...
+```
+
+Alternatively, to quickly install all Poetry dev-dependencies to a Tox environment, add the
+[`install_dev_deps`](#install_dev_deps) option to the environment configuration:
+
+```ini
+[testenv]
+description = Some very cool tests
+install_dev_deps = true
+```
+
+See the [Reference](#reference) section for more details on available
+configuration options and the [Advanced Usage](#advanced-usage) section for some
+unusual use cases.
+
+### Why would I use this?
+
+**The Problem**
+
+By default Tox uses Pip to install the [PEP-508](https://www.python.org/dev/peps/pep-0508/)
+compliant dependencies to a test environment. This plugin extends the default Tox
+dependency installation behavior to support installing dependencies using a Poetry-based
+installation method that makes use of the dependency metadata from Poetry's lockfile.
+
+Environment dependencies for a Tox environment are usually specified in PEP-508 format, like
+the below example:
+
+```ini
+[testenv]
+description = Some very cool tests
 deps =
     foo == 1.2.3
     bar >=1.3,<2.0
     baz
 ```
 
-This runs into the problem outlined above: many different versions of the `bar` dependency
-could be installed depending on what the latest version is that matches the defined range. The
-`baz` dependency is entirely unpinned making it a true wildcard, and even the seemingly static
-`foo` dependency could result in subtly different files being downloaded depending on what's
-available in the upstream mirrors.
+Let's assume these dependencies are also useful during development, so they can be added to the
+Poetry environment using this command:
 
-However these same versions, specified in the [pyproject.toml](https://snarky.ca/what-the-heck-is-pyproject-toml/) file, result in reproducible
-installations when using `poetry install` because they each have a specific version and file
-hash specified in the lockfile. The versions specified in the lockfile are updated only when
-`poetry update` is run.
+ ```
+ poetry add --dev \
+    foo==1.2.3 \
+    bar>=1.3,<2.0 \
+    baz
+ ```
 
-This plugin allows environment dependencies to be specified in the [tox.ini](https://tox.readthedocs.io/en/latest/config.html) configuration file
-just by name. The package is automatically retrieved from the lockfile and the Poetry backend
-is used to install the singular locked package version to the Tox environment. When the
-lockfile is updated, the Tox environment will automatically install the newly locked package
-as well. All dependency requirements are specified in one place (pyproject.toml), all
-dependencies have a locked version, and everything is installed from that source of truth.
+ However there is a potential problem that could arise from each of these environment
+ dependencies that would _only_ appear in the Tox environment and not in the Poetry
+ environment in use by a developer:
+
+ * **The `foo` dependency is pinned to a specific version:** let's imagine a security
+   vulnerability is discovered in `foo` and the maintainers release version `1.2.4` to fix
+   it. A developer can run `poetry remove foo` and then `poetry add foo^1.2` to get the new
+   version, but the Tox environment is left unchanged. The development environment, as defined by
+   the lockfile, is now patched against the vulnerability but the Tox environment is not.
+
+* **The `bar` dependency specifies a dynamic range:** a dynamic range allows a range of
+  versions to be installed, but the lockfile will have an exact version specified so that
+  the Poetry environment is reproducible; this allows versions to be updated with
+  `poetry update` rather than with the `remove` and `add` commands used above. If the
+  maintainers of `bar` release version `1.6.0` then the Tox environment will install it
+  because it is valid for the specified version range. Meanwhile the Poetry environment will
+  continue to install the version from the lockfile until `poetry update bar` explicitly
+  updates it. The development environment is now has a different version of `bar` than the Tox
+  environment.
+
+* **The `baz` dependency is unpinned:** unpinned dependencies are
+  [generally a bad idea](https://python-poetry.org/docs/faq/#why-are-unbound-version-constraints-a-bad-idea),
+  but here it can cause real problems. Poetry will interpret an unbound dependency using
+  [the carrot requirement](https://python-poetry.org/docs/dependency-specification/#caret-requirements)
+  but Pip (via Tox) will interpret it as a wildcard. If the latest version of `baz` is `1.0.0`
+  then `poetry add baz` will result in a constraint of `baz>=1.0.0,<2.0.0` while the Tox
+  environment will have a constraint of `baz==*`. The Tox environment can now install an
+  incompatible version of `baz` and any errors that causes cannot be replicated using `poetry update`.
+
+All of these problems can apply not only to the dependencies specified for a Tox environment,
+but also to the dependencies of those dependencies, those dependencies' dependencies, and so on.
+
+**The Solution**
+
+This plugin allows dependencies specified in Tox environment take their version directly from
+the Poetry lockfile without needing an independent version to be specified in the Tox
+environment configuration. The modified version of the example environment given below appears
+less stable than the one presented above because it does not specify any versions for its
+dependencies:
+
+```ini
+[testenv]
+description = Some very cool tests
+require_locked_deps = true
+locked_deps =
+    foo
+    bar
+    baz
+```
+
+However with the `tox-poetry-installer` plugin installed Tox will install these
+dependencies from the Poetry lockfile so that the version installed to the Tox
+environment exactly matches the version Poetry is managing. When `poetry update` updates
+the lockfile with new versions of these dependencies, Tox will automatically install
+these new versions without needing any changes to the configuration.
 
 
-## Planned features
+## Reference
 
-* Per-environment disabling (i.e. fallback to the default Tox installation backend)
-* Detection of lockfile changes that trigger Tox environment recreation
-* Tests
+### Configuration Options
+
+All options listed below are Tox environment options and can be applied to one or more
+environment sections of the `tox.ini` file. They cannot be applied to the global Tox
+configuration section.
+
+**NOTE:** Environment settings applied to the main `testenv` environment will be
+inherited by child environments (i.e. `testenv:foo`) unless they are explicitly
+overridden by the child environment's configuration.
+
+#### `locked_deps`
+
+* **Type:** multi-line list
+* **Default:** `[]`
+
+Names of packages in the Poetry lockfile to install to the Tox environment. All
+dependencies specified here will be installed to the Tox environment using the details
+given by the Poetry lockfile.
+
+#### `require_locked_deps`
+
+
+* **Type:** boolean
+* **Default:** `false`
+
+Whether the environment should allow unlocked dependencies (dependencies not in the
+Poetry lockfile) to be installed alongside locked dependencies. If `true` then an error
+will be raised if the environment specifies unlocked dependencies to install and the
+plugin will block any other plugins from using the
+[`tox_testenv_install_deps`](https://tox.readthedocs.io/en/latest/plugins.html#tox.hookspecs.tox_testenv_install_deps)
+hook.
+
+#### `install_dev_deps`
+
+* **Type:** boolean
+* **Default:** `false`
+
+Whether all Poetry dev-dependencies should be installed to the environment. If `true`
+then all dependencies specified in the
+[`dev-dependencies`](https://python-poetry.org/docs/pyproject/#dependencies-and-dev-dependencies)
+section of `pyproject.toml` will be installed automatically.
+
+### Command-line Arguments
+
+All arguments listed below can be passed to the `tox` command to modify runtime behavior
+of the plugin.
+
+#### `--require-poetry`
+
+Indicates that Poetry is expected to be available to Tox and, if it is not, then the Tox
+run should fail. If provided and the `poetry` package is not installed to the same
+environment as the `tox` package then Tox will fail.
+
+**NOTE:** See [Advanced Usage](#installing-alongside-an-existing-poetry-installation)
+for more information.
+
+### Errors
+
+If the plugin encounters an error while processing a Tox environment then it will mark
+the environment as failed and set the environment status to one of the values below:
+
+**NOTE:** In addition to the reasons noted below, the plugin can encounter errors if the
+Poetry lockfile is not up-to-date with `pyproject.toml`. To resynchronize the
+lockfile with the `pyproject.toml` run one of
+[`poetry update`](https://python-poetry.org/docs/cli/#update) or
+[`poetry lock`](https://python-poetry.org/docs/cli/#lock)
+
+#### Poetry Not Installed Error
+
+* **Status value:** `PoetryNotInstalledError`
+* **Cause:** Indicates that the `poetry` module could not be imported from the same
+  environment as the running `tox` module and the runtime flags specified
+  [`--require-poetry`](#--require-poetry).
+* **Resolution options:**
+  * Install Poetry: ensure that `poetry` is installed to the same environment as `tox`.
+  * Skip running the plugin: remove the `--require-poetry` flag from the runtime options.
+
+**NOTE:** See [Advanced Usage](#installing-alongside-an-existing-poetry-installation)
+for more information.
+
+#### Locked Dependency Version Conflict Error
+
+* **Status value:** `LockedDepVersionConflictError`
+* **Cause:** Indicates that a dependency specified in the [`locked_deps`](#locked_deps)
+  configuration option in `tox.ini` includes a
+  [PEP-508 version specifier](https://www.python.org/dev/peps/pep-0508/#grammar)
+  (i.e. `pytest >=6.0, <6.1`).
+* **Resolution options:**
+  * Use the dependency version from the lockfile: remove any/all version specifiers
+    from the item in the `locked_deps` list in `tox.ini`.
+  * Do not install the dependency: remove the item from the `locked_deps` list in
+    `tox.ini`.
+
+#### Locked Dependency Not Found Error
+
+* **Status value:** `LockedDepNotFoundError`
+* **Cause:** Indicates that a dependency specified in the [`locked_deps`](#locked_deps)
+  configuration option in `tox.ini` could not be found in the Poetry lockfile.
+* **Resolution options:**
+  * Add the dependency to the lockfile: run
+    [`poetry add <dependency>`](https://python-poetry.org/docs/cli/#add).
+  * Do not install the dependency: remove the item from the `locked_deps` list in
+    `tox.ini`.
+
+#### Extra Not Found Error
+
+* **Status value:** `ExtraNotFoundError`
+* **Cause:** Indicates that the [`extras`](https://tox.readthedocs.io/en/latest/config.html#conf-extras)
+  configuration option specified a setuptools extra that is not configured by Poetry in
+  `pyproject.toml`
+* **Resolution options:**
+  * Configure the extra: add a section for the named extra to the
+    [`extras`](https://python-poetry.org/docs/pyproject/#extras) section of
+    `pyproject.toml` and optionally assign dependencies to the named extra using the
+    [`--optional`](https://python-poetry.org/docs/cli/#options_3) dependency setting.
+  * Remove the extra: remove the item from the `extras` list in `tox.ini`.
+
+#### Locked Dependencies Required Error
+
+* **Status value:** `LockedDepsRequiredError`
+* **Cause:** Indicates that an environment with the [`require_locked_deps`](#require_locked_deps)
+  configuration option also specified unlocked dependencies using
+  [`deps`](https://tox.readthedocs.io/en/latest/config.html#conf-deps) option in
+  `tox.ini`.
+* **Resolution options:**
+  * Remove all unlocked dependencies: remove the `deps` configuration option in
+    `tox.ini`.
+  * Allow unlocked dependencies: remove the `require_locked_deps` configuration option
+    in `tox.ini` or explicitly set `require_locked_deps = false`.
+
+### Advanced Usage
+
+#### Unsupported Tox configuration options
+
+The `tox.ini` configuration options listed below have no effect on the dependencies
+installed by this plugin the Poetry lockfile. Note that these settings will still be
+applied by the default Tox installation backend when installing unlocked dependencies
+using the built-in `deps` option.
+
+  * [`install_command`](https://tox.readthedocs.io/en/latest/config.html#conf-install_command)
+  * [`pip_pre`](https://tox.readthedocs.io/en/latest/config.html#conf-pip_pre)
+  * [`download`](https://tox.readthedocs.io/en/latest/config.html#conf-download)
+  * [`indexserver`](https://tox.readthedocs.io/en/latest/config.html#conf-indexserver)
+  * [`usedevelop`](https://tox.readthedocs.io/en/latest/config.html#conf-indexserver)
+
+All of these options are obsoleted by using the Poetry backend. If a given package
+installs successfully using Poetry (using either `poetry add <package>` or
+`poetry install`) then the required configuration options are already properly set in
+the Poetry configuration and the plugin will automatically use the same settings when
+installing the package.
+
+#### Reinstalling locked dependencies to a Tox environment
+
+Updating the `poetry.lock` file will not automatically cause Tox to install the updated
+lockfile specifications to the Tox environments that specify them.
+
+The Tox environment(s) with updated locked dependencies must be deleted and recreated
+using the [`--recreate`](https://tox.readthedocs.io/en/latest/config.html#cmdoption-tox-r)
+runtime flag. Alternatively Tox can be configured to always recreate an environment by
+setting the [`recreate`](https://tox.readthedocs.io/en/latest/config.html#conf-recreate)
+option in `tox.ini`.
+
+#### Installing Poetry's unsafe dependencies
+
+There are several packages that cannot be installed from the lockfile because they are
+excluded by Poetry itself. As a result these packages cannot be installed by this plugin
+either as environment dependencies (passed directly to [`locked_deps`](#locked_deps)) or
+as transient dependencies (a dependency of a locked dependency).
+
+As of [Poetry-1.1.4](https://github.com/python-poetry/poetry/releases/tag/1.1.4) there
+are four packages classified as "unsafe" by Poetry and excluded from the lockfile:
+
+* `setuptools`
+* `distribute`
+* `pip`
+* `wheel`
+
+When one of these packages is encountered by the plugin a warning will be logged and
+_**the package will not be installed to the environment**_. If the unsafe package
+is required for the environment then it will need to be specified as an unlocked
+dependency using the [`deps`](https://tox.readthedocs.io/en/latest/config.html#conf-deps)
+configuration option in `tox.ini`, ideally with an exact pinned version.
+
+* The set of packages excluded from the Poetry lockfile can be found in
+  [`poetry.puzzle.provider.Provider.UNSAFE_DEPENDENCIES`](https://github.com/python-poetry/poetry/blob/master/poetry/puzzle/provider.py)
+* There is an ongoing discussion of Poetry's handling of these packages at
+  [python-poetry/poetry#1584](https://github.com/python-poetry/poetry/issues/1584)
+
+#### Installing alongside an existing Poetry installation
+
+The plugin specifies the `poetry` package as an optional dependency to support an
+externally managed Poetry installation such as in a container or CI environment. This
+gives greater flexibility when using Poetry arguments like `--no-root`, `--no-dev`, or
+`--remove-untracked` which can cause Poetry to uninstall itself if Poetry is specified
+as a dependency of one of the packages it is managing (like this plugin).
+
+To have the plugin use the externally-managed Poetry package simply do not install the
+`poetry` extra when installing this plugin:
+
+```bash
+# Installing Poetry as a dependency with the plugin
+poetry add tox-poetry-installer[poetry]
+
+# Relying on an externally managed Poetry installation
+poetry add tox-poetry-installer
+```
+
+Note that Poetry is an optional dependency to support this use case _only_: Poetry must
+be installed to the same environment as Tox for the plugin to function. To check that
+the local environment has all of the required modules in scope run the below command:
+
+```bash
+python -c '\
+  import tox;\
+  import tox_poetry_installer;\
+  from poetry.poetry import Poetry;\
+'
+```
+
+**NOTE:** To force Tox to fail if Poetry is not installed, run the `tox` command with
+the [`--require-poetry`](#--require-poetry) option.
+
+
+## Developing
+
+This project requires Poetry version 1.0+ on the development workstation, see
+the [installation instructions here](https://python-poetry.org/docs/#installation).
+
+Local environment setup instructions:
+
+```bash
+# Clone the repository...
+# ...over HTTPS
+git clone https://github.com/enpaul/tox-poetry-installer.git
+# ...over SSH
+git clone git@github.com:enpaul/tox-poetry-installer.git
+
+# Create a the local project virtual environment and install dependencies
+cd tox-poetry-installer
+poetry install -E poetry
+
+# Install pre-commit hooks
+poetry run pre-commit install
+
+# Run tests and static analysis
+poetry run tox
+```
+
+**NOTE:** Because the pre-commit hooks require dependencies in the Poetry environment it
+is recommend to [launch an environment shell](https://python-poetry.org/docs/cli/#shell)
+when developing the project. Alternatively, many `git` commands will need to be run from
+outside of the environment shell by prefacing the command with
+[`poetry run`](https://python-poetry.org/docs/cli/#run).
+
+
+## Contributing
+
+All project contributors and participants are expected to adhere to the
+[Contributor Covenant Code of Conduct, v2](CODE_OF_CONDUCT.md)
+([external link](https://www.contributor-covenant.org/version/2/0/code_of_conduct/)).
+
+The `devel` branch has the latest (potentially unstable) changes. The
+[tagged versions](https://github.com/enpaul/tox-poetry-installer/releases) correspond to the
+releases on PyPI.
+
+* To report a bug, request a feature, or ask for assistance, please
+  [open an issue on the Github repository](https://github.com/enpaul/tox-poetry-installer/issues/new).
+* To report a security concern or code of conduct violation, please contact the project author
+  directly at **‌me [at‌] enp dot‎ ‌one**.
+* To submit an update, please
+  [fork the repository](https://docs.github.com/en/enterprise/2.20/user/github/getting-started-with-github/fork-a-repo)
+  and
+  [open a pull request](https://github.com/enpaul/tox-poetry-installer/compare).
+
+
+## Roadmap
+
+This project is under active development and is classified as beta software, ready for
+production environments on a provisional basis only.
+
+* Beta classification was assigned with [v0.6.0](https://github.com/enpaul/tox-poetry-installer/releases/tag/0.6.0)
+* Stable classification will be assigned when the test suite covers an acceptable number of
+  use cases
+
+### Path to Beta
+
+- [X] Verify that primary package dependencies (from the `.package` env) are installed
+      correctly using the Poetry backend.
+- [X] Support the [`extras`](https://tox.readthedocs.io/en/latest/config.html#conf-extras)
+      Tox configuration option ([#4](https://github.com/enpaul/tox-poetry-installer/issues/4))
+- [X] Add per-environment Tox configuration option to fall back to default installation
+      backend.
+- [ ] ~Add warnings when an unsupported Tox configuration option is detected while using the
+      Poetry backend. ([#5](https://github.com/enpaul/tox-poetry-installer/issues/5))~
+- [X] Add trivial tests to ensure the project metadata is consistent between the pyproject.toml
+      and the module constants.
+- [X] Update to use [poetry-core](https://github.com/python-poetry/poetry-core) and
+      improve robustness of the Tox and Poetry module imports
+      to avoid potentially breaking API changes in upstream packages. ([#2](https://github.com/enpaul/tox-poetry-installer/issues/2))
+- [ ] ~Find and implement a way to mitigate the [UNSAFE_DEPENDENCIES issue](https://github.com/python-poetry/poetry/issues/1584) in Poetry.
+      ([#6](https://github.com/enpaul/tox-poetry-installer/issues/6))~
+- [X] Fix logging to make proper use of Tox's logging reporter infrastructure ([#3](https://github.com/enpaul/tox-poetry-installer/issues/3))
+- [X] Add configuration option for installing all dev-dependencies to a testenv ([#14](https://github.com/enpaul/tox-poetry-installer/issues/14))
+
+### Path to Stable
+
+Everything in Beta plus...
+
+- [ ] Add comprehensive unit tests
+- [ ] Add tests for each feature version of Tox between 3.0 and 3.20
+- [ ] Add tests for Python-3.6, 3.7, 3.8, and 3.9
+- [X] Add Github Actions based CI
+- [ ] Add CI for CPython, PyPy, and Conda
+- [ ] Add CI for Linux and Windows

pyproject.toml

@@ -1,25 +1,62 @@
 [tool.poetry]
 name = "tox-poetry-installer"
-version = "0.1.0"
-description = "Tox plugin to install Tox environment dependencies using the Poetry backend and lockfile"
-authors = ["Ethan Paul <e@enp.one>"]
+version = "0.6.0"
 license = "MIT"
+authors = ["Ethan Paul <24588726+enpaul@users.noreply.github.com>"]
+description = "Tox plugin to install Tox environment dependencies using the Poetry backend and lockfile"
+repository = "https://github.com/enpaul/tox-poetry-installer/"
+packages = [
+  {include = "tox_poetry_installer"},
+  {include = "tests/*.py", format = "sdist"}
+]
+include = [
+  "tox_poetry_installer/py.typed"
+]
+keywords = ["tox", "poetry", "plugin"]
+readme = "README.md"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Plugins",
+  "Framework :: tox",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3.6",
+  "Programming Language :: Python :: 3.7",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: Implementation :: CPython",
+]
 
 [tool.poetry.plugins.tox]
 poetry_installer = "tox_poetry_installer"
 
+[tool.poetry.extras]
+poetry = ["poetry"]
+
 [tool.poetry.dependencies]
-python = "^3.6"
-poetry = "^1.0.10"
-pluggy = "^0.13.1"
-poetry-semver = "^0.1.0"
-requests = "2.22.0"
+python = "^3.6.1"
+poetry = {version = "^1.0.0", optional = true}
+poetry-core = "^1.0.0"
+tox = "^3.0.0"
 
 [tool.poetry.dev-dependencies]
-ipython = {version = "^7.18.1", python = "^3.7"}
-tox = "^3.20.0"
+bandit = "^1.6.2"
+black = { version = "^20.8b1", allow-prereleases = true }
+blacken-docs = "^1.8.0"
+ipython = { version = "^7.18.1", python = "^3.7" }
 mypy = "^0.782"
+pre-commit = "^2.7.1"
+pre-commit-hooks = "^3.3.0"
+pylint = "^2.4.4"
+pytest = "^6.0.2"
+pytest-cov = "^2.10.1"
+reorder-python-imports = "^2.3.5"
+safety = "^1.9.0"
+toml = "^0.10.1"
+tox = "^3.20.0"
 
 [build-system]
-requires = ["poetry>=1.0.0"]
-build-backend = "poetry.masonry.api"
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

tests/test_metadata.py

@@ -0,0 +1,37 @@
+"""Ensure that the pyproject and module metadata never drift out of sync
+
+The next best thing to having one source of truth is having a way to ensure all of your
+sources of truth agree with each other.
+"""
+from pathlib import Path
+
+import toml
+
+from tox_poetry_installer import __about__
+
+
+def test_metadata():
+    """Test that module metadata matches pyproject poetry metadata"""
+
+    with (Path(__file__).resolve().parent / ".." / "pyproject.toml").open() as infile:
+        pyproject = toml.load(infile, _dict=dict)
+
+    assert pyproject["tool"]["poetry"]["name"] == __about__.__title__
+    assert pyproject["tool"]["poetry"]["version"] == __about__.__version__
+    assert pyproject["tool"]["poetry"]["license"] == __about__.__license__
+    assert pyproject["tool"]["poetry"]["description"] == __about__.__summary__
+    assert pyproject["tool"]["poetry"]["repository"] == __about__.__url__
+    assert (
+        all(
+            item in __about__.__authors__
+            for item in pyproject["tool"]["poetry"]["authors"]
+        )
+        is True
+    )
+    assert (
+        all(
+            item in pyproject["tool"]["poetry"]["authors"]
+            for item in __about__.__authors__
+        )
+        is True
+    )

tox.ini

@@ -1,11 +1,64 @@
 [tox]
-envlist = py38
+envlist = py36, py37, py38, py39, static, static-tests, security
 isolated_build = true
+skip_missing_interpreters = true
 
 [testenv]
-description = Run the tests (pytest)
-deps =
-    requests
-skip_install = true
+description = Run the tests
+require_locked_deps = true
+extras =
+    poetry
+locked_deps =
+    pytest
+    pytest-cov
+    toml
 commands =
-    pip freeze
+    pytest --cov {envsitepackagesdir}/tox_poetry_installer --cov-config {toxinidir}/.coveragerc --cov-report term-missing tests/
+
+[testenv:static]
+description = Static formatting and quality enforcement
+basepython = python3.8
+platform = linux
+ignore_errors = true
+require_locked_deps = true
+locked_deps =
+    pre-commit
+    pre-commit-hooks
+    black
+    blacken-docs
+    reorder-python-imports
+    pylint
+    mypy
+commands =
+    pre-commit run --all-files
+    pylint --rcfile {toxinidir}/.pylintrc {toxinidir}/tox_poetry_installer/
+    mypy --ignore-missing-imports --no-strict-optional {toxinidir}/tox_poetry_installer/
+
+[testenv:static-tests]
+description = Static formatting and quality enforcement for the tests
+basepython = python3.8
+platform = linux
+ingore_errors = true
+require_locked_deps = true
+locked_deps =
+    pylint
+    mypy
+commands =
+    pylint --rcfile {toxinidir}/.pylintrc {toxinidir}/tests/
+    mypy --ignore-missing-imports --no-strict-optional {toxinidir}/tests/
+
+[testenv:security]
+description = Security checks
+basepython = python3.8
+platform = linux
+ingore_errors = true
+require_locked_deps = true
+locked_deps =
+    bandit
+    safety
+    poetry
+commands =
+    bandit --recursive --quiet {toxinidir}/tox_poetry_installer/
+    bandit --recursive --quiet --skip B101 {toxinidir}/tests/
+    poetry export --format requirements.txt --output {envtmpdir}/requirements.txt --without-hashes --dev
+    safety check --bare --file {envtmpdir}/requirements.txt

tox_poetry_installer.py

@@ -1,78 +0,0 @@
-from pathlib import Path
-import logging
-from typing import Dict, List
-
-from poetry.factory import Factory
-from poetry.factory import Poetry
-from poetry.packages import Package
-from poetry.installation.pip_installer import PipInstaller
-from poetry.io.null_io import NullIO
-from poetry.utils.env import VirtualEnv
-
-from tox.action import Action as ToxAction
-from tox.venv import VirtualEnv as ToxVirtualEnv
-from tox import hookimpl
-
-
-__title__ = "tox-poetry-installer"
-__summary__ = "Tox plugin to install Tox environment dependencies using the Poetry backend and lockfile"
-__version__ = "0.1.0"
-__url__ = "https://github.com/enpaul/tox-poetry-installer/"
-__license__ = "MIT"
-__authors__ = ["Ethan Paul <e@enp.one>"]
-
-
-def _make_poetry(venv: ToxVirtualEnv) -> Poetry:
-    return Factory().create_poetry(venv.envconfig.config.toxinidir)
-
-
-def _find_locked_dependencies(poetry: Poetry, dependency_name: str) -> List[Package]:
-    packages: Dict[str, Package] = {
-        package.name: package
-        for package in poetry.locker.locked_repository(True).packages
-    }
-
-    try:
-        top_level = packages[dependency_name]
-    except KeyError:
-        raise
-
-    def find_transients(name: str) -> List[Package]:
-        transients = [packages[name]]
-        for dep in packages[name].requires:
-            transients += find_transients(dep.name)
-        return transients
-
-    return find_transients(top_level.name)
-
-
-@hookimpl
-def tox_testenv_install_deps(venv: ToxVirtualEnv, action: ToxAction):
-
-    logger = logging.getLogger(__name__)
-
-    if action.name == venv.envconfig.config.isolated_build_env:
-        logger.debug(f"Environment {action.name} is isolated build environment; skipping Poetry-based dependency installation")
-        return None
-
-    poetry = _make_poetry(venv)
-
-    logger.debug(f"Loaded project pyproject.toml from {poetry.file}")
-
-    dependencies = []
-    for env_dependency in venv.envconfig.deps:
-        dependencies += _find_locked_dependencies(poetry, env_dependency.name)
-
-    logger.debug(f"Identified {len(dependencies)} dependencies for environment {action.name}")
-
-    installer = PipInstaller(
-        env=VirtualEnv(path=Path(venv.envconfig.envdir)),
-        io=NullIO(),
-        pool=poetry.pool
-    )
-
-    for dependency in dependencies:
-        logger.info(f"Installing environment dependency: {dependency}")
-        installer.install(dependency)
-
-    return dependencies

tox_poetry_installer/__about__.py

@@ -0,0 +1,7 @@
+# pylint: disable=missing-docstring
+__title__ = "tox-poetry-installer"
+__summary__ = "Tox plugin to install Tox environment dependencies using the Poetry backend and lockfile"
+__version__ = "0.6.0"
+__url__ = "https://github.com/enpaul/tox-poetry-installer/"
+__license__ = "MIT"
+__authors__ = ["Ethan Paul <24588726+enpaul@users.noreply.github.com>"]

tox_poetry_installer/__init__.py

@@ -0,0 +1,3 @@
+# pylint: disable=missing-docstring
+from tox_poetry_installer.hooks import tox_addoption
+from tox_poetry_installer.hooks import tox_testenv_install_deps

tox_poetry_installer/_poetry.py

@@ -0,0 +1,40 @@
+"""You've heard of vendoirization, now get ready for internal namespace shadowing
+
+Poetry is an optional dependency of this package explicitly to support the use case of having the
+plugin and the `poetry` package installed to the same python environment; this is most common in
+containers and/or CI. In this case there are two potential problems that can arise in this case:
+
+* The installation of the plugin overwrites the installed version of Poetry resulting in
+  compatibility issues.
+* Running `poetry install --no-dev`, when this plugin is in the dev-deps, results in poetry being
+  uninstalled from the environment.
+
+To support these edge cases, and more broadly to support not messing with a system package manager,
+the `poetry` package dependency is listed as optional dependency. This allows the plugin to be
+installed to the same environment as Poetry and import that same Poetry installation here.
+
+However, simply importing Poetry on the assumption that it is installed breaks another valid use
+case: having this plugin installed alongside Tox when not using a Poetry-based project. To account
+for this the imports in this module are isolated and the resultant import error that would result
+is converted to an internal error that can be caught by callers. Rather than importing this module
+at the module scope it is imported into function scope wherever Poetry components are needed. This
+moves import errors from load time to runtime which allows the plugin to be skipped if Poetry isn't
+installed and/or a more helpful error be raised within the Tox framework.
+"""
+# pylint: disable=unused-import
+import sys
+
+from tox_poetry_installer import exceptions
+
+
+try:
+    from poetry.factory import Factory
+    from poetry.installation.pip_installer import PipInstaller
+    from poetry.io.null_io import NullIO
+    from poetry.poetry import Poetry
+    from poetry.puzzle.provider import Provider
+    from poetry.utils.env import VirtualEnv
+except ImportError:
+    raise exceptions.PoetryNotInstalledError(
+        f"No version of Poetry could be imported under the current environment for '{sys.executable}'"
+    ) from None

tox_poetry_installer/constants.py

@@ -0,0 +1,31 @@
+"""Static constants for reference
+
+Rule of thumb: if it's an arbitrary value that will never be changed at runtime, it should go
+in this module.
+
+All constants should be type hinted.
+"""
+import sys
+from typing import Tuple
+
+from poetry.core.semver.version import Version
+
+from tox_poetry_installer import __about__
+
+
+# Valid PEP508 version delimiters. These are used to test whether a given string (specifically a
+# dependency name) is just a package name or also includes a version identifier.
+PEP508_VERSION_DELIMITERS: Tuple[str, ...] = ("~=", "==", "!=", ">", "<")
+
+# Prefix all reporter messages should include to indicate that they came from this module in the
+# console output.
+REPORTER_PREFIX: str = f"[{__about__.__title__}]:"
+
+
+# Semver compatible version of the current python platform version. Used for checking
+# whether a package is compatible with the current python system version
+PLATFORM_VERSION: Version = Version(
+    major=sys.version_info.major,
+    minor=sys.version_info.minor,
+    patch=sys.version_info.micro,
+)

tox_poetry_installer/datatypes.py

@@ -0,0 +1,8 @@
+"""Definitions for typehints/containers used by the plugin"""
+from typing import Dict
+
+from poetry.core.packages import Package as PoetryPackage
+
+
+# Map of package names to the package object
+PackageMap = Dict[str, PoetryPackage]

tox_poetry_installer/exceptions.py

@@ -0,0 +1,43 @@
+"""Custom plugin exceptions
+
+All exceptions should inherit from the common base exception :exc:`ToxPoetryInstallerException`.
+
+::
+
+  ToxPoetryInstallerException
+   +-- SkipEnvironment
+   |    +-- PoetryNotInstalledError
+   +-- LockedDepVersionConflictError
+   +-- LockedDepNotFoundError
+   +-- ExtraNotFoundError
+   +-- LockedDepsRequiredError
+
+"""
+
+
+class ToxPoetryInstallerException(Exception):
+    """Error while installing locked dependencies to the test environment"""
+
+
+class SkipEnvironment(ToxPoetryInstallerException):
+    """Current environment does not meet preconditions and should be skipped by the plugin"""
+
+
+class PoetryNotInstalledError(SkipEnvironment):
+    """No version of Poetry could be imported from the current Python environment"""
+
+
+class LockedDepVersionConflictError(ToxPoetryInstallerException):
+    """Locked dependencies cannot specify an alternate version for installation"""
+
+
+class LockedDepNotFoundError(ToxPoetryInstallerException):
+    """Locked dependency was not found in the lockfile"""
+
+
+class ExtraNotFoundError(ToxPoetryInstallerException):
+    """Project package extra not defined in project's pyproject.toml"""
+
+
+class LockedDepsRequiredError(ToxPoetryInstallerException):
+    """Environment cannot specify unlocked dependencies when locked dependencies are required"""

tox_poetry_installer/hooks.py

@@ -0,0 +1,148 @@
+"""Main hook definition module
+
+All implementations of tox hooks are defined here, as well as any single-use helper functions
+specifically related to implementing the hooks (to keep the size/readability of the hook functions
+themselves manageable).
+"""
+from typing import List
+from typing import Optional
+
+from poetry.core.packages import Package as PoetryPackage
+from tox import hookimpl
+from tox import reporter
+from tox.action import Action as ToxAction
+from tox.config import Parser as ToxParser
+from tox.venv import VirtualEnv as ToxVirtualEnv
+
+from tox_poetry_installer import __about__
+from tox_poetry_installer import constants
+from tox_poetry_installer import exceptions
+from tox_poetry_installer import utilities
+from tox_poetry_installer.datatypes import PackageMap
+
+
+@hookimpl
+def tox_addoption(parser: ToxParser):
+    """Add required configuration options to the tox INI file
+
+    Adds the ``require_locked_deps`` configuration option to the venv to check whether all
+    dependencies should be treated as locked or not.
+    """
+
+    parser.add_argument(
+        "--require-poetry",
+        action="store_true",
+        dest="require_poetry",
+        help="Trigger a failure if Poetry is not available to Tox",
+    )
+
+    parser.add_testenv_attribute(
+        name="install_dev_deps",
+        type="bool",
+        default=False,
+        help="Automatically install all Poetry development dependencies to the environment",
+    )
+
+    parser.add_testenv_attribute(
+        name="require_locked_deps",
+        type="bool",
+        default=False,
+        help="Require all dependencies in the environment be installed using the Poetry lockfile",
+    )
+
+    parser.add_testenv_attribute(
+        name="locked_deps",
+        type="line-list",
+        help="List of locked dependencies to install to the environment using the Poetry lockfile",
+    )
+
+
+@hookimpl
+def tox_testenv_install_deps(venv: ToxVirtualEnv, action: ToxAction) -> Optional[bool]:
+    """Install the dependencies for the current environment
+
+    Loads the local Poetry environment and the corresponding lockfile then pulls the dependencies
+    specified by the Tox environment. Finally these dependencies are installed into the Tox
+    environment using the Poetry ``PipInstaller`` backend.
+
+    :param venv: Tox virtual environment object with configuration for the local Tox environment.
+    :param action: Tox action object
+    """
+
+    try:
+        poetry = utilities.check_preconditions(venv, action)
+    except exceptions.SkipEnvironment as err:
+        if (
+            isinstance(err, exceptions.PoetryNotInstalledError)
+            and venv.envconfig.config.option.require_poetry
+        ):
+            venv.status = err.__class__.__name__
+            reporter.error(str(err))
+            return False
+        reporter.verbosity1(str(err))
+        return None
+
+    reporter.verbosity1(
+        f"{constants.REPORTER_PREFIX} Loaded project pyproject.toml from {poetry.file}"
+    )
+
+    try:
+        if venv.envconfig.require_locked_deps and venv.envconfig.deps:
+            raise exceptions.LockedDepsRequiredError(
+                f"Unlocked dependencies '{venv.envconfig.deps}' specified for environment '{venv.name}' which requires locked dependencies"
+            )
+
+        package_map: PackageMap = {
+            package.name: package
+            for package in poetry.locker.locked_repository(True).packages
+        }
+
+        if venv.envconfig.install_dev_deps:
+            dev_deps: List[PoetryPackage] = [
+                dep
+                for dep in package_map.values()
+                if dep not in poetry.locker.locked_repository(False).packages
+            ]
+        else:
+            dev_deps = []
+
+        reporter.verbosity1(
+            f"{constants.REPORTER_PREFIX} Identified {len(dev_deps)} development dependencies to install to env"
+        )
+
+        env_deps: List[PoetryPackage] = []
+        for dep in venv.envconfig.locked_deps:
+            env_deps += utilities.find_transients(package_map, dep.lower())
+        reporter.verbosity1(
+            f"{constants.REPORTER_PREFIX} Identified {len(env_deps)} environment dependencies to install to env"
+        )
+
+        if not venv.envconfig.skip_install and not venv.envconfig.config.skipsdist:
+            project_deps: List[PoetryPackage] = utilities.find_project_dependencies(
+                venv, poetry, package_map
+            )
+        else:
+            project_deps = []
+            reporter.verbosity1(
+                f"{constants.REPORTER_PREFIX} Skipping installation of project dependencies, env does not install project package"
+            )
+        reporter.verbosity1(
+            f"{constants.REPORTER_PREFIX} Identified {len(project_deps)} project dependencies to install to env"
+        )
+    except exceptions.ToxPoetryInstallerException as err:
+        venv.status = err.__class__.__name__
+        reporter.error(f"{constants.REPORTER_PREFIX} {err}")
+        return False
+    except Exception as err:
+        venv.status = "InternalError"
+        reporter.error(f"{constants.REPORTER_PREFIX} Internal plugin error: {err}")
+        raise err
+
+    dependencies = list(set(dev_deps + env_deps + project_deps))
+    action.setactivity(
+        __about__.__title__,
+        f"Installing {len(dependencies)} dependencies from Poetry lock file",
+    )
+    utilities.install_to_venv(poetry, venv, dependencies)
+
+    return venv.envconfig.require_locked_deps or None

tox_poetry_installer/utilities.py

@@ -0,0 +1,176 @@
+"""Helper utility functions, usually bridging Tox and Poetry functionality"""
+# Silence this one globally to support the internal function imports for the proxied poetry module.
+# See the docstring in 'tox_poetry_installer._poetry' for more context.
+# pylint: disable=import-outside-toplevel
+import sys
+import typing
+from pathlib import Path
+from typing import List
+from typing import Sequence
+from typing import Set
+
+from poetry.core.packages import Package as PoetryPackage
+from tox import reporter
+from tox.action import Action as ToxAction
+from tox.venv import VirtualEnv as ToxVirtualEnv
+
+from tox_poetry_installer import constants
+from tox_poetry_installer import exceptions
+from tox_poetry_installer.datatypes import PackageMap
+
+if typing.TYPE_CHECKING:
+    from tox_poetry_installer import _poetry
+
+
+def install_to_venv(
+    poetry: "_poetry.Poetry", venv: ToxVirtualEnv, packages: Sequence[PoetryPackage]
+):
+    """Install a bunch of packages to a virtualenv
+
+    :param poetry: Poetry object the packages were sourced from
+    :param venv: Tox virtual environment to install the packages to
+    :param packages: List of packages to install to the virtual environment
+    """
+    from tox_poetry_installer import _poetry
+
+    reporter.verbosity1(
+        f"{constants.REPORTER_PREFIX} Installing {len(packages)} packages to environment at {venv.envconfig.envdir}"
+    )
+
+    installer = _poetry.PipInstaller(
+        env=_poetry.VirtualEnv(path=Path(venv.envconfig.envdir)),
+        io=_poetry.NullIO(),
+        pool=poetry.pool,
+    )
+
+    for dependency in packages:
+        reporter.verbosity1(f"{constants.REPORTER_PREFIX} Installing {dependency}")
+        installer.install(dependency)
+
+
+def find_transients(packages: PackageMap, dependency_name: str) -> Set[PoetryPackage]:
+    """Using a poetry object identify all dependencies of a specific dependency
+
+    :param poetry: Populated poetry object which can be used to build a populated locked
+                   repository object.
+    :param dependency_name: Bare name (without version) of the dependency to fetch the transient
+                            dependencies of.
+    :returns: List of packages that need to be installed for the requested dependency.
+
+    .. note:: The package corresponding to the dependency named by ``dependency_name`` is included
+              in the list of returned packages.
+    """
+    from tox_poetry_installer import _poetry
+
+    try:
+
+        def find_deps_of_deps(name: str, searched: Set[str]) -> PackageMap:
+            package = packages[name]
+            transients: PackageMap = {}
+            searched.update([name])
+
+            if name in _poetry.Provider.UNSAFE_PACKAGES:
+                reporter.warning(
+                    f"{constants.REPORTER_PREFIX} Installing package '{name}' using Poetry is not supported; skipping installation of package '{name}'"
+                )
+                reporter.verbosity2(
+                    f"{constants.REPORTER_PREFIX} Skip {package}: designated unsafe by Poetry"
+                )
+            elif not package.python_constraint.allows(constants.PLATFORM_VERSION):
+                reporter.verbosity2(
+                    f"{constants.REPORTER_PREFIX} Skip {package}: incompatible Python requirement '{package.python_constraint}' for current version '{constants.PLATFORM_VERSION}'"
+                )
+            elif package.platform is not None and package.platform != sys.platform:
+                reporter.verbosity2(
+                    f"{constants.REPORTER_PREFIX} Skip {package}: incompatible platform requirement '{package.platform}' for current platform '{sys.platform}'"
+                )
+            else:
+                reporter.verbosity2(f"{constants.REPORTER_PREFIX} Include {package}")
+                transients[name] = package
+                for dep in package.requires:
+                    if dep.name not in searched:
+                        transients.update(find_deps_of_deps(dep.name, searched))
+
+            return transients
+
+        searched: Set[str] = set()
+        transients: PackageMap = find_deps_of_deps(
+            packages[dependency_name].name, searched
+        )
+
+        return set(transients.values())
+    except KeyError:
+        if any(
+            delimiter in dependency_name
+            for delimiter in constants.PEP508_VERSION_DELIMITERS
+        ):
+            raise exceptions.LockedDepVersionConflictError(
+                f"Locked dependency '{dependency_name}' cannot include version specifier"
+            ) from None
+        raise exceptions.LockedDepNotFoundError(
+            f"No version of locked dependency '{dependency_name}' found in the project lockfile"
+        ) from None
+
+
+def check_preconditions(venv: ToxVirtualEnv, action: ToxAction) -> "_poetry.Poetry":
+    """Check that the local project environment meets expectations"""
+    # Skip running the plugin for the packaging environment. PEP-517 front ends can handle
+    # that better than we can, so let them do their thing. More to the point: if you're having
+    # problems in the packaging env that this plugin would solve, god help you.
+    if action.name == venv.envconfig.config.isolated_build_env:
+        raise exceptions.SkipEnvironment(
+            f"Skipping isolated packaging build env '{action.name}'"
+        )
+
+    from tox_poetry_installer import _poetry
+
+    try:
+        return _poetry.Factory().create_poetry(venv.envconfig.config.toxinidir)
+    # Support running the plugin when the current tox project does not use Poetry for its
+    # environment/dependency management.
+    #
+    # ``RuntimeError`` is dangerous to blindly catch because it can be (and in Poetry's case,
+    # is) raised in many different places for different purposes.
+    except RuntimeError:
+        raise exceptions.SkipEnvironment(
+            "Project does not use Poetry for env management, skipping installation of locked dependencies"
+        ) from None
+
+
+def find_project_dependencies(
+    venv: ToxVirtualEnv, poetry: "_poetry.Poetry", packages: PackageMap
+) -> List[PoetryPackage]:
+    """Install the dependencies of the project package
+
+    Install all primary dependencies of the project package.
+
+    :param venv: Tox virtual environment to install the packages to
+    :param poetry: Poetry object the packages were sourced from
+    :param packages: Mapping of package names to the corresponding package object
+    """
+
+    base_dependencies: List[PoetryPackage] = [
+        packages[item.name]
+        for item in poetry.package.requires
+        if not item.is_optional()
+    ]
+
+    extra_dependencies: List[PoetryPackage] = []
+    for extra in venv.envconfig.extras:
+        reporter.verbosity1(
+            f"{constants.REPORTER_PREFIX} Processing project extra '{extra}'"
+        )
+        try:
+            extra_dependencies += [
+                packages[item.name] for item in poetry.package.extras[extra]
+            ]
+        except KeyError:
+            raise exceptions.ExtraNotFoundError(
+                f"Environment '{venv.name}' specifies project extra '{extra}' which was not found in the lockfile"
+            ) from None
+
+    dependencies: List[PoetryPackage] = []
+    for dep in base_dependencies + extra_dependencies:
+        dependencies += find_transients(packages, dep.name.lower())
+
+    return dependencies