Deprecate functions from core module (#262)

* chore: Configure flake8-rst-docstrings for `deprecated` directive

* docs: Deprecate core module

* docs: Deprecate patch module

* feat: Add deprecation warnings to core functions

.flake8

@@ -6,3 +6,4 @@ max-complexity = 10
 docstring-convention = google
 per-file-ignores = tests/*:S101
 rst-roles = const,class,func,meth,mod
+rst-directives = deprecated

src/nox_poetry/core.py

@@ -1,7 +1,13 @@
-"""Core functions."""
+"""Core functions.
+
+.. deprecated:: 0.8
+   Use :func:`session` instead.
+"""
+import warnings
 from pathlib import Path
 from typing import Any
 from typing import Iterable
+from typing import Optional
 
 import nox.sessions
 
@@ -12,32 +18,59 @@
 Session_install = nox.sessions.Session.install
 
 
+def _deprecate(name: str, replacement: Optional[str] = None) -> None:
+    message = f"nox_poetry.{name} is deprecated, use @nox_poetry.session instead"
+    if replacement is not None:
+        message += f" and invoke {replacement}"
+    warnings.warn(message, category=FutureWarning, stacklevel=2)
+
+
 def export_requirements(session: nox.sessions.Session) -> Path:
-    """Export a requirements file from Poetry."""
+    """Export a requirements file from Poetry.
+
+    .. deprecated:: 0.8
+       Use :func:`session` instead.
+    """  # noqa: D
+    _deprecate("export_requirements", "session.poetry.export_requirements")
     return Session(session).poetry.export_requirements()
 
 
 def build_package(
     session: nox.sessions.Session, *, distribution_format: DistributionFormat
-) -> str:
-    """Build a distribution archive for the package."""
+) -> str:  # noqa: D
+    """Build a distribution archive for the package.
+
+    .. deprecated:: 0.8
+       Use :func:`session` instead.
+    """
+    _deprecate("build_package", "session.poetry.build_package")
     return Session(session).poetry.build_package(
         distribution_format=distribution_format
     )
 
 
 def install(session: nox.sessions.Session, *args: str, **kwargs: Any) -> None:
-    """Install packages into a Nox session using Poetry."""
+    """Install packages into a Nox session using Poetry.
+
+    .. deprecated:: 0.8
+       Use :func:`session` instead.
+    """  # noqa: D
+    _deprecate("install", "session.install")
     Session(session).install(*args, **kwargs)
 
 
 def installroot(
     session: nox.sessions.Session,
-    *,
+    *,  # noqa: D
     distribution_format: DistributionFormat,
     extras: Iterable[str] = (),
 ) -> None:
-    """Install the root package into a Nox session using Poetry."""
+    """Install the root package into a Nox session using Poetry.
+
+    .. deprecated:: 0.8
+       Use :func:`session` instead.
+    """
+    _deprecate("installroot", "session.poetry.installroot")
     Session(session).poetry.installroot(
         distribution_format=distribution_format, extras=extras
     )
@@ -48,6 +81,9 @@ def patch(
 ) -> None:
     """Monkey-patch Nox to intercept ``session.install``.
 
+    .. deprecated:: 0.8
+       Use :func:`session` instead.
+
     This function monkey-patches `nox.sessions.Session.install`_ to invoke
     :func:`nox_poetry.install` instead. In addition, the argument ``"."`` is
     replaced by the specified distribution format, or :const:`nox_poetry.WHEEL`
@@ -63,4 +99,5 @@ def patch(
         distribution_format: The distribution format to use when the ``"."``
             argument is encountered in calls to ``session.install``.
     """
+    _deprecate("patch")
     nox.sessions.Session.install = install  # type: ignore[assignment]

src/nox_poetry/patch.py

@@ -1,5 +1,8 @@
 """Monkey-patch Nox to install packages using nox-poetry.
 
+.. deprecated:: 0.8
+   Use :func:`session` instead.
+
 Import this module to monkey-patch Nox.
 See :func:`nox_poetry.core.patch` for details.
 """