Add support for poe_tasks.toml|yaml|json files

README.md

@@ -4,7 +4,7 @@
 
 [![PyPI version](https://img.shields.io/pypi/pyversions/poethepoet.svg)](https://pypi.org/project/poethepoet/)
 [![PyPI version](https://img.shields.io/pypi/v/poethepoet.svg)](https://pypi.org/project/poethepoet/)
-[![PyPI version](https://img.shields.io/pypi/dw/poethepoet.svg)](https://pypistats.org/packages/poethepoet)
+[![PyPI version](https://img.shields.io/pypi/dm/poethepoet.svg)](https://pypistats.org/packages/poethepoet)
 [![PyPI version](https://img.shields.io/pypi/l/ansicolortags.svg)](https://github.com/nat-n/poethepoet/blob/doc/init-sphinx/LICENSE)
 
 **A batteries included task runner that works well with [poetry](https://python-poetry.org/).**
@@ -15,8 +15,7 @@
 
 ## Features
 
-
-- ✅ Straight forward [declaration of project tasks in your pyproject.toml](https://poethepoet.natn.io/tasks/index.html)
+- ✅ Straight forward [declaration of project tasks in your pyproject.toml](https://poethepoet.natn.io/tasks/index.html) (or [poe_tasks.toml](https://poethepoet.natn.io/guides/without_poetry.html#usage-without-pyproject-toml))
 
 - ✅ Tasks are run in poetry's virtualenv ([or another env](https://poethepoet.natn.io/index.html#usage-without-poetry) you specify)
 
@@ -40,6 +39,7 @@
 
 - ✅ Can be [used as a library](https://poethepoet.natn.io/guides/library_guide.html) to embed in other tools
 
+- ✅ Also works fine [without poetry](https://poethepoet.natn.io/guides/without_poetry.html)
 
 ## Quick start
 

docs/conf.py

@@ -43,7 +43,6 @@
    :language: python
 .. |V| unicode:: ✅ 0xA0 0xA0
    :trim:
-
 """
 
 linkcheck_ignore = [

docs/guides/include_guide.rst

@@ -1,7 +1,11 @@
 Loading tasks from another file
 ===============================
 
-There are some scenarios where one might wish to define tasks outside of pyproject.toml, or to collect tasks from multiple projects into one. For example, if you want to share tasks between projects via git modules, generate tasks definitions dynamically, organise your code in a monorepo, or simply have a lot of tasks and don't want the pyproject.toml to get too large. This can be achieved by creating a toml or json file including the same structure for tasks as used in pyproject.toml
+There are some scenarios where one might wish to define tasks outside of pyproject.toml, or to collect tasks from multiple projects into one. For example, if you want to share tasks between projects via git modules, generate tasks definitions dynamically, organise your code in a monorepo, or simply have a lot of tasks and don't want the pyproject.toml to get too large. This can be achieved by creating a toml, yaml, or json file including the same structure for tasks as used in pyproject.toml
+
+.. tip::
+
+  Imported toml, yaml, or json files are not required to namespace config under ``tool.poe``. However if config exists under this structure then it will be used.
 
 For example:
 

docs/guides/index.rst

@@ -12,4 +12,5 @@ This section contains guides for using the various features of Poe the Poet.
    composition_guide
    include_guide
    global_tasks
+   without_poetry
    library_guide

docs/guides/without_poetry.rst

@@ -0,0 +1,72 @@
+Usage without poetry
+====================
+
+Poe the Poet was originally intended as the missing task runner for |poetry_link|. But it works just as well with any other kind of virtualenv, or simply as a general purpose way to define handy tasks for use within a certain directory structure! This behaviour is configurable via the :ref:`tool.poe.executor global option<Change the executor type>`.
+
+By default poe will run tasks in the poetry managed virtual environment, if the pyproject.toml contains a :toml:`tool.poetry` section. If it doesn't then poe looks for a virtualenv to use at ``./.venv`` or ``./venv`` relative to the pyproject.toml.
+
+If no virtualenv is found then poe will run tasks without any special environment management.
+
+
+Usage without pyproject.toml
+----------------------------
+
+When using Poe the Poet outside of a poetry (or other |pep518_link|) project, you can avoid the potential confusion of creating a `pyproject.toml` file and instead name the file ``poe_tasks.toml``.
+
+
+Usage with with json or yaml instead of toml
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As an alternative to toml, poethepoet configuration can also be provided via yaml or json files. When searching for a tasks file to load within a certain directory poe will try the following file names in order:
+
+- pyproject.toml
+- poe_tasks.toml
+- poe_tasks.yaml
+- poe_tasks.json
+
+If `pyproject.toml` exists but does not contain the key prefix ``tool.poe`` then the search continues with `poe_tasks.toml`. If one of the listed ``poe_tasks.*`` files exist then the search is terminated, even if the file is empty.
+
+When config is loaded from a file other than `pyproject.toml` the ``tool.poe`` namespace for poe config is optional. So for example the following two poe_tasks.yaml files are equivalent and both valid:
+
+.. code-block:: yaml
+  :caption: poe_tasks.yaml
+
+  env:
+    VAR0: FOO
+
+  tasks:
+    show-vars:
+      cmd: "echo $VAR0 $VAR1 $VAR2"
+      env:
+        VAR1: BAR
+      args:
+        - name: VAR2
+          options: ["--var"]
+          default: BAZ
+
+.. code-block:: yaml
+  :caption: poe_tasks.yaml
+
+  tool:
+    poe:
+      env:
+        VAR0: FOO
+
+      tasks:
+        show-vars:
+          cmd: "echo $VAR0 $VAR1 $VAR2"
+          env:
+            VAR1: BAR
+          args:
+            - name: VAR2
+              options: ["--var"]
+              default: BAZ
+
+
+.. |poetry_link| raw:: html
+
+   <a href="https://python-poetry.org/" target="_blank">poetry</a>
+
+.. |pep518_link| raw:: html
+
+   <a href="https://peps.python.org/pep-0518/" target="_blank">PEP 518</a>

docs/index.rst

@@ -26,7 +26,7 @@ Poe the Poet Documentation
    :target: https://pypi.org/project/poethepoet/
    :alt: PyPI
 
-.. image:: https://img.shields.io/pypi/dw/poethepoet
+.. image:: https://img.shields.io/pypi/dm/poethepoet
    :target: https://pypistats.org/packages/poethepoet
    :alt: PyPI - Downloads
 
@@ -44,7 +44,7 @@ It provides a simple way to define project tasks within your pyproject.toml, and
 Top features
 ============
 
-|V| Straight forward declaration of project tasks in your pyproject.toml
+|V| Straight forward declaration of project tasks in your pyproject.toml (or :doc:`poe_tasks.toml<./guides/without_poetry>`)
 
 |V| Tasks are run in poetry's virtualenv (or another env you specify)
 
@@ -68,6 +68,8 @@ Top features
 
 |V| Can be :doc:`used as a library<./guides/library_guide>` to embed in other tools
 
+|V| Also works fine :doc:`without poetry<./guides/without_poetry>`
+
 
 Quick start
 ===========
@@ -105,29 +107,20 @@ Quick start
   If you're using |poetry_link|, then poe will automatically use the poetry managed virtualenv to find executables and python libraries, without needing to use ``poetry run`` or ``poetry shell``.
 
 
-Usage without poetry
-====================
-
-Poe the Poet was originally intended as the missing task runner for |poetry_link|. But it works just as well with any other kind of virtualenv, or simply as a general purpose way to define handy tasks for use within a certain directory structure! This behaviour is configurable via the :ref:`tool.poe.executor global option<Change the executor type>`.
-
-By default poe will run tasks in the poetry managed virtual environment, if the pyproject.toml contains a :toml:`tool.poetry` section. If it doesn't then poe looks for a virtualenv to use at ``./.venv`` or ``./venv`` relative to the pyproject.toml.
-
-If no virtualenv is found then poe will run tasks without any special environment management.
-
-
 Run poe from anywhere
 =====================
 
 By default poe will detect when you're inside a project with a pyproject.toml in the root. However if you want to run it from elsewhere then that is supported by using the :sh:`-C` option to specify an alternate location for the toml file. The task will run with the given location as the current working directory.
 
 In all cases the path to project root (where the pyproject.toml resides) will be available as :sh:`$POE_ROOT` within the command line and process. The variable :sh:`$POE_PWD` contains the original working directory from which poe was run.
 
-.. |poetry_link| raw:: html
+Using this feature you can also define :doc:`global tasks<./guides/global_tasks>` that are not associated with any particular project.
 
-   <a href="https://python-poetry.org/" target="_blank">poetry</a>
 
 .. |pipx_link| raw:: html
 
    <a href="https://pypa.github.io/pipx/" target="_blank">pipx</a>
 
-Using this feature you can also define :doc:`global tasks<./guides/global_tasks>` that are not associated with any particular project.
+.. |poetry_link| raw:: html
+
+   <a href="https://python-poetry.org/" target="_blank">poetry</a>

poethepoet/app.py

@@ -43,8 +43,9 @@ class PoeThePoet:
         instead of having to execute poetry in a subprocess to determine this.
     :type poetry_env_path: str, optional
     :param config_name:
-        The name of the file to load tasks and configuration from, defaults to
-        "pyproject.toml"
+        The name of the file to load tasks and configuration from. If not set then poe
+        will search for config by the following file names: pyproject.toml
+        poe_tasks.toml poe_tasks.yaml poe_tasks.json
     :type config_name: str, optional
     :param program_name:
         The name of the program that is being run. This is used primarily when
@@ -64,7 +65,7 @@ def __init__(
         config: Optional[Union[Mapping[str, Any], "PoeConfig"]] = None,
         output: IO = sys.stdout,
         poetry_env_path: Optional[str] = None,
-        config_name: str = "pyproject.toml",
+        config_name: Optional[str] = None,
         program_name: str = "poe",
     ):
         from .config import PoeConfig